@principal-ai/subsystems-react 0.36.1 → 0.37.0

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

@@ -171,6 +171,8 @@ function FlowsDemo() {
       stepIndex,
       onOpenFile,
       proposedAliases,
+      resolveSymbol,
+      onSymbolClick,
     }: WalkthroughViewerContext) => (
       <PierreWalkthroughCodeView
         walkthrough={walkthrough}
@@ -179,6 +181,8 @@ function FlowsDemo() {
         contextLines={4}
         onOpenFile={onOpenFile}
         proposedAliases={proposedAliases}
+        resolveSymbol={resolveSymbol}
+        onSymbolClick={onSymbolClick}
       />
     ),
     [],
@@ -276,6 +280,8 @@ function ProposedMissingStepDemo() {
       stepIndex,
       onOpenFile,
       proposedAliases,
+      resolveSymbol,
+      onSymbolClick,
     }: WalkthroughViewerContext) => (
       <PierreWalkthroughCodeView
         walkthrough={walkthrough}
@@ -284,6 +290,8 @@ function ProposedMissingStepDemo() {
         contextLines={4}
         onOpenFile={onOpenFile}
         proposedAliases={proposedAliases}
+        resolveSymbol={resolveSymbol}
+        onSymbolClick={onSymbolClick}
       />
     ),
     [],
@@ -319,3 +327,217 @@ function ProposedMissingStepDemo() {
 export const ProposedMissingStep: Story = {
   render: () => <ProposedMissingStepDemo />,
 };
+
+// --- Clickable constructs -------------------------------------------------
+//
+// A walkthrough 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
+// declaration line in the bottom drawer. The second endpoint here is a
+// `method` construct (`DrawingStore.list`), so the bare `list` token is
+// clickable and jumps to the method's declaration.
+
+const clickableComponents: SubsystemComponent[] = [
+  {
+    alias: 'load-panel',
+    name: 'LoadPanel',
+    construct: 'function',
+    file: 'src/load/LoadPanel.tsx',
+    purl: 'pkg:github/principal-ai/desktop-app',
+    symbol: 'LoadPanel',
+    purpose: 'loads the drawing list and hands rows to the render surface',
+    process: 'draw-list',
+    declarationRef: {
+      file: 'src/load/LoadPanel.tsx',
+      startLine: 3,
+      lineHash: 'story',
+      capturedAt: '2026-01-01T00:00:00.000Z',
+    },
+    declaration: {
+      kind: 'function',
+      parameters: [],
+      returnType: 'JSX.Element',
+      callers: [],
+      callees: [],
+    },
+    declarationProvenance: 'authored',
+  },
+  {
+    alias: 'drawing-store-list',
+    name: 'list',
+    construct: 'method',
+    file: 'src/store/DrawingStore.ts',
+    purl: 'pkg:github/principal-ai/desktop-app',
+    symbol: 'DrawingStore.list',
+    purpose: 'lists stored drawings for the panel',
+    process: 'draw-list',
+    declarationRef: {
+      file: 'src/store/DrawingStore.ts',
+      startLine: 4,
+      lineHash: 'story',
+      capturedAt: '2026-01-01T00:00:00.000Z',
+    },
+    declaration: {
+      kind: 'method',
+      hostClass: 'DrawingStore',
+      parameters: [],
+      returnType: 'Drawing[]',
+    },
+    declarationProvenance: 'authored',
+  },
+  {
+    alias: 'render-surface',
+    name: 'RenderSurface',
+    construct: 'class',
+    file: 'src/render/RenderSurface.ts',
+    purl: 'pkg:github/principal-ai/desktop-app',
+    symbol: 'RenderSurface',
+    purpose: 'paints a drawing into a surface',
+    process: 'draw-host',
+    declarationRef: {
+      file: 'src/render/RenderSurface.ts',
+      startLine: 3,
+      lineHash: 'story',
+      capturedAt: '2026-01-01T00:00:00.000Z',
+    },
+    declaration: {
+      kind: 'class',
+      methods: [{ nodeId: 'RenderSurface.render', name: 'render' }],
+      properties: [],
+      extends: [],
+      implements: [],
+      instantiations: [],
+      references: [],
+    },
+    declarationProvenance: 'authored',
+  },
+];
+
+const clickableFiles: Record<string, string> = {
+  'src/load/LoadPanel.tsx': [
+    '// src/load/LoadPanel.tsx',
+    '',
+    'export function LoadPanel() {',
+    '  const rows = DrawingStore.list();',
+    '  return rows.map(RenderSurface.render);',
+    '}',
+  ].join('\n'),
+  'src/store/DrawingStore.ts': [
+    '// src/store/DrawingStore.ts',
+    '',
+    'export class DrawingStore {',
+    '  static list() {',
+    '    return RenderSurface.read();',
+    '  }',
+    '}',
+  ].join('\n'),
+};
+
+function readClickableFile(path: string): Promise<string> {
+  const content = clickableFiles[path];
+  if (content == null) {
+    return Promise.reject(new Error(`file not found in graph repos: ${path}`));
+  }
+  return Promise.resolve(content);
+}
+
+const clickableWalkthroughs: SubsystemWalkthrough[] = [
+  {
+    id: 'tl-load',
+    title: 'Load drawings',
+    steps: [
+      {
+        from: 'load-panel',
+        to: 'drawing-store-list',
+        mechanism: 'calls',
+        file: 'src/load/LoadPanel.tsx',
+        line: 4,
+        purl: stepPurl('src/load/LoadPanel.tsx'),
+        symbol: 'LoadPanel.load',
+        annotation:
+          'LoadPanel calls DrawingStore.list — click the `list` (or `DrawingStore`) token to jump to the method.',
+      },
+      {
+        from: 'drawing-store-list',
+        to: 'render-surface',
+        mechanism: 'calls',
+        file: 'src/store/DrawingStore.ts',
+        line: 5,
+        purl: stepPurl('src/store/DrawingStore.ts'),
+        symbol: 'DrawingStore.list',
+        annotation: 'list reads through RenderSurface — click RenderSurface.',
+      },
+    ],
+  },
+];
+
+function ClickableConstructsDemo() {
+  const [opened, setOpened] = React.useState<string | null>(null);
+  const renderWalkthroughViewer = useCallback(
+    ({
+      walkthrough,
+      stepIndex,
+      onOpenFile,
+      proposedAliases,
+      resolveSymbol,
+      onSymbolClick,
+    }: WalkthroughViewerContext) => (
+      <PierreWalkthroughCodeView
+        walkthrough={walkthrough}
+        stepIndex={stepIndex}
+        readFile={readClickableFile}
+        contextLines={4}
+        onOpenFile={onOpenFile}
+        proposedAliases={proposedAliases}
+        resolveSymbol={resolveSymbol}
+        onSymbolClick={onSymbolClick}
+      />
+    ),
+    [],
+  );
+
+  return (
+    <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
+      <div
+        style={{
+          padding: '8px 14px',
+          fontFamily: 'monospace',
+          fontSize: 12,
+          borderBottom: '1px solid #333',
+          background: '#141414',
+          color: '#ddd',
+        }}
+      >
+        Click the <strong>Load drawings</strong> step, then click the dotted-underlined{' '}
+        <code>list</code> <em>(a method)</em> or <code>RenderSurface</code> token in the
+        snippet. It opens that construct's file at its declaration line in the bottom drawer
+        — <code>list</code> jumps to <code>DrawingStore.ts:4</code>.
+        <span style={{ marginLeft: 8, color: '#8fd' }}>opened: {opened ?? '—'}</span>
+      </div>
+      <div style={{ flex: 1, minHeight: 0 }}>
+        <SubsystemComponentGraph
+          components={clickableComponents}
+          relations={[]}
+          walkthroughs={clickableWalkthroughs}
+          initialWalkthroughId="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}
+          onFileSelect={setOpened}
+          renderFileViewer={(file, opts) => (
+            <div style={{ padding: 12, fontFamily: 'monospace', fontSize: 12, color: '#bbb' }}>
+              {`// ${file}`}
+              {opts?.startLine != null ? `\n  // → focus line ${opts.startLine}` : ''}
+              {'\n  …'}
+            </div>
+          )}
+        />
+      </div>
+    </div>
+  );
+}
+
+export const ClickableConstructs: Story = {
+  render: () => <ClickableConstructsDemo />,
+};

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

@@ -0,0 +1,137 @@
+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 } from '../../../subsystem/model';
+import { graphSpecFromEdges } from './fixtures';
+
+const meta = {
+  title: 'Subsystem/ComponentGraph/WorkspacePackages',
+  component: SubsystemComponentGraph,
+  parameters: { layout: 'fullscreen' },
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <ThemeProvider theme={defaultEditorTheme}>
+        <Story />
+      </ThemeProvider>
+    ),
+  ],
+} satisfies Meta<typeof SubsystemComponentGraph>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const STUDIO = 'pkg:npm/@principal-ai/subsystems-studio';
+const REACT = 'pkg:npm/@principal-ai/subsystems-react';
+const RENDERER = 'principal-studio/renderer';
+
+/**
+ * Workspace-package preview — one repo, two packages.
+ *
+ * `purl` carries the workspace-package identity (npm purls here), so package
+ * frames draw per package instead of one frame per repo. The app package owns
+ * the runtime process: only `subsystems-studio` code sits inside
+ * `principal-studio/renderer`. The consumed library (`subsystems-react`) is a
+ * dependency, not a deployment unit, so it is housed in its own package frame
+ * outside that process — reached by cross-package edges instead of nesting.
+ *
+ * Tree: package → process → module → leaves, with the library package beside
+ * the process rather than inside it.
+ */
+const components: SubsystemComponent[] = [
+  // --- packages/subsystems-studio · inside process principal-studio/renderer
+  {
+    alias: 'model-view',
+    name: 'SubsystemModelView',
+    construct: 'function',
+    symbol: 'SubsystemModelView',
+    file: 'packages/subsystems-studio/src/mainview/views/SubsystemModelView.tsx',
+    module: 'packages/subsystems-studio/src/mainview/views/SubsystemModelView.tsx',
+    process: RENDERER,
+    purl: STUDIO,
+    purpose: 'renderer view that opens a subsystem model',
+    layer: 0,
+  },
+  {
+    alias: 'read-file',
+    name: 'readSubsystemFile',
+    construct: 'function',
+    symbol: 'readSubsystemFile',
+    file: 'packages/subsystems-studio/src/mainview/views/SubsystemModelView.tsx',
+    module: 'packages/subsystems-studio/src/mainview/views/SubsystemModelView.tsx',
+    process: RENDERER,
+    purl: STUDIO,
+    purpose: 'request a file slice for the drawer',
+    layer: 1,
+  },
+  {
+    alias: 'get-model',
+    name: 'getSubsystemModel',
+    construct: 'function',
+    symbol: 'getSubsystemModel',
+    file: 'packages/subsystems-studio/src/bun/subsystem-model-store.ts',
+    module: 'packages/subsystems-studio/src/bun/subsystem-model-store.ts',
+    process: RENDERER,
+    purl: STUDIO,
+    purpose: 'load a model document for the view',
+    layer: 2,
+  },
+
+  // --- packages/subsystems-react · consumed library, housed outside the process
+  {
+    alias: 'component-graph',
+    name: 'SubsystemComponentGraph',
+    construct: 'function',
+    symbol: 'SubsystemComponentGraph',
+    file: 'packages/subsystems-react/src/subsystem/SubsystemComponentGraph.tsx',
+    module: 'packages/subsystems-react/src/subsystem/SubsystemComponentGraph.tsx',
+    purl: REACT,
+    purpose: 'the graph canvas the view embeds',
+    layer: 1,
+  },
+  {
+    alias: 'file-drawer',
+    name: 'FileDrawer',
+    construct: 'function',
+    symbol: 'FileDrawer',
+    file: 'packages/subsystems-react/src/subsystem/FileDrawer.tsx',
+    module: 'packages/subsystems-react/src/subsystem/FileDrawer.tsx',
+    purl: REACT,
+    purpose: 'pierre-backed source drawer',
+    layer: 2,
+  },
+  {
+    alias: 'pierre-file-view',
+    name: 'PierreFileView',
+    construct: 'function',
+    symbol: 'PierreFileView',
+    file: 'packages/subsystems-react/src/pierre/PierreFileView.tsx',
+    module: 'packages/subsystems-react/src/pierre/PierreFileView.tsx',
+    purl: REACT,
+    purpose: 'renders one file slice',
+    layer: 3,
+  },
+];
+
+const spec = graphSpecFromEdges([
+  ['read-file', 'get-model', 'calls'],
+  ['model-view', 'component-graph', 'uses'],
+  ['component-graph', 'file-drawer', 'calls'],
+  ['file-drawer', 'pierre-file-view', 'uses'],
+]);
+
+export const PackageOwnedProcess: Story = {
+  name: 'Package-owned process · library outside',
+  args: {
+    components,
+    relations: spec.relations,
+    walkthroughs: spec.walkthroughs,
+    graphTitle: 'Opening a file — app package owns the process',
+  },
+  render: (args) => (
+    <div style={{ width: '100vw', height: '100vh' }}>
+      <SubsystemComponentGraph {...args} />
+    </div>
+  ),
+};

