feat(surfaces): add issue-tree part kind

A new native part kind renders a parent issue and its nested sub-issues as
a tight rail tree with a progress rollup the viewer computes (done ÷ total
over descendants, never stored). The shape is the normalized, recursive
Issue model — `root.children` are more issues — so a tree nests across
providers (a Linear epic owning a GitHub sub-issue and a Sentry leaf).

Threaded through every tier: types + recursive zod validation (strict
rejects, loose tolerates/drops), the Solid renderer, MCP/HTTP/CLI
(`sideshow issue-tree`, `--issue-tree`), the design guide, AGENTS, and the
README gallery. Adds an `--ok` status-green chrome token (themed via
viewerVars, with a styles.css fallback).

Hardening from review:
- bound nesting (MAX_ISSUE_TREE_DEPTH/NODES) with an iterative pre-check so
  a deep tree is a clean 400 (loose drops it), not a stack-overflow 500;
  plus an app.onError safety net.
- sanitize node.url (safeHref allowlist) so javascript:/data: never render
  as an executable link in the trusted viewer origin.
- drop coerced-empty loose children so phantom rows can't skew the rollup.
- memoize the rollup walk; progressbar aria; recursive JSON-schema children.

Tests: depth rejection, loose state/child coercion, update→issue-tree
history, partsByteLength recursion, store-contract deep round-trip, CLI
publish + envelope error, and e2e (render, structural nesting depth, and
javascript:-url safety).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: benvinegar

.changeset/issue-tree-surface-part.md

@@ -0,0 +1,5 @@
+---
+"sideshow": minor
+---
+
+Add an `issue-tree` surface part. Agents hand over a `root` issue whose `children` are more issues of the same shape, and the viewer renders it natively as a tight rail/elbow tree with a progress rollup computed (`done ÷ total` over descendants) — never stored, so editing a leaf moves the bar. Each node is `{ ref, title, state, source?, note?, url?, children? }`; `state` is one of `open | in-progress | blocked | done | closed`, and `source` (github / linear / jira / gitlab / sentry / …) drives a source chip — so a tree can nest across providers (a Linear epic owning a GitHub sub-issue and a Sentry leaf). Available on all three tiers: an `issue-tree` part over MCP and `POST /api/surfaces`, plus the CLI (`sideshow issue-tree`, and `--issue-tree` on `sideshow publish`). Rendered from data, not sandboxed markup; the viewer themes it (light and dark) from chrome tokens, including a new `--ok` status green.

AGENTS.md

@@ -7,7 +7,7 @@ _use_ a running sideshow lives in `guide/AGENT_SETUP.md`, served at `/setup`.)
 ## What this is and why
 
 A live visual surface for terminal coding agents: agents publish surfaces
-(multi-part cards — html, markdown, diff, terminal, image, mermaid) over
+(multi-part cards — html, markdown, diff, terminal, image, mermaid, issue-tree) over
 CLI/MCP/HTTP; the user watches them render in a browser and comments back. The
 two-way loop — publish → live render → comment → revise/reply — is the product.
 When in doubt, optimize for the loop.
@@ -33,7 +33,7 @@ consciously, not as a side effect):
   (`/api/assets`, `/a/:id`), and the shared flow functions both REST and MCP call.
 - `server/types.ts` — data model + `Store` interface; no runtime imports. A
   surface is an ordered list of parts (`html` | `markdown` | `diff` | `terminal`
-  | `image` | `mermaid`); a snippet is sugar for a single html part.
+  | `image` | `mermaid` | `issue-tree`); a snippet is sugar for a single html part.
   `htmlPart` bridges the legacy snippet shape. Assets (uploaded blobs)
   are a separate entity, referenced by `image` parts; `selectEvictions`
   is the reference-aware LRU policy.
@@ -44,8 +44,8 @@ consciously, not as a side effect):
   and both migrate legacy `snippets`/`snippetId` data to surfaces on load.
 - `server/surfacePage.ts` — sandboxed document for one html part: CSP allowlist
   and the postMessage bridge (resize, sendPrompt, openLink). Only html parts
-  reach here — markdown, diff, terminal, image, and mermaid parts are data the
-  viewer renders natively, never markup in the sandbox.
+  reach here — markdown, diff, terminal, image, mermaid, and issue-tree parts are
+  data the viewer renders natively, never markup in the sandbox.
 - `server/themes.ts` — theme registry (github/gruvbox/one), runtime-agnostic so
   both server and viewer import it. One `Palette` per light/dark per theme; the
   viewer-chrome vars and the html-part `--color-*` tokens are both _derived_

