@principal-ai/subsystems-react 0.55.3 → 0.56.0

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.0",
   "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,7 +218,52 @@ 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 {
+  buildStepEmphasisMap,
+  emphasisForTrail,
+  emphasisKey,
+  findStepEmphasis,
+  orphanedEmphasis,
+  stepClaimKey,
+} from './subsystem/stepEmphasis';
+export type {
+  StepEmphasisDocument,
+  StepEmphasisMap,
+  StepEmphasisProvenance,
+  StepEmphasisRecord,
+} from './subsystem/stepEmphasis';
+export {
+  decorationModelIds,
+  decorationTrailId,
+  decorationTrailKey,
+  findDecorationTrail,
+  groupDecorationTrailsByModel,
+} from './subsystem/decoration';
+export type {
+  DecorationBaseTrailRef,
+  DecorationDraft,
+  DecorationDraftComponent,
+  DecorationDraftEdge,
+  DecorationDraftTrailRef,
+  DecorationProvenance,
+  DecorationStepAnchor,
+  DecorationTrailRef,
+  SubsystemDecoration,
+} from './subsystem/decoration';
+export { DecorationPanel } from './subsystem/DecorationPanel';
+export type {
+  DecorationPanelProps,
+  DecorationPanelTrailMeta,
+} from './subsystem/DecorationPanel';
 export { GraphLayoutCover } from './subsystem/GraphLayoutCover';
 export type { GraphLayoutCoverProps } from './subsystem/GraphLayoutCover';
 export {
@@ -232,6 +277,8 @@ export type {
   SubsystemComponentEdge,
   SubsystemTrail,
   SubsystemTrailStep,
+  SubsystemSiteConstruct,
+  SubsystemTargetConstruct,
   SubsystemTrailMechanism,
   SubsystemModelDocument,
   SubsystemComponentConstruct,
@@ -315,7 +362,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={{

package/src/pierre/PierreTrailCodeView.tsx

@@ -100,11 +100,6 @@ export interface PierreTrailCodeViewProps {
    * rather than the selected step. Only fires on change, not per scroll event.
    */
   onVisibleStepChange?: (index: number) => void;
-  /**
-   * Aliases of components marked `proposed`. A step whose file can't be read
-   * but whose endpoint is proposed reads as "planned" rather than "missing".
-   */
-  proposedAliases?: ReadonlySet<string>;
   /**
    * Resolve a token to a model construct key (e.g. a component alias) for the
    * step its snippet belongs to. Return `null` when the token doesn't name a
@@ -138,10 +133,9 @@ function siteKey(step: Pick<SubsystemTrailStep, 'purl' | 'file'>): string {
 function unavailableNotice(
   step: SubsystemTrailStep,
   error: string,
-  proposed: boolean,
 ): string {
   return isFileUnavailableError(error)
-    ? fileUnavailableNotice(step.file, proposed)
+    ? fileUnavailableNotice(step.file)
     : `Couldn't load ${step.file}: ${error}`;
 }
 
@@ -206,7 +200,6 @@ export function PierreTrailCodeView({
   background: backgroundProp,
   onOpenFile,
   onVisibleStepChange,
-  proposedAliases,
   resolveSymbol,
   onSymbolClick,
 }: PierreTrailCodeViewProps) {
@@ -292,24 +285,15 @@ export function PierreTrailCodeView({
     scheduleVisibleStepReport();
   }, [scheduleVisibleStepReport]);
 
-  // A step onto a proposed component is planned work; label its missing file
-  // accordingly instead of showing a bare "not found".
-  const isProposedStep = useCallback(
-    (step: SubsystemTrailStep): boolean =>
-      proposedAliases != null &&
-      (proposedAliases.has(step.from) || proposedAliases.has(step.to)),
-    [proposedAliases],
-  );
-
   const pathsKey = useMemo(() => {
     const keys = [...new Set(trail.steps.map((s) => siteKey(s)))];
     keys.sort();
     return keys.join('\0');
   }, [trail.steps]);
 
-  // Load each site independently: one unreadable step (a proposed seam whose
-  // file isn't implemented yet) must not blank the whole trail. Failures
-  // are kept per-path and rendered as inline placeholders below.
+  // Load each site independently: one unreadable step must not blank the
+  // whole trail. Failures are kept per-path and rendered as inline
+  // placeholders below.
   useEffect(() => {
     let cancelled = false;
     setLoad({ status: 'loading' });
@@ -350,15 +334,26 @@ export function PierreTrailCodeView({
       const failure = load.unavailable.get(key);
       if (failure != null) {
         return unavailableSlice(
-          unavailableNotice(step, failure, isProposedStep(step)),
+          unavailableNotice(step, failure),
         );
       }
       const contents = load.byPath.get(key) ?? '';
-      const start = step.span?.startLine ?? 1;
-      const end = step.span?.endLine ?? start;
-      return sliceSnippetWindow(contents, start, end, contextLines, start);
+      // A resolved site construct is the frame the reader wants: show its
+      // whole declaration and focus the seam line inside it. Older models
+      // fall back to a context window around the seam.
+      const site = step.site?.span;
+      const start = site?.startLine ?? step.span?.startLine ?? 1;
+      const end = site?.endLine ?? step.span?.endLine ?? start;
+      const focus = step.span?.startLine ?? start;
+      return sliceSnippetWindow(
+        contents,
+        start,
+        end,
+        site ? 0 : contextLines,
+        focus,
+      );
     });
-  }, [load, trail.steps, contextLines, isProposedStep]);
+  }, [load, trail.steps, contextLines]);
 
   const items = useMemo((): CodeViewItem<TrailStepAnnotation>[] => {
     if (load.status !== 'ready' || slices.length === 0) return [];
@@ -392,11 +387,11 @@ export function PierreTrailCodeView({
           name: step.file,
           contents: slice.contents,
           lang: pierreLangForPath(step.file),
-          cacheKey: `${trail.id}:${index}:${step.file}:${step.span?.startLine ?? ''}:${slice.sliceStart}-${slice.sliceEnd}${failure != null ? ':unavailable' : ''}`,
+          cacheKey: `${trail.id}:${index}:${step.file}:${step.span?.startLine ?? ''}:${step.site?.span?.startLine ?? ''}-${step.site?.span?.endLine ?? ''}:${slice.sliceStart}-${slice.sliceEnd}${failure != null ? ':unavailable' : ''}`,
         },
       };
     });
-  }, [load, slices, trail.id, trail.steps, isProposedStep]);
+  }, [load, slices, trail.id, trail.steps]);
 
   const selectedLines = useMemo((): CodeViewLineSelection | null => {
     if (stepIndex == null || stepIndex < 0 || stepIndex >= slices.length) {
@@ -468,7 +463,9 @@ export function PierreTrailCodeView({
             </span>
           ) : (
             <>
-              L{step.span?.startLine ?? '?'}
+              {step.site?.span
+                ? `L${step.site.span.startLine}-${step.site.span.endLine}`
+                : `L${step.span?.startLine ?? '?'}`}
               {onOpenFile && (
                 <OpenFileHeaderButton
                   file={step.file}

package/src/pierre/fileAvailability.test.ts

@@ -23,12 +23,6 @@ describe('isFileUnavailableError', () => {
 });
 
 describe('fileUnavailableNotice', () => {
-  test('names proposed work as planned, not missing', () => {
-    expect(
-      fileUnavailableNotice('src/a.ts', true),
-    ).toBe("Proposed — src/a.ts isn't in the local checkout yet.");
-  });
-
   test('falls back to a plain not-in-checkout notice', () => {
     expect(fileUnavailableNotice('src/a.ts')).toBe(
       'Not in the local checkout: src/a.ts',

package/src/pierre/fileAvailability.ts

@@ -1,8 +1,7 @@
 /**
  * Host file reads fail with a small, stable set of messages when a path can't
- * be served from any local checkout — most often a *proposed* seam whose file
- * isn't implemented yet. These helpers detect that class of failure so the
- * Pierre views can show a proposed / not-yet-available notice instead of a raw
+ * be served from any local checkout. These helpers detect that class of failure
+ * so the Pierre views can show a not-yet-available notice instead of a raw
  * host error.
  */
 
@@ -23,15 +22,8 @@ export function isFileUnavailableError(
 }
 
 /**
- * One-line notice shown in place of a snippet whose file can't be read. When
- * the step touches a proposed component the wording names that, so a proposed
- * seam reads as "planned" rather than "missing".
+ * One-line notice shown in place of a snippet whose file can't be read.
  */
-export function fileUnavailableNotice(
-  path: string,
-  proposed?: boolean,
-): string {
-  return proposed
-    ? `Proposed — ${path} isn't in the local checkout yet.`
-    : `Not in the local checkout: ${path}`;
+export function fileUnavailableNotice(path: string): string {
+  return `Not in the local checkout: ${path}`;
 }

package/src/stories/Canvases/Subsystem/Deprecated.stories.tsx

@@ -12,9 +12,8 @@ import type {
 import { trailFromSteps } from './fixtures';
 
 /**
- * `deprecated` is the inverse of `proposed`: the claim was real, its source is
- * gone upstream. Mirrors Proposed.stories.tsx so the two temporary states read
- * as siblings — proposed = not built yet, deprecated = built once, removed since.
+ * `deprecated` marks a claim whose source is gone upstream. The node keeps a
+ * transitional marker until a cleanup pass removes it.
  */
 const meta = {
   title: 'Canvases/Subsystem/Deprecated',
@@ -154,22 +153,9 @@ const spotlightRows: Array<{ label: string; component: SubsystemComponent }> = [
       role: 'entry',
     },
   },
-  {
-    label: 'proposed (the sibling temporary state)',
-    component: {
-      alias: 'prop-fn',
-      name: 'OpenCodeV2Lifecycle',
-      construct: 'function',
-      file: '',
-      purl: PURL,
-      symbol: 'OpenCodeV2Lifecycle',
-      purpose: 'Proposed Studio host lifecycle',
-      proposed: true,
-    },
-  },
 ];
 
-/** Spotlights: slate deprecated badge + border vs live, proposed, and entry. */
+/** Spotlights: slate deprecated badge + border vs live and entry. */
 export const Spotlights: Story = {
   render: () => (
     <div

package/src/stories/Canvases/Subsystem/NodeAnatomy.stories.tsx

@@ -142,33 +142,6 @@ const CHANNELS: Channel[] = [
       declaration: storeDetail,
     },
   },
-  {
-    label: 'proposed',
-    note: 'dashed goldenrod border + right badge; fileless.',
-    component: {
-      alias: 'prop',
-      name: 'OpenCodeV2Lifecycle',
-      construct: 'function',
-      file: '',
-      purl: PURL,
-      symbol: 'OpenCodeV2Lifecycle',
-      proposed: true,
-    },
-  },
-  {
-    label: 'proposed + role',
-    note: 'proposed wins the right badge; role stays on the model.',
-    component: {
-      alias: 'prop-role',
-      name: 'startMaintainFlow',
-      construct: 'function',
-      file: '',
-      purl: PURL,
-      symbol: 'startMaintainFlow',
-      proposed: true,
-      role: 'service',
-    },
-  },
   {
     label: 'framework stereotype',
     note: 'left badge prefers "framework · stereotype"; border stays construct.',
@@ -230,11 +203,11 @@ function ChannelCell({ channel }: { channel: Channel }) {
 
 const LEGEND: Array<[string, string]> = [
   ['border color', 'construct kind (Pierre palette) — or primary when a file is open (spotlight)'],
-  ['border style', 'solid normally; dashed goldenrod when `proposed`; dotted when the node has findings'],
+  ['border style', 'solid normally; dotted when the node has findings'],
   ['border width', '2px; 4px when selected or file-matched'],
   ['corners', '8px rounded; square for `external`'],
   ['left badge (top edge)', 'construct / framework stereotype / entityKind'],
-  ['right badge (top edge)', 'role, or `proposed` (wins); storage sits beside it'],
+  ['right badge (top edge)', 'role; storage sits beside it'],
   ['bottom strip (bottom edge)', 'filename — hover only, or while that file is open'],
   ['fill', 'backgroundSecondary; opacity 0.18 when dimmed'],
   ['OCCUPIED', 'top-left · top-right · bottom-center · border · fill'],
@@ -439,8 +412,7 @@ export const IssueOverlayProposal: Story = {
           </div>
           <ul style={{ margin: 0, paddingLeft: 18, fontSize: 12, lineHeight: 1.7, color: '#b0b0b0' }}>
             <li>
-              <b>Dotted border</b> (keeps the construct color) = the node has findings — a sibling of
-              <b> proposed</b>&apos;s dashed, kept distinct so the two don&apos;t read alike.
+              <b>Dotted border</b> (keeps the construct color) = the node has findings.
             </li>
             <li>
               <b>Corner chip</b> carries severity (<b>red</b> = error / contradicts source,{' '}