@principal-ai/subsystems-react 0.44.4 → 0.46.0

package/src/stories/Subsystem/ComponentGraph/{WalkthroughAutoplay.stories.tsx → TrailAutoplay.stories.tsx}

@@ -3,20 +3,20 @@ import '@xyflow/react/dist/style.css';
 import type { Meta, StoryObj } from '@storybook/react';
 import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
 import { SubsystemComponentGraph } from '../../../subsystem/SubsystemComponentGraph';
-import type { SubsystemComponent, SubsystemWalkthrough } from '../../../subsystem/model';
+import type { SubsystemComponent, SubsystemTrail } from '../../../subsystem/model';
 
 /**
- * Autoplay-through-steps harness. Drives `autoPlayWalkthroughs` with the
+ * Autoplay-through-steps harness. Drives `autoPlayTrails` with the
  * camera/focus knobs exposed as Storybook controls so the step-focus behavior
  * can be tuned live.
  *
  * Note on current behavior: the autoplay loop advances by setting the
  * *hovered* step (dim-highlight) — it does not camera-focus each step, so
- * `walkthroughStepMode` / `zoomOnWalkthroughFocus` don't change the autoplay
+ * `trailStepMode` / `zoomOnTrailFocus` don't change the autoplay
  * camera today. This story exists to expose that gap and iterate on it.
  */
 const meta = {
-  title: 'Subsystem/ComponentGraph/WalkthroughAutoplay',
+  title: 'Subsystem/ComponentGraph/TrailAutoplay',
   component: SubsystemComponentGraph,
   parameters: { layout: 'fullscreen' },
   tags: ['autodocs'],
@@ -77,7 +77,7 @@ const components: SubsystemComponent[] = [
   },
 ];
 
