@principal-ai/subsystems-react 0.21.0 → 0.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@principal-ai/subsystems-react",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "React UI for Subsystem Models — graph, Pierre code views, and session-event feeds",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -37,7 +37,7 @@
   "peerDependencies": {
     "@pierre/diffs": ">=1.1.20",
     "@principal-ade/industry-theme": "^0.1.7",
-    "@principal-ai/subsystems-core": ">=0.32.0",
+    "@principal-ai/subsystems-core": ">=0.33.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
@@ -45,7 +45,7 @@
     "@pierre/diffs": "1.3.6",
     "@principal-ade/industry-theme": "0.1.7",
     "@principal-ai/agent-monitoring": "^0.3.38",
-    "@principal-ai/subsystems-core": "0.32.0",
+    "@principal-ai/subsystems-core": "0.33.0",
     "@storybook/addon-docs": "10.1.2",
     "@storybook/addon-links": "10.1.2",
     "@storybook/addon-onboarding": "10.1.2",

package/src/graphify/consolidated.ts

@@ -113,18 +113,6 @@ export interface GraphifyReferenceInfo {
   source_location?: string;
 }
 
-/** An import relationship (`imports` / `imports_from` / `re_exports`). */
-export interface GraphifyImportInfo {
-  /** The imported module/file node id. */
-  nodeId: string;
-  /** The imported module/file label. */
-  name: string;
-  /** Which relation carried the import. */
-  relation?: GraphifyRelation;
-  /** `L<line>` of the import statement. */
-  source_location?: string;
-}
-
 // ---------------------------------------------------------------------------
 // Discriminated union — the drill-down payload
 // ---------------------------------------------------------------------------
@@ -207,17 +195,6 @@ export interface GraphifyTypeDetail {
   rhs?: string;
 }
 
-/** A module/file-like node: a `contains` target with a filename label. */
-export interface GraphifyModuleDetail {
-  kind: 'module';
-  /** `re_exports` targets / contained public symbols. */
-  exports: string[];
-  /** `imports` / `imports_from` relationships. */
-  imports: GraphifyImportInfo[];
-  /** Symbols contained in the module (`contains` targets). */
-  symbols: string[];
-}
-
 /** A facet-only component with no graphify node (external consumer stub). */
 export interface GraphifyExternalDetail {
   kind: 'external';
@@ -281,15 +258,16 @@ export interface GraphifyMethodDetail {
  *
  * The discriminant is derived from graph structure, not read off the node:
  * method edges → class; `()` label + no method edges → function; incoming
- * `implements` → type; else module. `external` covers consumer stubs.
- * `method` covers standalone method components selected from a class.
+ * `implements` → type. File/module Graphify nodes are not subsystem
+ * declaration kinds — anchor to a concrete export instead. `external`
+ * covers consumer stubs. `method` covers standalone method components
+ * selected from a class.
  */
 export type GraphifyComponentDetail =
   | GraphifyClassDetail
   | GraphifyFunctionDetail
   | GraphifyMethodDetail
   | GraphifyTypeDetail
-  | GraphifyModuleDetail
   | GraphifyExternalDetail
   | GraphifyCustomEntityDetail
   | GraphifyStoreDetail;

package/src/graphify/index.ts

@@ -25,11 +25,9 @@ export type {
   GraphifyParamInfo,
   GraphifyCallInfo,
   GraphifyReferenceInfo,
-  GraphifyImportInfo,
   GraphifyClassDetail,
   GraphifyFunctionDetail,
   GraphifyTypeDetail,
-  GraphifyModuleDetail,
   GraphifyExternalDetail,
   GraphifyCustomEntityDetail,
   GraphifyCustomEntityAttribute,

package/src/index.ts

@@ -37,11 +37,9 @@ export type {
   GraphifyParamInfo,
   GraphifyCallInfo,
   GraphifyReferenceInfo,
-  GraphifyImportInfo,
   GraphifyClassDetail,
   GraphifyFunctionDetail,
   GraphifyTypeDetail,
-  GraphifyModuleDetail,
   GraphifyExternalDetail,
   GraphifyCustomEntityDetail,
   GraphifyCustomEntityAttribute,

package/src/pierre/PierreSnippetView.tsx

@@ -13,7 +13,7 @@ import { File } from '@pierre/diffs/react';
 import { useTheme } from '@principal-ade/industry-theme';
 import { buildPierreOptions, PIERRE_FILE_STYLE } from './pierreBackground';
 import { pierreLangForPath } from './pierreFileLang';
-import { sliceSnippetWindow } from './sliceSnippet';
+import { remapSnippetLineNumbers, sliceSnippetWindow } from './sliceSnippet';
 
 import { scrollAnchorLine } from './scrollAnchor';
 
@@ -101,30 +101,16 @@ export function PierreSnippetView({
     [fileName, filePath, slice],
   );
 
-  const lineNumberOffset = slice ? slice.sliceStart - 1 : 0;
-
   const onPostRender = useCallback(
     (fileContainer: HTMLElement) => {
-      if (lineNumberOffset !== 0) {
-        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;
-          }
-        });
+      if (slice != null) {
+        remapSnippetLineNumbers(fileContainer, slice.sliceStart);
       }
       if (slice?.focusOffset != null) {
         scrollFocusLineIntoView(fileContainer, slice.focusOffset);
       }
     },
-    [lineNumberOffset, slice?.focusOffset],
+    [slice],
   );
 
   const options = useMemo(

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,
@@ -32,7 +39,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;
@@ -154,6 +165,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);
@@ -235,10 +270,11 @@ const items = useMemo((): CodeViewItem<WalkthroughStepAnnotation>[] => {
       stickyHeaders: true,
       disableFileHeader: false,
       layout: { paddingTop: 8, paddingBottom: 16, gap: 12 },
+      onPostRender,
       ...(background ? buildPierreOptions(background) : {}),
       ...(mode === 'light' || mode === 'dark' ? { themeType: mode } : {}),
     };
-  }, [background, mode]);
+  }, [background, mode, onPostRender]);
 
   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/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)',