@principal-ai/subsystems-react 0.44.4 → 0.46.0

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

@@ -3,7 +3,7 @@ import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
 import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
 import { SubsystemComponentGraph } from '../../../subsystem/SubsystemComponentGraph';
-import { components, graphSpecFromHops } from './fixtures';
+import { components, graphSpecFromSteps } from './fixtures';
 
 const meta = {
   title: 'Subsystem/ComponentGraph/GraphTitle',
@@ -30,7 +30,7 @@ const graphOnlyComponents = components([
   ['caller', 'Web client', 'external', '', 'external', undefined, undefined],
 ]);
 
-const graphOnlyEdges = graphSpecFromHops([
+const graphOnlyEdges = graphSpecFromSteps([
   ['caller', 'entry', 'calls'],
   ['entry', 'store', 'writes'],
   ['entry', 'stripe', 'calls'],
@@ -41,7 +41,7 @@ function GraphOnly() {
     <div style={{ width: '100%', height: '100vh' }}>
       <SubsystemComponentGraph
         components={graphOnlyComponents}
-        walkthroughs={graphOnlyEdges.walkthroughs}
+        trails={graphOnlyEdges.trails}
         graphTitle="Checkout"
         hideSidebar
       />
@@ -60,7 +60,7 @@ export const WithSidebar: Story = {
     <div style={{ width: '100%', height: '100vh' }}>
       <SubsystemComponentGraph
         components={graphOnlyComponents}
-        walkthroughs={graphOnlyEdges.walkthroughs}
+        trails={graphOnlyEdges.trails}
         title="Checkout"
         description="A small e-commerce checkout subsystem: an HTTP entry point that writes to retained cart state and calls out to Stripe."
         graphTitle="Checkout"

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

@@ -3,7 +3,7 @@ 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';
 import {
   issueCategory,
   type SubsystemIssue,
@@ -20,8 +20,8 @@ import {
  * ("Maintain run — fire-and-forget RPC, wait for the finish event"): the
  * renderer picker → host RPC → background runner → maintain orchestrator →
  * opencode V2 session, plus the liveness-probe handshake. Its components and
- * three walkthroughs are reproduced verbatim below; the topology is carried by
- * the walkthroughs, exactly as stored.
+ * three trails are reproduced verbatim below; the topology is carried by
+ * the trails, exactly as stored.
  *
  * What this story exercises: the graph's diagnostics surface over the real
  * model — the title-row status chip, the grouped issue list, the per-node
@@ -204,8 +204,8 @@ const MAINTAIN_COMPONENTS: SubsystemComponent[] = [
   },
 ];
 
-/** The model's three runtime walkthroughs, verbatim (these carry the topology). */
-const MAINTAIN_WALKTHROUGHS: SubsystemWalkthrough[] = [
+/** The model's three runtime trails, verbatim (these carry the topology). */
+const MAINTAIN_TRAILS: SubsystemTrail[] = [
   {
     id: 'wt-start-maintain',
     title: 'Start a maintenance run',
@@ -421,7 +421,7 @@ const MAINTAIN_WALKTHROUGHS: SubsystemWalkthrough[] = [
  * Maintain-run model. The stored model's verification block is clean
  * (13/13 anchored, 0 missing), so these are the *shape* of findings the
  * diagnostics layer would receive — one per rung of the verification ladder
- * (file → symbol → declaration → type → signature) plus the topology / walkthrough
+ * (file → symbol → declaration → type → signature) plus the topology / trail
  * layers — to exercise the proposal end to end.
  */
 const MAINTAIN_ISSUES: SubsystemIssue[] = [
@@ -497,7 +497,7 @@ const MAINTAIN_ISSUES: SubsystemIssue[] = [
   {
     id: 'mr-wt',
     severity: 'info',
-    kind: 'walkthrough',
+    kind: 'trail',
     message:
       'Step 7 (terminal-matcher → session-runner) references a line that moved (was :469).',
     target: {
@@ -556,7 +556,7 @@ function MaintainRunGraph({
       <div style={{ flex: 1, minHeight: 0 }}>
         <SubsystemComponentGraph
           components={MAINTAIN_COMPONENTS}
-          walkthroughs={MAINTAIN_WALKTHROUGHS}
+          trails={MAINTAIN_TRAILS}
           title="Maintain run"
           description="Fire-and-forget RPC, wait for the finish event — picker → RPC → background runner → orchestrator → opencode V2 session, plus the liveness-probe handshake."
           diagnostic={{ status, issueCount, onToggle: () => {} }}

package/src/stories/Subsystem/ComponentGraph/Issues.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 { SubsystemIssueList, type SubsystemIssue } from '../../../subsystem/IssueList';
-import { components, graphSpecFromHops } from './fixtures';
+import { components, graphSpecFromSteps } from './fixtures';
 
 const meta = {
   title: 'Subsystem/ComponentGraph/Issues',
@@ -57,7 +57,7 @@ const ISSUES: SubsystemIssue[] = [
   {
     id: 'i6',
     severity: 'info',
-    kind: 'walkthrough',
+    kind: 'trail',
     message: 'Step 2 references a line that moved (was :42).',
     target: {
       kind: 'step',
@@ -133,7 +133,7 @@ const graphComponents = components([
   ['stripe', 'Stripe', 'external', '', 'external', undefined, undefined],
 ]);
 
-const graphEdges = graphSpecFromHops([
+const graphEdges = graphSpecFromSteps([
   ['entry', 'store', 'writes'],
   ['entry', 'stripe', 'calls'],
 ]);
@@ -166,7 +166,7 @@ export const GraphWithIssues: Story = {
     <div style={{ width: '100%', height: '100vh' }}>
       <SubsystemComponentGraph
         components={graphComponents}
-        walkthroughs={graphEdges.walkthroughs}
+        trails={graphEdges.trails}
         title="Checkout"
         description="A small e-commerce checkout subsystem."
         diagnostic={{

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

@@ -9,7 +9,7 @@ import type {
   SubsystemGraphNode,
   SubsystemProcessRegion,
 } from '../../../subsystem/model';
-import { graphSpecFromHops } from './fixtures';
+import { graphSpecFromSteps } from './fixtures';
 
 const meta = {
   title: 'Subsystem/ComponentGraph/ModuleBadges',
@@ -102,7 +102,7 @@ const deepComponents: SubsystemComponent[] = [
   },
 ];
 
-const deepEdges = graphSpecFromHops([
+const deepEdges = graphSpecFromSteps([
   ['node-comp', 'group-comp', 'calls'],
   ['edge-comp', 'group-comp', 'calls'],
   ['model-view', 'layers', 'calls'],
@@ -122,7 +122,7 @@ export const DeepModulePaths: Story = {
           'click the badge to expand the full path (the badge widens past the frame edge — the frame itself stays put), click again to collapse it back.'
         }
         components={deepComponents}
-        walkthroughs={deepEdges.walkthroughs}
+        trails={deepEdges.trails}
       />
     </div>
   ),

package/src/stories/Subsystem/ComponentGraph/Modules.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/Modules',
@@ -120,7 +120,7 @@ const moduleComponents: SubsystemComponent[] = [
   },
 ];
 
-const moduleEdges = graphSpecFromHops([
+const moduleEdges = graphSpecFromSteps([
   ['parse', 'record', 'uses'],
   ['is-rollout', 'record', 'uses'],
   ['reader', 'normalize', 'calls'],
@@ -137,7 +137,7 @@ export const ModuleBoundaries: Story = {
         title="Module boundaries"
         description="Concrete exports keep their real construct. Shared `module` (the source path) draws the file as a dashed frame — not `construct: module`. Singleton modules (registerAgent) stay unframed."
         components={moduleComponents}
-        walkthroughs={moduleEdges.walkthroughs}
+        trails={moduleEdges.trails}
       />
     </div>
   ),
@@ -259,7 +259,7 @@ const nestedComponents: SubsystemComponent[] = [
   },
 ];
 
-const nestedEdges = graphSpecFromHops([
+const nestedEdges = graphSpecFromSteps([
   ['boot', 'write-session', 'calls'],
   ['trail-view', 'bridge', 'calls'],
   ['trail-view', 'use-trail', 'uses'],
@@ -278,7 +278,7 @@ export const ProcessAndModuleNesting: Story = {
         title="Process × module nesting"
         description="process frames wrap module frames wrap exports. Leaves parent to module:; module groups parent to process: when every member shares that process."
         components={nestedComponents}
-        walkthroughs={nestedEdges.walkthroughs}
+        trails={nestedEdges.trails}
       />
     </div>
   ),

package/src/stories/Subsystem/ComponentGraph/Packages.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/Packages',
@@ -80,7 +80,7 @@ const multiRepoComponents: SubsystemComponent[] = [
   },
 ];
 
-const multiRepoEdges = graphSpecFromHops([
+const multiRepoEdges = graphSpecFromSteps([
   ['dispatch', 'session', 'calls'],
   ['dispatch', 'parse', 'calls'],
   ['parse', 'normalize', 'calls'],
@@ -90,7 +90,7 @@ export const MultiRepoPackageFrames: Story = {
   name: 'Multi-repo package frames',
   args: {
     components: multiRepoComponents,
-    walkthroughs: multiRepoEdges.walkthroughs,
+    trails: multiRepoEdges.trails,
   },
   render: (args) => (
     <div style={{ width: '100vw', height: '100vh' }}>
@@ -106,7 +106,7 @@ export const SingleRepoNoPackageFrames: Story = {
   name: 'Single-repo (no package frames)',
   args: {
     components: singleRepo,
-    walkthroughs: multiRepoEdges.walkthroughs,
+    trails: multiRepoEdges.trails,
   },
   render: (args) => (
     <div style={{ width: '100vw', height: '100vh' }}>
@@ -218,7 +218,7 @@ const nestedComponents: SubsystemComponent[] = [
   },
 ];
 
-const nestedEdges = graphSpecFromHops([
+const nestedEdges = graphSpecFromSteps([
   ['boot', 'dispatch', 'calls'],
   ['dispatch', 'session', 'calls'],
   ['dispatch', 'parse', 'calls'],
@@ -229,7 +229,7 @@ export const PackageProcessModuleNesting: Story = {
   name: 'Package → process → module nesting',
   args: {
     components: nestedComponents,
-    walkthroughs: nestedEdges.walkthroughs,
+    trails: nestedEdges.trails,
   },
   render: (args) => (
     <div style={{ width: '100vw', height: '100vh' }}>

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

@@ -2,7 +2,7 @@ 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 { components, graphSpecFromHops } from './fixtures';
+import { components, graphSpecFromSteps } from './fixtures';
 
 const meta = {
   title: 'Subsystem/ComponentGraph/Processes',
@@ -54,7 +54,7 @@ const processComponents = [
   },
 ];
 
-const processEdges = graphSpecFromHops([
+const processEdges = graphSpecFromSteps([
   ['main', 'store', 'writes'],
   ['main', 'bridge', 'calls'],
   ['bridge', 'view', 'feeds'],
@@ -69,7 +69,7 @@ export const ProcessBoundaries: Story = {
         title="Process boundaries"
         description="Host and renderer each render in their own ELK-aware boundary frame. The worker process holds a single node and still gets a frame (singleton frames default on). The telemetry service has no `process` and sits outside every boundary."
         components={processComponents}
-        walkthroughs={processEdges.walkthroughs}
+        trails={processEdges.trails}
       />
     </div>
   ),

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

@@ -9,7 +9,7 @@ import type {
   SubsystemComponent,
   SubsystemGraphNode,
 } from '../../../subsystem/model';
-import { walkthroughFromHops } from './fixtures';
+import { trailFromSteps } from './fixtures';
 
 const meta = {
   title: 'Subsystem/ComponentGraph/Proposed',
@@ -225,8 +225,8 @@ const migrationComponents: SubsystemComponent[] = [
   },
 ];
 
-const migrationWalkthroughs = [
-  walkthroughFromHops('migration-hops', 'Migration hops', [
+const migrationTrails = [
+  trailFromSteps('migration-steps', 'Migration steps', [
     ['audit', 'maintain', 'calls', 'src/bun/verify-subsystem-component.ts', 1],
     ['maintain', 'lifecycle', 'uses', 'src/bun/maintain-model.ts', 1],
     ['lifecycle', 'cli', 'calls', 'src/bun/opencode-v2.ts', 1],
@@ -239,7 +239,7 @@ function MigrationDemo() {
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
       <SubsystemComponentGraph
         components={migrationComponents}
-        walkthroughs={migrationWalkthroughs}
+        trails={migrationTrails}
         onSelect={(id) => setSelected(id)}
       />
       <div style={{ marginTop: 8, padding: '0 12px', fontFamily: 'monospace', fontSize: 12, color: '#aaa' }}>

package/src/stories/Subsystem/ComponentGraph/{ProposedWalkthroughs.stories.tsx → ProposedTrails.stories.tsx}

@@ -3,10 +3,10 @@ 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';
 
 const meta = {
-  title: 'Subsystem/ComponentGraph/ProposedWalkthroughs',
+  title: 'Subsystem/ComponentGraph/ProposedTrails',
   component: SubsystemComponentGraph,
   parameters: {
     layout: 'fullscreen',
@@ -82,7 +82,7 @@ const components: SubsystemComponent[] = [
   },
 ];
 
-const walkthroughs: SubsystemWalkthrough[] = [
+const trails: SubsystemTrail[] = [
   {
     id: 'wt-audit',
     title: 'Audit a model',
@@ -94,7 +94,7 @@ const walkthroughs: SubsystemWalkthrough[] = [
         file: 'src/bun/verify-subsystem-component.ts',
         line: 1,
         symbol: 'auditSubsystemModel',
-        annotation: 'Live-only walkthrough — no proposed badge.',
+        annotation: 'Live-only trail — no proposed badge.',
       },
     ],
   },
@@ -117,7 +117,7 @@ const walkthroughs: SubsystemWalkthrough[] = [
         file: 'src/bun/maintain-model.ts',
         line: 1,
         symbol: 'runMaintainModel',
-        annotation: 'Hop onto the proposed lifecycle — step index is tinted.',
+        annotation: 'Step onto the proposed lifecycle — step index is tinted.',
       },
       {
         from: 'lifecycle',
@@ -146,19 +146,19 @@ const walkthroughs: SubsystemWalkthrough[] = [
   },
 ];
 
-function ProposedWalkthroughsDemo() {
+function ProposedTrailsDemo() {
   return (
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
       <SubsystemComponentGraph
         components={components}
-        walkthroughs={walkthroughs}
+        trails={trails}
         title="proposed-work marker"
-        description="Walkthroughs that touch a **proposed** component get their title tinted darkgoldenrod in the flows panel; expand a row and each hop onto a proposed component is tinted too (index and title). Nodes for proposed components already draw dashed darkgoldenrod on the canvas."
+        description="Trails that touch a **proposed** component get their title tinted darkgoldenrod in the flows panel; expand a row and each step onto a proposed component is tinted too (index and title). Nodes for proposed components already draw dashed darkgoldenrod on the canvas."
       />
     </div>
   );
 }
 
 export const ProposedWorkflows: Story = {
-  render: () => <ProposedWalkthroughsDemo />,
+  render: () => <ProposedTrailsDemo />,
 };

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

@@ -3,8 +3,8 @@ 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 { WalkthroughsPanel } from '../../../subsystem/WalkthroughsPanel';
-import type { SubsystemComponent, SubsystemWalkthrough } from '../../../subsystem/model';
+import { TrailsPanel } from '../../../subsystem/TrailsPanel';
+import type { SubsystemComponent, SubsystemTrail } from '../../../subsystem/model';
 
 const meta = {
   title: 'Subsystem/ComponentGraph/Reorder',
@@ -68,7 +68,7 @@ const components: SubsystemComponent[] = [
   },
 ];
 
-const initialWalkthroughs: SubsystemWalkthrough[] = [
+const initialTrails: SubsystemTrail[] = [
   {
     id: 'tl-open-drawing',
     title: 'Open drawing',
@@ -103,9 +103,9 @@ const initialWalkthroughs: SubsystemWalkthrough[] = [
   },
 ];
 
-const orderLabel = (list: SubsystemWalkthrough[]) => list.map((w) => w.title).join('  →  ');
+const orderLabel = (list: SubsystemTrail[]) => list.map((w) => w.title).join('  →  ');
 
-function OrderHeader({ list }: { list: SubsystemWalkthrough[] }) {
+function OrderHeader({ list }: { list: SubsystemTrail[] }) {
   return (
     <div
       style={{
@@ -125,22 +125,22 @@ function OrderHeader({ list }: { list: SubsystemWalkthrough[] }) {
 }
 
 function ReorderGraphDemo() {
-  const [walkthroughs, setWalkthroughs] = useState(initialWalkthroughs);
+  const [trails, setTrails] = useState(initialTrails);
   const onReorder = useCallback(
-    (next: SubsystemWalkthrough[]) => setWalkthroughs(next),
+    (next: SubsystemTrail[]) => setTrails(next),
     [],
   );
 
   return (
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
-      <OrderHeader list={walkthroughs} />
+      <OrderHeader list={trails} />
       <div style={{ flex: 1, minHeight: 0 }}>
         <SubsystemComponentGraph
           components={components}
-          walkthroughs={walkthroughs}
-          onReorderWalkthroughs={onReorder}
+          trails={trails}
+          onReorderTrails={onReorder}
           title="drawing-files flows"
-          description="Drag the grip at the right of a walkthrough row to reorder it. Grips show only while every row is collapsed — expand one and they hide. The header above mirrors the array order; dropping a row calls `onReorderWalkthroughs` with the next array."
+          description="Drag the grip at the right of a trail row to reorder it. Grips show only while every row is collapsed — expand one and they hide. The header above mirrors the array order; dropping a row calls `onReorderTrails` with the next array."
         />
       </div>
     </div>
@@ -148,7 +148,7 @@ function ReorderGraphDemo() {
 }
 
 function PanelOnlyDemo() {
-  const [walkthroughs, setWalkthroughs] = useState(initialWalkthroughs);
+  const [trails, setTrails] = useState(initialTrails);
   // Start collapsed so the drag grips are visible; expanding any row hides them
   // (reordering is only offered when every row is collapsed).
   const [expanded, setExpanded] = useState<Set<string>>(new Set());
@@ -163,7 +163,7 @@ function PanelOnlyDemo() {
 
   return (
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
-      <OrderHeader list={walkthroughs} />
+      <OrderHeader list={trails} />
       <div style={{ flex: 1, minHeight: 0, display: 'flex' }}>
         <div
           style={{
@@ -173,12 +173,12 @@ function PanelOnlyDemo() {
             borderRight: '1px solid #2a2a2a',
           }}
         >
-          <WalkthroughsPanel
-            walkthroughs={walkthroughs}
-            expandedWalkthroughs={expanded}
-            focusedWalkthroughId={null}
+          <TrailsPanel
+            trails={trails}
+            expandedTrails={expanded}
+            focusedTrailId={null}
             focusedStepIndex={null}
-            hoveredWalkthroughStep={null}
+            hoveredTrailStep={null}
             onToggleCollapsed={onToggleCollapsed}
             onFocusFlow={() => {}}
             onClearFocus={() => {}}
@@ -186,7 +186,7 @@ function PanelOnlyDemo() {
             onHoverStep={() => {}}
             onHoverFlow={() => {}}
             onLeaveStep={() => {}}
-            onReorder={setWalkthroughs}
+            onReorder={setTrails}
           />
         </div>
       </div>

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

@@ -9,7 +9,7 @@ import type {
   SubsystemModelDocument,
 } from '../../../subsystem/model';
 import type { GraphifyComponentDetail } from '../../../graphify';
-import { components, graphSpecFromHops } from './fixtures';
+import { components, graphSpecFromSteps } from './fixtures';
 
 const meta = {
   title: 'Subsystem/ComponentGraph/Scenarios',
@@ -92,7 +92,7 @@ const mermaidComponents: SubsystemComponent[] = [
   },
 ];
 
-const mermaidEdges = graphSpecFromHops([
+const mermaidEdges = graphSpecFromSteps([
   ['input', 'slide', 'feeds'],
   ['slide', 'chunk', 'produces'],
   ['chunk', 'lazy', 'feeds'],
@@ -106,7 +106,7 @@ function MermaidDemo() {
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
       <SubsystemComponentGraph
         components={mermaidComponents}
-        walkthroughs={mermaidEdges.walkthroughs}
+        trails={mermaidEdges.trails}
         onSelect={(id) => setSelected(id)}
       />
       <div style={{ marginTop: 8, fontFamily: 'monospace', fontSize: 12, color: '#aaa' }}>
@@ -137,7 +137,7 @@ const multiRepoComponents = components([
   ['rewire', 'extract.py', 'function', 'graphify/extract.py', graphifyPurl, 'corpus pass folding unique-label stubs onto definitions', '_rewire_unique_stub_nodes'],
 ]);
 
-const multiRepoEdges = graphSpecFromHops([
+const multiRepoEdges = graphSpecFromSteps([
   ['detail', 'reftypes', 'uses'],
   ['resolver', 'reftypes', 'uses'],
   ['resolver', 'engine', 'calls'],
@@ -151,7 +151,7 @@ function MultiRepoDemo() {
         title="Type-ref resolution across repos"
         description="Two repos → two file trees. Each tree is scoped to its repo's files and headed by the owner avatar + repo name. Cross-repo edges land on external stubs."
         components={multiRepoComponents}
-        walkthroughs={multiRepoEdges.walkthroughs}
+        trails={multiRepoEdges.trails}
       />
     </div>
   );
@@ -354,7 +354,7 @@ const accessSurfaceComponents: SubsystemComponent[] = [
   },
 ];
 
-const accessSurfaceEdges = graphSpecFromHops([
+const accessSurfaceEdges = graphSpecFromSteps([
   ['agents', 'http-entry', 'calls'],
   ['http-entry', 'create', 'calls'],
   ['http-entry', 'update', 'calls'],
@@ -384,7 +384,7 @@ function AccessSurfacesDemo() {
         title="Access surfaces, roles, and process boundaries"
         description="Two process regions (host, renderer) + boundary entries; agents and the external service float outside every boundary. Hover for the role badge; click the store to drill into its state-only detail."
         components={accessSurfaceComponents}
-        walkthroughs={accessSurfaceEdges.walkthroughs}
+        trails={accessSurfaceEdges.trails}
         onSelect={(id) => setSelected(id)}
         onEdgeSelect={(e) => setSelectedEdge(e)}
       />
@@ -534,7 +534,7 @@ const storeFlavorComponents: SubsystemComponent[] = [
   },
 ];
 
-const storeFlavorEdges = graphSpecFromHops([
+const storeFlavorEdges = graphSpecFromSteps([
   ['f1-create', 'f1-store', 'writes'],
   ['f1-get', 'f1-store', 'reads'],
   ['f2-cache', 'f2-store', 'writes'],
@@ -549,7 +549,7 @@ function StoreFlavorsDemo() {
         title="Store flavors"
         description="construct:= the node's verifiable anchor. Class-managed stores are TWO nodes: the manager class (declaration, methods) + the state (store block). Click any node to see its anchor-honest drill-down."
         components={storeFlavorComponents}
-        walkthroughs={storeFlavorEdges.walkthroughs}
+        trails={storeFlavorEdges.trails}
         onSelect={(id) => setSelected(id)}
       />
       <div style={{ marginTop: 8, fontFamily: 'monospace', fontSize: 12, color: '#aaa' }}>
@@ -637,7 +637,7 @@ const sharedStoreComponents: SubsystemComponent[] = [
   },
 ];
 
-const sharedStoreEdges = graphSpecFromHops([
+const sharedStoreEdges = graphSpecFromSteps([
   ['ss-load', 'ss-store', 'reads'],
   ['ss-save', 'ss-store', 'writes'],
   ['ss-watch', 'ss-store', 'watches'],
@@ -652,7 +652,7 @@ function SharedStoreDemo() {
         title="Shared store across processes"
         description="A store with no process sits outside every boundary; accessors from both processes reach across to it."
         components={sharedStoreComponents}
-        walkthroughs={sharedStoreEdges.walkthroughs}
+        trails={sharedStoreEdges.trails}
         onEdgeSelect={(e) => setSelectedEdge(e)}
       />
       <div style={{ marginTop: 8, fontFamily: 'monospace', fontSize: 12, color: '#aaa' }}>
@@ -919,7 +919,7 @@ const storeSpectrumComponents: SubsystemComponent[] = [
   },
 ];
 
-const storeSpectrumEdges = graphSpecFromHops([
+const storeSpectrumEdges = graphSpecFromSteps([
   ['load', 'db', 'reads'],
   ['create', 'graph-store', 'writes'],
   ['cache', 'cache-state', 'writes'],
@@ -938,7 +938,7 @@ function StoreStateSpectrumDemo() {
         title="State → Store spectrum, all modeled as store"
         description="Every holder here claims construct: 'store' (state-block anatomy). They differ only in what they hold and how long it lives. Which ones do you call a store? Where is the cut?"
         components={storeSpectrumComponents}
-        walkthroughs={storeSpectrumEdges.walkthroughs}
+        trails={storeSpectrumEdges.trails}
         onSelect={(id) => setSelected(id)}
       />
       <div style={{ marginTop: 8, fontFamily: 'monospace', fontSize: 12, color: '#aaa' }}>
@@ -1114,7 +1114,7 @@ const typeSpectrumComponents: SubsystemComponent[] = [
   },
 ];
 
-const typeSpectrumEdges = graphSpecFromHops([
+const typeSpectrumEdges = graphSpecFromSteps([
   ['listener', 'subscriber', 'uses'],
   ['subscriber', 'messages', 'uses'],
   ['state', 'listener', 'feeds'],
@@ -1130,7 +1130,7 @@ function TypeFamilySpectrumDemo() {
         title="Type-family — what a type can hold"
         description="Structured buckets: callable signature (generics + params), interface properties, enum members, union, plain alias reference. `rhs` = verbatim escape hatch for shapes that don't fit (mapped/conditional/template-literal). Click each to see the declaration."
         components={typeSpectrumComponents}
-        walkthroughs={typeSpectrumEdges.walkthroughs}
+        trails={typeSpectrumEdges.trails}
         onSelect={(id) => setSelected(id)}
       />
       <div style={{ marginTop: 8, fontFamily: 'monospace', fontSize: 12, color: '#aaa' }}>
@@ -1209,7 +1209,7 @@ const queueComponents: SubsystemComponent[] = [
   },
 ];
 
-const queueEdges = graphSpecFromHops([
+const queueEdges = graphSpecFromSteps([
   ['q-producer', 'q-queue', 'writes'],
   ['q-worker', 'q-queue', 'reads'],
   ['q-worker', 'q-results', 'writes'],
@@ -1223,7 +1223,7 @@ function QueueAsStoreDemo() {
         title="Queue as store"
         description="Ordered retained state. Stores as pipeline stages: producer writes the queue, the worker reads it and writes results."
         components={queueComponents}
-        walkthroughs={queueEdges.walkthroughs}
+        trails={queueEdges.trails}
         onEdgeSelect={(e) => setSelectedEdge(e)}
       />
       <div style={{ marginTop: 8, fontFamily: 'monospace', fontSize: 12, color: '#aaa' }}>
@@ -1343,10 +1343,10 @@ const dataVizDoc: SubsystemModelDocument = {
       },
     },
   ],
-  walkthroughs: [
+  trails: [
     {
-      id: 'data-viz-hops',
-      title: 'Runtime hops',
+      id: 'data-viz-steps',
+      title: 'Runtime steps',
       steps: [
         { from: 'agents', to: 'http-entry', mechanism: 'calls', file: 'src/http.ts', line: 1 },
         { from: 'http-entry', to: 'create', mechanism: 'calls', file: 'src/http.ts', line: 2 },
@@ -1430,7 +1430,7 @@ function DataVsVisualizationDemo() {
           title="the visualization"
           description="Same document, rendered: construct:→ node anatomy, role → topology glyph, process → boundary region, mechanism → edge color/style."
           components={doc.components}
-          walkthroughs={doc.walkthroughs}
+          trails={doc.trails}
         />
       </div>
     </div>