README.md

@@ -114,6 +114,13 @@ viewer. A surface is an ordered list of **parts**; one card can carry several.
       <p><b>Parts compose.</b> One card can carry several — here a <code>markdown</code> rationale stacked above its <code>diff</code>, so a single surface holds the why and the what.</p>
     </td>
   </tr>
+  <tr>
+    <td width="50%" valign="top">
+      <img src="docs/surfaces/09-issue-tree.png" width="100%" alt="issue-tree part — nested sub-issues with a computed progress rollup">
+      <p><b><code>issue-tree</code></b> — a parent issue and its nested sub-issues, rendered as a rail tree with a rollup the viewer computes. Nests across providers — a Linear epic can own a GitHub sub-issue and a Sentry error.</p>
+    </td>
+    <td width="50%" valign="top"></td>
+  </tr>
 </table>
 
 ## Run it anywhere

bin/sideshow.js

@@ -24,6 +24,7 @@ usage:
       --mermaid <file|-> add a mermaid part (diagram source → SVG) — combine with html
       --diff <file|->   add a diff part from a unified/git patch (combine with html)
       --terminal <file|->  add a terminal part from monospace/ANSI output
+      --issue-tree <file|->  add an issue-tree part from a JSON root issue
       --image <file>    upload an image and append it as an image part
       --session <id>    target session (default: auto per agent session)
       --session-title <t>  name for a newly created session — name the task,
@@ -55,6 +56,10 @@ usage:
   sideshow mermaid <file|-> [options]     publish a mermaid surface (diagram → SVG)
       --title <t>       surface title
       (also: --session, --session-title, --agent, --new-session)
+  sideshow issue-tree <file|-> [options]  publish an issue-tree surface from JSON
+      --title <t>       surface title
+      (file is the root issue { ref, title, state, source?, note?, url?, children? })
+      (also: --session, --session-title, --agent, --new-session)
   sideshow update <id> <file|->           revise a surface (new version, same card)
       --title <t>       replace title
   sideshow wait [options]                 block until the user comments (long-poll)
@@ -294,6 +299,27 @@ function readContent(arg) {
   }
 }
 
+// Build an issue-tree part from JSON text. Accepts a full part ({ kind, root }),
+// a wrapper ({ root }), or a bare root issue ({ ref, title, state, … }) — the
+// server validates the shape, so this only normalizes the envelope.
+function issueTreePart(text) {
+  let data;
+  try {
+    data = JSON.parse(text);
+  } catch {
+    fail("issue-tree input must be JSON (a root issue, or { root } / { kind, root })");
+  }
+  if (data && typeof data === "object" && "root" in data) {
+    return { kind: "issue-tree", root: data.root };
+  }
+  // A part object that has a kind but no root ({kind:'issue-tree'}) is a mistake;
+  // don't silently wrap it as its own root (which yields a confusing field error).
+  if (data && typeof data === "object" && "kind" in data) {
+    fail("issue-tree input has a 'kind' but no 'root' — pass the root issue, or { root: {…} }");
+  }
+  return { kind: "issue-tree", root: data };
+}
+
 function out(value) {
   console.log(JSON.stringify(value, null, 2));
 }
