@principal-ai/subsystems-react 0.44.4 → 0.45.0

package/src/stories/Subsystem/ComponentDeclarationAudit.stories.tsx

@@ -302,13 +302,13 @@ const augmentationCases: { label: string; component: SubsystemComponent }[] = [
     label: 'augmented — no own declaration (bare signature today)',
     component: {
       alias: 'aug-bare',
-      name: 'WalkthroughsPanel',
+      name: 'TrailsPanel',
       construct: 'function',
-      file: 'packages/subsystems-react/src/subsystem/WalkthroughsPanel.tsx',
+      file: 'packages/subsystems-react/src/subsystem/TrailsPanel.tsx',
       purl: 'pkg:github/principal-ai/subsystem-modeling',
-      symbol: 'WalkthroughsPanel',
+      symbol: 'TrailsPanel',
       signatureAugmentation: {
-        parameters: [{ type: 'WalkthroughsPanelProps' }],
+        parameters: [{ type: 'TrailsPanelProps' }],
         returnType: 'JSX.Element',
       },
     },
@@ -337,15 +337,15 @@ const augmentationCases: { label: string; component: SubsystemComponent }[] = [
     label: 'baseline — no augmentation',
     component: {
       alias: 'no-aug',
-      name: 'reorderWalkthroughs',
+      name: 'reorderTrails',
       construct: 'function',
       file: 'packages/subsystems-react/src/subsystem/model.ts',
       purl: 'pkg:github/principal-ai/subsystem-modeling',
-      symbol: 'reorderWalkthroughs',
+      symbol: 'reorderTrails',
       declaration: {
         kind: 'function',
-        parameters: [{ name: 'walkthroughs', type: 'SubsystemWalkthrough[]' }],
-        returnType: 'SubsystemWalkthrough[]',
+        parameters: [{ name: 'trails', type: 'SubsystemTrail[]' }],
+        returnType: 'SubsystemTrail[]',
       } satisfies GraphifyComponentDetail,
     },
   },

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

@@ -6,11 +6,11 @@ import {
   SubsystemModelTransition,
   type SubsystemTransitionStep,
 } from '../../../subsystem/SubsystemModelTransition';
-import type { SubsystemComponent, SubsystemWalkthrough } from '../../../subsystem/model';
+import type { SubsystemComponent, SubsystemTrail } from '../../../subsystem/model';
 
 /**
  * Harness for `SubsystemModelTransition` — the same progression cases
- * (constructs → static → dynamic → walkthrough) animated between, with a nav.
+ * (constructs → static → dynamic → trail) animated between, with a nav.
  */
 
 const meta = {
@@ -34,7 +34,7 @@ const components: SubsystemComponent[] = [
   { alias: 'Database', name: 'Database', construct: 'external', role: 'service', purl: 'external', file: '' },
 ];
 
-const walkthroughs: SubsystemWalkthrough[] = [
+const trails: SubsystemTrail[] = [
   {
     id: 'wt-book',
     title: 'Guest books',
@@ -56,7 +56,7 @@ const walkthroughs: SubsystemWalkthrough[] = [
   },
 ];
 
-const LABELS = ['Constructs', 'Static topology', 'Dynamic topology', 'Walkthrough'];
+const LABELS = ['Constructs', 'Static topology', 'Dynamic topology', 'Trail'];
 
 const STEPS: SubsystemTransitionStep[] = [
   {
@@ -72,22 +72,22 @@ const STEPS: SubsystemTransitionStep[] = [
     moduleNesting: 'path',
   },
   {
-    model: { title: 'Booking', components, walkthroughs },
+    model: { title: 'Booking', components, trails },
     moduleNesting: 'path',
-    autoPlayWalkthroughs: true,
-    showWalkthroughTitle: true,
+    autoPlayTrails: true,
+    showTrailTitle: true,
   },
 ];
 
 const STEP_MS = 4000;
 
-/** Dwell long enough for an autoplaying step to cycle all its hops. */
+/** Dwell long enough for an autoplaying step to cycle all its steps. */
 function dwellFor(index: number): number {
   const step = STEPS[index];
-  if (step?.autoPlayWalkthroughs) {
-    const hops = step.model.walkthroughs?.reduce((n, w) => n + w.steps.length, 0) ?? 0;
-    // Whole-flow phase + one tick per hop.
-    if (hops > 0) return (hops + 1) * STEP_MS;
+  if (step?.autoPlayTrails) {
+    const steps = step.model.trails?.reduce((n, w) => n + w.steps.length, 0) ?? 0;
+    // Whole-flow phase + one tick per step.
+    if (steps > 0) return (steps + 1) * STEP_MS;
   }
   return 3200;
 }
@@ -109,7 +109,7 @@ function Harness() {
       <SubsystemModelTransition
         steps={steps}
         activeIndex={active}
-        walkthroughAutoPlayIntervalMs={STEP_MS}
+        trailAutoPlayIntervalMs={STEP_MS}
       />
       <div style={{ position: 'absolute', top: 12, left: 12, display: 'flex', gap: 8, zIndex: 10 }}>
         {LABELS.map((label, i) => (

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

@@ -5,7 +5,7 @@ import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme
 import { SubsystemComponentGraph } from '../../../subsystem/SubsystemComponentGraph';
 import type { SubsystemComponent, SubsystemComponentEdge } from '../../../subsystem/model';
 import type { GraphifyComponentDetail } from '../../../graphify';
-import { investigateOnlyComponents, investigateOnlyWalkthroughs } from './fixtures';
+import { investigateOnlyComponents, investigateOnlyTrails } from './fixtures';
 
 const meta = {
   title: 'Subsystem/ComponentGraph/Appearance',
@@ -32,7 +32,7 @@ export const NarrowMaxWidth: Story = {
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
       <SubsystemComponentGraph
         components={investigateOnlyComponents}
-        walkthroughs={investigateOnlyWalkthroughs}
+        trails={investigateOnlyTrails}
         maxNodeWidth={140}
       />
     </div>

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

@@ -4,7 +4,7 @@ import type { Meta, StoryObj } from '@storybook/react';
 import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
 import { SubsystemComponentGraph } from '../../../subsystem/SubsystemComponentGraph';
 import type { SubsystemComponent, SubsystemComponentEdge } from '../../../subsystem/model';
-import { components, graphSpecFromHops } from './fixtures';
+import { components, graphSpecFromSteps } from './fixtures';
 
 const meta = {
   title: 'Subsystem/ComponentGraph/Basics',
@@ -33,7 +33,7 @@ const twoNodeComponents = components([
   ['dst', 'SessionReader', 'class', 'SessionReader.ts', 'pkg:github/principal-ai/agent-monitoring', 'normalizes sessions into events'],
 ]);
 
-const twoNodeEdges = graphSpecFromHops([
+const twoNodeEdges = graphSpecFromSteps([
   ['src', 'dst', 'calls'],
 ]);
 
@@ -44,7 +44,7 @@ function TwoNodeDemo({ showEdgeLabels = true }: { showEdgeLabels?: boolean }) {
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
       <SubsystemComponentGraph
         components={twoNodeComponents}
-        walkthroughs={twoNodeEdges.walkthroughs}
+        trails={twoNodeEdges.trails}
         onSelect={(id) => setSelected(id)}
         onEdgeSelect={(e) => setSelectedEdge(e)}
         showEdgeLabels={showEdgeLabels}
@@ -102,11 +102,11 @@ function PlaygroundDemo({ leftCount, rightCount, showEdgeLabels }: { leftCount:
       edgeSpec.push([`l${i}`, `r${j}`, 'calls']);
     }
   }
-  const graph = graphSpecFromHops(edgeSpec);
+  const graph = graphSpecFromSteps(edgeSpec);
 
   return (
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
-      <SubsystemComponentGraph components={comps} walkthroughs={graph.walkthroughs} showEdgeLabels={showEdgeLabels} />
+      <SubsystemComponentGraph components={comps} trails={graph.trails} showEdgeLabels={showEdgeLabels} />
     </div>
   );
 }

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

@@ -5,7 +5,7 @@ import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme
 import { SubsystemComponentGraph } from '../../../subsystem/SubsystemComponentGraph';
 import type { SubsystemComponent, SubsystemComponentEdge } from '../../../subsystem/model';
 import type { GraphifyComponentDetail } from '../../../graphify';
-import { components, graphSpecFromHops, readerDetail, investigateOnlyComponents, investigateOnlyWalkthroughs } from './fixtures';
+import { components, graphSpecFromSteps, readerDetail, investigateOnlyComponents, investigateOnlyTrails } from './fixtures';
 
 const meta = {
   title: 'Subsystem/ComponentGraph/Captures',
@@ -37,7 +37,7 @@ const v2ReaderComponents = components([
   ['registry', 'supported-agents', 'function', 'supported-agents.ts', 'pkg:github/principal-ai/agent-monitoring', 'registry of supported agents (the shared seam)', 'registerAgent'],
 ]);
 
-const v2ReaderEdges = graphSpecFromHops([
+const v2ReaderEdges = graphSpecFromSteps([
   ['transcript', 'reader', 'calls'],
   ['paths', 'reader', 'uses'],
   ['capture', 'reader', 'calls'],
@@ -55,7 +55,7 @@ function V2ReaderDemo() {
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
       <SubsystemComponentGraph
         components={v2ReaderComponents}
-        walkthroughs={v2ReaderEdges.walkthroughs}
+        trails={v2ReaderEdges.trails}
         onSelect={(id) => setSelected(id)}
         onEdgeSelect={(e) => setSelectedEdge(e)}
       />
@@ -80,7 +80,7 @@ export const V2ReaderSubsystem: Story = {
 export const InvestigateOnly: Story = {
   render: () => (
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
-      <SubsystemComponentGraph components={investigateOnlyComponents} walkthroughs={investigateOnlyWalkthroughs} />
+      <SubsystemComponentGraph components={investigateOnlyComponents} trails={investigateOnlyTrails} />
     </div>
   ),
 };
@@ -98,7 +98,7 @@ const minimalComponents = components([
   ['transcript', 'transcript', 'function', 'transcript.ts', 'pkg:github/principal-ai/agent-monitoring', 'parses session records + type guards', 'transcript'],
 ]);
 
-const sharedEdges = graphSpecFromHops([
+const sharedEdges = graphSpecFromSteps([
   ['transcript', 'record', 'uses'],
   ['reader', 'normalize', 'calls'],
   ['normalize', 'record', 'uses'],
@@ -137,7 +137,7 @@ function MinimalVsResolvedDemo({ resolved }: { resolved: boolean }) {
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
       <SubsystemComponentGraph
         components={resolved ? resolvedComponents : minimalComponents}
-        walkthroughs={sharedEdges.walkthroughs}
+        trails={sharedEdges.trails}
         onSelect={(id) => setSelected(id)}
       />
       <div style={{ marginTop: 8, fontFamily: 'monospace', fontSize: 12, color: '#aaa' }}>
@@ -191,7 +191,7 @@ const investigationComponents: SubsystemComponent[] = [
   },
 ];
 
-const investigationEdges = graphSpecFromHops([
+const investigationEdges = graphSpecFromSteps([
   ['adapter', 'contracts', 'uses'],
   ['ingestion', 'adapter', 'uses'],
   ['ingestion', 'contracts', 'uses'],
@@ -203,7 +203,7 @@ function InvestigationDemo() {
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
       <SubsystemComponentGraph
         components={investigationComponents}
-        walkthroughs={investigationEdges.walkthroughs}
+        trails={investigationEdges.trails}
         onSelect={(id) => setSelected(id)}
       />
       <div style={{ marginTop: 8, fontFamily: 'monospace', fontSize: 12, color: '#aaa' }}>

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

@@ -5,7 +5,7 @@ import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme
 import { SubsystemComponentGraph } from '../../../subsystem/SubsystemComponentGraph';
 import type { SubsystemComponent, SubsystemComponentEdge } from '../../../subsystem/model';
 import type { GraphifyCustomEntityDetail } from '../../../graphify';
-import { graphSpecFromHops } from './fixtures';
+import { graphSpecFromSteps } from './fixtures';
 
 /** Authored attributes surfaced in the declaration panel. */
 function entityDetail(attributes: Array<[string, string]>): GraphifyCustomEntityDetail {
@@ -143,7 +143,7 @@ const components: SubsystemComponent[] = [
   },
 ];
 
-const entityGraph = graphSpecFromHops([
+const entityGraph = graphSpecFromSteps([
   ['wr', 'store', 'feeds'],
   ['store', 'tech', 'feeds'],
   ['tech', 'sup', 'watches'],
@@ -178,7 +178,7 @@ export const NovaTechWorkRequests: Story = {
         title="Custom entities — NovaTech work-request chain"
         description="Persons, an agent, and a queue as `custom_entity` nodes (badge = entityKind). Actors keep the themed coral; the agent and queue wear authored `color` overrides. Click a node for its declaration — `entity 'Name' — kind` plus authored `attributes` (key: value)."
         components={components}
-        walkthroughs={entityGraph.walkthroughs}
+        trails={entityGraph.trails}
       />
     </div>
   ),

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

@@ -7,7 +7,7 @@ import {
   SubsystemDiagnosticToggle,
   type SubsystemDiagnosticStatus,
 } from '../../../subsystem/DiagnosticToggle';
-import { components, graphSpecFromHops } from './fixtures';
+import { components, graphSpecFromSteps } from './fixtures';
 
 const meta = {
   title: 'Subsystem/ComponentGraph/Diagnostics',
@@ -34,7 +34,7 @@ const graphComponents = components([
   ['caller', 'Web client', 'external', '', 'external', undefined, undefined],
 ]);
 
-const graphEdges = graphSpecFromHops([
+const graphEdges = graphSpecFromSteps([
   ['caller', 'entry', 'calls'],
   ['entry', 'store', 'writes'],
   ['entry', 'stripe', 'calls'],
@@ -81,7 +81,7 @@ export const GraphClean: Story = {
     <div style={{ width: '100%', height: '100vh' }}>
       <SubsystemComponentGraph
         components={graphComponents}
-        walkthroughs={graphEdges.walkthroughs}
+        trails={graphEdges.trails}
         title="Checkout"
         description={GRAPH_DESCRIPTION}
         diagnostic={{ status: 'ok', onToggle: () => {} }}
@@ -95,7 +95,7 @@ export const GraphWithIssues: Story = {
     <div style={{ width: '100%', height: '100vh' }}>
       <SubsystemComponentGraph
         components={graphComponents}
-        walkthroughs={graphEdges.walkthroughs}
+        trails={graphEdges.trails}
         title="Checkout"
         description={GRAPH_DESCRIPTION}
         diagnostic={{ status: 'issues', issueCount: 3, onToggle: () => {} }}
@@ -110,7 +110,7 @@ export const GraphStale: Story = {
     <div style={{ width: '100%', height: '100vh' }}>
       <SubsystemComponentGraph
         components={graphComponents}
-        walkthroughs={graphEdges.walkthroughs}
+        trails={graphEdges.trails}
         title="Checkout"
         description={GRAPH_DESCRIPTION}
         diagnostic={{ status: 'issues', issueCount: 3, stale: true, onToggle: () => {} }}
@@ -125,7 +125,7 @@ export const GraphChipOnly: Story = {
     <div style={{ width: '100%', height: '100vh' }}>
       <SubsystemComponentGraph
         components={graphComponents}
-        walkthroughs={graphEdges.walkthroughs}
+        trails={graphEdges.trails}
         title="Checkout"
         diagnostic={{ status: 'gaps', issueCount: 2, onToggle: () => {} }}
       />

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

@@ -4,7 +4,7 @@ import type { Meta, StoryObj } from '@storybook/react';
 import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
 import { SubsystemComponentGraph } from '../../../subsystem/SubsystemComponentGraph';
 import type { SubsystemEdgeView, SubsystemGraphifyRelation } from '../../../subsystem/model';
-import { components, walkthroughFromHops } from './fixtures';
+import { components, trailFromSteps } from './fixtures';
 
 const meta = {
   title: 'Subsystem/ComponentGraph/EdgeViews',
@@ -28,9 +28,9 @@ type Story = StoryObj<typeof meta>;
 // ---------------------------------------------------------------------------
 // A graph that carries BOTH edge sources between overlapping node pairs:
 //   svc --references--> reader  (graphify static edge)
-//   svc --calls--> reader       (runtime hop)
+//   svc --calls--> reader       (runtime step)
 //   store --references--> db    (graphify static edge)
-//   store --calls--> db         (runtime hop)
+//   store --calls--> db         (runtime step)
 // so switching the label view visibly changes which labels appear.
 // ---------------------------------------------------------------------------
 const labelViewComponents = components([
@@ -49,14 +49,14 @@ const labelViewGraphify: SubsystemGraphifyRelation[] = [
   { id: 'g-reader-event', from: 'reader', to: 'event', relation: 'references' },
 ];
 
-const labelViewWalkthroughs = [
-  walkthroughFromHops('tl-capture', 'Capture session', [
+const labelViewTrails = [
+  trailFromSteps('tl-capture', 'Capture session', [
     ['api', 'svc', 'calls', 'src/api/handler.ts', 42],
     ['svc', 'store', 'writes', 'src/session/SessionService.ts', 88],
     ['store', 'db', 'calls', 'src/session/SessionStore.ts', 120],
     ['svc', 'event', 'produces', 'src/session/SessionService.ts', 95],
   ]),
-  walkthroughFromHops('tl-normalize', 'Normalize records', [
+  trailFromSteps('tl-normalize', 'Normalize records', [
     ['svc', 'reader', 'calls', 'src/session/SessionService.ts', 61],
     ['reader', 'event', 'produces', 'src/session/SessionReader.ts', 77],
   ]),
@@ -64,7 +64,7 @@ const labelViewWalkthroughs = [
 
 const VIEWS: { value: SubsystemEdgeView; label: string }[] = [
   { value: 'graphify', label: 'Graphify' },
-  { value: 'walkthroughs', label: 'Walkthroughs' },
+  { value: 'trails', label: 'Trails' },
 ];
 
 function EdgeViewDemo() {
@@ -119,9 +119,9 @@ function EdgeViewDemo() {
         <SubsystemComponentGraph
           components={labelViewComponents}
           graphifyRelations={labelViewGraphify}
-          walkthroughs={labelViewWalkthroughs}
+          trails={labelViewTrails}
           title="edge views"
-          description="The graphify and walkthrough edge sources are disjoint and never shown together. Toggle the view: **Graphify** draws `svc --references--> reader`; **Walkthroughs** draws `svc --calls--> reader`. The model is the same either way."
+          description="The graphify and trail edge sources are disjoint and never shown together. Toggle the view: **Graphify** draws `svc --references--> reader`; **Trails** draws `svc --calls--> reader`. The model is the same either way."
           showEdgeLabels={showEdgeLabels}
           edgeView={view}
         />
@@ -130,7 +130,7 @@ function EdgeViewDemo() {
   );
 }
 
-/** Interactive toggle between the `graphify` and `walkthroughs` edge views. */
+/** Interactive toggle between the `graphify` and `trails` edge views. */
 export const ToggleEdgeView: Story = {
   render: () => <EdgeViewDemo />,
 };
@@ -142,7 +142,7 @@ export const ViewControl: Story = {
       <SubsystemComponentGraph
         components={labelViewComponents}
         graphifyRelations={labelViewGraphify}
-        walkthroughs={labelViewWalkthroughs}
+        trails={labelViewTrails}
         showEdgeLabels={args.showEdgeLabels}
         edgeView={args.edgeView}
       />
@@ -154,6 +154,6 @@ export const ViewControl: Story = {
   },
   argTypes: {
     showEdgeLabels: { control: 'boolean' },
-    edgeView: { control: 'inline-radio', options: ['graphify', 'walkthroughs'] },
+    edgeView: { control: 'inline-radio', options: ['graphify', 'trails'] },
   },
 };

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

@@ -3,9 +3,9 @@ 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 { PierreWalkthroughCodeView } from '../../../pierre';
-import type { WalkthroughViewerContext } from '../../../subsystem/SubsystemComponentGraph';
+import type { SubsystemComponent, SubsystemTrail } from '../../../subsystem/model';
+import { PierreTrailCodeView } from '../../../pierre';
+import type { TrailViewerContext } from '../../../subsystem/SubsystemComponentGraph';
 
 const meta = {
   title: 'Subsystem/ComponentGraph/Flows',
@@ -129,7 +129,7 @@ const drawingComponents: SubsystemComponent[] = [
 const STORY_PURL = 'pkg:github/principal-ai/desktop-app';
 const stepPurl = (file: string) => `${STORY_PURL}#${file}`;
 
-const drawingWalkthroughs: SubsystemWalkthrough[] = [
+const drawingTrails: SubsystemTrail[] = [
   {
     id: 'tl-open-drawing',
     title: 'Open drawing',
@@ -165,17 +165,17 @@ const drawingWalkthroughs: SubsystemWalkthrough[] = [
 ];
 
 function FlowsDemo() {
-  const renderWalkthroughViewer = useCallback(
+  const renderTrailViewer = useCallback(
     ({
-      walkthrough,
+      trail,
       stepIndex,
       onOpenFile,
       proposedAliases,
       resolveSymbol,
       onSymbolClick,
-    }: WalkthroughViewerContext) => (
-      <PierreWalkthroughCodeView
-        walkthrough={walkthrough}
+    }: TrailViewerContext) => (
+      <PierreTrailCodeView
+        trail={trail}
         stepIndex={stepIndex}
         readFile={readStoryFile}
         contextLines={4}
@@ -192,10 +192,10 @@ function FlowsDemo() {
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
       <SubsystemComponentGraph
         components={drawingComponents}
-        walkthroughs={drawingWalkthroughs}
+        trails={drawingTrails}
         title="drawing-files flow"
-        description="Three walkthroughs over one graph — opening, saving, and deleting a drawing. The sidebar's **Walkthroughs** panel lists each step by **symbol**; clicking a step focuses that hop and scrolls the bottom CodeView to that snippet."
-        renderWalkthroughViewer={renderWalkthroughViewer}
+        description="Three trails over one graph — opening, saving, and deleting a drawing. The sidebar's **Trails** panel lists each step by **symbol**; clicking a step focuses that step and scrolls the bottom CodeView to that snippet."
+        renderTrailViewer={renderTrailViewer}
         renderFileViewer={(file, opts) => (
           <div
             style={{
@@ -222,10 +222,10 @@ export const ThreeFlows: Story = {
 };
 
 /**
- * The proposed-seam failure mode: a walkthrough hop whose component is
+ * The proposed-seam failure mode: a trail step whose component is
  * `proposed` points at a file that isn't in the checkout yet (no story
- * fixture). The hop must render an inline "Proposed — … isn't in the local
- * checkout yet." placeholder with no Open-file affordance, while the live hops
+ * fixture). The step must render an inline "Proposed — … isn't in the local
+ * checkout yet." placeholder with no Open-file affordance, while the live steps
  * around it still render their snippets — one bad step must not blank the flow.
  */
 const proposedComponents: SubsystemComponent[] = [
@@ -243,7 +243,7 @@ const proposedComponents: SubsystemComponent[] = [
   },
 ];
 
-const proposedWalkthroughs: SubsystemWalkthrough[] = [
+const proposedTrails: SubsystemTrail[] = [
   {
     id: 'tl-associate-run',
     title: 'Associate a finished run with its model (proposed)',
@@ -256,7 +256,7 @@ const proposedWalkthroughs: SubsystemWalkthrough[] = [
         line: 45,
         purl: stepPurl('src/hooks/useDrawingsHost.ts'),
         symbol: 'useDrawingsHost.openDrawing',
-        annotation: 'Live hop — its snippet still renders.',
+        annotation: 'Live step — its snippet still renders.',
       },
       {
         from: 'storage',
@@ -273,17 +273,17 @@ const proposedWalkthroughs: SubsystemWalkthrough[] = [
 ];
 
 function ProposedMissingStepDemo() {
-  const renderWalkthroughViewer = useCallback(
+  const renderTrailViewer = useCallback(
     ({
-      walkthrough,
+      trail,
       stepIndex,
       onOpenFile,
       proposedAliases,
       resolveSymbol,
       onSymbolClick,
-    }: WalkthroughViewerContext) => (
-      <PierreWalkthroughCodeView
-        walkthrough={walkthrough}
+    }: TrailViewerContext) => (
+      <PierreTrailCodeView
+        trail={trail}
         stepIndex={stepIndex}
         readFile={readStoryFile}
         contextLines={4}
@@ -300,10 +300,10 @@ function ProposedMissingStepDemo() {
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
       <SubsystemComponentGraph
         components={proposedComponents}
-        walkthroughs={proposedWalkthroughs}
+        trails={proposedTrails}
         title="proposed seam with a missing file"
-        description="Expand **Associate a finished run with its model** and click either step. The proposed hop has no file in the checkout, so its snippet shows an inline *Proposed — … isn't in the local checkout yet.* placeholder instead of failing the whole flow."
-        renderWalkthroughViewer={renderWalkthroughViewer}
+        description="Expand **Associate a finished run with its model** and click either step. The proposed step has no file in the checkout, so its snippet shows an inline *Proposed — … isn't in the local checkout yet.* placeholder instead of failing the whole flow."
+        renderTrailViewer={renderTrailViewer}
         renderFileViewer={(file) => (
           <div
             style={{
@@ -328,7 +328,7 @@ export const ProposedMissingStep: Story = {
 
 // --- Clickable constructs -------------------------------------------------
 //
-// A walkthrough step's line is an edge between two constructs. When the host
+// A trail step's line is an edge between two constructs. When the host
 // supplies `resolveSymbol`/`onSymbolClick` (the graph derives them from the
 // step's `from`/`to` components), a token in the snippet that names either
 // endpoint becomes clickable — clicking it opens that construct's file at its
@@ -440,7 +440,7 @@ function readClickableFile(path: string): Promise<string> {
   return Promise.resolve(content);
 }
 
-const clickableWalkthroughs: SubsystemWalkthrough[] = [
+const clickableTrails: SubsystemTrail[] = [
   {
     id: 'tl-load',
     title: 'Load drawings',
@@ -472,17 +472,17 @@ const clickableWalkthroughs: SubsystemWalkthrough[] = [
 
 function ClickableConstructsDemo() {
   const [opened, setOpened] = React.useState<string | null>(null);
-  const renderWalkthroughViewer = useCallback(
+  const renderTrailViewer = useCallback(
     ({
-      walkthrough,
+      trail,
       stepIndex,
       onOpenFile,
       proposedAliases,
       resolveSymbol,
       onSymbolClick,
-    }: WalkthroughViewerContext) => (
-      <PierreWalkthroughCodeView
-        walkthrough={walkthrough}
+    }: TrailViewerContext) => (
+      <PierreTrailCodeView
+        trail={trail}
         stepIndex={stepIndex}
         readFile={readClickableFile}
         contextLines={4}
@@ -516,11 +516,11 @@ function ClickableConstructsDemo() {
       <div style={{ flex: 1, minHeight: 0 }}>
         <SubsystemComponentGraph
           components={clickableComponents}
-          walkthroughs={clickableWalkthroughs}
-          initialWalkthroughId="tl-load"
+          trails={clickableTrails}
+          initialTrailId="tl-load"
           title="clickable constructs"
-          description="A walkthrough step's line is an edge to a construct. Tokens that name the step's `from`/`to` components are clickable and open that construct's declaration line in the file drawer — including a **method** endpoint (click `list` to jump to `DrawingStore.list`)."
-          renderWalkthroughViewer={renderWalkthroughViewer}
+          description="A trail step's line is an edge to a construct. Tokens that name the step's `from`/`to` components are clickable and open that construct's declaration line in the file drawer — including a **method** endpoint (click `list` to jump to `DrawingStore.list`)."
+          renderTrailViewer={renderTrailViewer}
           onFileSelect={setOpened}
           renderFileViewer={(file, opts) => (
             <div style={{ padding: 12, fontFamily: 'monospace', fontSize: 12, color: '#bbb' }}>

package/src/stories/Subsystem/ComponentGraph/FrameworkStereotype.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 { walkthroughFromHops } from './fixtures';
+import { trailFromSteps } from './fixtures';
 
 const meta = {
   title: 'Subsystem/ComponentGraph/FrameworkStereotype',
@@ -117,8 +117,8 @@ const reactUiComponents: SubsystemComponent[] = [
   },
 ];
 
-const reactUiWalkthroughs = [
-  walkthroughFromHops('react-ui-hops', 'React UI hops', [
+const reactUiTrails = [
+  trailFromSteps('react-ui-steps', 'React UI steps', [
     ['http-entry', 'create-graph', 'calls', 'packages/subsystems-studio/src/bun/http-server.ts', 1],
     ['sessions-view', 'drawings-host', 'uses', 'packages/subsystems-studio/src/mainview/views/AgentSessions.tsx', 1],
     ['analysis-view', 'graph-doc-type', 'uses', 'packages/subsystems-studio/src/mainview/views/AnalysisView.tsx', 1],
@@ -133,7 +133,7 @@ export const ReactComponentsAndHooks: Story = {
         title="Framework + stereotype"
         description="construct stays language-shaped (function / type_alias). framework + stereotype label React units as component / hook without inventing a react_component construct. Empty fields mean language-only."
         components={reactUiComponents}
-        walkthroughs={reactUiWalkthroughs}
+        trails={reactUiTrails}
       />
     </div>
   ),
@@ -192,8 +192,8 @@ const nestComponents: SubsystemComponent[] = [
   },
 ];
 
-const nestWalkthroughs = [
-  walkthroughFromHops('nest-stack-hops', 'Nest controller stack hops', [
+const nestTrails = [
+  trailFromSteps('nest-stack-steps', 'Nest controller stack steps', [
     ['logging-mw', 'auth-guard', 'uses', 'src/logging/logging.middleware.ts', 1],
     ['auth-guard', 'graphs-controller', 'uses', 'src/auth/auth.guard.ts', 1],
     ['graphs-controller', 'graphs-service', 'calls', 'src/graphs/graphs.controller.ts', 1],
@@ -207,7 +207,7 @@ export const NestControllerStack: Story = {
         title="Nest framework stereotypes"
         description="Same optional fields work outside React: class/function constructs plus nestjs controller / guard / middleware / injectable stereotypes."
         components={nestComponents}
-        walkthroughs={nestWalkthroughs}
+        trails={nestTrails}
       />
     </div>
   ),