@principal-ai/subsystems-react 0.36.2 → 0.37.1

package/src/pierre/PierreWalkthroughCodeView.tsx

@@ -23,6 +23,7 @@ import {
   type DiffLineAnnotation,
   type LineAnnotation,
 } from '@pierre/diffs/react';
+import type { TokenEventBase } from '@pierre/diffs';
 import { Maximize2 } from 'lucide-react';
 
 /** Mirrors Pierre's CodeViewLineSelection (not re-exported from the React entry). */
@@ -48,6 +49,33 @@ import {
   type SnippetSlice,
 } from './sliceSnippet';
 
+/**
+ * A token the user clicked or hovered inside a step's snippet. `stepIndex` is
+ * the zero-based index of the walkthrough step whose snippet it sits in, so a
+ * host can resolve the token against that step's construct endpoints.
+ */
+export interface WalkthroughSymbolQuery {
+  stepIndex: number;
+  tokenText: string;
+}
+
+/** Ctx item id → step index, for CodeView's `walkthroughId:index` item ids. */
+function stepIndexFromItemContext(context: unknown): number | null {
+  const id = (context as { item?: { id?: string } } | undefined)?.item?.id;
+  if (id == null) return null;
+  const index = Number.parseInt(id.split(':').pop() ?? '', 10);
+  return Number.isFinite(index) ? index : null;
+}
+
+/** Pointer/dotted-underline affordance for a clickable construct token. */
+function paintSymbolToken(el: HTMLElement | undefined, active: boolean): void {
+  if (el == null) return;
+  el.style.cursor = active ? 'pointer' : '';
+  el.style.textDecorationLine = active ? 'underline' : '';
+  el.style.textDecorationStyle = active ? 'dotted' : '';
+  el.style.textUnderlineOffset = active ? '2px' : '';
+}
+
 export interface PierreWalkthroughCodeViewProps {
   walkthrough: SubsystemWalkthrough;
   /** Focused step; `null` shows all snippets without scrolling to a step. */
@@ -65,6 +93,15 @@ export interface PierreWalkthroughCodeViewProps {
    * but whose endpoint is proposed reads as "planned" rather than "missing".
    */
   proposedAliases?: ReadonlySet<string>;
+  /**
+   * Resolve a token to a model construct key (e.g. a component alias) for the
+   * step its snippet belongs to. Return `null` when the token doesn't name a
+   * construct this flow touches. When both this and `onSymbolClick` are set,
+   * matching tokens read as clickable (pointer + dotted underline).
+   */
+  resolveSymbol?: (query: WalkthroughSymbolQuery) => string | null;
+  /** Fired when a token resolved by `resolveSymbol` is clicked. */
+  onSymbolClick?: (symbol: string, query: WalkthroughSymbolQuery) => void;
 }
 
 type FileLoadState =
@@ -157,11 +194,20 @@ export function PierreWalkthroughCodeView({
   background,
   onOpenFile,
   proposedAliases,
+  resolveSymbol,
+  onSymbolClick,
 }: PierreWalkthroughCodeViewProps) {
   const { theme, mode } = useTheme();
   const viewRef = useRef<CodeViewHandle<undefined>>(null);
   const [load, setLoad] = useState<FileLoadState>({ status: 'loading' });
 
+  // Keep the newest symbol callbacks in refs so the Pierre options object stays
+  // stable (host callbacks are recreated per render).
+  const resolveSymbolRef = useRef(resolveSymbol);
+  resolveSymbolRef.current = resolveSymbol;
+  const onSymbolClickRef = useRef(onSymbolClick);
+  onSymbolClickRef.current = onSymbolClick;
+
   // A hop onto a proposed component is planned work; label its missing file
   // accordingly instead of showing a bare "not found".
   const isProposedStep = useCallback(
@@ -415,6 +461,33 @@ export function PierreWalkthroughCodeView({
     [onOpenFile, walkthrough.steps, load],
   );
 
+  // Per-token interactions for construct navigation. Only wired when the host
+  // supplies both callbacks; providing them also switches Pierre into its
+  // token-transformer render path (pointer events land on token spans).
+  const symbolHandlers = useMemo((): Partial<CodeViewReactOptions> => {
+    if (resolveSymbol == null || onSymbolClick == null) return {};
+    const resolveAt = (
+      props: TokenEventBase,
+      context: unknown,
+    ): { symbol: string; query: WalkthroughSymbolQuery } | null => {
+      const stepIndex = stepIndexFromItemContext(context);
+      const tokenText = props?.tokenText;
+      if (stepIndex == null || !tokenText) return null;
+      const symbol = resolveSymbolRef.current?.({ stepIndex, tokenText });
+      return symbol == null ? null : { symbol, query: { stepIndex, tokenText } };
+    };
+    return {
+      onTokenClick: (props, _event, context) => {
+        const hit = resolveAt(props, context);
+        if (hit) onSymbolClickRef.current?.(hit.symbol, hit.query);
+      },
+      onTokenEnter: (props, _event, context) => {
+        if (resolveAt(props, context)) paintSymbolToken(props.tokenElement, true);
+      },
+      onTokenLeave: (props) => paintSymbolToken(props.tokenElement, false),
+    };
+  }, [resolveSymbol, onSymbolClick]);
+
   const options = useMemo((): CodeViewReactOptions => {
     return {
       theme: {
@@ -426,10 +499,11 @@ export function PierreWalkthroughCodeView({
       layout: { paddingTop: 0, paddingBottom: 0, gap: 4 },
       onPostRender,
       ...(onOpenFile ? { onLineClick } : {}),
+      ...symbolHandlers,
       ...(background ? buildPierreOptions(background) : {}),
       ...(mode === 'light' || mode === 'dark' ? { themeType: mode } : {}),
     };
-  }, [background, mode, onPostRender, onOpenFile, onLineClick]);
+  }, [background, mode, onPostRender, onOpenFile, onLineClick, symbolHandlers]);
 
   useEffect(() => {
     if (load.status !== 'ready' || stepIndex == null) return;

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 />,
+};