@@ -666,6 +692,7 @@ const commands = {
         diff: { type: "string" },
         image: { type: "string" },
         terminal: { type: "string" },
+        "issue-tree": { type: "string" },
         layout: { type: "string" },
         session: { type: "string" },
         "session-title": { type: "string" },
@@ -690,6 +717,9 @@ const commands = {
     if (flags.terminal !== undefined) {
       parts.push({ kind: "terminal", text: readContent(flags.terminal || "-") });
     }
+    if (flags["issue-tree"] !== undefined) {
+      parts.push(issueTreePart(readContent(flags["issue-tree"] || "-")));
+    }
     // Resolve the session first so the image upload and the surface share it.
     const session = await resolveSession(flags, { create: true });
     if (flags.image !== undefined) {
@@ -848,6 +878,21 @@ const commands = {
     outSurface(await publishSurface(parts, flags));
   },
 
+  async "issue-tree"() {
+    const { values: flags, positionals } = parse({
+      allowPositionals: true,
+      options: {
+        title: { type: "string" },
+        session: { type: "string" },
+        "session-title": { type: "string" },
+        agent: { type: "string" },
+        "new-session": { type: "boolean" },
+      },
+    });
+    const parts = [issueTreePart(readContent(positionals[0]))];
+    outSurface(await publishSurface(parts, flags));
+  },
+
   async update() {
     const { values: flags, positionals } = parse({
       allowPositionals: true,

docs/surfaces/09-issue-tree.png

@@ -0,0 +1,114 @@
+import { expect, publishParts, test } from "./fixtures.ts";
+
+const ROOT = {
+  ref: "ENG-204",
+  title: "Normalize issue states across providers",
+  state: "in-progress",
+  source: "linear",
+  children: [
+    { ref: "octo/web #1432", title: "Dark mode regression", state: "done", source: "github" },
+    { ref: "ENG-219", title: "Map GitHub closed states", state: "done", source: "linear" },
+    {
+      ref: "SUP-881",
+      title: "SSO login fails for SAML customers",
+      state: "blocked",
+      source: "jira",
+      children: [
+        { ref: "JS-4F2", title: "TypeError reading 'theme'", state: "open", source: "sentry" },
+      ],
+    },
+    { ref: "infra/ci !57", title: "Bump CI runners", state: "in-progress", source: "gitlab" },
+  ],
+};
+
+test("an issue-tree part renders a native rail tree with a computed rollup", async ({
+  page,
+  server,
+}) => {
+  await publishParts(server.url, {
+    title: "Sub-issues",
+    agent: "e2e",
+    parts: [{ kind: "issue-tree", root: ROOT }],
+  });
+
+  await page.goto(server.url);
+  const card = page.locator(".card:not(#sessionThread)");
+  const tree = card.locator(".itree");
+
+  // rendered natively in the viewer document (no sandboxed iframe)
+  await expect(tree).toBeVisible();
+  await expect(card.locator("iframe")).toHaveCount(0);
+
+  // the epic header and a nested cross-provider leaf both made it in
+  await expect(tree.locator(".itree-epic-title")).toContainText("Normalize issue states");
+  await expect(tree).toContainText("ENG-204");
+  await expect(tree).toContainText("JS-4F2");
+
+  // rollup is computed from descendants (2 done of 5: #1432, ENG-219)
+  await expect(tree.locator(".itree-prog")).toContainText("2 / 5 done");
+  await expect(tree.locator(".itree-prog")).toContainText("40%");
+
+  // structural depth: the grandchild lives two subtrees deep, so a regression
+  // that flattened the tree into siblings would fail this (a visibility-only
+  // check would not).
+  await expect(
+    tree.locator(".itree-subtree .itree-subtree .itree-node", { hasText: "JS-4F2" }),
+  ).toBeVisible();
+});
+
+test("a javascript: url on a node is not rendered as an executable link", async ({
+  page,
+  server,
+}) => {
+  await publishParts(server.url, {
+    title: "Links",
+    agent: "e2e",
+    parts: [
+      {
+        kind: "issue-tree",
+        root: {
+          ref: "SAFE-1",
+          title: "Epic",
+          state: "open",
+          url: "https://example.com/epic",
+          children: [
+            {
+              ref: "EVIL-1",
+              title: "xss",
+              state: "open",
+              url: "javascript:alert(document.domain)",
+            },
+          ],
+        },
+      },
+    ],
+  });
+
+  await page.goto(server.url);
+  const tree = page.locator(".card:not(#sessionThread) .itree");
+  // the safe https ref is a real anchor
+  await expect(tree.locator('a.itree-ref[href="https://example.com/epic"]')).toBeVisible();
+  // the javascript: ref is dropped to plain text — no anchor carries it
+  await expect(tree.locator("a.itree-ref", { hasText: "EVIL-1" })).toHaveCount(0);
+  await expect(tree.locator("span.itree-ref", { hasText: "EVIL-1" })).toBeVisible();
+  // and no anchor anywhere has a javascript: href
+  await expect(tree.locator('a[href^="javascript:"]')).toHaveCount(0);
+});
+
+test("an issue-tree with no children renders the epic and an empty note", async ({
+  page,
+  server,
+}) => {
+  await publishParts(server.url, {
+    title: "Lonely",
+    agent: "e2e",
+    parts: [{ kind: "issue-tree", root: { ref: "ENG-1", title: "Just me", state: "open" } }],
+  });
+
+  await page.goto(server.url);
+  const tree = page.locator(".card:not(#sessionThread) .itree");
+  await expect(tree.locator(".itree-epic-title")).toContainText("Just me");
+  // no descendants → no rollup bar, and the empty-state note shows
+  await expect(tree.locator(".itree-prog")).toHaveCount(0);
+  await expect(tree.locator(".itree-empty")).toBeVisible();
+});

e2e/issueTree.spec.ts

@@ -47,12 +47,21 @@ a `kind`:
   bold, italic, underline); the viewer renders those and HTML-escapes the rest.
   Reach for it to share shell output, build logs, or example commands. (Colors
   yes; cursor-addressing TUIs are not resolved — share a captured frame.)
+- **`issue-tree`** — a parent issue and its nested sub-issues, rendered natively
+  as a rail tree with a computed progress rollup. Hand over a `root` issue whose
+  `children` are more issues of the same shape (it nests as deep as you like, and
+  across providers — a Linear epic can own a GitHub sub-issue). Each node is
+  `{ ref, title, state, source?, note?, url?, children? }`; `state` is one of
+  `open | in-progress | blocked | done | closed`, `source` (github / linear /
+  jira / gitlab / sentry / …) picks the chip. The rollup (`done ÷ total` over
+  descendants) is computed by the viewer — don't send it. Reach for it for
+  sub-issues, epics → stories, or any parent/child issue hierarchy.
 
 A surface can combine parts, e.g. `[html, diff]` is a diagram with its code
 review in one card, and `[markdown, diff]` is a written rationale above its
 changeset. Trust differs: html parts are sandboxed because you author the
-markup; markdown/mermaid/diff/image/trace/terminal parts are rendered by the
-viewer from data — send data, never markup.
+markup; markdown/mermaid/diff/image/trace/terminal/issue-tree parts are rendered
+by the viewer from data — send data, never markup.
 
 A **`SurfacePart`** is one of:
 
@@ -66,6 +75,8 @@ A **`SurfacePart`** is one of:
 { "kind": "trace", "steps": [{ "label": "...", "kind": "tool", "detail": "...", "ts": "..." }] }
 { "kind": "trace", "assetId": "<id of an uploaded JSON/JSONL trace>", "title": "..." }
 { "kind": "terminal", "text": "<output, may include ANSI SGR escapes>", "cols": 80, "title": "..." }
+{ "kind": "issue-tree", "root": { "ref": "ENG-204", "title": "...", "state": "in-progress", "source": "linear",
+    "children": [ { "ref": "#1432", "title": "...", "state": "done", "source": "github" } ] } }
 ```
 
 For a diff, send a `patch` — it carries only the changed lines, so it is the

guide/DESIGN_GUIDE.md

@@ -171,6 +171,11 @@ const cards = [
       { kind: "diff", patch: read("dlq.patch"), layout: "unified" },
     ],
   },
+  {
+    file: "issue-tree",
+    title: "issue-tree part — nested sub-issues with a computed rollup",
+    parts: [{ kind: "issue-tree", root: JSON.parse(read("issue-tree.json")) }],
+  },
 ];
 
 let session;

scripts/shoot-surfaces.mjs

@@ -0,0 +1,41 @@
+{
+  "ref": "ENG-204",
+  "title": "Normalize issue states across providers",
+  "state": "in-progress",
+  "source": "linear",
+  "children": [
+    {
+      "ref": "octo/web #1432",
+      "title": "Dark mode regression in the settings panel",
+      "state": "done",
+      "source": "github"
+    },
+    {
+      "ref": "ENG-219",
+      "title": "Map GitHub closed states → Done / Closed",
+      "state": "done",
+      "source": "linear"
+    },
+    {
+      "ref": "SUP-881",
+      "title": "SSO login fails for SAML customers",
+      "state": "blocked",
+      "source": "jira",
+      "children": [
+        {
+          "ref": "JS-4F2",
+          "title": "TypeError: undefined (reading 'theme')",
+          "state": "open",
+          "source": "sentry",
+          "note": "unresolved →"
+        }
+      ]
+    },
+    {
+      "ref": "infra/ci !57",
+      "title": "Bump CI runners to reduce queue time",
+      "state": "in-progress",
+      "source": "gitlab"
+    }
+  ]
+}

scripts/surface-examples/issue-tree.json

@@ -201,6 +201,15 @@ export function createApp({
   const app = new Hono();
   const bus = new EventBus();
 
+  // Last-resort safety net: any handler that throws (rather than returning a
+  // status) becomes a clean JSON 500 instead of leaking a stack or a bare crash.
+  // Validation rejects bad input with 4xx before this, so reaching here means an
+  // unexpected bug — log it so it isn't swallowed silently.
+  app.onError((err, c) => {
+    console.error("sideshow: unhandled error", err);
+    return c.json({ error: "internal error" }, 500);
+  });
+
   // Cached, fail-silent update lookup: being offline or rate-limited must
   // cost nothing but the absence of the notice. Failures are cached too, so
   // a dead network doesn't retry on every viewer load.