@telorun/debug-ui 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/debug-ui",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Browser-safe debug event UI for Telo: wire types, filtering, SSE client, and React components for watching a running app's event stream.",
   "keywords": [
     "telo",
@@ -46,7 +46,7 @@
     "@dagrejs/dagre": "^3.0.0",
     "@xyflow/react": "^12.10.2",
     "lucide-react": "^1.8.0",
-    "@telorun/debug-wire": "0.1.0"
+    "@telorun/debug-wire": "0.2.0"
   },
   "peerDependencies": {
     "react": ">=18",

package/src/components/EventGraph.tsx

@@ -114,12 +114,12 @@ function TraceFlowNode({ data }: NodeProps<Node<TraceNodeData>>) {
       <Handle type="target" position={Position.Left} className="tdbg-node-handle" />
       <div className="tdbg-node-head">
         {node.isRoot && <span className="tdbg-node-roottag">root</span>}
-        <span className="tdbg-node-name">{node.name}</span>
+        <span className="tdbg-node-name">{node.label ?? node.name}</span>
         <span className={badgeClass(last.outcome)}>
           {node.invocations.length > 1 ? `${node.invocations.length}×` : last.suffix}
         </span>
       </div>
-      <div className="tdbg-node-kind">{node.kind}</div>
+      <div className="tdbg-node-kind">{node.label ? `${node.kind} · ${node.name}` : node.kind}</div>
       <Handle type="source" position={Position.Right} className="tdbg-node-handle" />
     </div>
   );
@@ -420,6 +420,12 @@ function TraceNodeDetail({
               <span className="tdbg-muted">{inv.timestamp.slice(11, 23)}</span>
             </div>
             <InOut inv={inv} resolveUrl={resolveUrl} />
+            {inv.context !== undefined && (
+              <>
+                <div className="tdbg-graph-detail-label">Available context</div>
+                <PayloadInspector value={inv.context} resolveUrl={resolveUrl} />
+              </>
+            )}
           </div>
         ))}
       </div>

package/src/filter.ts

