@principal-ai/subsystems-react 0.56.3 → 0.56.5

package/src/subsystem/TrailStepsNav.test.tsx

@@ -149,12 +149,44 @@ describe('TrailStepsNav', () => {
     expect(getByText('A.go')).toBeTruthy();
     expect(getByText('B.go')).toBeTruthy();
     expect(getByText('Read the source seam.')).toBeTruthy();
+    const accent = document.createElement('span');
+    accent.style.color = defaultEditorTheme.colors.primary;
+    const normal = document.createElement('span');
+    normal.style.color = defaultEditorTheme.colors.text;
+    expect(getByText('A.go').style.color).toBe(normal.style.color);
+    expect(getByText('B.go').style.color).toBe(normal.style.color);
+    expect(getByText('Read the source seam.').style.color).toBe(accent.style.color);
+    expect(getByRole('button', { name: /A\.go/ }).style.paddingLeft).toBe('12px');
+    expect(getByRole('button', { name: /B\.go/ }).style.paddingLeft).toBe('22px');
     fireEvent.click(getByRole('button', { name: /B\.go/ }));
     expect(focusedStep).toBe(1);
     fireEvent.click(getByLabelText('Back to trails'));
     expect(cleared).toBe(true);
   });
 
+  test('returns sibling calls to their parent indentation level', () => {
+    const trail: SubsystemTrail = {
+      id: 'nested',
+      title: 'Nested calls',
+      steps: [step('a', 'b', 'A.go'), step('b', 'c', 'B.go'), step('a', 'd', 'A.next')],
+    };
+    const { getByRole } = renderNav({
+      trails: [trail],
+      focusedTrailId: trail.id,
+      focusedStepIndex: null,
+      hoveredTrailStep: null,
+      onFocusFlow: () => {},
+      onClearFocus: () => {},
+      onFocusStep: () => {},
+      onHoverStep: () => {},
+      onHoverFlow: () => {},
+      onLeaveStep: () => {},
+    });
+    expect(getByRole('button', { name: /A\.go/ }).style.paddingLeft).toBe('12px');
+    expect(getByRole('button', { name: /B\.go/ }).style.paddingLeft).toBe('22px');
+    expect(getByRole('button', { name: /A\.next/ }).style.paddingLeft).toBe('12px');
+  });
+
   test('uses rows show the logical hop and the via site', () => {
     const usesTrail: SubsystemTrail = {
       id: 'uses',

package/src/subsystem/TrailStepsNav.tsx

@@ -7,6 +7,7 @@ import {
   trailStepDisplay,
   type TrailComponentLabels,
 } from './trailStepDisplay';
+import { buildTrailStack } from './trailStack';
 
 /**
  * TrailStepsNav — the trails side panel as a two-step slide: a list of trails,
@@ -288,6 +289,7 @@ export function TrailStepsNav({
                   hoveredTrailStep?.trailId === displayedTrail.id &&
                   hoveredTrailStep.stepIndex === i;
                 const display = trailStepDisplay(step, componentByAlias);
+                const stackDepth = buildTrailStack(displayedTrail, i, componentByAlias).frames.length;
                 return (
                   <button
                     key={`${step.from}->${step.to}-${i}`}
@@ -300,7 +302,7 @@ export function TrailStepsNav({
                       gap: 8,
                       width: '100%',
                       minWidth: 0,
-                      padding: '8px 16px 8px 12px',
+                      padding: `8px 16px 8px ${12 + Math.max(0, stackDepth - 1) * 10}px`,
                       border: 'none',
                       borderRadius: 0,
                       background: active || hovered ? hoverBg : 'transparent',
@@ -312,8 +314,8 @@ export function TrailStepsNav({
                     <span
                       style={{
                         flexShrink: 0,
-                        // Same 14px leading column as the header's trail icon,
-                        // so the digit sits under it.
+                        // Root steps align with the header icon; nested steps
+                        // move the number and text together.
                         width: 14,
                         textAlign: 'center',
                         paddingTop: 1,
@@ -340,7 +342,7 @@ export function TrailStepsNav({
                             overflowWrap: 'anywhere',
                             fontSize: theme.fontSizes[1],
                             fontFamily: theme.fonts.body,
-                            color: theme.colors.text,
+                            color: theme.colors.primary,
                             lineHeight: 1.35,
                           }}
                         >

package/src/subsystem/TrailsPanel.test.tsx

@@ -115,6 +115,26 @@ function renderPanel(overrides: Partial<TrailsPanelProps> = {}) {
 
 const COPY_LABEL = 'Copy step 1 of Auth flow for an agent';
 
+describe('TrailsPanel trail titles', () => {
+  for (const collapsed of [true, false]) {
+    test(`shows a decorative trail icon before the ${collapsed ? 'collapsed' : 'expanded'} trail name`, () => {
+      const onFocusFlow = mock(() => {});
+      const { getByRole } = renderPanel({
+        expandedTrails: collapsed ? new Set() : new Set(['auth-flow']),
+        onFocusFlow,
+      });
+      const button = getByRole('button', { name: 'Auth flow', exact: true });
+      const icon = button.firstElementChild;
+      expect(icon?.tagName.toLowerCase()).toBe('svg');
+      expect(icon?.classList.contains('lucide-route')).toBe(true);
+      expect(icon?.getAttribute('aria-hidden')).toBe('true');
+      expect(icon?.nextElementSibling?.textContent).toBe('Auth flow');
+      fireEvent.click(button);
+      expect(onFocusFlow).toHaveBeenCalledWith(trails[0]);
+    });
+  }
+});
+
 describe('TrailsPanel step copy', () => {
   test('copy icon is hidden until the step row is hovered', () => {
     const { getByText, queryByLabelText } = renderPanel();

package/src/subsystem/TrailsPanel.tsx

@@ -13,7 +13,7 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
 import type { DragEvent as ReactDragEvent } from 'react';
 import { useTheme } from '@principal-ade/industry-theme';
-import { Check, ChevronDown, Copy, Focus, GripVertical, Minimize2, Pause, Play, Star } from 'lucide-react';
+import { Check, ChevronDown, Copy, Focus, GripVertical, Minimize2, Pause, Play, Route, Star } from 'lucide-react';
 import { IndustryMarkdownSlide } from 'themed-markdown';
 import {
   reorderTargetIndex,
@@ -316,6 +316,7 @@ function TrailFlow({
             display: 'flex',
             alignItems: 'center',
             minWidth: 0,
+            gap: 8,
             // Vertical padding, not just the row's min-height: a title that
             // wraps to two+ lines must grow the header past `minHeight`, and
             // without this the text sits flush against the row's top and bottom
@@ -329,6 +330,15 @@ function TrailFlow({
             cursor: 'pointer',
           }}
         >
+          <Route
+            size={14}
+            strokeWidth={2}
+            aria-hidden
+            style={{
+              flexShrink: 0,
+              color: theme.colors.textMuted ?? theme.colors.textSecondary,
+            }}
+          />
           <span
             style={{
               minWidth: 0,

package/src/subsystem/decoration.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, test } from 'bun:test';
+import type { SubsystemTrail } from './model';
+import {
+  decorationModelIds,
+  decorationTrailId,
+  decorationTrailKey,
+  findDecorationTrail,
+  groupDecorationTrailsByModel,
+  type DecorationTrailRef,
+} from './decoration';
+
+function ref(modelId: string, trailId: string): DecorationTrailRef {
+  return { kind: 'base', modelId, trailId };
+}
+
+const draftTrail: SubsystemTrail = {
+  id: 'planned-open',
+  title: 'Planned open',
+  steps: [],
+};
+
+describe('decoration trail refs', () => {
+  test('keys are scoped by model', () => {
+    expect(decorationTrailKey(ref('model-a', 'open'))).toBe('model-a:open');
+    expect(decorationTrailKey(ref('model-a', 'open'))).not.toBe(
+      decorationTrailKey(ref('model-b', 'open')),
+    );
+  });
+
+  test('a draft trail keys like a base trail', () => {
+    const draft: DecorationTrailRef = {
+      kind: 'draft',
+      modelId: 'model-a',
+      trail: draftTrail,
+    };
+    expect(decorationTrailKey(draft)).toBe('model-a:planned-open');
+    expect(decorationTrailId(draft)).toBe('planned-open');
+  });
+
+  test('groups trails by their own model, preserving authored order', () => {
+    const groups = groupDecorationTrailsByModel([
+      ref('web', 'open'),
+      ref('server', 'handle'),
+      ref('web', 'save'),
+      ref('worker', 'consume'),
+    ]);
+    expect(groups.map((g) => g.modelId)).toEqual(['web', 'server', 'worker']);
+    expect(groups[0]!.trails.map((t) => decorationTrailId(t))).toEqual([
+      'open',
+      'save',
+    ]);
+    expect(groups[1]!.trails.map((t) => decorationTrailId(t))).toEqual([
+      'handle',
+    ]);
+  });
+
+  test('lists distinct models in first-seen order', () => {
+    expect(
+      decorationModelIds([
+        ref('web', 'open'),
+        ref('server', 'handle'),
+        ref('web', 'save'),
+      ]),
+    ).toEqual(['web', 'server']);
+  });
+
+  test('finds a trail by model and trail id, not trail id alone', () => {
+    const refs = [ref('web', 'open'), ref('server', 'open')];
+    expect(findDecorationTrail(refs, 'server', 'open')?.modelId).toBe('server');
+    expect(findDecorationTrail(refs, 'worker', 'open')).toBeUndefined();
+  });
+});

package/src/subsystem/decoration.ts

@@ -0,0 +1,151 @@
+/**
+ * Subsystem decoration — PROTOTYPE contract for the ephemeral, unverified layer.
+ *
+ * A decoration composes trails from one or more models, carries a markdown
+ * description, and may add draft structure. The base model stays verified-only;
+ * a decoration is never audited against source.
+ *
+ * **Each trail ref names its own model.** There is no decoration-level `base`
+ * field: a decoration can mix models by construction, and a single-model
+ * decoration is just the case where every ref happens to share a `modelId`.
+ *
+ * A trail can be either:
+ * - `base` — a reference to a trail that already exists in a model; or
+ * - `draft` — a trail that only exists in the decoration. This is what
+ *   migration needs when a base trail depends on draft components: the whole
+ *   trail moves into the decoration rather than dangling in the base.
+ *
+ * The contract is deliberately host-local and not part of the portable
+ * subsystem document. If decorations become shareable, `modelId` needs a
+ * portable identity key (the local `sg-...` ids are re-minted).
+ */
+
+import type { SubsystemTrail, SubsystemTrailMechanism } from './model';
+
+export interface DecorationStepAnchor {
+  /** Claim fingerprint of the anchored step (see `stepClaimKey`). */
+  stepKey: string;
+  /** Optional per-anchor note. The decoration description carries the prose. */
+  note?: string;
+}
+
+interface DecorationTrailRefBase {
+  /** Store-local model id. The trail id is only unique within this model. */
+  modelId: string;
+  /** Optional step-level anchors inside this trail. */
+  stepAnchors?: DecorationStepAnchor[];
+}
+
+/** A trail that already exists in the base model. */
+export interface DecorationBaseTrailRef extends DecorationTrailRefBase {
+  kind: 'base';
+  trailId: string;
+}
+
+/** A speculative trail that exists only in the decoration. */
+export interface DecorationDraftTrailRef extends DecorationTrailRefBase {
+  kind: 'draft';
+  trail: SubsystemTrail;
+}
+
+export type DecorationTrailRef =
+  | DecorationBaseTrailRef
+  | DecorationDraftTrailRef;
+
+/**
+ * Draft structure: a component that does not exist in source yet. No
+ * `file`/`symbol` — those are the verification coordinates the base model
+ * requires, and a draft component deliberately has none.
+ */
+export interface DecorationDraftComponent {
+  alias: string;
+  name: string;
+  /** Intended construct shape (`class`, `function`, …). */
+  construct?: string;
+  purpose?: string;
+  module?: string;
+  process?: string;
+}
+
+/** A speculative edge between base or draft aliases. */
+export interface DecorationDraftEdge {
+  from: string;
+  to: string;
+  mechanism: SubsystemTrailMechanism;
+}
+
+export interface DecorationDraft {
+  components?: DecorationDraftComponent[];
+  edges?: DecorationDraftEdge[];
+}
+
+export interface DecorationProvenance {
+  source: 'author' | 'agent';
+  author?: string;
+  /** ISO timestamp. */
+  at: string;
+}
+
+export interface SubsystemDecoration {
+  version: 1;
+  id: string;
+  title: string;
+  /** Markdown, rendered like the model description. */
+  description: string;
+  /**
+   * Ordered trails the decoration cares about. Order is the reading order;
+   * `modelId` may vary from ref to ref. A trail is either a base ref or a
+   * draft trail that lives only here.
+   */
+  trails: DecorationTrailRef[];
+  /** Optional draft delta. Absent = a pure reading path. */
+  draft?: DecorationDraft;
+  provenance: DecorationProvenance;
+}
+
+/** The trail id for either kind of ref. */
+export function decorationTrailId(ref: DecorationTrailRef): string {
+  return ref.kind === 'base' ? ref.trailId : ref.trail.id;
+}
+
+/** Stable key for a trail ref across models. `trailId` alone is not enough. */
+export function decorationTrailKey(
+  ref: Pick<DecorationTrailRef, 'modelId'> & { trailId?: string; trail?: SubsystemTrail },
+): string {
+  const trailId = ref.trailId ?? ref.trail?.id ?? '';
+  return `${ref.modelId}:${trailId}`;
+}
+
+/**
+ * Group trail refs by their owning model, preserving first-seen model order
+ * and the authored trail order within each group. The UI uses this to render
+ * "which trails it cares about" without a separate model list.
+ */
+export function groupDecorationTrailsByModel(
+  refs: readonly DecorationTrailRef[],
+): Array<{ modelId: string; trails: DecorationTrailRef[] }> {
+  const groups = new Map<string, DecorationTrailRef[]>();
+  for (const ref of refs) {
+    const existing = groups.get(ref.modelId);
+    if (existing) existing.push(ref);
+    else groups.set(ref.modelId, [ref]);
+  }
+  return [...groups].map(([modelId, trails]) => ({ modelId, trails }));
+}
+
+/** The distinct models a decoration touches, in first-seen order. */
+export function decorationModelIds(
+  refs: readonly DecorationTrailRef[],
+): string[] {
+  return [...new Set(refs.map((ref) => ref.modelId))];
+}
+
+export function findDecorationTrail(
+  refs: readonly DecorationTrailRef[],
+  modelId: string,
+  trailId: string,
+): DecorationTrailRef | undefined {
+  return refs.find(
+    (ref) => ref.modelId === modelId && decorationTrailId(ref) === trailId,
+  );
+}

package/src/subsystem/stepEmphasis.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, test } from 'bun:test';
+import type { SubsystemTrail } from './model';
+import {
+  buildStepEmphasisMap,
+  emphasisForTrail,
+  emphasisKey,
+  findStepEmphasis,
+  orphanedEmphasis,
+  stepClaimKey,
+  type StepEmphasisRecord,
+} from './stepEmphasis';
+
+function step(overrides: Partial<SubsystemTrail['steps'][number]> = {}): SubsystemTrail['steps'][number] {
+  return {
+    from: 'ui',
+    to: 'api',
+    mechanism: 'calls',
+    file: 'src/ui/login.tsx',
+    span: { startLine: 42, endLine: 42, contentHash: 'abc' },
+    purl: 'pkg:github/acme/app#src/ui/login.tsx',
+    symbol: 'Login.submit',
+    ...overrides,
+  };
+}
+
+function trail(id: string, steps: SubsystemTrail['steps']): SubsystemTrail {
+  return { id, title: id, steps };
+}
+
+function record(trailId: string, stepKey: string): StepEmphasisRecord {
+  return {
+    trailId,
+    stepKey,
+    guidance: 'Why this step matters.',
+    provenance: { source: 'author', at: '2026-10-19T00:00:00.000Z' },
+  };
+}
+
+describe('stepClaimKey', () => {
+  test('is stable for the same claim', () => {
+    expect(stepClaimKey(step())).toBe(stepClaimKey(step()));
+  });
+
+  test('ignores annotation, which is not the claim', () => {
+    expect(stepClaimKey(step({ annotation: 'why' }))).toBe(
+      stepClaimKey(step()),
+    );
+  });
+
+  test('changes when the claim changes', () => {
+    const base = stepClaimKey(step());
+    expect(base).not.toBe(stepClaimKey(step({ from: 'other' })));
+    expect(base).not.toBe(stepClaimKey(step({ to: 'other' })));
+    expect(base).not.toBe(stepClaimKey(step({ mechanism: 'feeds' })));
+    expect(base).not.toBe(stepClaimKey(step({ file: 'src/other.ts' })));
+    expect(base).not.toBe(stepClaimKey(step({ symbol: 'Other.submit' })));
+    expect(base).not.toBe(
+      stepClaimKey(step({ span: { startLine: 43, endLine: 43, contentHash: 'abc' } })),
+    );
+    expect(base).not.toBe(
+      stepClaimKey(step({ span: { startLine: 42, endLine: 42, contentHash: 'changed' } })),
+    );
+  });
+});
+
+describe('step emphasis lookup', () => {
+  test('resolves after steps are reordered', () => {
+    const first = step({ symbol: 'first' });
+    const second = step({ symbol: 'second' });
+    const map = buildStepEmphasisMap([record('flow', stepClaimKey(first))]);
+    const reordered = trail('flow', [second, first]);
+    expect(findStepEmphasis(map, 'flow', reordered.steps[1]!)).toBeDefined();
+    expect(findStepEmphasis(map, 'flow', reordered.steps[0]!)).toBeUndefined();
+  });
+
+  test('emphasisForTrail reports marks in current step order', () => {
+    const a = step({ symbol: 'a' });
+    const b = step({ symbol: 'b' });
+    const c = step({ symbol: 'c' });
+    const map = buildStepEmphasisMap([
+      record('flow', stepClaimKey(c)),
+      record('flow', stepClaimKey(a)),
+    ]);
+    expect(emphasisForTrail(map, trail('flow', [b, a, c])).map((r) => r.stepIndex)).toEqual([
+      1, 2,
+    ]);
+  });
+
+  test('an edited claim orphans its mark rather than re-binding it', () => {
+    const original = step();
+    const edited = step({ file: 'src/ui/login-v2.tsx' });
+    const records = [record('flow', stepClaimKey(original))];
+    const orphans = orphanedEmphasis(records, [trail('flow', [edited])]);
+    expect(orphans).toHaveLength(1);
+    expect(orphans[0]!.stepKey).toBe(stepClaimKey(original));
+  });
+
+  test('live marks are not reported as orphans', () => {
+    const live = step();
+    const records = [record('flow', stepClaimKey(live))];
+    expect(orphanedEmphasis(records, [trail('flow', [live])])).toEqual([]);
+  });
+
+  test('keys are scoped by trail id', () => {
+    const shared = step();
+    const map = buildStepEmphasisMap([record('flow-a', stepClaimKey(shared))]);
+    expect(emphasisKey('flow-b', shared)).not.toBe(emphasisKey('flow-a', shared));
+    expect(findStepEmphasis(map, 'flow-b', shared)).toBeUndefined();
+  });
+});