@principal-ai/subsystems-react 0.55.3 → 0.56.1

package/dist/subsystem/stepEmphasis.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 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>;
+/** Stable content key for a step's claim. */
+export declare function stepClaimKey(step: Pick<SubsystemTrailStep, 'from' | 'to' | 'mechanism' | 'file' | 'symbol' | 'span'>): string;
+/** Map key for one step's mark. */
+export declare function emphasisKey(trailId: string, step: Pick<SubsystemTrailStep, 'from' | 'to' | 'mechanism' | 'file' | 'symbol' | 'span'>): string;
+export declare function buildStepEmphasisMap(records: readonly StepEmphasisRecord[]): StepEmphasisMap;
+export declare function findStepEmphasis(map: StepEmphasisMap | undefined, trailId: string, step: SubsystemTrailStep): StepEmphasisRecord | undefined;
+/**
+ * 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 declare function orphanedEmphasis(records: readonly StepEmphasisRecord[], trails: readonly SubsystemTrail[]): StepEmphasisRecord[];
+/** Records for one trail, in current step order (for reader surfaces). */
+export declare function emphasisForTrail(map: StepEmphasisMap | undefined, trail: SubsystemTrail): Array<{
+    stepIndex: number;
+    step: SubsystemTrailStep;
+    record: StepEmphasisRecord;
+}>;
+//# sourceMappingURL=stepEmphasis.d.ts.map

package/dist/subsystem/stepEmphasis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stepEmphasis.d.ts","sourceRoot":"","sources":["../../src/subsystem/stepEmphasis.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAElE,MAAM,WAAW,sBAAsB;IACrC,2DAA2D;IAC3D,MAAM,EAAE,QAAQ,GAAG,OAAO,CAAC;IAC3B,qBAAqB;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,qCAAqC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,sDAAsD;AACtD,MAAM,WAAW,kBAAkB;IACjC,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,sBAAsB,CAAC;CACpC;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,CAAC,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,kBAAkB,EAAE,CAAC;CAChC;AAED;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,WAAW,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;AA8BtE,6CAA6C;AAC7C,wBAAgB,YAAY,CAC1B,IAAI,EAAE,IAAI,CAAC,kBAAkB,EAAE,MAAM,GAAG,IAAI,GAAG,WAAW,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC,GACvF,MAAM,CAER;AAED,mCAAmC;AACnC,wBAAgB,WAAW,CACzB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,IAAI,CAAC,kBAAkB,EAAE,MAAM,GAAG,IAAI,GAAG,WAAW,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC,GACvF,MAAM,CAER;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,SAAS,kBAAkB,EAAE,GACrC,eAAe,CAEjB;AAED,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,eAAe,GAAG,SAAS,EAChC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,kBAAkB,GACvB,kBAAkB,GAAG,SAAS,CAEhC;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,SAAS,kBAAkB,EAAE,EACtC,MAAM,EAAE,SAAS,cAAc,EAAE,GAChC,kBAAkB,EAAE,CAMtB;AAED,0EAA0E;AAC1E,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,eAAe,GAAG,SAAS,EAChC,KAAK,EAAE,cAAc,GACpB,KAAK,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,kBAAkB,CAAC;IAAC,MAAM,EAAE,kBAAkB,CAAA;CAAE,CAAC,CAQpF"}

package/dist/subsystem/stepEmphasis.js

@@ -0,0 +1,89 @@
+/**
+ * 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.
+ */
+/** The claim fields a mark is attached to. Deliberately excludes `annotation`. */
+function claimFields(step) {
+    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) {
+    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) {
+    return fnv1a(claimFields(step).join('\u001f'));
+}
+/** Map key for one step's mark. */
+export function emphasisKey(trailId, step) {
+    return `${trailId}:${stepClaimKey(step)}`;
+}
+export function buildStepEmphasisMap(records) {
+    return new Map(records.map((r) => [`${r.trailId}:${r.stepKey}`, r]));
+}
+export function findStepEmphasis(map, trailId, step) {
+    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, trails) {
+    const live = new Set();
+    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, trail) {
+    if (!map)
+        return [];
+    const rows = [];
+    trail.steps.forEach((step, stepIndex) => {
+        const record = map.get(emphasisKey(trail.id, step));
+        if (record)
+            rows.push({ stepIndex, step, record });
+    });
+    return rows;
+}
+//# sourceMappingURL=stepEmphasis.js.map