@@ -23,8 +23,12 @@ export function matchesFilter(event: DebugEvent, filter: EventFilter): boolean {
   if (suffixes.length > 0 && !suffixes.includes(eventSuffix(event.event))) {
     return false;
   }
-  if (filter.kind && !event.event.toLowerCase().includes(filter.kind.toLowerCase())) {
-    return false;
+  if (filter.kind) {
+    // Lifecycle events carry the kind in the dotted name; dispatch (trace) events
+    // carry it in `payload.ref.kind` (the name dropped the kind prefix). Match either.
+    const refKind = (event.payload as { ref?: { kind?: unknown } } | undefined)?.ref?.kind;
+    const haystack = `${event.event} ${typeof refKind === "string" ? refKind : ""}`.toLowerCase();
+    if (!haystack.includes(filter.kind.toLowerCase())) return false;
   }
   if (filter.text) {
     const needle = filter.text.toLowerCase();

package/src/graph.test.ts

@@ -12,6 +12,19 @@ const ev = (event: string, payload?: unknown): DebugFrame => ({
 const created = (kind: string, name: string, deps: { kind: string; name: string }[] = []) =>
   ev(`${kind}.${name}.Created`, { resource: { kind, name }, dependencies: deps });
 
+type Outcome = "ok" | "failed" | "rejected" | "cancelled";
+
+/** A terminal dispatch (trace) event: the name drops the kind, the payload carries
+ *  the structured trace contract `{ capability, phase, outcome, ref, … }`. */
+const disp = (
+  name: string,
+  kind: string,
+  outcome: Outcome,
+  suffix: string,
+  detail: Record<string, unknown> = {},
+): DebugFrame =>
+  ev(`${name}.${suffix}`, { capability: "invoke", phase: "end", outcome, ref: { kind, name }, ...detail });
+
 describe("deriveGraph", () => {
   it("creates a gray (created) node on Created", () => {
     const { nodes } = deriveGraph([created("Http.Server", "api")]);
@@ -52,7 +65,7 @@ describe("deriveGraph", () => {
   it("records an ok invocation with inputs and outputs", () => {
     const { nodes } = deriveGraph([
       created("Js.Script", "echo"),
-      ev("Js.Script.echo.Invoked", { inputs: { msg: "hi" }, outputs: { echoed: "hi" } }),
+      disp("echo", "Js.Script", "ok", "Invoked", { inputs: { msg: "hi" }, outputs: { echoed: "hi" } }),
     ]);
     expect(nodes[0].invokeCount).toBe(1);
     expect(nodes[0].lastInvoke).toMatchObject({
@@ -63,18 +76,27 @@ describe("deriveGraph", () => {
     });
   });
 
-  it("classifies failure, rejection and cancellation outcomes", () => {
+  it("skips a phase:start event (no outcome) — only terminal events count", () => {
+    const { nodes } = deriveGraph([
+      created("Js.Script", "echo"),
+      ev("echo.Invoking", { capability: "invoke", phase: "start", ref: { kind: "Js.Script", name: "echo" }, inputs: {} }),
+    ]);
+    expect(nodes[0].invokeCount).toBe(0);
+    expect(nodes[0].lastInvoke).toBeUndefined();
+  });
+
+  it("records failure, rejection and cancellation outcomes from the payload", () => {
     const base = created("Js.Script", "x");
     expect(
-      deriveGraph([base, ev("Js.Script.x.InvokeFailed", { inputs: {}, name: "Error", message: "boom" })])
+      deriveGraph([base, disp("x", "Js.Script", "failed", "InvokeFailed", { inputs: {}, name: "Error", message: "boom" })])
         .nodes[0].lastInvoke?.outcome,
     ).toBe("failed");
     expect(
-      deriveGraph([base, ev("Js.Script.x.InvokeRejected", { inputs: {}, code: "E", message: "no" })])
+      deriveGraph([base, disp("x", "Js.Script", "rejected", "InvokeRejected", { inputs: {}, code: "E", message: "no" })])
         .nodes[0].lastInvoke?.outcome,
     ).toBe("rejected");
     expect(
-      deriveGraph([base, ev("Js.Script.x.InvokeCancelled", { inputs: {}, reason: "stop" })])
+      deriveGraph([base, disp("x", "Js.Script", "cancelled", "InvokeCancelled", { inputs: {}, reason: "stop" })])
         .nodes[0].lastInvoke?.outcome,
     ).toBe("cancelled");
   });
@@ -82,29 +104,27 @@ describe("deriveGraph", () => {
   it("treats InvokeRejected.Undeclared as a rejection on the right node", () => {
     const { nodes } = deriveGraph([
       created("Js.Script", "x"),
-      ev("Js.Script.x.InvokeRejected.Undeclared", { inputs: {}, code: "E", message: "no" }),
+      disp("x", "Js.Script", "rejected", "InvokeRejected.Undeclared", { inputs: {}, code: "E", message: "no" }),
     ]);
-    expect(nodes[0].lastInvoke).toMatchObject({ outcome: "rejected", suffix: "InvokeRejected.Undeclared" });
+    expect(nodes[0].lastInvoke).toMatchObject({ outcome: "rejected", suffix: "Undeclared" });
   });
 
   it("counts repeated invocations and advances the activity index", () => {
     const { nodes } = deriveGraph([
       created("Js.Script", "x"),
-      ev("Js.Script.x.Invoked", { inputs: {}, outputs: 1 }),
-      ev("Js.Script.x.Invoked", { inputs: {}, outputs: 2 }),
+      disp("x", "Js.Script", "ok", "Invoked", { inputs: {}, outputs: 1 }),
+      disp("x", "Js.Script", "ok", "Invoked", { inputs: {}, outputs: 2 }),
     ]);
     expect(nodes[0].invokeCount).toBe(2);
     expect(nodes[0].lastInvoke?.outputs).toBe(2);
     expect(nodes[0].lastActivitySeq).toBeGreaterThan(0);
   });
 
-  it("attributes an invocation to the longest matching resource prefix", () => {
-    // `Http.Server.api` and `Http.Server.api.sub` share a prefix; the event must
-    // land on the deeper node, not the shorter one.
+  it("attributes an invocation to the resource named in the payload ref", () => {
     const { nodes } = deriveGraph([
       created("Http.Server", "api"),
       created("Http.Server.api", "sub"),
-      ev("Http.Server.api.sub.Invoked", { inputs: {}, outputs: "ok" }),
+      disp("sub", "Http.Server.api", "ok", "Invoked", { inputs: {}, outputs: "ok" }),
     ]);
     expect(nodes.find((n) => n.name === "sub")?.invokeCount).toBe(1);
     expect(nodes.find((n) => n.name === "api")?.invokeCount).toBe(0);
@@ -121,46 +141,54 @@ describe("deriveGraph", () => {
   });
 });
 
+/** A terminal dispatch event carrying trace ids — `spanId` / `parentSpanId`. */
 const inv = (
-  event: string,
-  invocationId: number,
-  parentInvocationId: number | undefined,
-  payload: unknown,
-): DebugFrame => ({
-  timestamp: `2026-01-01T00:00:00.${String(seq++).padStart(3, "0")}Z`,
-  event,
-  payload,
-  metadata: { invocationId, ...(parentInvocationId !== undefined ? { parentInvocationId } : {}) },
-});
+  name: string,
+  kind: string,
+  spanId: number,
+  parentSpanId: number | undefined,
+  outcome: Outcome,
+  suffix: string,
+  detail: Record<string, unknown> = {},
+): DebugFrame =>
+  ev(`${name}.${suffix}`, {
+    spanId,
+    parentSpanId,
+    capability: "invoke",
+    phase: "end",
+    outcome,
+    ref: { kind, name },
+    ...detail,
+  });
 
 describe("deriveInvocations", () => {
-  it("is empty when events carry no invocation metadata (tracing off)", () => {
-    const t = deriveInvocations([ev("Js.Script.x.Invoked", { outputs: 1 })]);
+  it("is empty when events carry no span ids (tracing off)", () => {
+    const t = deriveInvocations([disp("x", "Js.Script", "ok", "Invoked", { outputs: 1 })]);
     expect(t.roots).toHaveLength(0);
     expect(t.byId.size).toBe(0);
   });
 
   it("collects a root invocation with its resource, inputs and outputs", () => {
-    const t = deriveInvocations([inv("Http.Server.api.Invoked", 1, undefined, { inputs: { a: 1 }, outputs: "ok" })]);
+    const t = deriveInvocations([inv("api", "Http.Server", 1, undefined, "ok", "Invoked", { inputs: { a: 1 }, outputs: "ok" })]);
     expect(t.roots).toHaveLength(1);
     expect(t.roots[0]).toMatchObject({ id: 1, kind: "Http.Server", name: "api", outcome: "ok", inputs: { a: 1 }, outputs: "ok" });
   });
 
   it("links children to parents and keeps only roots at the top", () => {
     const t = deriveInvocations([
-      inv("A.root.Invoked", 1, undefined, { outputs: 1 }),
-      inv("B.child.Invoked", 2, 1, { outputs: 2 }),
-      inv("C.grand.Invoked", 3, 2, { outputs: 3 }),
+      inv("root", "A", 1, undefined, "ok", "Invoked", { outputs: 1 }),
+      inv("child", "B", 2, 1, "ok", "Invoked", { outputs: 2 }),
+      inv("grand", "C", 3, 2, "ok", "Invoked", { outputs: 3 }),
     ]);
     expect(t.roots.map((r) => r.id)).toEqual([1]);
     expect(t.childrenOf.get(1)).toEqual([2]);
     expect(t.childrenOf.get(2)).toEqual([3]);
   });
 
-  it("dedupes the InvokeRejected.Undeclared echo by id", () => {
+  it("dedupes the InvokeRejected.Undeclared echo by id, keeping the primary", () => {
     const t = deriveInvocations([
-      inv("A.x.InvokeRejected", 1, undefined, { code: "E" }),
-      inv("A.x.InvokeRejected.Undeclared", 1, undefined, { code: "E" }),
+      inv("x", "A", 1, undefined, "rejected", "InvokeRejected", { code: "E" }),
+      inv("x", "A", 1, undefined, "rejected", "InvokeRejected.Undeclared", { code: "E" }),
     ]);
     expect(t.byId.size).toBe(1);
     expect(t.byId.get(1)).toMatchObject({ outcome: "rejected", suffix: "InvokeRejected" });
@@ -170,9 +198,9 @@ describe("deriveInvocations", () => {
 describe("traceSubgraph", () => {
   it("returns only the participating resources wired by call edges", () => {
     const t = deriveInvocations([
-      inv("A.root.Invoked", 1, undefined, { outputs: 1 }),
-      inv("B.child.Invoked", 2, 1, { outputs: 2 }),
-      inv("C.other.Invoked", 9, undefined, { outputs: 9 }), // a different trace
+      inv("root", "A", 1, undefined, "ok", "Invoked", { outputs: 1 }),
+      inv("child", "B", 2, 1, "ok", "Invoked", { outputs: 2 }),
+      inv("other", "C", 9, undefined, "ok", "Invoked", { outputs: 9 }), // a different trace
     ]);
     const g = traceSubgraph(t, 1);
     expect(g.nodes.map((n) => n.id).sort()).toEqual(["A.root", "B.child"]);
@@ -182,9 +210,9 @@ describe("traceSubgraph", () => {
 
   it("collapses repeated calls to one node holding every invocation", () => {
     const t = deriveInvocations([
-      inv("A.root.Invoked", 1, undefined, { outputs: 1 }),
-      inv("B.svc.Invoked", 2, 1, { outputs: 2 }),
-      inv("B.svc.Invoked", 3, 1, { outputs: 3 }),
+      inv("root", "A", 1, undefined, "ok", "Invoked", { outputs: 1 }),
+      inv("svc", "B", 2, 1, "ok", "Invoked", { outputs: 2 }),
+      inv("svc", "B", 3, 1, "ok", "Invoked", { outputs: 3 }),
     ]);
     const g = traceSubgraph(t, 1);
     const svc = g.nodes.find((n) => n.id === "B.svc");

package/src/graph.ts

@@ -7,18 +7,19 @@ import { type DebugEvent, type DebugFrame, eventSuffix, isLogFrame } from "./wir
  * tracks each node's lifecycle status and most-recent invocation. The component
  * layer adds positions (dagre) and rendering.
  *
- * Three event families drive it, all named `<Kind>.<Name>.<Suffix>`:
- *  - `.Created`     → a node appears (status `created`); its payload carries the
- *                     resolved `{kind,name}` and the `dependencies` (the edges).
- *  - `.Initialized` → the node flips to `initialized`.
- *  - `.Teardown`    → the node flips to `torndown`.
- *  - invocation suffixes (`Invoked`, `InvokeFailed`, `InvokeRejected[.Undeclared]`,
- *    `InvokeCancelled`, `RunCancelled`) → record the call's outcome, inputs and
- *    outputs on the matching node.
+ * Two event families drive it:
+ *  - Lifecycle events `<Kind>.<Name>.{Created,Initialized,Teardown}` — a node
+ *    appears (its payload carries the resolved `{kind,name}` and `dependencies`),
+ *    then flips to `initialized` / `torndown`.
+ *  - Dispatch (trace) events — every capability call emits a structured payload
+ *    `{ spanId, parentSpanId, capability, phase, outcome, ref:{kind,name}, … }`.
+ *    The consumer reads the *payload*, never the dotted name: `ref` locates the
+ *    node, `outcome` records the result. Terminal events carry an `outcome`;
+ *    `phase:"start"` events carry none and are skipped here.
  *
- * When the producer has tracing on, invocation events also carry
- * `metadata.invocationId` / `metadata.parentInvocationId`; {@link deriveInvocations}
- * folds those into the call tree behind the invocation list + scoped trace graph.
+ * When the producer has tracing on, dispatch events also carry `spanId` /
+ * `parentSpanId`; {@link deriveInvocations} folds those into the call tree behind
+ * the invocation list + scoped trace graph.
  */
 
 export type NodeStatus = "created" | "initialized" | "torndown";
@@ -28,7 +29,7 @@ export type InvokeOutcome = "ok" | "failed" | "rejected" | "cancelled";
 /** The most recent invocation observed for a node. */
 export interface InvokeRecord {
   outcome: InvokeOutcome;
-  /** The suffix part after `<Kind>.<Name>.` (e.g. `Invoked`, `InvokeFailed`). */
+  /** The terminal event's suffix (`Invoked`, `InvokeFailed`, …) — for display only. */
   suffix: string;
   timestamp: string;
   /** The dispatched inputs (present on every invocation event the kernel emits). */
@@ -85,14 +86,34 @@ function asResource(payload: unknown): WireResourceRef | undefined {
   return undefined;
 }
 
-function classify(suffix: string): InvokeOutcome | undefined {
-  if (suffix === "Invoked") return "ok";
-  if (suffix.startsWith("InvokeFailed")) return "failed";
-  if (suffix.startsWith("InvokeRejected")) return "rejected";
-  if (suffix === "InvokeCancelled" || suffix === "RunCancelled") return "cancelled";
+/** The resolved `{kind,name}` a dispatch event's payload carries under `ref`. */
+function readRef(payload: Record<string, unknown> | undefined): { kind: string; name: string } | undefined {
+  const ref = payload?.ref;
+  if (ref && typeof ref === "object") {
+    const { kind, name } = ref as Record<string, unknown>;
+    if (typeof kind === "string" && typeof name === "string") return { kind, name };
+  }
   return undefined;
 }
 
+/** Narrow a payload `outcome` to a known {@link InvokeOutcome}. Absent on
+ *  `phase:"start"` events, so they are naturally skipped by callers. */
+function asOutcome(value: unknown): InvokeOutcome | undefined {
+  return value === "ok" || value === "failed" || value === "rejected" || value === "cancelled"
+    ? value
+    : undefined;
+}
+
+function num(value: unknown): number | undefined {
+  return typeof value === "number" ? value : undefined;
+}
+
+function asCapability(value: unknown): SpanCapability | undefined {
+  return value === "invoke" || value === "run" || value === "provide" || value === "request"
+    ? value
+    : undefined;
+}
+
 /**
  * Fold a frame buffer into the resource graph. Logs are ignored; events are
  * applied in arrival order so the returned status / `lastInvoke` reflect the
@@ -145,19 +166,19 @@ export function deriveGraph(frames: readonly DebugFrame[]): GraphState {
       return;
     }
 
-    // Invocation events share `parseInvocationEvent` with the trace fold — nodes
-    // are name-keyed, so the parsed resource name resolves the target directly.
-    const parsed = parseInvocationEvent(event.event);
-    const node = parsed ? nodes.get(parsed.name) : undefined;
-    if (!parsed || !node) return;
-    const outcome = classify(parsed.suffix);
-    if (!outcome) return;
+    // Dispatch (trace) events: the payload's `ref.name` resolves the target node
+    // directly (nodes are name-keyed). `phase:"start"` events carry no `outcome`
+    // and are skipped — only terminal events record a result.
+    const p = (event.payload ?? undefined) as Record<string, unknown> | undefined;
+    const ref = readRef(p);
+    const outcome = asOutcome(p?.outcome);
+    const node = ref ? nodes.get(ref.name) : undefined;
+    if (!node || !outcome) return;
     node.invokeCount += 1;
     node.lastActivitySeq = seq;
-    const p = (event.payload ?? undefined) as Record<string, unknown> | undefined;
     node.lastInvoke = {
       outcome,
-      suffix: parsed.suffix,
+      suffix: eventSuffix(event.event),
       timestamp: event.timestamp,
       inputs: p && "inputs" in p ? p.inputs : undefined,
       outputs: p && "outputs" in p ? p.outputs : undefined,
@@ -170,15 +191,28 @@ export function deriveGraph(frames: readonly DebugFrame[]): GraphState {
 
 // ── Invocation traces ──────────────────────────────────────────────────────
 
-/** One invocation — a single dispatched call, identified by its `invocationId`. */
+/** Which capability the span represents. `"request"` is an inbound-boundary span. */
+export type SpanCapability = "invoke" | "run" | "provide" | "request";
+
+/** One invocation — a single dispatched call, identified by its `spanId`. */
 export interface Invocation {
   id: number;
   parentId?: number;
+  /** Trace this span belongs to — present while tracing; groups the call tree. */
+  traceId?: string;
   kind: string;
   name: string;
+  capability?: SpanCapability;
   outcome: InvokeOutcome;
-  /** The event suffix (`Invoked`, `InvokeFailed`, …). */
+  /** The terminal event's suffix (`Invoked`, `InvokeFailed`, …) — for display only. */
   suffix: string;
+  /** Human label (e.g. a route `"POST /feedback"`), for `request` spans. */
+  label?: string;
+  /** Structured span attributes (e.g. `{ method, path }`). */
+  attributes?: Record<string, unknown>;
+  /** On a trace root: the redacted CEL root scope (variables / secrets / resources
+   *  / ports) the trace could reference. */
+  context?: Record<string, unknown>;
   timestamp: string;
   inputs?: unknown;
   outputs?: unknown;
@@ -195,39 +229,12 @@ export interface TraceState {
   roots: Invocation[];
 }
 
-/** Known invocation suffixes, longest first so `InvokeRejected.Undeclared` wins
- *  over `InvokeRejected`. */
-const INVOKE_SUFFIXES = [
-  "InvokeRejected.Undeclared",
-  "InvokeCancelled",
-  "InvokeRejected",
-  "InvokeFailed",
-  "Invoked",
-  "RunCancelled",
-] as const;
-
-/** Split a dotted invocation event into `{ kind, name, suffix }` by stripping a
- *  known trailing suffix — self-contained, no node registry needed. */
-function parseInvocationEvent(event: string): { kind: string; name: string; suffix: string } | undefined {
-  for (const suffix of INVOKE_SUFFIXES) {
-    if (event.endsWith(`.${suffix}`)) {
-      const head = event.slice(0, event.length - suffix.length - 1);
-      const dot = head.lastIndexOf(".");
-      if (dot <= 0) return undefined;
-      return { kind: head.slice(0, dot), name: head.slice(dot + 1), suffix };
-    }
-  }
-  return undefined;
-}
-
-function metaId(value: unknown): number | undefined {
-  return typeof value === "number" ? value : undefined;
-}
-
 /**
- * Fold the invocation events that carry `metadata.invocationId` into a call tree.
- * Each invocation appears once (the `.Undeclared` rejection echo is deduped by id,
- * keeping the primary event). Empty when the producer isn't tracing.
+ * Fold the dispatch events that carry a `spanId` into a call tree. Each
+ * invocation appears once — keyed by `spanId`, the first terminal event wins, so
+ * the `InvokeRejected.Undeclared` echo (same id, emitted after `InvokeRejected`)
+ * is deduped. `phase:"start"` events carry no `outcome` and are skipped. Empty
+ * when the producer isn't tracing (no `spanId`).
  */
 export function deriveInvocations(frames: readonly DebugFrame[]): TraceState {
   const byId = new Map<number, Invocation>();
@@ -237,22 +244,33 @@ export function deriveInvocations(frames: readonly DebugFrame[]): TraceState {
   for (const frame of frames) {
     if (isLogFrame(frame)) continue;
     const event = frame as DebugEvent;
-    const id = metaId((event.metadata as Record<string, unknown> | undefined)?.invocationId);
+    const p = (event.payload ?? undefined) as Record<string, unknown> | undefined;
+    const id = num(p?.spanId);
     if (id === undefined || byId.has(id)) continue;
-    const parsed = parseInvocationEvent(event.event);
-    if (!parsed) continue;
-    const outcome = classify(parsed.suffix);
+    const outcome = asOutcome(p?.outcome);
     if (!outcome) continue;
+    const ref = readRef(p);
+    if (!ref) continue;
 
-    const parentId = metaId((event.metadata as Record<string, unknown>).parentInvocationId);
-    const p = (event.payload ?? undefined) as Record<string, unknown> | undefined;
+    const parentId = num(p?.parentSpanId);
     const invocation: Invocation = {
       id,
       parentId,
-      kind: parsed.kind,
-      name: parsed.name,
+      traceId: typeof p?.traceId === "string" ? p.traceId : undefined,
+      kind: ref.kind,
+      name: ref.name,
+      capability: asCapability(p?.capability),
       outcome,
-      suffix: parsed.suffix,
+      suffix: eventSuffix(event.event),
+      label: typeof p?.label === "string" ? p.label : undefined,
+      attributes:
+        p?.attributes && typeof p.attributes === "object"
+          ? (p.attributes as Record<string, unknown>)
+          : undefined,
+      context:
+        p?.context && typeof p.context === "object"
+          ? (p.context as Record<string, unknown>)
+          : undefined,
       timestamp: event.timestamp,
       inputs: p && "inputs" in p ? p.inputs : undefined,
       outputs: p && "outputs" in p ? p.outputs : undefined,
@@ -278,6 +296,8 @@ export interface TraceNode {
   id: string;
   kind: string;
   name: string;
+  /** Human label from the span (e.g. a route `"POST /feedback"`), if any. */
+  label?: string;
   isRoot: boolean;
   invocations: Invocation[];
 }
@@ -313,7 +333,15 @@ export function traceSubgraph(trace: TraceState, rootId: number): TraceSubgraph
     const key = resourceKey(inv);
     const node = nodes.get(key);
     if (node) node.invocations.push(inv);
-    else nodes.set(key, { id: key, kind: inv.kind, name: inv.name, isRoot: id === rootId, invocations: [inv] });
+    else
+      nodes.set(key, {
+        id: key,
+        kind: inv.kind,
+        name: inv.name,
+        label: inv.label,
+        isRoot: id === rootId,
+        invocations: [inv],
+      });
 
     for (const childId of trace.childrenOf.get(id) ?? []) {
       const child = trace.byId.get(childId);