package/src/subsystem/SubsystemComponentGraph.tsx

@@ -53,6 +53,7 @@ import {
 } from './model';
 import { ConstructsCatalog } from './ConstructsCatalog';
 import type { SubsystemOpenFileOptions } from './declarationRef';
+import type { WalkthroughSymbolQuery } from '../pierre/PierreWalkthroughCodeView';
 import { SubsystemComponentNode, SubsystemGroupNode, SubsystemEdge, SUBSYSTEM_CALLBACKS, hexWithAlpha, EDGE_DIM_ALPHA, fileMatchForNode, flowElementVisibility } from './nodes';
 import { SubsystemDiagnosticToggle, type SubsystemDiagnostic } from './DiagnosticToggle';
 import {
@@ -88,6 +89,28 @@ export interface WalkthroughViewerContext {
    * but whose endpoint is proposed can be labelled as planned, not missing.
    */
   proposedAliases: ReadonlySet<string>;
+  /**
+   * Resolve a token in a step's snippet to a construct the step touches (its
+   * `from`/`to` component), returning that component's alias. `null` when the
+   * token names no touched construct. Forward to the code view so constructs
+   * read as clickable.
+   */
+  resolveSymbol?: (query: WalkthroughSymbolQuery) => string | null;
+  /** A clicked construct token — open that construct's declaration line. */
+  onSymbolClick?: (symbol: string, query: WalkthroughSymbolQuery) => void;
+}
+
+/** Identifiers a token could match to name this component as a construct. */
+function constructIdentifiers(comp: SubsystemComponent): string[] {
+  const ids = new Set<string>();
+  if (comp.name) ids.add(comp.name);
+  if (comp.symbol) {
+    ids.add(comp.symbol);
+    for (const part of comp.symbol.split('.')) {
+      if (part) ids.add(part);
+    }
+  }
+  return [...ids];
 }
 
 type DrawerTarget =
@@ -390,14 +413,29 @@ const WalkthroughDrawerContent = memo(function WalkthroughDrawerContent({
   stepIndex,
   onOpenFile,
   proposedAliases,
+  resolveSymbol,
+  onSymbolClick,
 }: {
   render: (ctx: WalkthroughViewerContext) => ReactNode;
   walkthrough: SubsystemWalkthrough;
   stepIndex: number | null;
   onOpenFile: (path: string, opts?: SubsystemOpenFileOptions) => void;
   proposedAliases: ReadonlySet<string>;
+  resolveSymbol?: (query: WalkthroughSymbolQuery) => string | null;
+  onSymbolClick?: (symbol: string, query: WalkthroughSymbolQuery) => void;
 }) {
-  return <>{render({ walkthrough, stepIndex, onOpenFile, proposedAliases })}</>;
+  return (
+    <>
+      {render({
+        walkthrough,
+        stepIndex,
+        onOpenFile,
+        proposedAliases,
+        resolveSymbol,
+        onSymbolClick,
+      })}
+    </>
+  );
 });
 
 interface InnerProps extends SubsystemComponentGraphProps {
@@ -570,6 +608,10 @@ function Inner({ components, relations, walkthroughs, initialWalkthroughId, onRe
     if (drawerTarget?.kind !== 'walkthrough' || !walkthroughs) return null;
     return walkthroughs.find((t) => t.id === drawerTarget.walkthroughId) ?? null;
   }, [drawerTarget, walkthroughs]);
+  // Ref mirror of the drawer's walkthrough id so the symbol resolver stays
+  // stable across graph re-renders (the drawer is memoized on callback identity).
+  const drawerWalkthroughIdRef = useRef<string | null>(null);
+  drawerWalkthroughIdRef.current = focusedWalkthrough?.id ?? null;
 
   // Walkthrough shown on the canvas title chip (focus or hover/autoplay highlight).
   const overlayWalkthroughTitle = useMemo(() => {
@@ -1576,6 +1618,60 @@ function Inner({ components, relations, walkthroughs, initialWalkthroughId, onRe
     [components, onSelect],
   );
 
+  // Construct tokens inside a walkthrough snippet. A step's line is an edge
+  // between its `from`/`to` components, so a token naming either of those
+  // constructs should navigate to that construct's declaration. Index the
+  // matchable identifiers per step (`walkthroughId:index`).
+  const walkthroughSymbolIndex = useMemo(() => {
+    const byAlias = new Map(components.map((c) => [c.alias, c]));
+    const index = new Map<string, Map<string, string>>();
+    for (const wt of walkthroughs ?? []) {
+      wt.steps.forEach((step, i) => {
+        const tokens = new Map<string, string>();
+        for (const alias of [step.from, step.to]) {
+          const comp = byAlias.get(alias);
+          if (!comp) continue;
+          for (const ident of constructIdentifiers(comp)) tokens.set(ident, alias);
+        }
+        index.set(`${wt.id}:${i}`, tokens);
+      });
+    }
+    return index;
+  }, [components, walkthroughs]);
+  const walkthroughSymbolIndexRef = useRef(walkthroughSymbolIndex);
+  walkthroughSymbolIndexRef.current = walkthroughSymbolIndex;
+
+  // Stable resolver: reads the live index + focused walkthrough from refs so
+  // the memoized walkthrough drawer isn't rebuilt on every graph render.
+  const resolveWalkthroughSymbol = useCallback(
+    (query: WalkthroughSymbolQuery): string | null => {
+      const walkthroughId = drawerWalkthroughIdRef.current;
+      if (walkthroughId == null) return null;
+      return (
+        walkthroughSymbolIndexRef.current
+          .get(`${walkthroughId}:${query.stepIndex}`)
+          ?.get(query.tokenText) ?? null
+      );
+    },
+    [],
+  );
+
+  // A construct token click navigates to that construct's declaration: open
+  // its file at the anchored declaration line (same path as the declaration
+  // panel's file link), falling back to the file top when unanchored.
+  const openConstructDeclaration = useCallback(
+    (alias: string) => {
+      const comp = components.find((c) => c.alias === alias);
+      if (!comp?.file) return;
+      const startLine = comp.declarationRef?.startLine;
+      onOpenDeclarationFile(
+        comp.file,
+        startLine != null ? { startLine } : undefined,
+      );
+    },
+    [components, onOpenDeclarationFile],
+  );
+
   // Edge label data for the overlay (rendered OUTSIDE ReactFlow so the pane
   // doesn't intercept pointer events). Uses ELK-computed label midpoints from
   // the actual edge path (not node-center approximations).
@@ -2210,6 +2306,8 @@ function Inner({ components, relations, walkthroughs, initialWalkthroughId, onRe
             stepIndex={drawerTarget.stepIndex}
             onOpenFile={onOpenFileFromWalkthrough}
             proposedAliases={proposedAliases}
+            resolveSymbol={resolveWalkthroughSymbol}
+            onSymbolClick={openConstructDeclaration}
           />
         ) : drawerTarget?.kind === 'file' ? (
           <FileDrawerContent