@principal-ai/subsystems-react 0.55.3 → 0.56.1

package/src/subsystem/model.test.ts

@@ -98,7 +98,7 @@ describe('subsystem graph model', () => {
     const withExternal: SubsystemComponent[] = [
       ...comps,
       {
-        alias: "proposed-watcher",
+        alias: "external-watcher",
         name: "watchDir",
         construct: "external",
         // Intentionally omit file/purl — agents often leave these off for externals.
@@ -111,10 +111,10 @@ describe('subsystem graph model', () => {
       trails: [{
         id: 'w1',
         title: 'feed',
-        steps: [{ from: 'reader', to: 'proposed-watcher', mechanism: 'feeds', file: 'x.ts' }],
+        steps: [{ from: 'reader', to: 'external-watcher', mechanism: 'feeds', file: 'x.ts' }],
       }],
     });
-    expect(nodes.find((n) => n.id === 'proposed-watcher')).toBeDefined();
+    expect(nodes.find((n) => n.id === 'external-watcher')).toBeDefined();
   });
 
   test('buildSubsystemGraph creates external stub nodes for non-component targets', async () => {
@@ -223,33 +223,18 @@ describe('subsystem graph model', () => {
     });
     expect(withRole).toBeGreaterThan(stereotype);
 
-    const withProposed = nodeMinWidthForBadges({
-      construct: 'function',
-      proposed: true,
-    });
-    expect(withProposed).toBeGreaterThan(plain);
-
-    const withBoth = nodeMinWidthForBadges({
-      construct: 'function',
-      role: 'entry',
-      proposed: true,
-    });
-    // proposed-only label is shorter than entry · proposed; still wider than plain
-    expect(withBoth).toBe(withProposed);
-
     // The pair floor must leave a real gap between the left and right badge,
     // over and above both insets — regression: the node border was omitted from
     // the floor, and the char width was underestimated, so the two badges met.
     const left = estimateBadgeLabelWidth(constructBadgeLabel({ construct: 'function' }));
-    const right = estimateBadgeLabelWidth(rightBadgeLabel({ proposed: true })!);
-    expect(withBoth).toBeGreaterThan(left + right + 2 * BADGE_EDGE_INSET);
+    const right = estimateBadgeLabelWidth(rightBadgeLabel({ role: 'entry' })!);
+    expect(withRole).toBeGreaterThan(left + right + 2 * BADGE_EDGE_INSET);
   });
 
-  test('rightBadgeLabel prefers proposed over role', () => {
+  test('rightBadgeLabel reports the role', () => {
     expect(rightBadgeLabel({})).toBeNull();
-    expect(rightBadgeLabel({ proposed: true })).toBe('proposed');
     expect(rightBadgeLabel({ role: 'entry' })).toBe('entry');
-    expect(rightBadgeLabel({ role: 'service', proposed: true })).toBe('proposed');
+    expect(rightBadgeLabel({ role: 'service' })).toBe('service');
   });
 
   test('deriveNameFromSymbol falls back to existing name when no symbol', () => {

package/src/subsystem/model.ts

@@ -101,6 +101,8 @@ export type {
   SubsystemModelDocument,
   SubsystemTrail,
   SubsystemTrailStep,
+  SubsystemSiteConstruct,
+  SubsystemTargetConstruct,
   SubsystemComponentRole,
   SubsystemFramework,
   SubsystemStereotype,
@@ -1156,7 +1158,7 @@ export type SubsystemIssueRung =
   | 'signature';
 
 /**
- * Per-node diagnostics badge — the proposed issue overlay (severity ring +
+ * Per-node diagnostics badge — the issue overlay (severity ring +
  * earliest-rung corner chip). The graph derives one per component from the
  * audit issues whose component target resolves to that node. Absent when the
  * node has no rung-mapped findings.
@@ -1226,12 +1228,6 @@ export interface SubsystemGraphEdgeData extends Record<string, unknown> {
   /** True while another edge is selected — render this edge (and its label)
    *  dimmed to focus the selected relationship. */
   dimmed?: boolean;
-  /**
-   * A backing trail step declares itself `proposed` — a planned seam between
-   * otherwise-real components. The SVG edge and its label draw dashed;
-   * distinct from a proposed ENDPOINT, which dashes the node instead.
-   */
-  proposedStep?: boolean;
   /** ELK-computed label midpoint (from the actual edge path, not node centers). */
   labelX?: number;
   labelY?: number;
@@ -1522,9 +1518,6 @@ export const ROLE_LABEL: Record<SubsystemComponentRole, string> = {
   service: 'service',
 };
 
-/** Right-badge accent for `proposed: true` (no role, or combined with role). */
-export const PROPOSED_COLOR = '#b8860b'; // darkgoldenrod — not-yet-in-source
-
 /**
  * Border accent for `deprecated: true` — the claim was real, its source is gone.
  * A desaturated slate rather than true silver: role badges already own silver
@@ -1545,25 +1538,19 @@ export function deprecatedBadgeColor(component: {
 }
 
 /**
- * Top-right badge label: proposed wins over role when both are set
- * (proposed is the temporary exception to scan for; role stays on the model).
- * Returns null when neither applies.
+ * Top-right badge label: the role, when set. Returns null otherwise.
  */
 export function rightBadgeLabel(component: {
   role?: SubsystemComponentRole;
-  proposed?: boolean;
 }): string | null {
-  if (component.proposed) return 'proposed';
   if (component.role != null) return ROLE_LABEL[component.role];
   return null;
 }
 
-/** Color for the top-right badge (role and/or proposed). */
+/** Color for the top-right role badge. */
 export function rightBadgeColor(component: {
   role?: SubsystemComponentRole;
-  proposed?: boolean;
 }): string | null {
-  if (component.proposed) return PROPOSED_COLOR;
   if (component.role != null) return ROLE_COLOR[component.role];
   return null;
 }
@@ -1593,7 +1580,7 @@ function storeStorage(component: {
 
 /** Top-right storage badge for `construct: 'store'` nodes with an authored
  *  `storage` declaration — how the retained state is backed. Sits beside the
- *  role/proposed badge (storage is orthogonal to topology). Null otherwise. */
+ *  role badge (storage is orthogonal to topology). Null otherwise. */
 export function storageBadgeLabel(component: {
   construct: SubsystemComponentConstruct;
   declaration?: AnyComponentDetail;
@@ -1688,7 +1675,6 @@ export function nodeMinWidthForBadges(component: {
   framework?: string;
   stereotype?: string;
   role?: SubsystemComponentRole;
-  proposed?: boolean;
   deprecated?: boolean;
   entityKind?: string;
   declaration?: AnyComponentDetail;

package/src/subsystem/nodes.tsx

@@ -20,7 +20,6 @@ import {
   edgeColor,
   edgeStrokeStyle,
   DEPRECATED_COLOR,
-  PROPOSED_COLOR,
   deprecatedBadgeColor,
   deprecatedBadgeLabel,
   constructBadgeColor,
@@ -221,7 +220,7 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
   // `symbol` is the source of truth; `name` is derived from it consistently.
   const displayName = deriveNameFromSymbol(c.symbol, c.construct, c.name, c.file, c.stereotype);
   // Top badges are absolutely positioned — widen the node so they nowrap
-  // instead of wrapping, including when construct + role/proposed share the top.
+  // instead of wrapping, including when construct + role share the top.
   const badgeMinWidth = nodeMinWidthForBadges(c);
   const topRightLabel = rightBadgeLabel(c);
   const topRightColor = rightBadgeColor(c);
@@ -243,17 +242,14 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
   const nodeBg = theme.colors.backgroundSecondary ?? theme.colors.background;
   const hoverBg =
     theme.colors.backgroundHover ?? theme.colors.backgroundTertiary ?? nodeBg;
-  // Border: proposed uses the goldenrod accent (dashed), deprecated the slate
-  // accent (dotted, same family as issue) since both mean "not a live claim";
-  // construct color stays on the left badge. File-open spotlight still wins
-  // with primary.
+  // Border: deprecated uses the slate accent (dotted, same family as issue)
+  // since it means "not a live claim"; construct color stays on the left
+  // badge. File-open spotlight still wins with primary.
   const borderColor = fileMatch
     ? theme.colors.primary
-    : c.proposed
-      ? PROPOSED_COLOR
-      : c.deprecated
-        ? DEPRECATED_COLOR
-        : color;
+    : c.deprecated
+      ? DEPRECATED_COLOR
+      : color;
   // Selection is stamped into data by the graph component — React Flow's own
   // `selected` never updates because the node stops click propagation.
   const isSelected = selected || (data.isSelected as boolean | undefined) === true;
@@ -269,21 +265,19 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
   const borderW = isSelected || fileMatch ? 4 : 2;
   const badgeTop = -9 - borderW;
   const badgeEdge = -borderW;
-  // A node with diagnostics turns its border dotted — a "something's off"
-  // sibling of `proposed`'s dashed, but distinct so the two don't read alike.
-  // The border keeps its construct color; the severity rides on the chip.
-  // Verification skips `proposed` nodes, so the two rarely stack — issue wins.
+  // A node with diagnostics turns its border dotted — an "something's off"
+  // signal. The border keeps its construct color; the severity rides on the
+  // chip. Deprecated is also dotted, but slate rather than construct-colored:
+  // "this claim was retired" is closer to a diagnostic than to a placeholder.
   const hasIssue = data.issue != null;
   // Deprecated is dotted like issue but slate rather than construct-colored:
   // "this claim was retired" is closer to a diagnostic than to a placeholder,
   // and verification skips deprecated nodes so the two never stack in practice.
   const borderStyle = hasIssue
     ? 'dotted'
-    : c.proposed
-      ? 'dashed'
-      : c.deprecated
-        ? 'dotted'
-        : 'solid';
+    : c.deprecated
+      ? 'dotted'
+      : 'solid';
 
   return (
     <div
@@ -352,9 +346,9 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
         {constructBadgeLabel(c)}
       </div>
 
-      {/* Secondary badge cluster — proposed wins over role when both are set;
-          store storage (retention backing) sits beside, since it is
-          orthogonal to topology. Persistent; pointer-events pass through.
+      {/* Secondary badge cluster — the role badge, with store storage
+          (retention backing) beside it since it is orthogonal to topology.
+          Persistent; pointer-events pass through.
           Sits astride the bottom edge, centered (mirroring the top construct
           badge's straddle), so the top edge stays free for the construct tag. */}
       {(topRightLabel != null || storageLabel != null || deprecatedLabel != null) && (
@@ -869,11 +863,8 @@ export function SubsystemEdge({
   const edgeRef = { mechanism, provenance: data?.provenance };
   const color = edgeColor(edgeRef);
   // Dash style encodes provenance (graphify) and relationship kind (dashed =
-  // inverted-control or observational: hierarchy, registration, watches). A
-  // step-proposed edge also dashes — the seam itself is planned — matching
-  // the dashed edge label and a proposed node's dashed border.
-  const isDashed =
-    edgeStrokeStyle(edgeRef) === 'dashed' || data?.proposedStep === true;
+  // inverted-control or observational: hierarchy, registration, watches).
+  const isDashed = edgeStrokeStyle(edgeRef) === 'dashed';
   const dimmed = data?.dimmed === true;
   // Dim the stroke by color, never via path `opacity`. SVG markers are shared
   // by id; opacity on the referencing path paints every arrowhead that uses

package/src/subsystem/stepEmphasis.ts

@@ -0,0 +1,151 @@
+/**
+ * Step emphasis — PROTOTYPE contract for the "guiding focus" augmentation.
+ *
+ * A step emphasis is an authored pointer at a walkthrough step: "look here
+ * first", with optional markdown guidance explaining why. It is deliberately
+ * **not** part of the portable subsystem model and **not** a verification
+ * signal — it belongs in a separate, host-owned augmentation document:
+ *
+ *   `~/.principal/subsystem-model-augmentations/<model-identity>.json`
+ *
+ * The key question this prototype is here to answer is identity: a step has no
+ * id today and steps move. `stepClaimKey` fingerprints the step's *claim*
+ * (`from`/`to`/`mechanism`/site/symbol/span), so a mark survives a reorder but
+ * stops resolving when the claim itself is edited. Orphaned records are kept
+ * (and can be pruned deliberately) rather than silently dropped.
+ *
+ * The mark is a single star rather than a closed kind vocabulary. `guidance`
+ * is markdown so a mark can carry the same kind of prose as a model
+ * description — headings, emphasis, links, code — while staying a string.
+ *
+ * Nothing here is wired to disk yet. The story `Canvases/Subsystem/Step
+ * Emphasis` exercises the shape with an in-memory store and a live JSON view.
+ */
+
+import type { SubsystemTrail, SubsystemTrailStep } from './model';
+
+export interface StepEmphasisProvenance {
+  /** Who authored the mark. Agent marks are expected too. */
+  source: 'author' | 'agent';
+  /** ISO timestamp. */
+  at: string;
+  /** Optional human/agent identity. */
+  author?: string;
+}
+
+/** One mark in the separate augmentation document. */
+export interface StepEmphasisRecord {
+  /** The trail the step belongs to. */
+  trailId: string;
+  /**
+   * Fingerprint of the step's claim (see `stepClaimKey`). Stable across
+   * reorder; changes when the claim changes.
+   */
+  stepKey: string;
+  /** Optional markdown "why look here", rendered like a model description. */
+  guidance?: string;
+  provenance: StepEmphasisProvenance;
+}
+
+/**
+ * The whole separate document. `modelId` is the host-store id (or an identity
+ * key) — this document is host-local and never rides on the portable model.
+ */
+export interface StepEmphasisDocument {
+  version: 1;
+  modelId: string;
+  emphasis: StepEmphasisRecord[];
+}
+
+/**
+ * Lookup key for the UI. `trailId:stepKey` — one flat map is enough for a
+ * graph and keeps the panel from re-deriving a nested structure per render.
+ */
+export type StepEmphasisMap = ReadonlyMap<string, StepEmphasisRecord>;
+
+/** The claim fields a mark is attached to. Deliberately excludes `annotation`. */
+function claimFields(step: Pick<SubsystemTrailStep, 'from' | 'to' | 'mechanism' | 'file' | 'symbol' | 'span'>): string[] {
+  return [
+    step.from,
+    step.to,
+    step.mechanism,
+    step.file,
+    step.symbol,
+    step.span?.startLine == null ? '' : String(step.span.startLine),
+    step.span?.endLine == null ? '' : String(step.span.endLine),
+    step.span?.contentHash ?? '',
+  ];
+}
+
+/**
+ * FNV-1a (32-bit) fingerprint. Good enough for a local key: the point is
+ * "same claim => same key", not cryptographic resistance. Swap for SHA-256 at
+ * the store boundary if marks ever travel between hosts.
+ */
+function fnv1a(value: string): string {
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < value.length; i++) {
+    hash ^= value.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return (hash >>> 0).toString(16).padStart(8, '0');
+}
+
+/** Stable content key for a step's claim. */
+export function stepClaimKey(
+  step: Pick<SubsystemTrailStep, 'from' | 'to' | 'mechanism' | 'file' | 'symbol' | 'span'>,
+): string {
+  return fnv1a(claimFields(step).join('\u001f'));
+}
+
+/** Map key for one step's mark. */
+export function emphasisKey(
+  trailId: string,
+  step: Pick<SubsystemTrailStep, 'from' | 'to' | 'mechanism' | 'file' | 'symbol' | 'span'>,
+): string {
+  return `${trailId}:${stepClaimKey(step)}`;
+}
+
+export function buildStepEmphasisMap(
+  records: readonly StepEmphasisRecord[],
+): StepEmphasisMap {
+  return new Map(records.map((r) => [`${r.trailId}:${r.stepKey}`, r]));
+}
+
+export function findStepEmphasis(
+  map: StepEmphasisMap | undefined,
+  trailId: string,
+  step: SubsystemTrailStep,
+): StepEmphasisRecord | undefined {
+  return map?.get(emphasisKey(trailId, step));
+}
+
+/**
+ * Records whose step claim no longer exists in the current trails. Kept in the
+ * document (so a bad edit does not destroy authored intent) but surfaced so
+ * the author can prune them.
+ */
+export function orphanedEmphasis(
+  records: readonly StepEmphasisRecord[],
+  trails: readonly SubsystemTrail[],
+): StepEmphasisRecord[] {
+  const live = new Set<string>();
+  for (const trail of trails) {
+    for (const step of trail.steps) live.add(emphasisKey(trail.id, step));
+  }
+  return records.filter((r) => !live.has(`${r.trailId}:${r.stepKey}`));
+}
+
+/** Records for one trail, in current step order (for reader surfaces). */
+export function emphasisForTrail(
+  map: StepEmphasisMap | undefined,
+  trail: SubsystemTrail,
+): Array<{ stepIndex: number; step: SubsystemTrailStep; record: StepEmphasisRecord }> {
+  if (!map) return [];
+  const rows: Array<{ stepIndex: number; step: SubsystemTrailStep; record: StepEmphasisRecord }> = [];
+  trail.steps.forEach((step, stepIndex) => {
+    const record = map.get(emphasisKey(trail.id, step));
+    if (record) rows.push({ stepIndex, step, record });
+  });
+  return rows;
+}

package/src/subsystem/trailBrief.test.ts

@@ -38,6 +38,11 @@ describe('buildStepBrief', () => {
     expect(brief).toContain('- symbol: `Login.submit`');
     expect(brief).toContain('- site: `src/ui/login.tsx:42`');
     expect(brief).toContain('- purl: `pkg:github/acme/app`');
+    expect(brief).not.toContain('- site role:');
+  });
+
+  test('marks a non-call site as via evidence', () => {
+    expect(buildStepBrief(trail, 1)).toContain('- site role: `via`');
   });
 
   test('omits the note when the step has no annotation', () => {
@@ -50,6 +55,30 @@ describe('buildStepBrief', () => {
     expect(brief).toContain('- note: session row is written here');
   });
 
+  test('includes resolved site and target constructs when present', () => {
+    const resolved: SubsystemTrail = {
+      ...trail,
+      steps: [
+        {
+          ...trail.steps[0]!,
+          site: {
+            symbol: 'Login.submit',
+            span: { startLine: 30, endLine: 60, contentHash: 'h' },
+          },
+          target: {
+            purl: 'pkg:github/acme/app#src/api/session.ts',
+            file: 'src/api/session.ts',
+            symbol: 'Session.create',
+            span: { startLine: 7, endLine: 7, contentHash: 'h' },
+          },
+        },
+      ],
+    };
+    const brief = buildStepBrief(resolved, 0);
+    expect(brief).toContain('- site construct: `Login.submit` (src/ui/login.tsx:30-60)');
+    expect(brief).toContain('- target: `Session.create` (src/api/session.ts:7)');
+  });
+
   test('returns an empty string for an out-of-range index', () => {
     expect(buildStepBrief(trail, 9)).toBe('');
     expect(buildStepBrief(trail, -1)).toBe('');

package/src/subsystem/trailBrief.ts

@@ -31,12 +31,32 @@ export function buildStepBrief(
   lines.push(`- to: \`${step.to}\``);
   lines.push(`- mechanism: \`${step.mechanism}\``);
   lines.push(`- symbol: \`${step.symbol}\``);
+  // `calls` means the site is the caller frame. Every other mechanism is a
+  // logical hop whose evidence can live in another construct; say so, so an
+  // agent does not treat the site symbol as the source component.
+  if (step.mechanism !== 'calls') {
+    lines.push(`- site role: \`via\``);
+  }
   const site = step.span
     ? step.span.startLine === step.span.endLine
       ? `${step.file}:${step.span.startLine}`
       : `${step.file}:${step.span.startLine}-${step.span.endLine}`
     : step.file;
   lines.push(`- site: \`${site}\``);
+  if (step.site) {
+    const frame = step.site.span.startLine === step.site.span.endLine
+      ? `${step.file}:${step.site.span.startLine}`
+      : `${step.file}:${step.site.span.startLine}-${step.site.span.endLine}`;
+    lines.push(`- site construct: \`${step.site.symbol}\` (${frame})`);
+  }
+  if (step.target) {
+    const targetSpan = step.target.span
+      ? step.target.span.startLine === step.target.span.endLine
+        ? `:${step.target.span.startLine}`
+        : `:${step.target.span.startLine}-${step.target.span.endLine}`
+      : '';
+    lines.push(`- target: \`${step.target.symbol}\` (${step.target.file}${targetSpan})`);
+  }
   lines.push(`- purl: \`${step.purl}\``);
   if (step.annotation != null && step.annotation.length > 0) {
     lines.push(`- note: ${step.annotation}`);

package/src/subsystem/trailStack.test.ts

@@ -0,0 +1,133 @@
+import { describe, expect, test } from 'bun:test';
+import type { SubsystemTrail } from './model';
+import { buildTrailStack } from './trailStack';
+
+const trail: SubsystemTrail = {
+  id: 'stack',
+  title: 'Stack',
+  steps: [
+    {
+      from: 'panel',
+      to: 'rpc',
+      mechanism: 'calls',
+      file: 'src/panel.ts',
+      purl: 'pkg:github/acme/app#src/panel.ts',
+      symbol: 'MaintenancePanel',
+      target: {
+        purl: 'pkg:github/acme/app#src/rpc.ts',
+        file: 'src/rpc.ts',
+        symbol: 'getRpc',
+      },
+    },
+    {
+      from: 'rpc',
+      to: 'detail',
+      mechanism: 'calls',
+      file: 'src/rpc.ts',
+      purl: 'pkg:github/acme/app#src/rpc.ts',
+      symbol: 'getRpc',
+      target: {
+        purl: 'pkg:github/acme/app#src/detail.ts',
+        file: 'src/detail.ts',
+        symbol: 'modelDetail',
+      },
+    },
+    {
+      from: 'detail',
+      to: 'touches',
+      mechanism: 'calls',
+      file: 'src/detail.ts',
+      purl: 'pkg:github/acme/app#src/detail.ts',
+      symbol: 'modelDetail',
+      target: {
+        purl: 'pkg:github/acme/app#src/touches.ts',
+        file: 'src/touches.ts',
+        symbol: 'commitTouches',
+      },
+    },
+    {
+      from: 'detail',
+      to: 'remote',
+      mechanism: 'calls',
+      file: 'src/detail.ts',
+      purl: 'pkg:github/acme/app#src/detail.ts',
+      symbol: 'modelDetail',
+      target: {
+        purl: 'pkg:github/acme/app#src/remote.ts',
+        file: 'src/remote.ts',
+        symbol: 'remoteRefSha',
+      },
+    },
+    {
+      from: 'panel',
+      to: 'merge',
+      mechanism: 'uses',
+      file: 'src/list.tsx',
+      purl: 'pkg:github/acme/app#src/list.tsx',
+      symbol: 'ModelList',
+    },
+    {
+      from: 'merge',
+      to: 'dots',
+      mechanism: 'feeds',
+      file: 'src/dots.tsx',
+      purl: 'pkg:github/acme/app#src/dots.tsx',
+      symbol: 'CommitDots',
+    },
+  ],
+};
+
+describe('buildTrailStack', () => {
+  test('builds the caller chain for a nested call', () => {
+    const stack = buildTrailStack(trail, 2);
+    expect(stack.isCall).toBe(true);
+    expect(stack.frames.map((f) => f.label)).toEqual([
+      'MaintenancePanel',
+      'getRpc',
+      'modelDetail',
+    ]);
+    expect(stack.frames.map((f) => f.current)).toEqual([false, false, true]);
+    expect(stack.callee).toBe('commitTouches');
+  });
+
+  test('a sibling call links to the shared parent, not the previous sibling', () => {
+    const stack = buildTrailStack(trail, 3);
+    expect(stack.frames.map((f) => f.stepIndex)).toEqual([0, 1, 3]);
+    expect(stack.frames.map((f) => f.label)).toEqual([
+      'MaintenancePanel',
+      'getRpc',
+      'modelDetail',
+    ]);
+    expect(stack.callee).toBe('remoteRefSha');
+  });
+
+  test('uses is an annotation on the frame it belongs to, not a frame', () => {
+    const stack = buildTrailStack(trail, 4);
+    expect(stack.isCall).toBe(false);
+    expect(stack.frames.map((f) => f.label)).toEqual(['MaintenancePanel']);
+    expect(stack.annotations).toEqual([
+      { stepIndex: 4, mechanism: 'uses', label: 'uses merge', selected: true },
+    ]);
+  });
+
+  test('a root call still shows its caller frame and callee', () => {
+    const stack = buildTrailStack(trail, 0);
+    expect(stack.frames.map((f) => f.label)).toEqual(['MaintenancePanel']);
+    expect(stack.callee).toBe('getRpc');
+  });
+
+  test('a non-call step with no call context falls back to its source frame', () => {
+    const stack = buildTrailStack(trail, 5);
+    expect(stack.isCall).toBe(false);
+    expect(stack.frames.map((f) => f.label)).toEqual(['CommitDots']);
+    expect(stack.annotations[0]?.label).toBe('feeds dots');
+  });
+
+  test('out-of-range returns an empty view', () => {
+    expect(buildTrailStack(trail, 99)).toEqual({
+      frames: [],
+      annotations: [],
+      isCall: false,
+    });
+  });
+});