@principal-ai/subsystems-react 0.21.1 → 0.23.0

package/src/pierre/PierreWalkthroughCodeView.tsx

@@ -7,7 +7,14 @@
  * `PierreSnippetView`).
  */
 
-import { useEffect, useMemo, useRef, useState, type ReactElement } from 'react';
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactElement,
+} from 'react';
 import {
   CodeView,
   type CodeViewHandle,
@@ -16,6 +23,7 @@ import {
   type DiffLineAnnotation,
   type LineAnnotation,
 } from '@pierre/diffs/react';
+import { Maximize2 } from 'lucide-react';
 
 /** Mirrors Pierre's CodeViewLineSelection (not re-exported from the React entry). */
 type CodeViewLineSelection = {
@@ -32,7 +40,11 @@ import {
   pierreLangForPath,
 } from './pierreFileLang';
 import { resolvePierreSyntaxThemeName } from './pierreSyntaxTheme';
-import { sliceSnippetWindow, type SnippetSlice } from './sliceSnippet';
+import {
+  remapSnippetLineNumbers,
+  sliceSnippetWindow,
+  type SnippetSlice,
+} from './sliceSnippet';
 
 export interface PierreWalkthroughCodeViewProps {
   walkthrough: SubsystemWalkthrough;
@@ -43,6 +55,8 @@ export interface PierreWalkthroughCodeViewProps {
   contextLines?: number;
   /** Override Pierre's container background. */
   background?: string;
+  /** Open the step's full source file (header button or double-click snippet body). */
+  onOpenFile?: (path: string) => void;
 }
 
 type FileLoadState =
@@ -54,12 +68,54 @@ function stepItemId(walkthroughId: string, index: number): string {
   return `${walkthroughId}:${index}`;
 }
 
+function OpenFileHeaderButton({
+  file,
+  onOpenFile,
+}: {
+  file: string;
+  onOpenFile: (path: string) => void;
+}) {
+  const { theme } = useTheme();
+  const [hover, setHover] = useState(false);
+  return (
+    <button
+      type="button"
+      onClick={(e) => {
+        e.stopPropagation();
+        onOpenFile(file);
+      }}
+      onMouseEnter={() => setHover(true)}
+      onMouseLeave={() => setHover(false)}
+      title={`Open ${file}`}
+      aria-label={`Open full file ${file}`}
+      style={{
+        display: 'inline-flex',
+        alignItems: 'center',
+        gap: 4,
+        padding: '1px 6px',
+        border: `1px solid ${theme.colors.border}`,
+        borderRadius: 4,
+        background: hover ? theme.colors.border : 'transparent',
+        color: hover ? theme.colors.text : theme.colors.textSecondary,
+        cursor: 'pointer',
+        fontFamily: theme.fonts.monospace,
+        fontSize: theme.fontSizes[0],
+        transition: 'background 120ms ease, color 120ms ease',
+      }}
+    >
+      <Maximize2 size={11} />
+      Open file
+    </button>
+  );
+}
+
 export function PierreWalkthroughCodeView({
   walkthrough,
   stepIndex,
   readFile,
   contextLines = 8,
   background,
+  onOpenFile,
 }: PierreWalkthroughCodeViewProps) {
   const { theme, mode } = useTheme();
   const viewRef = useRef<CodeViewHandle<undefined>>(null);
@@ -154,6 +210,30 @@ const items = useMemo((): CodeViewItem<WalkthroughStepAnnotation>[] => {
     };
   }, [stepIndex, slices, walkthrough.id]);
 
+  const sliceStartByItemId = useMemo(() => {
+    const map = new Map<string, number>();
+    for (let i = 0; i < slices.length; i++) {
+      map.set(stepItemId(walkthrough.id, i), slices[i]!.sliceStart);
+    }
+    return map;
+  }, [slices, walkthrough.id]);
+
+  const onPostRender = useCallback(
+    (
+      node: HTMLElement,
+      _instance: unknown,
+      _phase: unknown,
+      context?: { item?: { id?: string } },
+    ) => {
+      const id = context?.item?.id;
+      if (id == null) return;
+      const sliceStart = sliceStartByItemId.get(id);
+      if (sliceStart == null) return;
+      remapSnippetLineNumbers(node, sliceStart);
+    },
+    [sliceStartByItemId],
+  );
+
   const renderHeaderPrefix = useMemo(() => {
     return (item: CodeViewItem) => {
       const index = Number.parseInt(item.id.split(':').pop() ?? '', 10);
@@ -186,17 +266,23 @@ const items = useMemo((): CodeViewItem<WalkthroughStepAnnotation>[] => {
       return (
         <span
           style={{
+            display: 'inline-flex',
+            alignItems: 'center',
+            gap: 6,
+            marginLeft: 8,
             fontFamily: theme.fonts.monospace,
             fontSize: theme.fontSizes[0],
             color: theme.colors.textSecondary,
-            marginLeft: 8,
           }}
         >
           L{step.line}
+          {onOpenFile && (
+            <OpenFileHeaderButton file={step.file} onOpenFile={onOpenFile} />
+          )}
         </span>
       );
     };
-  }, [walkthrough.steps, theme]);
+  }, [walkthrough.steps, theme, onOpenFile]);
 
   const renderAnnotation = useMemo(() => {
     return (
@@ -226,6 +312,23 @@ const items = useMemo((): CodeViewItem<WalkthroughStepAnnotation>[] => {
     };
   }, [walkthrough.steps, theme]);
 
+  const onLineClick = useCallback(
+    (
+      props: { event?: { detail?: number } },
+      context?: { item?: { id?: string } },
+    ) => {
+      if (!onOpenFile) return;
+      if (props.event?.detail !== 2) return;
+      const id = context?.item?.id;
+      if (id == null) return;
+      const index = Number.parseInt(id.split(':').pop() ?? '', 10);
+      const step = walkthrough.steps[index];
+      if (!step) return;
+      onOpenFile(step.file);
+    },
+    [onOpenFile, walkthrough.steps],
+  );
+
   const options = useMemo((): CodeViewReactOptions => {
     return {
       theme: {
@@ -235,10 +338,12 @@ const items = useMemo((): CodeViewItem<WalkthroughStepAnnotation>[] => {
       stickyHeaders: true,
       disableFileHeader: false,
       layout: { paddingTop: 8, paddingBottom: 16, gap: 12 },
+      onPostRender,
+      ...(onOpenFile ? { onLineClick } : {}),
       ...(background ? buildPierreOptions(background) : {}),
       ...(mode === 'light' || mode === 'dark' ? { themeType: mode } : {}),
     };
-  }, [background, mode]);
+  }, [background, mode, onPostRender, onOpenFile, onLineClick]);
 
   useEffect(() => {
     if (load.status !== 'ready' || stepIndex == null) return;

package/src/pierre/constructColors.test.ts

@@ -13,7 +13,6 @@ const CONSTRUCTS: SubsystemComponentConstruct[] = [
   'interface',
   'type_alias',
   'enum',
-  'module',
   'store',
   'external',
   'custom_entity',
@@ -31,7 +30,7 @@ describe('constructColorsFromPierreTheme', () => {
     }
   });
 
-  test('all ten constructs are distinguishable within a theme', () => {
+  test('all nine constructs are distinguishable within a theme', () => {
     for (const themeName of ['pierre-dark', 'pierre-light'] as const) {
       const colors = constructColorsFromPierreTheme(themeName);
       const values = CONSTRUCTS.map((c) => colors[c]);

package/src/pierre/constructColors.ts

@@ -89,7 +89,6 @@ export function constructColorsFromPierreTheme(
   const classColor = pick('entity.name.class');
   const functionColor = pick('entity.name.function');
   const typeColor = pick('support.type');
-  const moduleColor = pick('entity.name.namespace');
 
   return {
     class: classColor,
@@ -101,10 +100,6 @@ export function constructColorsFromPierreTheme(
     method: towardBackground(functionColor, 0.14),
     // enum members are constants — the generic constant hue
     enum: pick('constant'),
-    // module and store share the constant hue — the module holds the store,
-    // and the store IS the retained value, so the store keeps the pure
-    // `variable.other.constant` color and the module takes the shade
-    module: towardBackground(moduleColor, 0.18),
     store: pick('variable.other.constant'),
     external: pick('comment'),
     // custom entities are actors, not code — the heading/emphasis coral reads

package/src/pierre/index.ts

@@ -4,7 +4,7 @@ export { PierreSnippetView } from './PierreSnippetView';
 export type { PierreSnippetViewProps } from './PierreSnippetView';
 export { PierreWalkthroughCodeView } from './PierreWalkthroughCodeView';
 export type { PierreWalkthroughCodeViewProps } from './PierreWalkthroughCodeView';
-export { sliceSnippetWindow } from './sliceSnippet';
+export { remapSnippetLineNumbers, sliceSnippetWindow } from './sliceSnippet';
 export type { SnippetSlice } from './sliceSnippet';
 export {
   isPierreCFamilyPath,

package/src/pierre/scrollAnchor.ts

@@ -9,3 +9,16 @@ export function scrollAnchorLine(
   if (focusOffset <= 1) return 1;
   return Math.max(1, focusOffset - leadingLines);
 }
+
+/** Scroll a Pierre file container so `focusLine` (1-based) sits near the top. */
+export function scrollFocusLineIntoView(
+  fileContainer: HTMLElement,
+  focusLine: number,
+): void {
+  const root = fileContainer.shadowRoot ?? fileContainer;
+  const anchorLine = scrollAnchorLine(focusLine);
+  const lineEl = root.querySelector(
+    `[data-line="${anchorLine}"]`,
+  ) as HTMLElement | null;
+  lineEl?.scrollIntoView({ block: 'start', behavior: 'auto' });
+}

package/src/pierre/sliceSnippet.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from 'bun:test';
-import { sliceSnippetWindow } from './sliceSnippet';
+import { Window } from 'happy-dom';
+import { remapSnippetLineNumbers, sliceSnippetWindow } from './sliceSnippet';
 
 describe('sliceSnippetWindow', () => {
   const content = ['line1', 'line2', 'line3', 'line4', 'line5'].join('\n');
@@ -19,3 +20,45 @@ describe('sliceSnippetWindow', () => {
     expect(s.focusOffset).toBe(95);
   });
 });
+
+describe('remapSnippetLineNumbers', () => {
+  function gutter(doc: Document, lineIndex: number, label: string): HTMLElement {
+    const el = doc.createElement('div');
+    el.setAttribute('data-column-number', '');
+    el.dataset.lineIndex = String(lineIndex);
+    const span = doc.createElement('span');
+    span.setAttribute('data-line-number-content', '');
+    span.textContent = label;
+    el.appendChild(span);
+    return el;
+  }
+
+  test('rewrites gutters to absolute file lines', () => {
+    const win = new Window();
+    const doc = win.document;
+    const root = doc.createElement('div');
+    root.appendChild(gutter(doc, 0, '1'));
+    root.appendChild(gutter(doc, 1, '2'));
+    root.appendChild(gutter(doc, 2, '3'));
+
+    remapSnippetLineNumbers(root as unknown as HTMLElement, 250);
+
+    const labels = [...root.querySelectorAll('[data-line-number-content]')].map(
+      (n) => n.textContent,
+    );
+    expect(labels).toEqual(['250', '251', '252']);
+  });
+
+  test('no-ops when slice already starts at line 1', () => {
+    const win = new Window();
+    const doc = win.document;
+    const root = doc.createElement('div');
+    root.appendChild(gutter(doc, 0, '1'));
+
+    remapSnippetLineNumbers(root as unknown as HTMLElement, 1);
+
+    expect(
+      root.querySelector('[data-line-number-content]')?.textContent,
+    ).toBe('1');
+  });
+});

package/src/pierre/sliceSnippet.ts

@@ -29,3 +29,31 @@ export function sliceSnippetWindow(
       focusLine == null ? null : Math.max(1, focusLine - sliceStart + 1),
   };
 }
+
+/**
+ * Remap Pierre gutter numbers from slice-local (1-based) to absolute file lines.
+ * Pierre numbers whatever `contents` it receives starting at 1; sliced snippets
+ * need `sliceStart` applied so the gutter matches the source file.
+ */
+export function remapSnippetLineNumbers(
+  fileContainer: HTMLElement,
+  sliceStart: number,
+): void {
+  const lineNumberOffset = sliceStart - 1;
+  if (lineNumberOffset === 0) return;
+  const root = fileContainer.shadowRoot ?? fileContainer;
+  const items = root.querySelectorAll(
+    '[data-column-number][data-line-index]',
+  );
+  items.forEach((el) => {
+    const idxStr = (el as HTMLElement).dataset.lineIndex;
+    if (idxStr == null) return;
+    const idx = Number.parseInt(idxStr, 10);
+    if (Number.isNaN(idx)) return;
+    const display = String(idx + 1 + lineNumberOffset);
+    const span = el.querySelector('[data-line-number-content]');
+    if (span && span.textContent !== display) {
+      span.textContent = display;
+    }
+  });
+}

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

@@ -197,37 +197,6 @@ const cases: { label: string; component: SubsystemComponent }[] = [
       } satisfies GraphifyComponentDetail,
     },
   },
-  {
-    label: 'module — imports + exports',
-    component: {
-      id: 'mod-full',
-      name: 'index',
-      construct: 'module',
-      file: 'src/index.ts',
-      purl: 'pkg:github/principal-ai/agent-monitoring',
-      symbol: 'index',
-      declaration: {
-        kind: 'module',
-        imports: [
-          { name: './session/SessionReader' },
-          { name: './event-processing/EventProcessor' },
-        ],
-        exports: ['SessionReader', 'EventProcessor'],
-        symbols: ['SessionReader', 'EventProcessor', 'normalizeSession'],
-      } satisfies GraphifyComponentDetail,
-    },
-  },
-  {
-    label: 'module — no detail (fallback)',
-    component: {
-      id: 'mod-plain',
-      name: 'utils',
-      construct: 'module',
-      file: 'src/utils.ts',
-      purl: 'pkg:github/principal-ai/agent-monitoring',
-      symbol: 'utils',
-    },
-  },
   {
     label: 'external',
     component: {

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

@@ -109,7 +109,7 @@ export const NamingConventions: Story = {
 };
 
 // ---------------------------------------------------------------------------
-// Kind variations — one column per kind (class / function / type / module /
+// Kind variations — one column per kind (class / function / type / external —
 // external), rows going bare → detailed. Click a node to see its declaration
 // panel; type names inside it are clickable when they match another node here.
 // ---------------------------------------------------------------------------
@@ -269,50 +269,6 @@ const kindVariationComponents: SubsystemComponent[] = [
     } satisfies GraphifyComponentDetail,
   },
 
-  // --- module: bare → exports only → exports + imports
-  {
-    id: 'mod-bare',
-    name: 'transcript',
-    construct: 'module',
-    file: 'src/session/transcript.ts',
-    purl: variationPurl,
-    purpose: 'no drill-down — symbol-less module named from its file basename',
-    symbol: '',
-    layer: 4,
-  },
-  {
-    id: 'mod-exports',
-    name: 'paths',
-    construct: 'module',
-    file: 'src/session/paths.ts',
-    purl: variationPurl,
-    purpose: 'exports only — export statement + defines comment',
-    symbol: '',
-    layer: 4,
-    declaration: {
-      kind: 'module',
-      exports: ['extractToolName', 'extractFilePath'],
-      imports: [],
-      symbols: ['extractToolName', 'extractFilePath'],
-    } satisfies GraphifyComponentDetail,
-  },
-  {
-    id: 'mod-full',
-    name: 'index',
-    construct: 'module',
-    file: 'src/index.ts',
-    purl: variationPurl,
-    purpose: 'full — import statements + re-export statement + defines comment',
-    symbol: '',
-    layer: 4,
-    declaration: {
-      kind: 'module',
-      exports: ['SessionReader', 'SessionStore'],
-      imports: [{ nodeId: 'i1', name: 'transcript', relation: 'imports_from' }],
-      symbols: ['SessionReader', 'SessionStore'],
-    } satisfies GraphifyComponentDetail,
-  },
-
   // --- external: bare → labeled
   {
     id: 'ext-bare',
@@ -351,7 +307,7 @@ function KindVariationsDemo() {
         onSelect={(id) => setSelected(id)}
       />
       <div style={{ marginTop: 8, fontFamily: 'monospace', fontSize: 12, color: '#aaa' }}>
-        columns: class · function · type · module · external — each goes bare → detailed
+        columns: class · function · type · external — each goes bare → detailed
         {selected ? ` · selected: ${selected}` : ''}
       </div>
     </div>

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

@@ -31,10 +31,10 @@ type Story = StoryObj<typeof meta>;
 // ---------------------------------------------------------------------------
 const v2ReaderComponents = components([
   ['capture', 'capture script', 'function', 'scripts/capture-session.ts', 'pkg:github/principal-ai/agent-monitoring', 'captures a real session for fixtures'],
-  ['transcript', 'transcript', 'module', 'transcript.ts', 'pkg:github/principal-ai/agent-monitoring', 'parses session records + type guards'],
-  ['paths', 'paths', 'module', 'paths.ts', 'pkg:github/principal-ai/agent-monitoring', 'extracts tool names + file paths'],
+  ['transcript', 'transcript', 'function', 'transcript.ts', 'pkg:github/principal-ai/agent-monitoring', 'parses session records + type guards'],
+  ['paths', 'paths', 'function', 'paths.ts', 'pkg:github/principal-ai/agent-monitoring', 'extracts tool names + file paths'],
   ['reader', 'SessionReader', 'class', 'SessionReader.ts', 'pkg:github/principal-ai/agent-monitoring', 'normalizes a session into universal events', 'SessionReader.normalize', readerDetail],
-  ['registry', 'supported-agents', 'module', 'supported-agents.ts', 'pkg:github/principal-ai/agent-monitoring', 'registry of supported agents (the shared seam)', 'registerAgent'],
+  ['registry', 'supported-agents', 'function', 'supported-agents.ts', 'pkg:github/principal-ai/agent-monitoring', 'registry of supported agents (the shared seam)', 'registerAgent'],
 ]);
 
 const v2ReaderEdges = graphSpecFromEdges([
@@ -95,11 +95,11 @@ const minimalComponents = components([
   ['reader', 'SessionReader', 'class', 'SessionReader.ts', 'pkg:github/principal-ai/agent-monitoring', 'normalizes a session into universal events', 'SessionReader'],
   ['normalize', 'normalize', 'function', 'SessionReader.ts', 'pkg:github/principal-ai/agent-monitoring', 'maps a session into universal events', 'SessionReader.normalize'],
   ['record', 'SessionRecord', 'type', 'transcript.ts', 'pkg:github/principal-ai/agent-monitoring', 'the parsed codex session record', 'SessionRecord'],
-  ['transcript', 'transcript', 'module', 'transcript.ts', 'pkg:github/principal-ai/agent-monitoring', 'parses session records + type guards', 'transcript'],
+  ['transcript', 'transcript', 'function', 'transcript.ts', 'pkg:github/principal-ai/agent-monitoring', 'parses session records + type guards', 'transcript'],
 ]);
 
 const sharedEdges = graphSpecFromEdges([
-  ['transcript', 'record', 'defines'],
+  ['transcript', 'record', 'references'],
   ['reader', 'normalize', 'method'],
   ['normalize', 'record', 'references'],
 ]);
@@ -129,15 +129,6 @@ const resolvedComponents: SubsystemComponent[] = [
       implementors: ['SessionReaderLike'],
     } satisfies GraphifyComponentDetail,
   },
-  {
-    ...minimalComponents[3],
-    declaration: {
-      kind: 'module',
-      exports: ['CodexRolloutRecord', 'CodexSessionMeta'],
-      imports: [{ nodeId: 'i1', name: 'paths', relation: 'imports_from' }],
-      symbols: ['CodexRolloutRecord', 'CodexSessionMeta'],
-    } satisfies GraphifyComponentDetail,
-  },
 ];
 
 function MinimalVsResolvedDemo({ resolved }: { resolved: boolean }) {
@@ -174,22 +165,16 @@ const investigationComponents: SubsystemComponent[] = [
   {
     id: 'adapter',
     name: 'OpenCodeAdapter',
-    construct: 'module',
+    construct: 'function',
     file: 'apps/server/src/provider/Layers/OpenCodeAdapter.ts',
     purl: 'pkg:github/t3code/t3code',
     purpose: 'adapts opencode session/threads + events to the t3 runtime',
     symbol: 'makeOpenCodeAdapter',
-    declaration: {
-      kind: 'module',
-      exports: ['makeOpenCodeAdapter', 'OpenCodeAdapterLiveOptions'],
-      imports: [{ nodeId: 'i1', name: 'orchestration', relation: 'imports_from' }],
-      symbols: ['makeOpenCodeAdapter', 'isOpenCodeNotFound', 'OpenCodeSessionContext'],
-    } satisfies GraphifyComponentDetail,
   },
   {
     id: 'ingestion',
     name: 'ProviderRuntimeIngestion',
-    construct: 'module',
+    construct: 'function',
     file: 'apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts',
     purl: 'pkg:github/t3code/t3code',
     purpose: 'ingests provider events into the runtime',
@@ -198,7 +183,7 @@ const investigationComponents: SubsystemComponent[] = [
   {
     id: 'contracts',
     name: 'orchestration',
-    construct: 'module',
+    construct: 'function',
     file: 'packages/contracts/src/orchestration.ts',
     purl: 'pkg:github/t3code/t3code',
     purpose: 'contracts for orchestration/providers',
@@ -207,7 +192,7 @@ const investigationComponents: SubsystemComponent[] = [
 ];
 
 const investigationEdges = graphSpecFromEdges([
-  ['adapter', 'contracts', 'imports_from'],
+  ['adapter', 'contracts', 'imports'],
   ['ingestion', 'adapter', 'uses'],
   ['ingestion', 'contracts', 'references'],
 ]);

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

@@ -234,7 +234,7 @@ const declarationOpenComponents: SubsystemComponent[] = [
   {
     id: 'detail',
     name: 'ComponentDeclaration',
-    construct: 'module',
+    construct: 'function',
     file: 'packages/subsystems-react/src/subsystem/ComponentDeclaration.tsx',
     purl: 'pkg:github/principal-ai/principal-view-core-library',
     purpose: 'declaration panel — click file or L251 to open the drawer at the export line',
@@ -249,7 +249,7 @@ const declarationOpenComponents: SubsystemComponent[] = [
   {
     id: 'resolver',
     name: 'resolve.ts',
-    construct: 'module',
+    construct: 'function',
     file: 'packages/subsystems-react/src/graphify/resolve.ts',
     purl: 'pkg:github/principal-ai/principal-view-core-library',
     purpose: 'graphify type-ref resolver (second file for tree navigation)',

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

@@ -159,12 +159,13 @@ const drawingWalkthroughs: SubsystemWalkthrough[] = [
 
 function FlowsDemo() {
   const renderWalkthroughViewer = useCallback(
-    ({ walkthrough, stepIndex }: WalkthroughViewerContext) => (
+    ({ walkthrough, stepIndex, onOpenFile }: WalkthroughViewerContext) => (
       <PierreWalkthroughCodeView
         walkthrough={walkthrough}
         stepIndex={stepIndex}
         readFile={readStoryFile}
         contextLines={4}
+        onOpenFile={onOpenFile}
       />
     ),
     [],