@principal-ai/subsystems-react 0.20.5 → 0.21.0

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, edges, readerDetail, investigateOnlyComponents, investigateOnlyEdges } from './fixtures';
+import { components, graphSpecFromEdges, readerDetail, investigateOnlyComponents, investigateOnlyRelations, investigateOnlyWalkthroughs } from './fixtures';
 
 const meta = {
   title: 'Subsystem/ComponentGraph/Captures',
@@ -37,7 +37,7 @@ const v2ReaderComponents = components([
   ['registry', 'supported-agents', 'module', 'supported-agents.ts', 'pkg:github/principal-ai/agent-monitoring', 'registry of supported agents (the shared seam)', 'registerAgent'],
 ]);
 
-const v2ReaderEdges = edges([
+const v2ReaderEdges = graphSpecFromEdges([
   ['transcript', 'reader', 'imports'],
   ['paths', 'reader', 'imports'],
   ['capture', 'reader', 'calls'],
@@ -55,7 +55,7 @@ function V2ReaderDemo() {
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
       <SubsystemComponentGraph
         components={v2ReaderComponents}
-        edges={v2ReaderEdges}
+        relations={v2ReaderEdges.relations} walkthroughs={v2ReaderEdges.walkthroughs}
         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} edges={investigateOnlyEdges} />
+      <SubsystemComponentGraph components={investigateOnlyComponents} relations={investigateOnlyRelations} walkthroughs={investigateOnlyWalkthroughs} />
     </div>
   ),
 };
@@ -98,7 +98,7 @@ const minimalComponents = components([
   ['transcript', 'transcript', 'module', 'transcript.ts', 'pkg:github/principal-ai/agent-monitoring', 'parses session records + type guards', 'transcript'],
 ]);
 
-const sharedEdges = edges([
+const sharedEdges = graphSpecFromEdges([
   ['transcript', 'record', 'defines'],
   ['reader', 'normalize', 'method'],
   ['normalize', 'record', 'references'],
@@ -106,10 +106,10 @@ const sharedEdges = edges([
 
 /** The same subsystem after `resolveSubsystemToGraphify` populates `detail`. */
 const resolvedComponents: SubsystemComponent[] = [
-  { ...minimalComponents[0], detail: readerDetail },
+  { ...minimalComponents[0], declaration: readerDetail },
   {
     ...minimalComponents[1],
-    detail: {
+    declaration: {
       kind: 'function',
       parameters: [{ name: 'session', type: 'SessionRecord' }],
       returnType: 'SessionEvent[]',
@@ -119,7 +119,7 @@ const resolvedComponents: SubsystemComponent[] = [
   },
   {
     ...minimalComponents[2],
-    detail: {
+    declaration: {
       kind: 'type',
       properties: [
         { name: 'id', type: 'string' },
@@ -131,7 +131,7 @@ const resolvedComponents: SubsystemComponent[] = [
   },
   {
     ...minimalComponents[3],
-    detail: {
+    declaration: {
       kind: 'module',
       exports: ['CodexRolloutRecord', 'CodexSessionMeta'],
       imports: [{ nodeId: 'i1', name: 'paths', relation: 'imports_from' }],
@@ -146,12 +146,12 @@ function MinimalVsResolvedDemo({ resolved }: { resolved: boolean }) {
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
       <SubsystemComponentGraph
         components={resolved ? resolvedComponents : minimalComponents}
-        edges={sharedEdges}
+        relations={sharedEdges.relations} walkthroughs={sharedEdges.walkthroughs}
         onSelect={(id) => setSelected(id)}
       />
       <div style={{ marginTop: 8, fontFamily: 'monospace', fontSize: 12, color: '#aaa' }}>
         {resolved
-          ? 'post-graphify: click a component to see the enriched GraphifyComponentDetail'
+          ? 'post-graphify: click a component to see the enriched declaration'
           : 'pre-graphify: LLM-authored symbols only — no detail yet'}
       </div>
     </div>
@@ -168,8 +168,7 @@ export const ResolvedPostGraphify: Story = {
 
 // ---------------------------------------------------------------------------
 // Investigation-derived subsystem — grok session 019fd2a9 (t3code)
-// Read-only analysis of "provider / event threading". Components are occupied
-// (analyzed, not edited) — no code touched, but a coherent concept was worked.
+// Read-only analysis of "provider / event threading".
 // ---------------------------------------------------------------------------
 const investigationComponents: SubsystemComponent[] = [
   {
@@ -180,8 +179,7 @@ const investigationComponents: SubsystemComponent[] = [
     purl: 'pkg:github/t3code/t3code',
     purpose: 'adapts opencode session/threads + events to the t3 runtime',
     symbol: 'makeOpenCodeAdapter',
-    capture: 'analyzed',
-    detail: {
+    declaration: {
       kind: 'module',
       exports: ['makeOpenCodeAdapter', 'OpenCodeAdapterLiveOptions'],
       imports: [{ nodeId: 'i1', name: 'orchestration', relation: 'imports_from' }],
@@ -196,7 +194,6 @@ const investigationComponents: SubsystemComponent[] = [
     purl: 'pkg:github/t3code/t3code',
     purpose: 'ingests provider events into the runtime',
     symbol: 'ProviderRuntimeIngestion',
-    capture: 'analyzed',
   },
   {
     id: 'contracts',
@@ -206,11 +203,10 @@ const investigationComponents: SubsystemComponent[] = [
     purl: 'pkg:github/t3code/t3code',
     purpose: 'contracts for orchestration/providers',
     symbol: 'ORCHESTRATION_WS_METHODS',
-    capture: 'analyzed',
   },
 ];
 
-const investigationEdges = edges([
+const investigationEdges = graphSpecFromEdges([
   ['adapter', 'contracts', 'imports_from'],
   ['ingestion', 'adapter', 'uses'],
   ['ingestion', 'contracts', 'references'],
@@ -222,11 +218,11 @@ function InvestigationDemo() {
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
       <SubsystemComponentGraph
         components={investigationComponents}
-        edges={investigationEdges}
+        relations={investigationEdges.relations} walkthroughs={investigationEdges.walkthroughs}
         onSelect={(id) => setSelected(id)}
       />
       <div style={{ marginTop: 8, fontFamily: 'monospace', fontSize: 12, color: '#aaa' }}>
-        read-only investigation snapshot (grok 019fd2a9) — components analyzed, not edited
+        read-only investigation snapshot (grok 019fd2a9)
         {selected ? ` · selected: ${selected}` : ''}
       </div>
     </div>

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

@@ -5,6 +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 { graphSpecFromEdges } from './fixtures';
 
 /** Authored attributes surfaced in the declaration panel. */
 function entityDetail(attributes: Array<[string, string]>): GraphifyCustomEntityDetail {
@@ -32,7 +33,7 @@ const components: SubsystemComponent[] = [
     purl: 'external',
     purpose: 'submits a facilities work request',
     role: 'entry',
-    detail: entityDetail([
+    declaration: entityDetail([
       ['vertical', 'buildings'],
       ['escalationPath', 'FacilitiesTechnician → ShiftSupervisor'],
     ]),
@@ -47,7 +48,7 @@ const components: SubsystemComponent[] = [
     purpose: 'performs repairs, resolves L1 requests',
     process: 'novatech/core-ops',
     layer: 1,
-    detail: entityDetail([
+    declaration: entityDetail([
       ['level', 'L1'],
       ['projects', 'HVAC, plumbing'],
     ]),
@@ -62,7 +63,7 @@ const components: SubsystemComponent[] = [
     purpose: 'assigns technicians, approves out-of-scope work',
     process: 'novatech/core-ops',
     layer: 2,
-    detail: entityDetail([
+    declaration: entityDetail([
       ['level', 'L2'],
       ['approvalLimit', '$500'],
     ]),
@@ -77,7 +78,7 @@ const components: SubsystemComponent[] = [
     purpose: 'owns the queue, escalates campus-wide issues',
     process: 'novatech/core-ops',
     layer: 3,
-    detail: entityDetail([
+    declaration: entityDetail([
       ['level', 'L3'],
       ['approvalLimit', '$5,000'],
     ]),
@@ -92,7 +93,7 @@ const components: SubsystemComponent[] = [
     purpose: 'funds large projects, signs off L4 requests',
     process: 'novatech/core-ops',
     layer: 4,
-    detail: entityDetail([
+    declaration: entityDetail([
       ['level', 'L4'],
       ['approvalLimit', 'unlimited'],
     ]),
@@ -108,7 +109,7 @@ const components: SubsystemComponent[] = [
     purpose: 'proposes nudges from open-request patterns; never owns the queue',
     process: 'novatech/core-ops',
     layer: 2,
-    detail: entityDetail([
+    declaration: entityDetail([
       ['slack', 'novatech/facilities-ops'],
       ['permission', 'propose-only'],
     ]),
@@ -124,7 +125,7 @@ const components: SubsystemComponent[] = [
     purpose: 'holds proposed nudges until a supervisor confirms them',
     process: 'novatech/core-ops',
     layer: 3,
-    detail: entityDetail([
+    declaration: entityDetail([
       ['durable', 'postgres + outbox'],
       ['owner', 'CampusOpsManager'],
     ]),
@@ -142,7 +143,7 @@ const components: SubsystemComponent[] = [
   },
 ];
 
-const edges: SubsystemComponentEdge[] = [
+const entityGraph = graphSpecFromEdges([
   ['wr', 'store', 'feeds'],
   ['store', 'tech', 'feeds'],
   ['tech', 'sup', 'watches'],
@@ -151,7 +152,7 @@ const edges: SubsystemComponentEdge[] = [
   ['agent', 'queue', 'feeds'],
   ['queue', 'mgr', 'feeds'],
   ['mgr', 'vp', 'watches'],
-].map(([from, to, mechanism], i) => ({ id: `e${i}`, from, to, mechanism }));
+]);
 
 const meta = {
   title: 'Subsystem/ComponentGraph/CustomEntities',
@@ -177,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}
-        edges={edges}
+        relations={entityGraph.relations} walkthroughs={entityGraph.walkthroughs}
       />
     </div>
   ),

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

@@ -31,7 +31,7 @@ export default meta;
 type Story = StoryObj<typeof meta>;
 
 // ---------------------------------------------------------------------------
-// One node per GraphifyComponentDetail kind — what each looks like + drills down
+// One node per declaration kind — what each looks like + drills down
 // ---------------------------------------------------------------------------
 const detailKindComponents: SubsystemComponent[] = [
   {
@@ -42,7 +42,7 @@ const detailKindComponents: SubsystemComponent[] = [
     purl: 'pkg:github/principal-ai/agent-monitoring',
     purpose: 'class-like: owns outgoing method edges',
     symbol: '',
-    detail: readerDetail,
+    declaration: readerDetail,
   },
   {
     id: 'detail-method',
@@ -52,7 +52,7 @@ const detailKindComponents: SubsystemComponent[] = [
     purl: 'pkg:github/principal-ai/agent-monitoring',
     purpose: 'a class method — the specific thing this session focused on',
     symbol: 'SessionReader.normalize',
-    detail: {
+    declaration: {
       kind: 'function',
       parameters: [{ name: 'session', type: 'SessionRecord' }],
       returnType: 'SessionEvent[]',
@@ -68,7 +68,7 @@ const detailKindComponents: SubsystemComponent[] = [
     purl: 'pkg:github/principal-ai/agent-monitoring',
     purpose: 'function-like: label ends () with no method edges',
     symbol: 'normalizeSession',
-    detail: {
+    declaration: {
       kind: 'function',
       parameters: [
         { name: 'session', type: 'SessionRecord' },
@@ -87,7 +87,7 @@ const detailKindComponents: SubsystemComponent[] = [
     purl: 'pkg:github/principal-ai/agent-monitoring',
     purpose: 'multi-param signature — named, positional (graphify captures types only), union types, generic return',
     symbol: 'mergeSessions',
-    detail: {
+    declaration: {
       kind: 'function',
       parameters: [
         { name: 'sessions', type: 'SessionRecord[]' },
@@ -111,7 +111,7 @@ const detailKindComponents: SubsystemComponent[] = [
     purl: 'pkg:github/principal-ai/agent-monitoring',
     purpose: 'no parameters, no return type — the barest function signature',
     symbol: 'flush',
-    detail: {
+    declaration: {
       kind: 'function',
       parameters: [],
       callers: [{ nodeId: 'c4', name: 'EventProcessor.dispose', source_location: 'L142' }],
@@ -126,7 +126,7 @@ const detailKindComponents: SubsystemComponent[] = [
     purl: 'pkg:github/principal-ai/agent-monitoring',
     purpose: 'class with fully-typed members — method params + returns, field types, extends + implements',
     symbol: 'EventProcessor',
-    detail: {
+    declaration: {
       kind: 'class',
       methods: [
         { nodeId: 'rm1', name: 'process', parameters: [{ type: 'RawEvent' }, { type: 'ProcessingOptions' }], returnType: 'ProcessedEvent' },
@@ -156,7 +156,7 @@ const detailKindComponents: SubsystemComponent[] = [
     purl: 'pkg:github/principal-ai/agent-monitoring',
     purpose: 'type-like: revealed by incoming implements edges',
     symbol: 'SessionRecord',
-    detail: {
+    declaration: {
       kind: 'type',
       properties: [
         { name: 'id', type: 'string' },
@@ -174,7 +174,7 @@ const detailKindComponents: SubsystemComponent[] = [
     purl: 'pkg:github/principal-ai/agent-monitoring',
     purpose: 'a type symbol that lives in the transcript module; the node is the symbol, the file is its location',
     symbol: 'CodexRolloutRecord',
-    detail: {
+    declaration: {
       kind: 'type',
       properties: [
         { name: 'type', type: 'string' },
@@ -193,14 +193,13 @@ const detailKindComponents: SubsystemComponent[] = [
     purl: 'pkg:npm/@principal-ai/subsystems-studio',
     purpose: 'an npm package consumer — the whole package as a node',
     symbol: '',
-    detail: {
+    declaration: {
       kind: 'external',
       label: 'pkg:npm/@principal-ai/subsystems-studio',
     } satisfies GraphifyComponentDetail,
   },
 ];
 
-const detailKindEdges: SubsystemComponentEdge[] = [];
 
 function DetailKindsDemo() {
   const [selected, setSelected] = useState<string | null>(null);
@@ -208,11 +207,11 @@ function DetailKindsDemo() {
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
       <SubsystemComponentGraph
         components={detailKindComponents}
-        edges={detailKindEdges}
+        relations={[]}
         onSelect={(id) => setSelected(id)}
       />
       <div style={{ marginTop: 8, fontFamily: 'monospace', fontSize: 12, color: '#aaa' }}>
-        {selected ? `selected: ${selected}` : 'click a component to see its GraphifyComponentDetail'}
+        {selected ? `selected: ${selected}` : 'click a component to see its declaration'}
       </div>
     </div>
   );
@@ -303,7 +302,7 @@ function DeclarationLineOpenDemo() {
         title="Declaration line open (Storybook)"
         description="Uses bundled ?raw fixtures + PierreSnippetView from this package. Select ComponentDeclaration, toggle file, click the path or L251."
         components={declarationOpenComponents}
-        edges={[]}
+        relations={[]}
         renderFileViewer={renderFileViewer}
       />
     </div>

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

@@ -3,13 +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,
-  SubsystemComponentEdge,
-  SubsystemThroughline,
-} from '../../../subsystem/model';
-import { PierreThroughlineCodeView } from '../../../pierre';
-import type { ThroughlineViewerContext } from '../../../subsystem/SubsystemComponentGraph';
+import type { SubsystemComponent, SubsystemWalkthrough } from '../../../subsystem/model';
+import { PierreWalkthroughCodeView } from '../../../pierre';
+import type { WalkthroughViewerContext } from '../../../subsystem/SubsystemComponentGraph';
 
 const meta = {
   title: 'Subsystem/ComponentGraph/Flows',
@@ -30,16 +26,6 @@ const meta = {
 export default meta;
 type Story = StoryObj<typeof meta>;
 
-// ---------------------------------------------------------------------------
-// Mirror of the retrofitted electron-app drawing graph: the sidebar's Files
-// panel swaps to a Flows panel listing three throughlines (open / save /
-// delete). Clicking a flow row toggles its steps; clicking a step focuses
-// that step's edge, frames it on the canvas, and scrolls the bottom CodeView
-// to that step's snippet. Other opened flows stay dimmed; the rest of the
-// graph is hidden.
-// ---------------------------------------------------------------------------
-
-/** Build enough placeholder lines so step `line` values land inside the file. */
 function fakeSource(path: string, markedLines: number[]): string {
   const maxLine = Math.max(80, ...markedLines);
   const marks = new Set(markedLines);
@@ -58,19 +44,11 @@ function fakeSource(path: string, markedLines: number[]): string {
 }
 
 const storyFiles: Record<string, string> = {
-  'src/panels/DrawingsLeftPanel.tsx': fakeSource('src/panels/DrawingsLeftPanel.tsx', [
-    56, 85,
-  ]),
-  'src/hooks/useDrawingsHost.ts': fakeSource('src/hooks/useDrawingsHost.ts', [
-    45, 64, 66,
-  ]),
-  'src/workspace/WorkspaceShell.tsx': fakeSource('src/workspace/WorkspaceShell.tsx', [
-    369, 372,
-  ]),
+  'src/panels/DrawingsLeftPanel.tsx': fakeSource('src/panels/DrawingsLeftPanel.tsx', [56, 85]),
+  'src/hooks/useDrawingsHost.ts': fakeSource('src/hooks/useDrawingsHost.ts', [45, 64, 66]),
+  'src/workspace/WorkspaceShell.tsx': fakeSource('src/workspace/WorkspaceShell.tsx', [369, 372]),
   'src/storage/drawingsStorage.ts': fakeSource('src/storage/drawingsStorage.ts', [90]),
-  'src/components/DrawingTabContent.tsx': fakeSource('src/components/DrawingTabContent.tsx', [
-    83, 112, 121,
-  ]),
+  'src/components/DrawingTabContent.tsx': fakeSource('src/components/DrawingTabContent.tsx', [83, 112, 121]),
 };
 
 function readStoryFile(path: string): Promise<string> {
@@ -144,59 +122,46 @@ const drawingComponents: SubsystemComponent[] = [
   },
 ];
 
-const drawingEdges: SubsystemComponentEdge[] = [
-  { id: 'e-scan', from: 'panel', to: 'storage', mechanism: 'calls' },
-  { id: 'e-open-event', from: 'panel', to: 'host', mechanism: 'produces' },
-  { id: 'e-refresh', from: 'host', to: 'panel', mechanism: 'produces' },
-  { id: 'e-open', from: 'host', to: 'storage', mechanism: 'calls' },
-  { id: 'e-read', from: 'storage', to: 'fs', mechanism: 'calls' },
-  { id: 'e-delete', from: 'host', to: 'fs', mechanism: 'calls' },
-  { id: 'e-show', from: 'host', to: 'shell', mechanism: 'produces' },
-  { id: 'e-mount', from: 'shell', to: 'tab', mechanism: 'feeds' },
-  { id: 'e-tab-io', from: 'tab', to: 'fs', mechanism: 'calls' },
-  { id: 'e-saved-event', from: 'tab', to: 'host', mechanism: 'produces' },
-];
-
-const drawingThroughlines: SubsystemThroughline[] = [
+const drawingWalkthroughs: SubsystemWalkthrough[] = [
   {
     id: 'tl-open-drawing',
     title: 'Open drawing',
     steps: [
-      { edgeId: 'e-scan', file: 'src/panels/DrawingsLeftPanel.tsx', line: 56, symbol: 'DrawingsLeftPanel.scan', annotation: 'Lists the drawings directory; each row feeds an open intent.' },
-      { edgeId: 'e-open-event', file: 'src/panels/DrawingsLeftPanel.tsx', line: 85, symbol: 'DrawingsLeftPanel.openDrawing', annotation: 'Emits the open intent up to the host.' },
-      { edgeId: 'e-open', file: 'src/hooks/useDrawingsHost.ts', line: 45, symbol: 'useDrawingsHost.openDrawing', annotation: 'Host resolves the path and delegates to storage.' },
-      { edgeId: 'e-show', file: 'src/workspace/WorkspaceShell.tsx', line: 369, symbol: 'WorkspaceShell.openTab', annotation: 'Asks the shell to surface the drawing as a tab.' },
-      { edgeId: 'e-mount', file: 'src/workspace/WorkspaceShell.tsx', line: 372, symbol: 'WorkspaceShell.mountTab' },
-      { edgeId: 'e-read', file: 'src/storage/drawingsStorage.ts', line: 90, symbol: 'DrawingsStorage.read', annotation: 'Reads the file through the sandboxed fs service.' },
-      { edgeId: 'e-tab-io', file: 'src/components/DrawingTabContent.tsx', line: 83, symbol: 'DrawingTabContent.load' },
+      { from: 'panel', to: 'storage', mechanism: 'calls', file: 'src/panels/DrawingsLeftPanel.tsx', line: 56, symbol: 'DrawingsLeftPanel.scan', annotation: 'Lists the drawings directory; each row feeds an open intent.' },
+      { from: 'panel', to: 'host', mechanism: 'produces', file: 'src/panels/DrawingsLeftPanel.tsx', line: 85, symbol: 'DrawingsLeftPanel.openDrawing', annotation: 'Emits the open intent up to the host.' },
+      { from: 'host', to: 'storage', mechanism: 'calls', file: 'src/hooks/useDrawingsHost.ts', line: 45, symbol: 'useDrawingsHost.openDrawing', annotation: 'Host resolves the path and delegates to storage.' },
+      { from: 'host', to: 'shell', mechanism: 'produces', file: 'src/workspace/WorkspaceShell.tsx', line: 369, symbol: 'WorkspaceShell.openTab', annotation: 'Asks the shell to surface the drawing as a tab.' },
+      { from: 'shell', to: 'tab', mechanism: 'feeds', file: 'src/workspace/WorkspaceShell.tsx', line: 372, symbol: 'WorkspaceShell.mountTab' },
+      { from: 'storage', to: 'fs', mechanism: 'calls', file: 'src/storage/drawingsStorage.ts', line: 90, symbol: 'DrawingsStorage.read', annotation: 'Reads the file through the sandboxed fs service.' },
+      { from: 'tab', to: 'fs', mechanism: 'calls', file: 'src/components/DrawingTabContent.tsx', line: 83, symbol: 'DrawingTabContent.load' },
     ],
   },
   {
     id: 'tl-save-drawing',
     title: 'Save drawing',
     steps: [
-      { edgeId: 'e-tab-io', file: 'src/components/DrawingTabContent.tsx', line: 112, symbol: 'DrawingTabContent.save' },
-      { edgeId: 'e-saved-event', file: 'src/components/DrawingTabContent.tsx', line: 121, symbol: 'DrawingTabContent.emitSaved' },
-      { edgeId: 'e-refresh', file: 'src/hooks/useDrawingsHost.ts', line: 64, symbol: 'useDrawingsHost.onSaved' },
-      { edgeId: 'e-scan', file: 'src/panels/DrawingsLeftPanel.tsx', line: 56, symbol: 'DrawingsLeftPanel.scan' },
+      { from: 'tab', to: 'fs', mechanism: 'calls', file: 'src/components/DrawingTabContent.tsx', line: 112, symbol: 'DrawingTabContent.save' },
+      { from: 'tab', to: 'host', mechanism: 'produces', file: 'src/components/DrawingTabContent.tsx', line: 121, symbol: 'DrawingTabContent.emitSaved' },
+      { from: 'host', to: 'panel', mechanism: 'produces', file: 'src/hooks/useDrawingsHost.ts', line: 64, symbol: 'useDrawingsHost.onSaved' },
+      { from: 'panel', to: 'storage', mechanism: 'calls', file: 'src/panels/DrawingsLeftPanel.tsx', line: 56, symbol: 'DrawingsLeftPanel.scan' },
     ],
   },
   {
     id: 'tl-delete-drawing',
     title: 'Delete drawing',
     steps: [
-      { edgeId: 'e-delete', file: 'src/hooks/useDrawingsHost.ts', line: 64, symbol: 'useDrawingsHost.deleteDrawing' },
-      { edgeId: 'e-refresh', file: 'src/hooks/useDrawingsHost.ts', line: 66, symbol: 'useDrawingsHost.refreshList' },
-      { edgeId: 'e-scan', file: 'src/panels/DrawingsLeftPanel.tsx', line: 56, symbol: 'DrawingsLeftPanel.scan' },
+      { from: 'host', to: 'fs', mechanism: 'calls', file: 'src/hooks/useDrawingsHost.ts', line: 64, symbol: 'useDrawingsHost.deleteDrawing' },
+      { from: 'host', to: 'panel', mechanism: 'produces', file: 'src/hooks/useDrawingsHost.ts', line: 66, symbol: 'useDrawingsHost.refreshList' },
+      { from: 'panel', to: 'storage', mechanism: 'calls', file: 'src/panels/DrawingsLeftPanel.tsx', line: 56, symbol: 'DrawingsLeftPanel.scan' },
     ],
   },
 ];
 
 function FlowsDemo() {
-  const renderThroughlineViewer = useCallback(
-    ({ throughline, stepIndex }: ThroughlineViewerContext) => (
-      <PierreThroughlineCodeView
-        throughline={throughline}
+  const renderWalkthroughViewer = useCallback(
+    ({ walkthrough, stepIndex }: WalkthroughViewerContext) => (
+      <PierreWalkthroughCodeView
+        walkthrough={walkthrough}
         stepIndex={stepIndex}
         readFile={readStoryFile}
         contextLines={4}
@@ -209,11 +174,11 @@ function FlowsDemo() {
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
       <SubsystemComponentGraph
         components={drawingComponents}
-        edges={drawingEdges}
-        throughlines={drawingThroughlines}
+        relations={[]}
+        walkthroughs={drawingWalkthroughs}
         title="drawing-files flow"
-        description="Three throughlines over one graph — opening, saving, and deleting a drawing. The sidebar's **Flows** panel lists each step by **symbol**; clicking a step focuses that edge and scrolls the bottom CodeView to that snippet."
-        renderThroughlineViewer={renderThroughlineViewer}
+        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}
         renderFileViewer={(file, opts) => (
           <div
             style={{
@@ -236,4 +201,4 @@ function FlowsDemo() {
 
 export const ThreeFlows: Story = {
   render: () => <FlowsDemo />,
-};
+};

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

@@ -137,7 +137,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}
-        edges={reactUiEdges}
+        relations={reactUiEdges.relations} walkthroughs={reactUiEdges.walkthroughs}
       />
     </div>
   ),
@@ -209,7 +209,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}
-        edges={nestEdges}
+        relations={nestEdges.relations} walkthroughs={nestEdges.walkthroughs}
       />
     </div>
   ),

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, edges } from './fixtures';
+import { components, graphSpecFromEdges, relations } from './fixtures';
 
 const meta = {
   title: 'Subsystem/ComponentGraph/GraphTitle',
@@ -30,7 +30,7 @@ const graphOnlyComponents = components([
   ['caller', 'Web client', 'external', '', 'external', undefined, undefined],
 ]);
 
-const graphOnlyEdges = edges([
+const graphOnlyEdges = graphSpecFromEdges([
   ['caller', 'entry', 'calls'],
   ['entry', 'store', 'writes'],
   ['entry', 'stripe', 'calls'],
@@ -41,7 +41,7 @@ function GraphOnly() {
     <div style={{ width: '100%', height: '100vh' }}>
       <SubsystemComponentGraph
         components={graphOnlyComponents}
-        edges={graphOnlyEdges}
+        relations={graphOnlyEdges.relations} walkthroughs={graphOnlyEdges.walkthroughs}
         graphTitle="Checkout"
         hideSidebar
       />
@@ -60,7 +60,7 @@ export const WithSidebar: Story = {
     <div style={{ width: '100%', height: '100vh' }}>
       <SubsystemComponentGraph
         components={graphOnlyComponents}
-        edges={graphOnlyEdges}
+        relations={graphOnlyEdges.relations} walkthroughs={graphOnlyEdges.walkthroughs}
         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/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, edges } from './fixtures';
+import { components, graphSpecFromEdges, relations } from './fixtures';
 
 const meta = {
   title: 'Subsystem/ComponentGraph/Processes',
@@ -47,7 +47,7 @@ const processComponents = [
       : c,
 );
 
-const processEdges = edges([
+const processEdges = graphSpecFromEdges([
   ['main', 'store', 'writes'],
   ['main', 'bridge', 'calls'],
   ['bridge', 'view', 'feeds'],
@@ -61,7 +61,7 @@ export const ProcessBoundaries: Story = {
         title="Process boundaries"
         description="Host and renderer each render in their own ELK-aware boundary frame. The telemetry service has no `process` and sits outside every boundary."
         components={processComponents}
-        edges={processEdges}
+        relations={processEdges.relations} walkthroughs={processEdges.walkthroughs}
       />
     </div>
   ),