-const walkthroughs: SubsystemWalkthrough[] = [
+const trails: SubsystemTrail[] = [
   {
     id: 'wt-book',
     title: 'Book a slot',
@@ -172,38 +172,38 @@ const readFile = (path: string): Promise<string> =>
 
 export const AutoplayFocus: Story = {
   args: {
-    autoPlayWalkthroughs: true,
-    walkthroughStepMode: 'focus',
-    zoomOnWalkthroughFocus: true,
-    walkthroughAutoPlayIntervalMs: 5000,
-    walkthroughFocusDurationMs: 800,
-    showWalkthroughTitle: true,
-    initialWalkthroughId: 'wt-book',
+    autoPlayTrails: true,
+    trailStepMode: 'focus',
+    zoomOnTrailFocus: true,
+    trailAutoPlayIntervalMs: 5000,
+    trailFocusDurationMs: 800,
+    showTrailTitle: true,
+    initialTrailId: 'wt-book',
   },
   argTypes: {
-    autoPlayWalkthroughs: { control: 'boolean' },
-    walkthroughStepMode: { control: 'inline-radio', options: ['focus', 'dim'] },
-    zoomOnWalkthroughFocus: { control: 'boolean' },
-    walkthroughAutoPlayIntervalMs: {
+    autoPlayTrails: { control: 'boolean' },
+    trailStepMode: { control: 'inline-radio', options: ['focus', 'dim'] },
+    zoomOnTrailFocus: { control: 'boolean' },
+    trailAutoPlayIntervalMs: {
       control: { type: 'range', min: 400, max: 8000, step: 100 },
     },
-    walkthroughFocusDurationMs: {
+    trailFocusDurationMs: {
       control: { type: 'range', min: 100, max: 2000, step: 50 },
     },
-    showWalkthroughTitle: { control: 'boolean' },
+    showTrailTitle: { control: 'boolean' },
   },
   render: (args) => (
     <div style={{ width: '100%', height: '100vh' }}>
       <SubsystemComponentGraph
         {...args}
         components={components}
-        walkthroughs={walkthroughs}
+        trails={trails}
         hideSidebar
         hideDrawer
-        edgeView="walkthroughs"
-        initialWalkthroughId="wt-book"
+        edgeView="trails"
+        initialTrailId="wt-book"
         title="Autoplay through steps"
-        description="Autoplay cycles the walkthrough steps. **Goal to refine:** each advance should camera-focus the step (and optionally open its snippet), not just dim the rest of the graph. Use the controls to compare `focus` vs `dim` and the zoom gate."
+        description="Autoplay cycles the trail steps. **Goal to refine:** each advance should camera-focus the step (and optionally open its snippet), not just dim the rest of the graph. Use the controls to compare `focus` vs `dim` and the zoom gate."
         renderFileViewer={(file, opts) => (
           <div style={{ padding: 12, fontFamily: 'monospace', fontSize: 12, color: '#bbb', whiteSpace: 'pre' }}>
             {`// ${file}`}

package/src/stories/Subsystem/ComponentGraph/WorkspacePackageFrames.stories.tsx

@@ -3,7 +3,7 @@ import type { Meta, StoryObj } from '@storybook/react';
 import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
 import { SubsystemComponentGraph } from '../../../subsystem/SubsystemComponentGraph';
 import type { SubsystemComponent } from '../../../subsystem/model';
-import { graphSpecFromHops } from './fixtures';
+import { graphSpecFromSteps } from './fixtures';
 
 const meta = {
   title: 'Subsystem/ComponentGraph/WorkspacePackages',
@@ -114,7 +114,7 @@ const components: SubsystemComponent[] = [
   },
 ];
 
-const spec = graphSpecFromHops([
+const spec = graphSpecFromSteps([
   ['read-file', 'get-model', 'calls'],
   ['model-view', 'component-graph', 'uses'],
   ['component-graph', 'file-drawer', 'calls'],
@@ -125,7 +125,7 @@ export const PackageOwnedProcess: Story = {
   name: 'Package-owned process · library outside',
   args: {
     components,
-    walkthroughs: spec.walkthroughs,
+    trails: spec.trails,
     graphTitle: 'Opening a file — app package owns the process',
   },
   render: (args) => (

package/src/stories/Subsystem/ComponentGraph/fixtures.ts

@@ -1,8 +1,8 @@
 import type {
   SubsystemComponent,
   SubsystemComponentEdge,
-  SubsystemWalkthrough,
-  SubsystemWalkthroughMechanism,
+  SubsystemTrail,
+  SubsystemTrailMechanism,
 } from '../../../subsystem/model';
 import type { GraphifyComponentDetail } from '../../../graphify';
 
@@ -24,16 +24,16 @@ export function components(
   }));
 }
 
-/** Story helper: one walkthrough whose hops derive Set B display edges. */
-export function walkthroughFromHops(
+/** Story helper: one trail whose steps derive Set B display edges. */
+export function trailFromSteps(
   id: string,
   title: string,
-  hops: Array<[from: string, to: string, mechanism: SubsystemWalkthroughMechanism, file: string, line: number, symbol?: string]>,
-): SubsystemWalkthrough {
+  steps: Array<[from: string, to: string, mechanism: SubsystemTrailMechanism, file: string, line: number, symbol?: string]>,
+): SubsystemTrail {
   return {
     id,
     title,
-    steps: hops.map(([from, to, mechanism, file, line, symbol]) => ({
+    steps: steps.map(([from, to, mechanism, file, line, symbol]) => ({
       from,
       to,
       mechanism,
@@ -45,35 +45,23 @@ export function walkthroughFromHops(
   };
 }
 
-/** @deprecated story helper — prefer `graphSpecFromHops` + `walkthroughFromHops`. */
-export function edges(
+/** Turn every spec entry into a trail step — the sole authored edge form. */
+export function graphSpecFromSteps(
   spec: Array<[from: string, to: string, mechanism: SubsystemComponentEdge['mechanism']]>,
-): SubsystemComponentEdge[] {
-  return spec.map(([from, to, mechanism], i) => ({
-    id: `e${i}`,
+): { trails?: SubsystemTrail[] } {
+  const steps: SubsystemTrail['steps'] = spec.map(([from, to, mechanism]) => ({
     from,
     to,
-    mechanism,
-  }));
-}
-
-/** Turn every spec entry into a walkthrough hop — the sole authored edge form. */
-export function graphSpecFromHops(
-  spec: Array<[from: string, to: string, mechanism: SubsystemComponentEdge['mechanism']]>,
-): { walkthroughs?: SubsystemWalkthrough[] } {
-  const hops: SubsystemWalkthrough['steps'] = spec.map(([from, to, mechanism]) => ({
-    from,
-    to,
-    mechanism: mechanism as SubsystemWalkthroughMechanism,
+    mechanism: mechanism as SubsystemTrailMechanism,
     file: 'story-placeholder.ts',
     line: 1,
     purl: 'pkg:github/storybook/fixture#story-placeholder.ts',
     symbol: from,
   }));
   return {
-    walkthroughs:
-      hops.length > 0
-        ? [{ id: 'story-hops', title: 'Story hops', steps: hops }]
+    trails:
+      steps.length > 0
+        ? [{ id: 'story-steps', title: 'Story steps', steps: steps }]
         : undefined,
   };
 }
@@ -153,19 +141,11 @@ export const investigateOnlyComponents: SubsystemComponent[] = [
   },
 ];
 
-const investigateSpec = graphSpecFromHops([
+const investigateSpec = graphSpecFromSteps([
   ['v1', 'input', 'produces'],
   ['v2', 'input', 'produces'],
   ['input', 'acc', 'feeds'],
   ['acc', 'out', 'produces'],
 ]);
 
-export const investigateOnlyWalkthroughs = investigateSpec.walkthroughs;
-
-/** @deprecated use investigateOnlyWalkthroughs */
-export const investigateOnlyEdges: SubsystemComponentEdge[] = edges([
-  ['v1', 'input', 'produces'],
-  ['v2', 'input', 'produces'],
-  ['input', 'acc', 'feeds'],
-  ['acc', 'out', 'produces'],
-]);
+export const investigateOnlyTrails = investigateSpec.trails;

package/src/subsystem/C4Graph.tsx

@@ -3,12 +3,12 @@
  *
  * Prototype test case: feed it a `C4Model` from `toC4()` and it draws the
  * system as a compound frame, its containers (or components) as boxes, and
- * externals/actors outside the system. `walkthrough` hops render as flow
+ * externals/actors outside the system. `trail` steps render as flow
  * edges. Click a box to list the source components it rolled up.
  *
  * Same interaction language as the other graphs: React Flow + ELK + the shared
  * `GRAPH_NAV_PROPS` chrome. Deliberately small — no measurement passes, no
- * drawers, no walkthrough playback.
+ * drawers, no trail playback.
  */
 
 import { useEffect, useMemo, useState } from 'react';

package/src/subsystem/ConstructsCatalog.tsx

@@ -1,6 +1,6 @@
 /**
  * ConstructsCatalog — master/detail for a constructs-only subsystem
- * (components, no topology or walkthrough edges).
+ * (components, no topology or trail edges).
  *
  * Left: the model's files as a tree; clicking a file toggles its
  * constructs. Right: signatures grouped by repo, and within a repo stacked
@@ -60,7 +60,6 @@ export interface ConstructsCatalogProps {
   sidebarExtra?: ReactNode;
   sidebarAfterDescription?: ReactNode;
   renderFileViewer?: (file: string, opts?: SubsystemOpenFileOptions) => ReactNode;
-  renderFileView?: (component: SubsystemComponent) => ReactNode;
   onFileSelect?: (file: string) => void;
   componentVerification?: ComponentVerificationState | null;
   /** Referenced-symbol click → host graphify lookup (purl/file from the card). */
@@ -192,7 +191,6 @@ export function ConstructsCatalog({
   sidebarExtra,
   sidebarAfterDescription,
   renderFileViewer,
-  renderFileView,
   onFileSelect,
   componentVerification,
   onInspectSymbol,
@@ -537,19 +535,7 @@ export function ConstructsCatalog({
     [components, show, searchActive],
   );
 
-  const fileViewer = useMemo(() => {
-    if (renderFileViewer) return renderFileViewer;
-    if (renderFileView) {
-      const byFile = new Map(
-        components.filter((c) => c.file).map((c) => [c.file, c] as const),
-      );
-      return (file: string, _opts?: SubsystemOpenFileOptions) => {
-        const comp = byFile.get(file);
-        return comp ? renderFileView(comp) : null;
-      };
-    }
-    return undefined;
-  }, [renderFileViewer, renderFileView, components]);
+  const fileViewer = renderFileViewer;
 
   const fileViewerRef = useRef(fileViewer);
   fileViewerRef.current = fileViewer;

package/src/subsystem/DiagnosticToggle.tsx

@@ -4,7 +4,7 @@
  * A compact button that lives in the sidebar title row (beside the description
  * toggle). It carries the *status* of the graph's last verification pass in its
  * icon color + count, and toggles the sidebar between the diagnostics list and
- * the normal files/walkthroughs view. The graph owns that view; this component
+ * the normal files/trails view. The graph owns that view; this component
  * only surfaces state and calls `onToggle`.
  *
  * Status → color (theme):

package/src/subsystem/FileDrawer.tsx

@@ -1,7 +1,7 @@
 /**
  * FileDrawer — bottom panel that slides up from the bottom of the graph area
- * to show file / walkthrough code. Opened by sidebar file-tree clicks,
- * declaration links, and walkthrough step focus; content is injected as
+ * to show file / trail code. Opened by sidebar file-tree clicks,
+ * declaration links, and trail step focus; content is injected as
  * children by the graph component.
  */
 

package/src/subsystem/IssueList.focus.test.tsx

@@ -35,9 +35,9 @@ const issues: SubsystemIssue[] = [
   {
     id: 'wl',
     severity: 'info',
-    kind: 'walkthrough',
-    message: 'walkthrough finding',
-    target: { kind: 'walkthrough', id: 'w', label: 'Walkthrough' },
+    kind: 'trail',
+    message: 'trail finding',
+    target: { kind: 'trail', id: 'w', label: 'Trail' },
   },
 ];
 
@@ -87,7 +87,7 @@ describe('collapsing a category retracts the focus it established', () => {
     fireEvent.click(category('Constructs'));
     fireEvent.click(card('Alpha'));
 
-    fireEvent.click(category('Walkthrough'));
+    fireEvent.click(category('Trail'));
     expect(events).toEqual(['select:ct', 'deselect:ct']);
   });
 

package/src/subsystem/IssueList.icon.test.tsx

@@ -27,7 +27,7 @@ afterEach(cleanup);
 const issue: SubsystemIssue = {
   id: 'i1',
   severity: 'info',
-  kind: 'walkthrough',
+  kind: 'trail',
   message: 'Step 2 references a line that moved.',
   target: {
     kind: 'step',
@@ -59,7 +59,7 @@ const hasIcon = (container: HTMLElement, name: string) =>
 
 describe('issue card icon', () => {
   test('a step finding wears the step icon, not the flow lane icon', () => {
-    // The audit kind is `walkthrough` (the whole flow), so without a
+    // The audit kind is `trail` (the whole flow), so without a
     // target-shape icon this card would read as a comment on the flow rather
     // than on the one step that is wrong.
     const { container } = renderCard();
@@ -69,7 +69,7 @@ describe('issue card icon', () => {
 
   test('a finding about the flow as a whole keeps the lane icon', () => {
     const { container } = renderCard({
-      target: { kind: 'walkthrough', id: 'flow-1', label: 'Checkout' },
+      target: { kind: 'trail', id: 'flow-1', label: 'Checkout' },
     });
     expect(hasIcon(container, 'route')).toBe(true);
     expect(hasIcon(container, 'footprints')).toBe(false);

package/src/subsystem/IssueList.tsx

@@ -39,14 +39,14 @@ export type SubsystemIssueSeverity = 'error' | 'info';
 export type SubsystemIssueTargetKind =
   | 'component'
   | 'module'
-  | 'walkthrough'
+  | 'trail'
   | 'step'
   | 'repo'
   | 'graph';
 
 /**
  * The four verification layers, in order. Mirrors the docs' progression:
- * constructs → static topology → dynamic topology → walkthrough.
+ * constructs → static topology → dynamic topology → trail.
  * Static topology = package/module (containment); dynamic topology = process
  * (runtime).
  */
@@ -55,7 +55,7 @@ export type SubsystemIssueCategory =
   | 'construct'
   | 'static-topology'
   | 'dynamic-topology'
-  | 'walkthrough';
+  | 'trail';
 
 /** Layer order + display names, shared by the list and its headers. */
 export const SUBSYSTEM_ISSUE_CATEGORIES: SubsystemIssueCategory[] = [
@@ -63,7 +63,7 @@ export const SUBSYSTEM_ISSUE_CATEGORIES: SubsystemIssueCategory[] = [
   'construct',
   'static-topology',
   'dynamic-topology',
-  'walkthrough',
+  'trail',
 ];
 
 /** Per-category header icon — mirrors the Maintainer tab's lane icons. */
@@ -75,7 +75,7 @@ export const SUBSYSTEM_ISSUE_CATEGORY_ICON: Record<
   construct: Component,
   'static-topology': Network,
   'dynamic-topology': Server,
-  walkthrough: Route,
+  trail: Route,
 };
 
 export const SUBSYSTEM_ISSUE_CATEGORY_LABEL: Record<
@@ -86,7 +86,7 @@ export const SUBSYSTEM_ISSUE_CATEGORY_LABEL: Record<
   construct: 'Constructs',
   'static-topology': 'Static topology',
   'dynamic-topology': 'Dynamic topology',
-  walkthrough: 'Walkthrough',
+  trail: 'Trail',
 };
 
 /** Default `kind` → layer. Module containment is static; process nest is dynamic. */
@@ -103,7 +103,7 @@ const KIND_CATEGORY: Record<string, SubsystemIssueCategory> = {
   graphify_unavailable: 'repo',
   boundary_module_file_mismatch: 'static-topology',
   boundary_process_nest_disagree: 'dynamic-topology',
-  walkthrough: 'walkthrough',
+  trail: 'trail',
 };
 
 /**
@@ -117,7 +117,7 @@ export function issueCategory(issue: SubsystemIssue): SubsystemIssueCategory {
 /**
  * Construct-layer verification rung for a finding kind (file → symbol →
  * declaration → type → signature), or null for findings outside that ladder
- * (topology / walkthrough / repo). Drives the node overlay's earliest-rung chip.
+ * (topology / trail / repo). Drives the node overlay's earliest-rung chip.
  */
 const KIND_RUNG: Record<string, SubsystemIssueRung> = {
   missing_file: 'file',
@@ -168,7 +168,7 @@ export const ISSUE_KIND_ICON: Record<string, LucideIcon> = {
 
 /**
  * Icons for target SHAPES that are more specific than their verification lane.
- * An audit `kind` of `walkthrough` covers the whole flow, so a finding about
+ * An audit `kind` of `trail` covers the whole flow, so a finding about
  * one step of it would otherwise wear the lane's `Route` icon and read as a
  * comment on the flow rather than on the step that is actually wrong.
  */
@@ -188,8 +188,8 @@ export interface SubsystemIssueTarget {
   /** Optional sub-label (step number, …). */
   detail?: string;
   /**
-   * For a `step` target: the walkthrough id, plus a 0-based index into that
-   * walkthrough's steps. Carried structurally rather than parsed back out of
+   * For a `step` target: the trail id, plus a 0-based index into that
+   * trail's steps. Carried structurally rather than parsed back out of
    * `detail` ("step 7") so focusing a step is exact rather than best-effort —
    * `detail` is a display string and is free to change its phrasing.
    */
@@ -243,7 +243,7 @@ const KIND_LABEL: Record<string, string> = {
   graphify_unavailable: 'Graphify cache unavailable',
   boundary_module_file_mismatch: 'Declaration file outside module',
   boundary_process_nest_disagree: 'Module spans multiple process contexts',
-  walkthrough: 'Step issue',
+  trail: 'Step issue',
 };
 
 /** Label for an issue's kind. Explicit `kindLabel` wins; unknown kinds humanize. */
@@ -275,8 +275,8 @@ const KIND_ORDER: Record<string, number> = {
   boundary_module_file_mismatch: 23,
   // Runtime topology — process containment
   boundary_process_nest_disagree: 30,
-  // Walkthrough
-  walkthrough: 40,
+  // Trail
+  trail: 40,
 };
 
 const KIND_ORDER_FALLBACK = 100;

package/src/subsystem/SubsystemAggregateGraph.tsx

@@ -4,12 +4,12 @@
  * Same stack and interaction language as SubsystemComponentGraph
  * (React Flow + ELK + custom nodes + select/hover), but purpose-built for
  * composed views: nodes are process / module frames (plus one ungrouped
- * bucket), edges are the deduped walkthrough flows between them.
+ * bucket), edges are the deduped trail flows between them.
  *
  * Deliberately leaner than the component graph: fixed node sizes (no
  * measurement passes), flat ELK layout (no compound groups, so the
  * double-parent failure mode is structurally impossible), no edge labels,
- * no walkthrough playback, no drawers. Frame detail (members, models)
+ * no trail playback, no drawers. Frame detail (members, models)
  * renders in a side panel.
  */
 
@@ -57,7 +57,7 @@ export interface AggregateFrameEdge {
   from: string;
   to: string;
   mechanisms: string[];
-  walkthroughIds: string[];
+  trailIds: string[];
   steps: number;
   /** Real member endpoint behind a hub-routed edge (see aggregate). */
   source?: string;