package/dist/subsystem/stepEmphasis.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stepEmphasis.js","sourceRoot":"","sources":["../../src/subsystem/stepEmphasis.ts"],"names":[],"mappings":"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"}

package/dist/subsystem/trailBrief.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"trailBrief.d.ts","sourceRoot":"","sources":["../../src/subsystem/trailBrief.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,cAAc,EACrB,SAAS,EAAE,MAAM,GAChB,MAAM,CAuBR"}
+{"version":3,"file":"trailBrief.d.ts","sourceRoot":"","sources":["../../src/subsystem/trailBrief.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,cAAc,EACrB,SAAS,EAAE,MAAM,GAChB,MAAM,CA2CR"}

package/dist/subsystem/trailBrief.js

@@ -24,12 +24,32 @@ export function buildStepBrief(trail, stepIndex) {
     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/dist/subsystem/trailBrief.js.map

@@ -1 +1 @@
-{"version":3,"file":"trailBrief.js","sourceRoot":"","sources":["../../src/subsystem/trailBrief.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH;;;GAGG;AACH,MAAM,UAAU,cAAc,CAC5B,KAAqB,EACrB,SAAiB;IAEjB,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IACpC,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,CAAC;IACrB,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CACR,UAAU,KAAK,CAAC,KAAK,KAAK,KAAK,CAAC,EAAE,YAAY,SAAS,GAAG,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,CACpF,CAAC;IACF,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,aAAa,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC;IACvC,KAAK,CAAC,IAAI,CAAC,WAAW,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;IACnC,KAAK,CAAC,IAAI,CAAC,kBAAkB,IAAI,CAAC,SAAS,IAAI,CAAC,CAAC;IACjD,KAAK,CAAC,IAAI,CAAC,eAAe,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC;IAC3C,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI;QACpB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,KAAK,IAAI,CAAC,IAAI,CAAC,OAAO;YACzC,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE;YACvC,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE;QAC9D,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;IACd,KAAK,CAAC,IAAI,CAAC,aAAa,IAAI,IAAI,CAAC,CAAC;IAClC,KAAK,CAAC,IAAI,CAAC,aAAa,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC;IACvC,IAAI,IAAI,CAAC,UAAU,IAAI,IAAI,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE;QACzD,KAAK,CAAC,IAAI,CAAC,WAAW,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;KAC1C;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}
+{"version":3,"file":"trailBrief.js","sourceRoot":"","sources":["../../src/subsystem/trailBrief.ts"],"names":[],"mappings":"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"}

package/dist/subsystem/trailStack.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Derive a call stack for one trail step.
+ *
+ * A trail is a timeline, not a stack frame dump: steps can return to an
+ * ancestor, take sibling calls, or describe a non-call seam (`uses`, `feeds`,
+ * …). This module links each `calls` step to the prior call that entered its
+ * caller construct, then renders that ancestry as a stack. Non-call steps are
+ * annotations on the nearest frame — they are not frames.
+ *
+ * The links use the resolved `site`/`target` when present, falling back to the
+ * component aliases. That keeps the view useful before every step has its
+ * construct refs captured.
+ */
+import type { SubsystemTrail, SubsystemTrailMechanism } from './model';
+import { type TrailComponentLabels } from './trailStepDisplay';
+export interface TrailStackFrame {
+    /** The step whose call creates this frame. */
+    stepIndex: number;
+    /** Frame label — the caller construct, or the component alias. */
+    label: string;
+    /** Component alias of the caller (for focus/selection wiring). */
+    componentAlias: string;
+    /** The selected step's own frame (innermost). */
+    current: boolean;
+}
+export interface TrailStackAnnotation {
+    /** Non-call step attached to the current frame. */
+    stepIndex: number;
+    mechanism: SubsystemTrailMechanism;
+    label: string;
+    /** The selected step itself (vs context around it). */
+    selected: boolean;
+}
+export interface TrailStackView {
+    /** Outermost → innermost. Empty only for an out-of-range index. */
+    frames: TrailStackFrame[];
+    /** Non-call seams attached to the current frame. */
+    annotations: TrailStackAnnotation[];
+    /** True when the selected step is a call frame. */
+    isCall: boolean;
+    /** The selected call's target, shown as the next frame-to-be. */
+    callee?: string;
+}
+/**
+ * Build the stack at one trail step.
+ *
+ * - `calls` → the chain of calls into the caller frame, plus the callee as the
+ *   next frame (not yet on the stack).
+ * - `uses` / data + event seams → the nearest call frame they attach to, with
+ *   the seam as an annotation.
+ */
+export declare function buildTrailStack(trail: SubsystemTrail, stepIndex: number, byAlias?: TrailComponentLabels): TrailStackView;
+//# sourceMappingURL=trailStack.d.ts.map

package/dist/subsystem/trailStack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trailStack.d.ts","sourceRoot":"","sources":["../../src/subsystem/trailStack.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,uBAAuB,EAExB,MAAM,SAAS,CAAC;AACjB,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,oBAAoB,CAAC;AAE5B,MAAM,WAAW,eAAe;IAC9B,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,cAAc,EAAE,MAAM,CAAC;IACvB,iDAAiD;IACjD,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,oBAAoB;IACnC,mDAAmD;IACnD,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,uBAAuB,CAAC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,mEAAmE;IACnE,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,oDAAoD;IACpD,WAAW,EAAE,oBAAoB,EAAE,CAAC;IACpC,mDAAmD;IACnD,MAAM,EAAE,OAAO,CAAC;IAChB,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AA+GD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,cAAc,EACrB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,oBAAoB,GAC7B,cAAc,CAoDhB"}

package/dist/subsystem/trailStack.js

@@ -0,0 +1,154 @@
+/**
+ * Derive a call stack for one trail step.
+ *
+ * A trail is a timeline, not a stack frame dump: steps can return to an
+ * ancestor, take sibling calls, or describe a non-call seam (`uses`, `feeds`,
+ * …). This module links each `calls` step to the prior call that entered its
+ * caller construct, then renders that ancestry as a stack. Non-call steps are
+ * annotations on the nearest frame — they are not frames.
+ *
+ * The links use the resolved `site`/`target` when present, falling back to the
+ * component aliases. That keeps the view useful before every step has its
+ * construct refs captured.
+ */
+import { trailComponentLabel, } from './trailStepDisplay';
+function callerSymbol(step) {
+    return step.site?.symbol?.trim() || step.symbol?.trim() || step.from;
+}
+function calleeSymbol(step) {
+    return step.target?.symbol?.trim() || step.to;
+}
+function callerLabel(step, byAlias) {
+    return callerSymbol(step) || trailComponentLabel(step.from, byAlias);
+}
+function calleeLabel(step, byAlias) {
+    return step.target?.symbol?.trim() || trailComponentLabel(step.to, byAlias);
+}
+function isCallStep(step) {
+    return step?.mechanism === 'calls';
+}
+/** Does call `a` lead into the caller of call `b`? */
+function leadsInto(a, b) {
+    return a.to === b.from || calleeSymbol(a) === callerSymbol(b);
+}
+/** The nearest earlier call that entered this step's caller frame. */
+function parentCallIndex(trail, stepIndex) {
+    const child = trail.steps[stepIndex];
+    if (!child)
+        return null;
+    for (let i = stepIndex - 1; i >= 0; i--) {
+        const candidate = trail.steps[i];
+        if (!isCallStep(candidate))
+            continue;
+        if (leadsInto(candidate, child))
+            return i;
+    }
+    return null;
+}
+/** The call chain ending at `stepIndex`, outermost first. */
+function callChain(trail, stepIndex) {
+    const chain = [];
+    const seen = new Set();
+    let cursor = stepIndex;
+    while (cursor != null && !seen.has(cursor)) {
+        seen.add(cursor);
+        chain.unshift(cursor);
+        cursor = parentCallIndex(trail, cursor);
+    }
+    return chain;
+}
+function framesForChain(trail, chain, selectedStepIndex, byAlias) {
+    return chain.map((idx) => {
+        const step = trail.steps[idx];
+        return {
+            stepIndex: idx,
+            label: callerLabel(step, byAlias),
+            componentAlias: step.from,
+            current: idx === selectedStepIndex,
+        };
+    });
+}
+/**
+ * The nearest earlier call that shares this non-call step's source component.
+ * `uses`/`feeds`/… are dependencies of that frame, not new frames.
+ */
+function anchorCallIndex(trail, stepIndex) {
+    const step = trail.steps[stepIndex];
+    if (!step)
+        return null;
+    const source = callerSymbol(step);
+    for (let i = stepIndex - 1; i >= 0; i--) {
+        const candidate = trail.steps[i];
+        if (!isCallStep(candidate))
+            continue;
+        if (candidate.from === step.from ||
+            candidate.to === step.from ||
+            callerSymbol(candidate) === source ||
+            calleeSymbol(candidate) === source) {
+            return i;
+        }
+    }
+    return null;
+}
+function annotationLabel(step, byAlias) {
+    return `${step.mechanism} ${calleeLabel(step, byAlias)}`;
+}
+/**
+ * Build the stack at one trail step.
+ *
+ * - `calls` → the chain of calls into the caller frame, plus the callee as the
+ *   next frame (not yet on the stack).
+ * - `uses` / data + event seams → the nearest call frame they attach to, with
+ *   the seam as an annotation.
+ */
+export function buildTrailStack(trail, stepIndex, byAlias) {
+    const step = trail.steps[stepIndex];
+    if (!step) {
+        return { frames: [], annotations: [], isCall: false };
+    }
+    if (isCallStep(step)) {
+        const chain = callChain(trail, stepIndex);
+        return {
+            frames: framesForChain(trail, chain, stepIndex, byAlias),
+            annotations: [],
+            isCall: true,
+            callee: calleeLabel(step, byAlias),
+        };
+    }
+    const anchor = anchorCallIndex(trail, stepIndex);
+    if (anchor != null) {
+        const chain = callChain(trail, anchor);
+        return {
+            frames: framesForChain(trail, chain, anchor, byAlias),
+            annotations: [
+                {
+                    stepIndex,
+                    mechanism: step.mechanism,
+                    label: annotationLabel(step, byAlias),
+                    selected: true,
+                },
+            ],
+            isCall: false,
+        };
+    }
+    return {
+        frames: [
+            {
+                stepIndex,
+                label: callerLabel(step, byAlias),
+                componentAlias: step.from,
+                current: true,
+            },
+        ],
+        annotations: [
+            {
+                stepIndex,
+                mechanism: step.mechanism,
+                label: annotationLabel(step, byAlias),
+                selected: true,
+            },
+        ],
+        isCall: false,
+    };
+}
+//# sourceMappingURL=trailStack.js.map

package/dist/subsystem/trailStack.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trailStack.js","sourceRoot":"","sources":["../../src/subsystem/trailStack.ts"],"names":[],"mappings":"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"}

package/dist/subsystem/trailStepDisplay.d.ts

@@ -0,0 +1,38 @@
+/**
+ * How a trail step reads in the Trails panel.
+ *
+ * A step is one seam, but the panel shows the logical hop and the site in a
+ * single wrapping line:
+ *
+ * - `calls` — the caller frame (the site construct).
+ * - `uses` — `from uses to`, where `to` is the precise target when resolved.
+ * - Everything else — `from mechanism to`.
+ *
+ * The evidence site lives in the code view and the stack breadcrumb; the
+ * sidebar row stays one line so it can wrap instead of truncating.
+ */
+import type { SubsystemTrailStep, SubsystemTrailMechanism } from './model';
+/** The slice of a component the labels need — keeps fixtures light. */
+export interface TrailComponentLabelSource {
+    alias: string;
+    name?: string;
+    symbol?: string;
+}
+/** Alias → component, for turning model-local aliases into display names. */
+export type TrailComponentLabels = ReadonlyMap<string, TrailComponentLabelSource>;
+/** One row's primary text. */
+export interface TrailStepDisplay {
+    mechanism: SubsystemTrailMechanism;
+    /** The line that names the step: caller frame for `calls`, hop otherwise. */
+    primary: string;
+}
+/** Display label for a component alias; falls back to the alias. */
+export declare function trailComponentLabel(alias: string, byAlias?: TrailComponentLabels): string;
+/**
+ * Build the single display line for one step.
+ *
+ * The resolved target (`step.target.symbol`) is the precise callee, while `to`
+ * is only a component alias and can be a whole class/store. Prefer the target.
+ */
+export declare function trailStepDisplay(step: SubsystemTrailStep, byAlias?: TrailComponentLabels): TrailStepDisplay;
+//# sourceMappingURL=trailStepDisplay.d.ts.map

package/dist/subsystem/trailStepDisplay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trailStepDisplay.d.ts","sourceRoot":"","sources":["../../src/subsystem/trailStepDisplay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAE3E,uEAAuE;AACvE,MAAM,WAAW,yBAAyB;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,6EAA6E;AAC7E,MAAM,MAAM,oBAAoB,GAAG,WAAW,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC;AAElF,8BAA8B;AAC9B,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,uBAAuB,CAAC;IACnC,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,oEAAoE;AACpE,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,oBAAoB,GAC7B,MAAM,CAIR;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,kBAAkB,EACxB,OAAO,CAAC,EAAE,oBAAoB,GAC7B,gBAAgB,CAelB"}

package/dist/subsystem/trailStepDisplay.js

@@ -0,0 +1,41 @@
+/**
+ * How a trail step reads in the Trails panel.
+ *
+ * A step is one seam, but the panel shows the logical hop and the site in a
+ * single wrapping line:
+ *
+ * - `calls` — the caller frame (the site construct).
+ * - `uses` — `from uses to`, where `to` is the precise target when resolved.
+ * - Everything else — `from mechanism to`.
+ *
+ * The evidence site lives in the code view and the stack breadcrumb; the
+ * sidebar row stays one line so it can wrap instead of truncating.
+ */
+/** Display label for a component alias; falls back to the alias. */
+export function trailComponentLabel(alias, byAlias) {
+    const component = byAlias?.get(alias);
+    const label = component?.name?.trim() || component?.symbol?.trim();
+    return label || alias;
+}
+/**
+ * Build the single display line for one step.
+ *
+ * The resolved target (`step.target.symbol`) is the precise callee, while `to`
+ * is only a component alias and can be a whole class/store. Prefer the target.
+ */
+export function trailStepDisplay(step, byAlias) {
+    const from = trailComponentLabel(step.from, byAlias);
+    const to = step.target?.symbol?.trim() || trailComponentLabel(step.to, byAlias);
+    const siteSymbol = step.site?.symbol?.trim() || step.symbol?.trim() || from;
+    if (step.mechanism === 'calls') {
+        return { mechanism: step.mechanism, primary: siteSymbol };
+    }
+    if (step.mechanism === 'uses') {
+        return { mechanism: step.mechanism, primary: `${from} uses ${to}` };
+    }
+    return {
+        mechanism: step.mechanism,
+        primary: `${from} ${step.mechanism} ${to}`,
+    };
+}
+//# sourceMappingURL=trailStepDisplay.js.map

package/dist/subsystem/trailStepDisplay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trailStepDisplay.js","sourceRoot":"","sources":["../../src/subsystem/trailStepDisplay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAqBH,oEAAoE;AACpE,MAAM,UAAU,mBAAmB,CACjC,KAAa,EACb,OAA8B;IAE9B,MAAM,SAAS,GAAG,OAAO,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC;IACtC,MAAM,KAAK,GAAG,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IACnE,OAAO,KAAK,IAAI,KAAK,CAAC;AACxB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAC9B,IAAwB,EACxB,OAA8B;IAE9B,MAAM,IAAI,GAAG,mBAAmB,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACrD,MAAM,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,mBAAmB,CAAC,IAAI,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;IAChF,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC;IAE5E,IAAI,IAAI,CAAC,SAAS,KAAK,OAAO,EAAE;QAC9B,OAAO,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC;KAC3D;IACD,IAAI,IAAI,CAAC,SAAS,KAAK,MAAM,EAAE;QAC7B,OAAO,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,OAAO,EAAE,GAAG,IAAI,SAAS,EAAE,EAAE,EAAE,CAAC;KACrE;IACD,OAAO;QACL,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,OAAO,EAAE,GAAG,IAAI,IAAI,IAAI,CAAC,SAAS,IAAI,EAAE,EAAE;KAC3C,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@principal-ai/subsystems-react",
-  "version": "0.55.3",
+  "version": "0.56.1",
   "description": "React UI for Subsystem Models — graph, Pierre code views, and session-event feeds",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -38,7 +38,7 @@
   "peerDependencies": {
     "@pierre/diffs": ">=1.1.20",
     "@principal-ade/industry-theme": "^0.1.7",
-    "@principal-ai/subsystems-core": "^0.49.0",
+    "@principal-ai/subsystems-core": "^0.50.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
@@ -46,7 +46,7 @@
     "@pierre/diffs": "1.3.6",
     "@principal-ade/industry-theme": "0.1.7",
     "@principal-ai/agent-monitoring": "^0.3.38",
-    "@principal-ai/subsystems-core": "^0.49.1",
+    "@principal-ai/subsystems-core": "^0.50.0",
     "@storybook/addon-docs": "10.1.2",
     "@storybook/addon-links": "10.1.2",
     "@storybook/addon-onboarding": "10.1.2",

package/src/index.ts

@@ -218,6 +218,14 @@ export {
 export type { TrailsPanelProps } from './subsystem/TrailsPanel';
 export { TrailStepsNav } from './subsystem/TrailStepsNav';
 export type { TrailStepsNavProps } from './subsystem/TrailStepsNav';
+export { TrailStackBreadcrumb } from './subsystem/TrailStackBreadcrumb';
+export type { TrailStackBreadcrumbProps } from './subsystem/TrailStackBreadcrumb';
+export { buildTrailStack } from './subsystem/trailStack';
+export type {
+  TrailStackAnnotation,
+  TrailStackFrame,
+  TrailStackView,
+} from './subsystem/trailStack';
 export { buildStepBrief } from './subsystem/trailBrief';
 export { GraphLayoutCover } from './subsystem/GraphLayoutCover';
 export type { GraphLayoutCoverProps } from './subsystem/GraphLayoutCover';
@@ -232,6 +240,8 @@ export type {
   SubsystemComponentEdge,
   SubsystemTrail,
   SubsystemTrailStep,
+  SubsystemSiteConstruct,
+  SubsystemTargetConstruct,
   SubsystemTrailMechanism,
   SubsystemModelDocument,
   SubsystemComponentConstruct,
@@ -315,7 +325,6 @@ export {
   ROLE_COLOR,
   ROLE_LABEL,
   FRAMEWORK_BADGE_COLOR,
-  PROPOSED_COLOR,
 } from './subsystem/model';
 export type {
   SubsystemSourceSpan,

package/src/pierre/PierreFileView.tsx

@@ -105,14 +105,14 @@ export function PierreFileView({
   );
 
   if (error) {
-    // A file with no local checkout is usually a proposed seam that isn't
-    // implemented yet — explain that instead of echoing the host error.
+    // A file with no local checkout is usually a seam that isn't implemented
+    // yet — explain that instead of echoing the host error.
     if (isFileUnavailableError(error)) {
       return (
         <div style={{ padding: 16, display: 'flex', flexDirection: 'column', gap: 4 }}>
           <span style={{ color: theme.colors.text }}>
             This file isn't in the local checkout for this repo — it may be
-            proposed or not yet implemented.
+            missing or not yet implemented.
           </span>
           <span
             style={{