@principal-ai/subsystems-react 0.20.5 → 0.21.0

package/src/pierre/{PierreThroughlineCodeView.tsx → PierreWalkthroughCodeView.tsx}

@@ -1,7 +1,7 @@
 /**
- * PierreThroughlineCodeView — multi-file step snippets via `@pierre/diffs` CodeView.
+ * PierreWalkthroughCodeView — multi-file step snippets via `@pierre/diffs` CodeView.
  *
- * Renders one sliced window per throughline step in a single virtualized
+ * Renders one sliced window per walkthrough step in a single virtualized
  * scroll; when `stepIndex` changes, scrolls that step's site line into view
  * and highlights it via CodeView `selectedLines` (same mechanism as
  * `PierreSnippetView`).
@@ -22,10 +22,10 @@ type CodeViewLineSelection = {
   id: string;
   range: { start: number; end: number };
 };
-/** Metadata carried on a throughline step's line annotation. */
-type ThroughlineStepAnnotation = { text: string };
+/** Metadata carried on a walkthrough step's line annotation. */
+type WalkthroughStepAnnotation = { text: string };
 import { useTheme } from '@principal-ade/industry-theme';
-import type { SubsystemThroughline } from '../subsystem/model';
+import type { SubsystemWalkthrough } from '../subsystem/model';
 import { buildPierreOptions, PIERRE_FILE_STYLE } from './pierreBackground';
 import {
   pierreCodeViewFileName,
@@ -34,8 +34,8 @@ import {
 import { resolvePierreSyntaxThemeName } from './pierreSyntaxTheme';
 import { sliceSnippetWindow, type SnippetSlice } from './sliceSnippet';
 
-export interface PierreThroughlineCodeViewProps {
-  throughline: SubsystemThroughline;
+export interface PierreWalkthroughCodeViewProps {
+  walkthrough: SubsystemWalkthrough;
   /** Focused step; `null` shows all snippets without scrolling to a step. */
   stepIndex: number | null;
   readFile: (path: string) => Promise<string>;
@@ -50,31 +50,31 @@ type FileLoadState =
   | { status: 'error'; message: string }
   | { status: 'ready'; byPath: Map<string, string> };
 
-function stepItemId(throughlineId: string, index: number): string {
-  return `${throughlineId}:${index}`;
+function stepItemId(walkthroughId: string, index: number): string {
+  return `${walkthroughId}:${index}`;
 }
 
-export function PierreThroughlineCodeView({
-  throughline,
+export function PierreWalkthroughCodeView({
+  walkthrough,
   stepIndex,
   readFile,
   contextLines = 8,
   background,
-}: PierreThroughlineCodeViewProps) {
+}: PierreWalkthroughCodeViewProps) {
   const { theme, mode } = useTheme();
   const viewRef = useRef<CodeViewHandle<undefined>>(null);
   const [load, setLoad] = useState<FileLoadState>({ status: 'loading' });
 
   const pathsKey = useMemo(() => {
-    const paths = [...new Set(throughline.steps.map((s) => s.file))];
+    const paths = [...new Set(walkthrough.steps.map((s) => s.file))];
     paths.sort();
     return paths.join('\0');
-  }, [throughline.steps]);
+  }, [walkthrough.steps]);
 
   useEffect(() => {
     let cancelled = false;
     setLoad({ status: 'loading' });
-    const paths = [...new Set(throughline.steps.map((s) => s.file))];
+    const paths = [...new Set(walkthrough.steps.map((s) => s.file))];
     void Promise.all(
       paths.map(async (path) => {
         const contents = await readFile(path);
@@ -95,11 +95,11 @@ export function PierreThroughlineCodeView({
     return () => {
       cancelled = true;
     };
-  }, [throughline.id, pathsKey, readFile]);
+  }, [walkthrough.id, pathsKey, readFile]);
 
   const slices = useMemo((): SnippetSlice[] => {
     if (load.status !== 'ready') return [];
-    return throughline.steps.map((step) => {
+    return walkthrough.steps.map((step) => {
       const contents = load.byPath.get(step.file) ?? '';
       return sliceSnippetWindow(
         contents,
@@ -109,15 +109,15 @@ export function PierreThroughlineCodeView({
         step.line,
       );
     });
-  }, [load, throughline.steps, contextLines]);
+  }, [load, walkthrough.steps, contextLines]);
 
-const items = useMemo((): CodeViewItem<ThroughlineStepAnnotation>[] => {
+const items = useMemo((): CodeViewItem<WalkthroughStepAnnotation>[] => {
     if (load.status !== 'ready' || slices.length === 0) return [];
-    return throughline.steps.map((step, index) => {
+    return walkthrough.steps.map((step, index) => {
       const slice = slices[index]!;
       const focus = slice.focusOffset;
       const annotations:
-        | LineAnnotation<ThroughlineStepAnnotation>[]
+        | LineAnnotation<WalkthroughStepAnnotation>[]
         | undefined =
         step.annotation != null && step.annotation.length > 0 && focus != null
           ? [
@@ -128,26 +128,20 @@ const items = useMemo((): CodeViewItem<ThroughlineStepAnnotation>[] => {
             ]
           : undefined;
       return {
-        id: stepItemId(throughline.id, index),
+        id: stepItemId(walkthrough.id, index),
         type: 'file' as const,
         version: 1,
         annotations,
         file: {
-          // Unique per-step name: many throughline steps share one path
-          // (e.g. seven sites in main.cpp), and identical `name`s have
-          // correlated with WebKit renderer traps in CodeView.
           name: pierreCodeViewFileName(step.file, index),
           contents: slice.contents,
-          // C-family → plain text: cpp Shiki still traps WebKit even with
-          // unique names (reproduced on 0.16.67).
           lang: pierreLangForPath(step.file),
-          cacheKey: `${throughline.id}:${index}:${step.file}:${step.line}:${slice.sliceStart}-${slice.sliceEnd}`,
+          cacheKey: `${walkthrough.id}:${index}:${step.file}:${step.line}:${slice.sliceStart}-${slice.sliceEnd}`,
         },
       };
     });
-  }, [load, slices, throughline.id, throughline.steps]);
+  }, [load, slices, walkthrough.id, walkthrough.steps]);
 
-  /** Highlight the focused step's site line (1-based within its sliced window). */
   const selectedLines = useMemo((): CodeViewLineSelection | null => {
     if (stepIndex == null || stepIndex < 0 || stepIndex >= slices.length) {
       return null;
@@ -155,15 +149,15 @@ const items = useMemo((): CodeViewItem<ThroughlineStepAnnotation>[] => {
     const focus = slices[stepIndex]?.focusOffset;
     if (focus == null) return null;
     return {
-      id: stepItemId(throughline.id, stepIndex),
+      id: stepItemId(walkthrough.id, stepIndex),
       range: { start: focus, end: focus },
     };
-  }, [stepIndex, slices, throughline.id]);
+  }, [stepIndex, slices, walkthrough.id]);
 
   const renderHeaderPrefix = useMemo(() => {
     return (item: CodeViewItem) => {
       const index = Number.parseInt(item.id.split(':').pop() ?? '', 10);
-      const step = throughline.steps[index];
+      const step = walkthrough.steps[index];
       if (!step) return null;
       const label =
         step.symbol != null && step.symbol.length > 0
@@ -182,12 +176,12 @@ const items = useMemo((): CodeViewItem<ThroughlineStepAnnotation>[] => {
         </span>
       );
     };
-  }, [throughline.steps, theme]);
+  }, [walkthrough.steps, theme]);
 
   const renderHeaderMetadata = useMemo(() => {
     return (item: CodeViewItem) => {
       const index = Number.parseInt(item.id.split(':').pop() ?? '', 10);
-      const step = throughline.steps[index];
+      const step = walkthrough.steps[index];
       if (!step) return null;
       return (
         <span
@@ -202,17 +196,17 @@ const items = useMemo((): CodeViewItem<ThroughlineStepAnnotation>[] => {
         </span>
       );
     };
-  }, [throughline.steps, theme]);
+  }, [walkthrough.steps, theme]);
 
   const renderAnnotation = useMemo(() => {
     return (
       annotation:
-        | LineAnnotation<ThroughlineStepAnnotation>
-        | DiffLineAnnotation<ThroughlineStepAnnotation>,
-      item: CodeViewItem<ThroughlineStepAnnotation>,
+        | LineAnnotation<WalkthroughStepAnnotation>
+        | DiffLineAnnotation<WalkthroughStepAnnotation>,
+      item: CodeViewItem<WalkthroughStepAnnotation>,
     ) => {
       const index = Number.parseInt(item.id.split(':').pop() ?? '', 10);
-      const step = throughline.steps[index];
+      const step = walkthrough.steps[index];
       const text = annotation.metadata?.text;
       if (!text || !step) return null;
       return (
@@ -230,7 +224,7 @@ const items = useMemo((): CodeViewItem<ThroughlineStepAnnotation>[] => {
         </span>
       );
     };
-  }, [throughline.steps, theme]);
+  }, [walkthrough.steps, theme]);
 
   const options = useMemo((): CodeViewReactOptions => {
     return {
@@ -248,11 +242,10 @@ const items = useMemo((): CodeViewItem<ThroughlineStepAnnotation>[] => {
 
   useEffect(() => {
     if (load.status !== 'ready' || stepIndex == null) return;
-    if (stepIndex < 0 || stepIndex >= throughline.steps.length) return;
+    if (stepIndex < 0 || stepIndex >= walkthrough.steps.length) return;
     const focus = slices[stepIndex]?.focusOffset;
     if (focus == null) return;
-    // Defer until CodeView has laid out items.
-    const id = stepItemId(throughline.id, stepIndex);
+    const id = stepItemId(walkthrough.id, stepIndex);
     const t = window.setTimeout(() => {
       viewRef.current?.scrollTo({
         type: 'line',
@@ -265,8 +258,8 @@ const items = useMemo((): CodeViewItem<ThroughlineStepAnnotation>[] => {
   }, [
     load.status,
     stepIndex,
-    throughline.id,
-    throughline.steps.length,
+    walkthrough.id,
+    walkthrough.steps.length,
     slices,
     items.length,
   ]);
@@ -286,7 +279,6 @@ const items = useMemo((): CodeViewItem<ThroughlineStepAnnotation>[] => {
     );
   }
 
-  // Pierre's CodeView prop / item unions blow past TS's complexity limit.
   const CodeViewLoose = CodeView as unknown as (props: Record<string, unknown>) => ReactElement;
 
   return (

package/src/pierre/index.ts

@@ -2,8 +2,8 @@ export { PierreFileView } from './PierreFileView';
 export type { PierreFileViewProps } from './PierreFileView';
 export { PierreSnippetView } from './PierreSnippetView';
 export type { PierreSnippetViewProps } from './PierreSnippetView';
-export { PierreThroughlineCodeView } from './PierreThroughlineCodeView';
-export type { PierreThroughlineCodeViewProps } from './PierreThroughlineCodeView';
+export { PierreWalkthroughCodeView } from './PierreWalkthroughCodeView';
+export type { PierreWalkthroughCodeViewProps } from './PierreWalkthroughCodeView';
 export { sliceSnippetWindow } from './sliceSnippet';
 export type { SnippetSlice } from './sliceSnippet';
 export {

package/src/pierre/pierreFileLang.ts

@@ -7,7 +7,7 @@
  * `file.name`s — so we force plain text for those paths until Pierre/WebKit
  * is safe with them.
  *
- * Distinct throughline slices of the same path still need unique `file.name`s
+ * Distinct walkthrough slices of the same path still need unique `file.name`s
  * (see `pierreCodeViewFileName`).
  */
 

package/src/stories/Pierre/CodeView.stories.tsx

@@ -1,7 +1,7 @@
 /**
  * Demo: Pierre CodeView with snippets from different files.
  *
- * Throughlines want many short windows across files in one scroll —
+ * Walkthroughs want many short windows across files in one scroll —
  * CodeView is the Pierre primitive for that (virtualized list of file items).
  */
 import React, { useMemo, useRef } from 'react';
@@ -54,7 +54,7 @@ const SNIPPETS: SnippetSpec[] = [
     startLine: 216,
     endLine: 250,
     focusLine: 216,
-    label: '3 · Throughline types',
+    label: '3 · Walkthrough types',
   },
 ];
 
@@ -159,7 +159,7 @@ function MultiFileSnippetsDemo() {
         }}
       >
         <div style={{ fontSize: 13, fontWeight: 600, marginBottom: 4 }}>
-          Throughline steps
+          Walkthrough steps
         </div>
         <div style={{ fontSize: 12, color: theme.colors.textSecondary, marginBottom: 8 }}>
           Click a step to scroll + highlight its site line.

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

@@ -43,7 +43,7 @@ const cases: { label: string; component: SubsystemComponent }[] = [
       file: 'src/event-processing/sink.ts',
       purl: 'pkg:github/principal-ai/agent-monitoring',
       symbol: 'flush',
-      detail: {
+      declaration: {
         kind: 'function',
         parameters: [],
       } satisfies GraphifyComponentDetail,
@@ -58,7 +58,7 @@ const cases: { label: string; component: SubsystemComponent }[] = [
       file: 'src/session/SessionReader.ts',
       purl: 'pkg:github/principal-ai/agent-monitoring',
       symbol: 'SessionReader.normalize',
-      detail: {
+      declaration: {
         kind: 'function',
         parameters: [{ name: 'session', type: 'SessionRecord' }],
         returnType: 'SessionEvent[]',
@@ -74,7 +74,7 @@ const cases: { label: string; component: SubsystemComponent }[] = [
       file: 'src/event-processing/normalize.ts',
       purl: 'pkg:github/principal-ai/agent-monitoring',
       symbol: 'normalizeSession',
-      detail: {
+      declaration: {
         kind: 'function',
         parameters: [
           { name: 'session', type: 'SessionRecord' },
@@ -93,7 +93,7 @@ const cases: { label: string; component: SubsystemComponent }[] = [
       file: 'src/session/merge.ts',
       purl: 'pkg:github/principal-ai/agent-monitoring',
       symbol: 'mergeSessions',
-      detail: {
+      declaration: {
         kind: 'function',
         parameters: [
           { name: 'sessions', type: 'SessionRecord[]' },
@@ -114,7 +114,7 @@ const cases: { label: string; component: SubsystemComponent }[] = [
       file: 'src/empty.ts',
       purl: 'pkg:github/principal-ai/agent-monitoring',
       symbol: 'EmptyClass',
-      detail: {
+      declaration: {
         kind: 'class',
       } satisfies GraphifyComponentDetail,
     },
@@ -128,7 +128,7 @@ const cases: { label: string; component: SubsystemComponent }[] = [
       file: 'src/config.ts',
       purl: 'pkg:github/principal-ai/agent-monitoring',
       symbol: 'Config',
-      detail: {
+      declaration: {
         kind: 'class',
         properties: [
           { name: 'host', type: 'string' },
@@ -147,7 +147,7 @@ const cases: { label: string; component: SubsystemComponent }[] = [
       file: 'src/event-processing/EventProcessor.ts',
       purl: 'pkg:github/principal-ai/agent-monitoring',
       symbol: 'EventProcessor',
-      detail: {
+      declaration: {
         kind: 'class',
         methods: [
           { name: 'process', parameters: [{ type: 'RawEvent' }, { type: 'ProcessingOptions' }], returnType: 'ProcessedEvent' },
@@ -174,7 +174,7 @@ const cases: { label: string; component: SubsystemComponent }[] = [
       file: 'src/session/transcript.ts',
       purl: 'pkg:github/principal-ai/agent-monitoring',
       symbol: 'SessionRecord',
-      detail: {
+      declaration: {
         kind: 'type',
         properties: [
           { name: 'id', type: 'string' },
@@ -192,7 +192,7 @@ const cases: { label: string; component: SubsystemComponent }[] = [
       file: 'src/types.ts',
       purl: 'pkg:github/principal-ai/agent-monitoring',
       symbol: 'BrandedId',
-      detail: {
+      declaration: {
         kind: 'type',
       } satisfies GraphifyComponentDetail,
     },
@@ -206,7 +206,7 @@ const cases: { label: string; component: SubsystemComponent }[] = [
       file: 'src/index.ts',
       purl: 'pkg:github/principal-ai/agent-monitoring',
       symbol: 'index',
-      detail: {
+      declaration: {
         kind: 'module',
         imports: [
           { name: './session/SessionReader' },
@@ -237,7 +237,7 @@ const cases: { label: string; component: SubsystemComponent }[] = [
       file: '',
       purl: 'pkg:npm/@principal-ai/subsystems-studio',
       symbol: '',
-      detail: {
+      declaration: {
         kind: 'external',
         label: 'pkg:npm/@principal-ai/subsystems-studio',
       } satisfies GraphifyComponentDetail,
@@ -251,7 +251,7 @@ const cases: { label: string; component: SubsystemComponent }[] = [
       construct: 'function',
       file: 'src/helpers.ts',
       purl: 'pkg:github/principal-ai/agent-monitoring',
-      detail: {
+      declaration: {
         kind: 'function',
         parameters: [{ name: 'input', type: 'string' }],
         returnType: 'void',
@@ -267,7 +267,7 @@ const cases: { label: string; component: SubsystemComponent }[] = [
       file: 'src/session/SessionReader.ts',
       purl: 'pkg:github/principal-ai/agent-monitoring',
       symbol: 'SessionReader.normalize',
-      detail: {
+      declaration: {
         kind: 'method',
         hostClass: 'SessionReader',
         parameters: [{ name: 'session', type: 'SessionRecord' }],
@@ -284,7 +284,7 @@ const cases: { label: string; component: SubsystemComponent }[] = [
       file: 'src/event-processing/EventProcessor.ts',
       purl: 'pkg:github/principal-ai/agent-monitoring',
       symbol: 'EventProcessor.dispose',
-      detail: {
+      declaration: {
         kind: 'method',
         hostClass: 'EventProcessor',
       } satisfies GraphifyComponentDetail,

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, investigateOnlyEdges } from './fixtures';
+import { investigateOnlyComponents, investigateOnlyRelations, investigateOnlyWalkthroughs } 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}
-        edges={investigateOnlyEdges}
+        relations={investigateOnlyRelations} walkthroughs={investigateOnlyWalkthroughs}
         maxNodeWidth={140}
       />
     </div>
@@ -93,7 +93,6 @@ const namingConventionComponents: SubsystemComponent[] = [
   },
 ];
 
-const namingConventionEdges: SubsystemComponentEdge[] = [];
 
 /** Nodes with compact `maxNodeWidth` so the different conventions visibly wrap
  *  at their word boundaries (camelCase, snake_case, PascalCase, acronyms). */
@@ -102,7 +101,7 @@ export const NamingConventions: Story = {
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
       <SubsystemComponentGraph
         components={namingConventionComponents}
-        edges={namingConventionEdges}
+        relations={[]}
         maxNodeWidth={180}
       />
     </div>
@@ -137,7 +136,7 @@ const kindVariationComponents: SubsystemComponent[] = [
     purpose: 'members only — methods with typed params + returns, a typed field',
     symbol: 'Transcoder',
     layer: 1,
-    detail: {
+    declaration: {
       kind: 'class',
       methods: [
         { nodeId: 'tm1', name: 'encode', parameters: [{ type: 'RawFrame' }], returnType: 'Uint8Array' },
@@ -160,7 +159,7 @@ const kindVariationComponents: SubsystemComponent[] = [
     purpose: 'relationships only — extends + implements, constructed-by comment; empty body elides the braces',
     symbol: 'HttpTransport',
     layer: 1,
-    detail: {
+    declaration: {
       kind: 'class',
       methods: [],
       properties: [],
@@ -191,7 +190,7 @@ const kindVariationComponents: SubsystemComponent[] = [
     purpose: 'signature only — named + positional (type-only) params, array return; no callers/callees comments',
     symbol: 'normalizeSession',
     layer: 2,
-    detail: {
+    declaration: {
       kind: 'function',
       parameters: [
         { name: 'session', type: 'SessionRecord' },
@@ -211,7 +210,7 @@ const kindVariationComponents: SubsystemComponent[] = [
     purpose: 'signature + call relationships — union-typed param, generic return, called-by / calls trailing comments',
     symbol: 'mergeSessions',
     layer: 2,
-    detail: {
+    declaration: {
       kind: 'function',
       parameters: [
         { name: 'sessions', type: 'SessionRecord[]' },
@@ -243,7 +242,7 @@ const kindVariationComponents: SubsystemComponent[] = [
     purpose: 'fields only — typed interface body, nothing else',
     symbol: 'SessionRecord',
     layer: 3,
-    detail: {
+    declaration: {
       kind: 'type',
       properties: [
         { name: 'id', type: 'string' },
@@ -262,7 +261,7 @@ const kindVariationComponents: SubsystemComponent[] = [
     purpose: 'full — fields + implemented-by (clicks through to HttpTransport) + used-by comments',
     symbol: 'Transport',
     layer: 3,
-    detail: {
+    declaration: {
       kind: 'type',
       properties: [{ name: 'name', type: 'string' }],
       usedBy: [{ nodeId: 'u1', name: 'main', context: 'parameter_type' }],
@@ -290,7 +289,7 @@ const kindVariationComponents: SubsystemComponent[] = [
     purpose: 'exports only — export statement + defines comment',
     symbol: '',
     layer: 4,
-    detail: {
+    declaration: {
       kind: 'module',
       exports: ['extractToolName', 'extractFilePath'],
       imports: [],
@@ -306,7 +305,7 @@ const kindVariationComponents: SubsystemComponent[] = [
     purpose: 'full — import statements + re-export statement + defines comment',
     symbol: '',
     layer: 4,
-    detail: {
+    declaration: {
       kind: 'module',
       exports: ['SessionReader', 'SessionStore'],
       imports: [{ nodeId: 'i1', name: 'transcript', relation: 'imports_from' }],
@@ -334,14 +333,13 @@ const kindVariationComponents: SubsystemComponent[] = [
     purpose: 'labeled — the full purl as a quoted string literal',
     symbol: '',
     layer: 5,
-    detail: {
+    declaration: {
       kind: 'external',
       label: 'pkg:npm/@principal-ai/subsystems-studio',
     } satisfies GraphifyComponentDetail,
   },
 ];
 
-const kindVariationEdges: SubsystemComponentEdge[] = [];
 
 function KindVariationsDemo() {
   const [selected, setSelected] = useState<string | null>(null);
@@ -349,7 +347,7 @@ function KindVariationsDemo() {
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
       <SubsystemComponentGraph
         components={kindVariationComponents}
-        edges={kindVariationEdges}
+        relations={[]}
         onSelect={(id) => setSelected(id)}
       />
       <div style={{ marginTop: 8, fontFamily: 'monospace', fontSize: 12, color: '#aaa' }}>

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, edges } from './fixtures';
+import { components, graphSpecFromEdges } 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 = edges([
+const twoNodeEdges = graphSpecFromEdges([
   ['src', 'dst', 'imports'],
 ]);
 
@@ -44,7 +44,7 @@ function TwoNodeDemo({ showEdgeLabels = true }: { showEdgeLabels?: boolean }) {
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
       <SubsystemComponentGraph
         components={twoNodeComponents}
-        edges={twoNodeEdges}
+        relations={twoNodeEdges.relations} walkthroughs={twoNodeEdges.walkthroughs}
         onSelect={(id) => setSelected(id)}
         onEdgeSelect={(e) => setSelectedEdge(e)}
         showEdgeLabels={showEdgeLabels}
@@ -74,7 +74,7 @@ export const TwoNodeNoLabels: Story = {
 // ---------------------------------------------------------------------------
 function PlaygroundDemo({ leftCount, rightCount, showEdgeLabels }: { leftCount: number; rightCount: number; showEdgeLabels: boolean }) {
   const comps: SubsystemComponent[] = [];
-  const edgeList: SubsystemComponentEdge[] = [];
+  const edgeSpec: Array<[string, string, SubsystemComponentEdge['mechanism']]> = [];
 
   for (let i = 0; i < leftCount; i++) {
     comps.push({
@@ -97,16 +97,16 @@ function PlaygroundDemo({ leftCount, rightCount, showEdgeLabels }: { leftCount:
     });
   }
 
-  let ei = 0;
   for (let i = 0; i < leftCount; i++) {
     for (let j = 0; j < rightCount; j++) {
-      edgeList.push({ id: `e${ei++}`, from: `l${i}`, to: `r${j}`, mechanism: 'imports' });
+      edgeSpec.push([`l${i}`, `r${j}`, 'imports']);
     }
   }
+  const graph = graphSpecFromEdges(edgeSpec);
 
   return (
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
-      <SubsystemComponentGraph components={comps} edges={edgeList} showEdgeLabels={showEdgeLabels} />
+      <SubsystemComponentGraph components={comps} relations={graph.relations} walkthroughs={graph.walkthroughs} showEdgeLabels={showEdgeLabels} />
     </div>
   );
 }
@@ -131,7 +131,7 @@ export const Playground: Story = {
 export const Empty: Story = {
   render: () => (
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
-      <SubsystemComponentGraph components={[]} edges={[]} />
+      <SubsystemComponentGraph components={[]} relations={[]} />
     </div>
   ),
 };