@principal-ai/principal-view-react 0.16.56 → 0.16.57

package/src/stories/{FileCitySequence.stories.tsx → RealWorld/FileCitySequence.stories.tsx}

@@ -1,13 +1,13 @@
 import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
-import { SequenceDiagramRenderer } from '../components/SequenceDiagramRenderer';
-import { WorkflowSequenceDiagram } from '../components/WorkflowSequenceDiagram';
+import { SequenceDiagramRenderer } from '../../components/SequenceDiagramRenderer';
+import { WorkflowSequenceDiagram } from '../../components/WorkflowSequenceDiagram';
 import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
-import workflowData from './data/file-city-workflows.json';
+import workflowData from '../data/file-city-workflows.json';
 import type { WorkflowScenario } from '@principal-ai/principal-view-core';
 
 const meta = {
-  title: 'Workflows/File City Image Generation',
+  title: 'RealWorld/FileCitySequence',
   component: SequenceDiagramRenderer,
   parameters: {
     layout: 'fullscreen',

package/src/stories/{RealCanvasFiles.stories.tsx → RealWorld/RealCanvasFiles.stories.tsx}

@@ -1,16 +1,16 @@
 import React, { useState, useEffect } from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
 import '@xyflow/react/dist/style.css';
-import { GraphRenderer } from '../components/GraphRenderer';
+import { GraphRenderer } from '../../components/GraphRenderer';
 import type { ExtendedCanvas } from '@principal-ai/principal-view-core';
 import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
 
 // Import canvas files as URLs
-import scopesCanvasUrl from '../../../../.principal-views/architecture.scopes.canvas?url';
-import spansCanvasUrl from '../../../../.principal-views/architecture.spans.canvas?url';
-import resourcesCanvasUrl from '../../../../.principal-views/resources.canvas?url';
-import matchingLogicCanvasUrl from '../../../../.principal-views/matching-logic-current-state.canvas?url';
-import validationCanvasUrl from '../../../../.principal-views/validation/validation.otel.canvas?url';
+import scopesCanvasUrl from '../../../../../.principal-views/architecture.scopes.canvas?url';
+import spansCanvasUrl from '../../../../../.principal-views/architecture.spans.canvas?url';
+import resourcesCanvasUrl from '../../../../../.principal-views/resources.canvas?url';
+import matchingLogicCanvasUrl from '../../../../../.principal-views/matching-logic-current-state.canvas?url';
+import validationCanvasUrl from '../../../../../.principal-views/validation/validation.otel.canvas?url';
 
 // Helper to load canvas from URL
 async function loadCanvas(url: string): Promise<ExtendedCanvas> {
@@ -45,7 +45,7 @@ function CanvasLoader({ url, children }: { url: string; children: (canvas: Exten
 }
 
 const meta = {
-  title: 'Real Canvas Files',
+  title: 'RealWorld/RealCanvasFiles',
   component: GraphRenderer,
   parameters: {
     layout: 'fullscreen',

package/src/stories/{ComponentDeclarationAudit.stories.tsx → Subsystem/ComponentDeclarationAudit.stories.tsx}

@@ -2,12 +2,12 @@ import React from 'react';
 import '@xyflow/react/dist/style.css';
 import type { Meta, StoryObj } from '@storybook/react';
 import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
-import { ComponentDeclaration } from '../subsystem/ComponentDeclaration';
-import type { SubsystemComponent } from '../subsystem/model';
-import type { GraphifyComponentDetail } from '../graphify';
+import { ComponentDeclaration } from '../../subsystem/ComponentDeclaration';
+import type { SubsystemComponent } from '../../subsystem/model';
+import type { GraphifyComponentDetail } from '../../graphify';
 
 const meta = {
-  title: 'Subsystem/Component Declaration Audit',
+  title: 'Subsystem/ComponentDeclarationAudit',
   component: ComponentDeclaration,
   parameters: { layout: 'padded' },
   tags: ['autodocs'],
@@ -28,7 +28,6 @@ const meta = {
   ],
 } satisfies Meta<typeof ComponentDeclaration>;
 export default meta;
-type Story = StoryObj<typeof ComponentDeclaration>;
 
 // ---------------------------------------------------------------------------
 // All cases — one SubsystemComponent per shape, rendered stacked
@@ -40,7 +39,7 @@ const cases: { label: string; component: SubsystemComponent }[] = [
     component: {
       id: 'fn-void',
       name: 'flush',
-      kind: 'function',
+      construct: 'function',
       file: 'src/event-processing/sink.ts',
       purl: 'pkg:github/principal-ai/agent-monitoring',
       symbol: 'flush',
@@ -55,7 +54,7 @@ const cases: { label: string; component: SubsystemComponent }[] = [
     component: {
       id: 'fn-one',
       name: 'normalize',
-      kind: 'function',
+      construct: 'function',
       file: 'src/session/SessionReader.ts',
       purl: 'pkg:github/principal-ai/agent-monitoring',
       symbol: 'SessionReader.normalize',
@@ -71,7 +70,7 @@ const cases: { label: string; component: SubsystemComponent }[] = [
     component: {
       id: 'fn-two',
       name: 'normalizeSession',
-      kind: 'function',
+      construct: 'function',
       file: 'src/event-processing/normalize.ts',
       purl: 'pkg:github/principal-ai/agent-monitoring',
       symbol: 'normalizeSession',
@@ -90,7 +89,7 @@ const cases: { label: string; component: SubsystemComponent }[] = [
     component: {
       id: 'fn-rich',
       name: 'mergeSessions',
-      kind: 'function',
+      construct: 'function',
       file: 'src/session/merge.ts',
       purl: 'pkg:github/principal-ai/agent-monitoring',
       symbol: 'mergeSessions',
@@ -111,7 +110,7 @@ const cases: { label: string; component: SubsystemComponent }[] = [
     component: {
       id: 'class-empty',
       name: 'EmptyClass',
-      kind: 'class',
+      construct: 'class',
       file: 'src/empty.ts',
       purl: 'pkg:github/principal-ai/agent-monitoring',
       symbol: 'EmptyClass',
@@ -125,7 +124,7 @@ const cases: { label: string; component: SubsystemComponent }[] = [
     component: {
       id: 'class-props',
       name: 'Config',
-      kind: 'class',
+      construct: 'class',
       file: 'src/config.ts',
       purl: 'pkg:github/principal-ai/agent-monitoring',
       symbol: 'Config',
@@ -144,7 +143,7 @@ const cases: { label: string; component: SubsystemComponent }[] = [
     component: {
       id: 'class-rich',
       name: 'EventProcessor',
-      kind: 'class',
+      construct: 'class',
       file: 'src/event-processing/EventProcessor.ts',
       purl: 'pkg:github/principal-ai/agent-monitoring',
       symbol: 'EventProcessor',
@@ -171,7 +170,7 @@ const cases: { label: string; component: SubsystemComponent }[] = [
     component: {
       id: 'type-props',
       name: 'SessionRecord',
-      kind: 'type',
+      construct: 'interface',
       file: 'src/session/transcript.ts',
       purl: 'pkg:github/principal-ai/agent-monitoring',
       symbol: 'SessionRecord',
@@ -189,7 +188,7 @@ const cases: { label: string; component: SubsystemComponent }[] = [
     component: {
       id: 'type-empty',
       name: 'BrandedId',
-      kind: 'type',
+      construct: 'interface',
       file: 'src/types.ts',
       purl: 'pkg:github/principal-ai/agent-monitoring',
       symbol: 'BrandedId',
@@ -203,7 +202,7 @@ const cases: { label: string; component: SubsystemComponent }[] = [
     component: {
       id: 'mod-full',
       name: 'index',
-      kind: 'module',
+      construct: 'module',
       file: 'src/index.ts',
       purl: 'pkg:github/principal-ai/agent-monitoring',
       symbol: 'index',
@@ -223,7 +222,7 @@ const cases: { label: string; component: SubsystemComponent }[] = [
     component: {
       id: 'mod-plain',
       name: 'utils',
-      kind: 'module',
+      construct: 'module',
       file: 'src/utils.ts',
       purl: 'pkg:github/principal-ai/agent-monitoring',
       symbol: 'utils',
@@ -234,7 +233,7 @@ const cases: { label: string; component: SubsystemComponent }[] = [
     component: {
       id: 'ext',
       name: 'trail-viewer',
-      kind: 'external',
+      construct: 'external',
       file: '',
       purl: 'pkg:npm/@principal-ai/trail-viewer',
       symbol: '',
@@ -249,7 +248,7 @@ const cases: { label: string; component: SubsystemComponent }[] = [
     component: {
       id: 'fn-no-symbol',
       name: 'anonymousHelper',
-      kind: 'function',
+      construct: 'function',
       file: 'src/helpers.ts',
       purl: 'pkg:github/principal-ai/agent-monitoring',
       detail: {
@@ -264,7 +263,7 @@ const cases: { label: string; component: SubsystemComponent }[] = [
     component: {
       id: 'method-normalize',
       name: 'normalize',
-      kind: 'method',
+      construct: 'method',
       file: 'src/session/SessionReader.ts',
       purl: 'pkg:github/principal-ai/agent-monitoring',
       symbol: 'SessionReader.normalize',
@@ -281,7 +280,7 @@ const cases: { label: string; component: SubsystemComponent }[] = [
     component: {
       id: 'method-dispose',
       name: 'dispose',
-      kind: 'method',
+      construct: 'method',
       file: 'src/event-processing/EventProcessor.ts',
       purl: 'pkg:github/principal-ai/agent-monitoring',
       symbol: 'EventProcessor.dispose',

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

@@ -0,0 +1,365 @@
+import React, { useState } from 'react';
+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, SubsystemComponentEdge } from '../../../subsystem/model';
+import type { GraphifyComponentDetail } from '../../../graphify';
+import { investigateOnlyComponents, investigateOnlyEdges } from './fixtures';
+
+const meta = {
+  title: 'Subsystem/ComponentGraph/Appearance',
+  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>;
+
+/** Same pipeline as Captures/InvestigateOnly with a narrower `maxNodeWidth` (140) — long names wrap. */
+export const NarrowMaxWidth: Story = {
+  render: () => (
+    <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
+      <SubsystemComponentGraph
+        components={investigateOnlyComponents}
+        edges={investigateOnlyEdges}
+        maxNodeWidth={140}
+      />
+    </div>
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// Naming-convention wrap check — one node per common symbol convention.
+// ---------------------------------------------------------------------------
+const namingConventionComponents: SubsystemComponent[] = [
+  {
+    id: 'camel',
+    name: 'accumulateToAgentSessionEvents',
+    construct: 'function',
+    file: 'src/event-processing/accumulator.ts',
+    purl: 'pkg:github/principal-ai/agent-monitoring',
+    symbol: 'accumulateToAgentSessionEvents',
+  },
+  {
+    id: 'snake',
+    name: 'repo_normalized_universal_event',
+    construct: 'interface',
+    file: 'src/event-processing/repo_normalized.ts',
+    purl: 'pkg:github/principal-ai/agent-monitoring',
+    symbol: 'repo_normalized_universal_event',
+  },
+  {
+    id: 'pascal',
+    name: 'RepoNormalizedUniversalAgentSessionEvent',
+    construct: 'class',
+    file: 'src/event-processing/RepoNormalized.ts',
+    purl: 'pkg:github/principal-ai/agent-monitoring',
+    symbol: 'RepoNormalizedUniversalAgentSessionEvent',
+  },
+  {
+    id: 'acronym',
+    name: 'ProcessSSEStreamForEventToken',
+    construct: 'function',
+    file: 'src/event-processing/sse.ts',
+    purl: 'pkg:github/principal-ai/agent-monitoring',
+    symbol: 'ProcessSSEStreamForEventToken',
+  },
+  {
+    id: 'method',
+    name: 'normalize',
+    construct: 'function',
+    file: 'src/session/SessionReader.ts',
+    purl: 'pkg:github/principal-ai/agent-monitoring',
+    symbol: 'SessionReader.normalize',
+  },
+  {
+    id: 'pkg',
+    name: 'trail-viewer',
+    construct: 'external',
+    file: '',
+    purl: 'pkg:npm/@principal-ai/trail-viewer',
+    symbol: '',
+  },
+];
+
+const namingConventionEdges: SubsystemComponentEdge[] = [];
+
+/** Nodes with compact `maxNodeWidth` so the different conventions visibly wrap
+ *  at their word boundaries (camelCase, snake_case, PascalCase, acronyms). */
+export const NamingConventions: Story = {
+  render: () => (
+    <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
+      <SubsystemComponentGraph
+        components={namingConventionComponents}
+        edges={namingConventionEdges}
+        maxNodeWidth={180}
+      />
+    </div>
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// Kind variations — one column per kind (class / function / type / module /
+// 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.
+// ---------------------------------------------------------------------------
+const variationPurl = 'pkg:github/principal-ai/agent-monitoring';
+
+const kindVariationComponents: SubsystemComponent[] = [
+  // --- class: bare → members only → relationships only
+  {
+    id: 'cls-bare',
+    name: 'SessionStore',
+    construct: 'class',
+    file: 'src/session/SessionStore.ts',
+    purl: variationPurl,
+    purpose: 'no drill-down — renders a plain `class SessionStore`',
+    symbol: 'SessionStore',
+    layer: 1,
+  },
+  {
+    id: 'cls-members',
+    name: 'Transcoder',
+    construct: 'class',
+    file: 'src/session/Transcoder.ts',
+    purl: variationPurl,
+    purpose: 'members only — methods with typed params + returns, a typed field',
+    symbol: 'Transcoder',
+    layer: 1,
+    detail: {
+      kind: 'class',
+      methods: [
+        { nodeId: 'tm1', name: 'encode', parameters: [{ type: 'RawFrame' }], returnType: 'Uint8Array' },
+        { nodeId: 'tm2', name: 'decode', parameters: [{ type: 'Uint8Array' }], returnType: 'RawFrame' },
+        { nodeId: 'tm3', name: 'reset' },
+      ],
+      properties: [{ name: 'bufferSize', type: 'number' }],
+      extends: [],
+      implements: [],
+      instantiations: [],
+      references: [],
+    } satisfies GraphifyComponentDetail,
+  },
+  {
+    id: 'cls-relations',
+    name: 'HttpTransport',
+    construct: 'class',
+    file: 'src/transport/HttpTransport.ts',
+    purl: variationPurl,
+    purpose: 'relationships only — extends + implements, constructed-by comment; empty body elides the braces',
+    symbol: 'HttpTransport',
+    layer: 1,
+    detail: {
+      kind: 'class',
+      methods: [],
+      properties: [],
+      extends: ['BaseTransport'],
+      implements: ['Transport'],
+      instantiations: [{ nodeId: 'x1', name: 'main' }],
+      references: [],
+    } satisfies GraphifyComponentDetail,
+  },
+
+  // --- function: bare → signature only → signature + call relationships
+  {
+    id: 'fn-bare',
+    name: 'bootstrap',
+    construct: 'function',
+    file: 'src/bootstrap.ts',
+    purl: variationPurl,
+    purpose: 'no drill-down — renders a plain `function bootstrap()`',
+    symbol: 'bootstrap',
+    layer: 2,
+  },
+  {
+    id: 'fn-signature',
+    name: 'normalizeSession',
+    construct: 'function',
+    file: 'src/event-processing/normalize.ts',
+    purl: variationPurl,
+    purpose: 'signature only — named + positional (type-only) params, array return; no callers/callees comments',
+    symbol: 'normalizeSession',
+    layer: 2,
+    detail: {
+      kind: 'function',
+      parameters: [
+        { name: 'session', type: 'SessionRecord' },
+        { type: 'NormalizeOptions' },
+      ],
+      returnType: 'SessionEvent[]',
+      callers: [],
+      callees: [],
+    } satisfies GraphifyComponentDetail,
+  },
+  {
+    id: 'fn-calls',
+    name: 'mergeSessions',
+    construct: 'function',
+    file: 'src/session/merge.ts',
+    purl: variationPurl,
+    purpose: 'signature + call relationships — union-typed param, generic return, called-by / calls trailing comments',
+    symbol: 'mergeSessions',
+    layer: 2,
+    detail: {
+      kind: 'function',
+      parameters: [
+        { name: 'sessions', type: 'SessionRecord[]' },
+        { name: 'strategy', type: `'append' | 'replace'` },
+      ],
+      returnType: 'Promise<SessionEvent[]>',
+      callers: [{ nodeId: 'c1', name: 'capture-session', source_location: 'L88' }],
+      callees: [{ nodeId: 'c2', name: 'toUniversalEvents', source_location: 'L64' }],
+    } satisfies GraphifyComponentDetail,
+  },
+
+  // --- type: bare → fields only → fields + implementors + used-by
+  {
+    id: 'ty-bare',
+    name: 'RawFrame',
+    construct: 'interface',
+    file: 'src/session/RawFrame.ts',
+    purl: variationPurl,
+    purpose: 'no drill-down — renders a plain `interface RawFrame`',
+    symbol: 'RawFrame',
+    layer: 3,
+  },
+  {
+    id: 'ty-fields',
+    name: 'SessionRecord',
+    construct: 'interface',
+    file: 'src/session/transcript.ts',
+    purl: variationPurl,
+    purpose: 'fields only — typed interface body, nothing else',
+    symbol: 'SessionRecord',
+    layer: 3,
+    detail: {
+      kind: 'type',
+      properties: [
+        { name: 'id', type: 'string' },
+        { name: 'admittedSeq', type: 'number' },
+      ],
+      usedBy: [],
+      implementors: [],
+    } satisfies GraphifyComponentDetail,
+  },
+  {
+    id: 'ty-full',
+    name: 'Transport',
+    construct: 'interface',
+    file: 'src/transport/Transport.ts',
+    purl: variationPurl,
+    purpose: 'full — fields + implemented-by (clicks through to HttpTransport) + used-by comments',
+    symbol: 'Transport',
+    layer: 3,
+    detail: {
+      kind: 'type',
+      properties: [{ name: 'name', type: 'string' }],
+      usedBy: [{ nodeId: 'u1', name: 'main', context: 'parameter_type' }],
+      implementors: ['HttpTransport'],
+    } 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,
+    detail: {
+      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,
+    detail: {
+      kind: 'module',
+      exports: ['SessionReader', 'SessionStore'],
+      imports: [{ nodeId: 'i1', name: 'transcript', relation: 'imports_from' }],
+      symbols: ['SessionReader', 'SessionStore'],
+    } satisfies GraphifyComponentDetail,
+  },
+
+  // --- external: bare → labeled
+  {
+    id: 'ext-bare',
+    name: 'left-pad',
+    construct: 'external',
+    file: '',
+    purl: 'pkg:npm/left-pad',
+    purpose: 'no drill-down — renders a plain `external left-pad`',
+    symbol: '',
+    layer: 5,
+  },
+  {
+    id: 'ext-label',
+    name: 'trail-viewer',
+    construct: 'external',
+    file: '',
+    purl: 'pkg:npm/@principal-ai/trail-viewer',
+    purpose: 'labeled — the full purl as a quoted string literal',
+    symbol: '',
+    layer: 5,
+    detail: {
+      kind: 'external',
+      label: 'pkg:npm/@principal-ai/trail-viewer',
+    } satisfies GraphifyComponentDetail,
+  },
+];
+
+const kindVariationEdges: SubsystemComponentEdge[] = [];
+
+function KindVariationsDemo() {
+  const [selected, setSelected] = useState<string | null>(null);
+  return (
+    <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
+      <SubsystemComponentGraph
+        components={kindVariationComponents}
+        edges={kindVariationEdges}
+        onSelect={(id) => setSelected(id)}
+      />
+      <div style={{ marginTop: 8, fontFamily: 'monospace', fontSize: 12, color: '#aaa' }}>
+        columns: class · function · type · module · external — each goes bare → detailed
+        {selected ? ` · selected: ${selected}` : ''}
+      </div>
+    </div>
+  );
+}
+
+export const KindVariations: Story = {
+  render: () => <KindVariationsDemo />,
+};