@principal-ai/subsystems-react 0.25.0 → 0.26.0

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

@@ -78,7 +78,7 @@ function PlaygroundDemo({ leftCount, rightCount, showEdgeLabels }: { leftCount:
 
   for (let i = 0; i < leftCount; i++) {
     comps.push({
-      id: `l${i}`,
+      alias: `l${i}`,
       name: `Left${i}`,
       construct: 'class',
       file: `left${i}.ts`,
@@ -88,7 +88,7 @@ function PlaygroundDemo({ leftCount, rightCount, showEdgeLabels }: { leftCount:
   }
   for (let i = 0; i < rightCount; i++) {
     comps.push({
-      id: `r${i}`,
+      alias: `r${i}`,
       name: `Right${i}`,
       construct: 'class',
       file: `right${i}.ts`,

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

@@ -163,7 +163,7 @@ export const ResolvedPostGraphify: Story = {
 // ---------------------------------------------------------------------------
 const investigationComponents: SubsystemComponent[] = [
   {
-    id: 'adapter',
+    alias: 'adapter',
     name: 'OpenCodeAdapter',
     construct: 'function',
     file: 'apps/server/src/provider/Layers/OpenCodeAdapter.ts',
@@ -172,7 +172,7 @@ const investigationComponents: SubsystemComponent[] = [
     symbol: 'makeOpenCodeAdapter',
   },
   {
-    id: 'ingestion',
+    alias: 'ingestion',
     name: 'ProviderRuntimeIngestion',
     construct: 'function',
     file: 'apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts',
@@ -181,7 +181,7 @@ const investigationComponents: SubsystemComponent[] = [
     symbol: 'ProviderRuntimeIngestion',
   },
   {
-    id: 'contracts',
+    alias: 'contracts',
     name: 'orchestration',
     construct: 'function',
     file: 'packages/contracts/src/orchestration.ts',

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

@@ -0,0 +1,73 @@
+import React, { useRef, 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 {
+  composedComponents,
+  composedRelations,
+  composedWalkthroughs,
+} from './composedFixture';
+
+const meta = {
+  title: 'Subsystem/ComponentGraph/ComposedGraph',
+  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>;
+
+// ---------------------------------------------------------------------------
+// Composed repo graph: 165 nodes merged from live store models. Repro case
+// for the silent child-death seen in Studio — hover nodes and watch the
+// render counter: a hover storm (enter/leave oscillation) shows up as the
+// counter spinning without settling.
+// ---------------------------------------------------------------------------
+
+function ComposedDemo() {
+  const renders = useRef(0);
+  renders.current += 1;
+  const [selected, setSelected] = useState<string | null>(null);
+  const [, forceTick] = useState(0);
+  // Re-render once a second so the counter visibly settles when idle.
+  // NOTE: this counts demo renders only. For hover storms inside the graph,
+  // use React DevTools Profiler (record 10s of hovering, check commit count)
+  // and watch the console for '[subsystem-graph]' layout warnings.
+  React.useEffect(() => {
+    const t = setInterval(() => forceTick((n) => n + 1), 1000);
+    return () => clearInterval(t);
+  }, []);
+  return (
+    <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
+      <div style={{ flex: 1, minHeight: 0, position: 'relative' }}>
+        <SubsystemComponentGraph
+          components={composedComponents}
+          relations={composedRelations}
+          walkthroughs={composedWalkthroughs}
+          title="Composed: pkg:github/principal-ai/subsystem-modeling"
+          onSelect={(alias) => setSelected(alias)}
+        />
+      </div>
+      <div style={{ padding: '4px 12px', fontFamily: 'monospace', fontSize: 12, color: '#aaa', borderTop: '1px solid #333', display: 'flex', gap: 24 }}>
+        <span>renders: {renders.current}</span>
+        <span>selected: {selected ?? '(none)'}</span>
+        <span>nodes: {composedComponents.length} relations: {composedRelations.length} walks: {composedWalkthroughs.length}</span>
+      </div>
+    </div>
+  );
+}
+
+export const Composed: Story = {
+  render: () => <ComposedDemo />,
+};

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

@@ -32,7 +32,7 @@ const PURL = 'pkg:github/you/notes-intake';
 /** One construct of each core kind, no relations — the catalog view. */
 const constructsOnly: SubsystemComponent[] = [
   {
-    id: 'submit-note',
+    alias: 'submit-note',
     name: 'submitNote',
     construct: 'function',
     symbol: 'submitNote',
@@ -58,7 +58,7 @@ const constructsOnly: SubsystemComponent[] = [
     } satisfies GraphifyComponentDetail,
   },
   {
-    id: 'note-service',
+    alias: 'note-service',
     name: 'NoteService',
     construct: 'class',
     symbol: 'NoteService',
@@ -86,7 +86,7 @@ const constructsOnly: SubsystemComponent[] = [
     } satisfies GraphifyComponentDetail,
   },
   {
-    id: 'note-service-persist',
+    alias: 'note-service-persist',
     name: 'persist',
     construct: 'method',
     symbol: 'NoteService.persist',
@@ -108,7 +108,7 @@ const constructsOnly: SubsystemComponent[] = [
     } satisfies GraphifyComponentDetail,
   },
   {
-    id: 'note-repository',
+    alias: 'note-repository',
     name: 'NoteRepository',
     construct: 'interface',
     symbol: 'NoteRepository',
@@ -131,7 +131,7 @@ const constructsOnly: SubsystemComponent[] = [
     } satisfies GraphifyComponentDetail,
   },
   {
-    id: 'note-id',
+    alias: 'note-id',
     name: 'NoteId',
     construct: 'type_alias',
     symbol: 'NoteId',
@@ -150,7 +150,7 @@ const constructsOnly: SubsystemComponent[] = [
     } satisfies GraphifyComponentDetail,
   },
   {
-    id: 'note-kind',
+    alias: 'note-kind',
     name: 'NoteKind',
     construct: 'enum',
     symbol: 'NoteKind',

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

@@ -25,7 +25,7 @@ function entityDetail(attributes: Array<[string, string]>): GraphifyCustomEntity
 
 const components: SubsystemComponent[] = [
   {
-    id: 'wr',
+    alias: 'wr',
     name: 'WorkRequester',
     construct: 'custom_entity',
     entityKind: 'Person',
@@ -39,7 +39,7 @@ const components: SubsystemComponent[] = [
     ]),
   },
   {
-    id: 'tech',
+    alias: 'tech',
     name: 'FacilitiesTechnician',
     construct: 'custom_entity',
     entityKind: 'Person',
@@ -54,7 +54,7 @@ const components: SubsystemComponent[] = [
     ]),
   },
   {
-    id: 'sup',
+    alias: 'sup',
     name: 'ShiftSupervisor',
     construct: 'custom_entity',
     entityKind: 'Person',
@@ -69,7 +69,7 @@ const components: SubsystemComponent[] = [
     ]),
   },
   {
-    id: 'mgr',
+    alias: 'mgr',
     name: 'CampusOpsManager',
     construct: 'custom_entity',
     entityKind: 'Person',
@@ -84,7 +84,7 @@ const components: SubsystemComponent[] = [
     ]),
   },
   {
-    id: 'vp',
+    alias: 'vp',
     name: 'VPOperations',
     construct: 'custom_entity',
     entityKind: 'Person',
@@ -99,7 +99,7 @@ const components: SubsystemComponent[] = [
     ]),
   },
   {
-    id: 'agent',
+    alias: 'agent',
     name: 'OpsInsightAgent',
     construct: 'custom_entity',
     entityKind: 'agent',
@@ -115,7 +115,7 @@ const components: SubsystemComponent[] = [
     ]),
   },
   {
-    id: 'queue',
+    alias: 'queue',
     name: 'NudgeQueue',
     construct: 'custom_entity',
     entityKind: 'queue',
@@ -131,7 +131,7 @@ const components: SubsystemComponent[] = [
     ]),
   },
   {
-    id: 'store',
+    alias: 'store',
     name: 'WorkRequestStore',
     construct: 'store',
     file: 'src/ops/workRequests.ts',

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

@@ -35,7 +35,7 @@ type Story = StoryObj<typeof meta>;
 // ---------------------------------------------------------------------------
 const detailKindComponents: SubsystemComponent[] = [
   {
-    id: 'detail-class',
+    alias: 'detail-class',
     name: 'SessionReader',
     construct: 'class',
     file: 'src/session/SessionReader.ts',
@@ -45,7 +45,7 @@ const detailKindComponents: SubsystemComponent[] = [
     declaration: readerDetail,
   },
   {
-    id: 'detail-method',
+    alias: 'detail-method',
     name: 'normalize',
     construct: 'function',
     file: 'src/session/SessionReader.ts',
@@ -61,7 +61,7 @@ const detailKindComponents: SubsystemComponent[] = [
     } satisfies GraphifyComponentDetail,
   },
   {
-    id: 'detail-fn',
+    alias: 'detail-fn',
     name: 'normalizeSession',
     construct: 'function',
     file: 'src/event-processing/normalize.ts',
@@ -80,7 +80,7 @@ const detailKindComponents: SubsystemComponent[] = [
     } satisfies GraphifyComponentDetail,
   },
   {
-    id: 'detail-fn-rich',
+    alias: 'detail-fn-rich',
     name: 'mergeSessions',
     construct: 'function',
     file: 'src/session/merge.ts',
@@ -104,7 +104,7 @@ const detailKindComponents: SubsystemComponent[] = [
     } satisfies GraphifyComponentDetail,
   },
   {
-    id: 'detail-fn-void',
+    alias: 'detail-fn-void',
     name: 'flush',
     construct: 'function',
     file: 'src/event-processing/sink.ts',
@@ -119,7 +119,7 @@ const detailKindComponents: SubsystemComponent[] = [
     } satisfies GraphifyComponentDetail,
   },
   {
-    id: 'detail-class-rich',
+    alias: 'detail-class-rich',
     name: 'EventProcessor',
     construct: 'class',
     file: 'src/event-processing/EventProcessor.ts',
@@ -149,7 +149,7 @@ const detailKindComponents: SubsystemComponent[] = [
     } satisfies GraphifyComponentDetail,
   },
   {
-    id: 'detail-type',
+    alias: 'detail-type',
     name: 'SessionRecord',
     construct: 'interface',
     file: 'src/session/transcript.ts',
@@ -167,7 +167,7 @@ const detailKindComponents: SubsystemComponent[] = [
     } satisfies GraphifyComponentDetail,
   },
   {
-    id: 'detail-module',
+    alias: 'detail-module',
     name: 'CodexRolloutRecord',
     construct: 'interface',
     file: 'src/session/transcript.ts',
@@ -185,7 +185,7 @@ const detailKindComponents: SubsystemComponent[] = [
     } satisfies GraphifyComponentDetail,
   },
   {
-    id: 'detail-external',
+    alias: 'detail-external',
     // name = the package's name after the namespace; namespace shown above.
     name: 'principal-studio',
     construct: 'external',
@@ -232,7 +232,7 @@ const storyFileContents: Record<string, string> = {
 
 const declarationOpenComponents: SubsystemComponent[] = [
   {
-    id: 'detail',
+    alias: 'detail',
     name: 'ComponentDeclaration',
     construct: 'function',
     file: 'packages/subsystems-react/src/subsystem/ComponentDeclaration.tsx',
@@ -247,7 +247,7 @@ const declarationOpenComponents: SubsystemComponent[] = [
     },
   },
   {
-    id: 'resolver',
+    alias: 'resolver',
     name: 'resolve.ts',
     construct: 'function',
     file: 'packages/subsystems-react/src/graphify/resolve.ts',

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

@@ -61,7 +61,7 @@ function readStoryFile(path: string): Promise<string> {
 
 const drawingComponents: SubsystemComponent[] = [
   {
-    id: 'panel',
+    alias: 'panel',
     name: 'DrawingsLeftPanel',
     construct: 'class',
     file: 'src/panels/DrawingsLeftPanel.tsx',
@@ -71,7 +71,7 @@ const drawingComponents: SubsystemComponent[] = [
     process: 'draw-list',
   },
   {
-    id: 'host',
+    alias: 'host',
     name: 'useDrawingsHost',
     construct: 'function',
     file: 'src/hooks/useDrawingsHost.ts',
@@ -81,7 +81,7 @@ const drawingComponents: SubsystemComponent[] = [
     process: 'draw-list',
   },
   {
-    id: 'storage',
+    alias: 'storage',
     name: 'DrawingsStorage',
     construct: 'class',
     file: 'src/storage/drawingsStorage.ts',
@@ -91,7 +91,7 @@ const drawingComponents: SubsystemComponent[] = [
     process: 'draw-host',
   },
   {
-    id: 'fs',
+    alias: 'fs',
     name: 'FileSystemService',
     construct: 'external',
     file: 'src/services/fileSystem.ts',
@@ -101,7 +101,7 @@ const drawingComponents: SubsystemComponent[] = [
     role: 'service',
   },
   {
-    id: 'shell',
+    alias: 'shell',
     name: 'WorkspaceShell',
     construct: 'class',
     file: 'src/workspace/WorkspaceShell.tsx',
@@ -111,7 +111,7 @@ const drawingComponents: SubsystemComponent[] = [
     process: 'draw-host',
   },
   {
-    id: 'tab',
+    alias: 'tab',
     name: 'DrawingTabContent',
     construct: 'class',
     file: 'src/components/DrawingTabContent.tsx',

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

@@ -30,7 +30,7 @@ const purl = 'pkg:github/principal-ai/principal-view-core-library';
  */
 const reactUiComponents: SubsystemComponent[] = [
   {
-    id: 'create-graph',
+    alias: 'create-graph',
     name: 'createSubsystemModel',
     construct: 'function',
     file: 'packages/subsystems-studio/src/bun/subsystem-model-store.ts',
@@ -41,7 +41,7 @@ const reactUiComponents: SubsystemComponent[] = [
     layer: 1,
   },
   {
-    id: 'http-entry',
+    alias: 'http-entry',
     name: 'handleSubsystemModelRequest',
     construct: 'function',
     file: 'packages/subsystems-studio/src/bun/http-server.ts',
@@ -53,7 +53,7 @@ const reactUiComponents: SubsystemComponent[] = [
     layer: 1,
   },
   {
-    id: 'sessions-view',
+    alias: 'sessions-view',
     name: 'AgentSessionsOverviewView',
     construct: 'function',
     file: 'packages/subsystems-studio/src/mainview/views/AgentSessions.tsx',
@@ -66,7 +66,7 @@ const reactUiComponents: SubsystemComponent[] = [
     layer: 2,
   },
   {
-    id: 'analysis-view',
+    alias: 'analysis-view',
     name: 'AnalysisView',
     construct: 'function',
     file: 'packages/subsystems-studio/src/mainview/views/AnalysisView.tsx',
@@ -79,7 +79,7 @@ const reactUiComponents: SubsystemComponent[] = [
     layer: 2,
   },
   {
-    id: 'drawings-host',
+    alias: 'drawings-host',
     name: 'useDrawingsHost',
     construct: 'function',
     file: 'packages/subsystems-studio/src/mainview/hooks/useDrawingsHost.ts',
@@ -92,7 +92,7 @@ const reactUiComponents: SubsystemComponent[] = [
     layer: 2,
   },
   {
-    id: 'graph-doc-type',
+    alias: 'graph-doc-type',
     name: 'SubsystemModelDocument',
     construct: 'type_alias',
     file: 'packages/subsystems-core/src/types/subsystem-model.ts',
@@ -146,7 +146,7 @@ export const ReactComponentsAndHooks: Story = {
 /** Nest-style stereotypes on the same ontology — controller / middleware / guard. */
 const nestComponents: SubsystemComponent[] = [
   {
-    id: 'graphs-controller',
+    alias: 'graphs-controller',
     name: 'SubsystemModelsController',
     construct: 'class',
     file: 'src/graphs/graphs.controller.ts',
@@ -159,7 +159,7 @@ const nestComponents: SubsystemComponent[] = [
     layer: 1,
   },
   {
-    id: 'auth-guard',
+    alias: 'auth-guard',
     name: 'AuthGuard',
     construct: 'class',
     file: 'src/auth/auth.guard.ts',
@@ -171,7 +171,7 @@ const nestComponents: SubsystemComponent[] = [
     layer: 1,
   },
   {
-    id: 'logging-mw',
+    alias: 'logging-mw',
     name: 'LoggingMiddleware',
     construct: 'function',
     file: 'src/logging/logging.middleware.ts',
@@ -183,7 +183,7 @@ const nestComponents: SubsystemComponent[] = [
     layer: 1,
   },
   {
-    id: 'graphs-service',
+    alias: 'graphs-service',
     name: 'GraphsService',
     construct: 'class',
     file: 'src/graphs/graphs.service.ts',

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

@@ -39,7 +39,7 @@ const DEEP_VIEWS = 'packages/subsystems-studio/src/mainview/views/AnalysisView.t
  */
 const deepComponents: SubsystemComponent[] = [
   {
-    id: 'node-comp',
+    alias: 'node-comp',
     name: 'SubsystemComponentNode',
     construct: 'function',
     symbol: 'SubsystemComponentNode',
@@ -49,7 +49,7 @@ const deepComponents: SubsystemComponent[] = [
     purpose: 'Leaf component renderer',
   },
   {
-    id: 'group-comp',
+    alias: 'group-comp',
     name: 'SubsystemGroupNode',
     construct: 'function',
     symbol: 'SubsystemGroupNode',
@@ -59,7 +59,7 @@ const deepComponents: SubsystemComponent[] = [
     purpose: 'Boundary frame renderer',
   },
   {
-    id: 'edge-comp',
+    alias: 'edge-comp',
     name: 'SubsystemEdge',
     construct: 'function',
     symbol: 'SubsystemEdge',
@@ -69,7 +69,7 @@ const deepComponents: SubsystemComponent[] = [
     purpose: 'Edge renderer',
   },
   {
-    id: 'analysis',
+    alias: 'analysis',
     name: 'AnalysisView',
     construct: 'function',
     symbol: 'AnalysisView',
@@ -79,7 +79,7 @@ const deepComponents: SubsystemComponent[] = [
     purpose: 'Renders an analysis',
   },
   {
-    id: 'layers',
+    alias: 'layers',
     name: 'LayersProvider',
     construct: 'function',
     symbol: 'LayersProvider',
@@ -89,7 +89,7 @@ const deepComponents: SubsystemComponent[] = [
     purpose: 'Provides the layer UI',
   },
   {
-    id: 'use-drawings',
+    alias: 'use-drawings',
     name: 'useDrawingsHost',
     construct: 'function',
     symbol: 'useDrawingsHost',

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

@@ -30,7 +30,7 @@ const PURL = 'pkg:github/principal-ai/agent-monitoring';
  */
 const moduleComponents: SubsystemComponent[] = [
   {
-    id: 'record',
+    alias: 'record',
     name: 'CodexRolloutRecord',
     construct: 'type_alias',
     symbol: 'CodexRolloutRecord',
@@ -41,7 +41,7 @@ const moduleComponents: SubsystemComponent[] = [
     layer: 1,
   },
   {
-    id: 'is-rollout',
+    alias: 'is-rollout',
     name: 'isCodexRollout',
     construct: 'function',
     symbol: 'isCodexRollout',
@@ -52,7 +52,7 @@ const moduleComponents: SubsystemComponent[] = [
     layer: 1,
   },
   {
-    id: 'parse',
+    alias: 'parse',
     name: 'parseTranscript',
     construct: 'function',
     symbol: 'parseTranscript',
@@ -63,7 +63,7 @@ const moduleComponents: SubsystemComponent[] = [
     layer: 1,
   },
   {
-    id: 'tool-name',
+    alias: 'tool-name',
     name: 'extractToolName',
     construct: 'function',
     symbol: 'extractToolName',
@@ -74,7 +74,7 @@ const moduleComponents: SubsystemComponent[] = [
     layer: 2,
   },
   {
-    id: 'file-path',
+    alias: 'file-path',
     name: 'extractFilePath',
     construct: 'function',
     symbol: 'extractFilePath',
@@ -85,7 +85,7 @@ const moduleComponents: SubsystemComponent[] = [
     layer: 2,
   },
   {
-    id: 'reader',
+    alias: 'reader',
     name: 'SessionReader',
     construct: 'class',
     symbol: 'SessionReader',
@@ -96,7 +96,7 @@ const moduleComponents: SubsystemComponent[] = [
     layer: 3,
   },
   {
-    id: 'normalize',
+    alias: 'normalize',
     name: 'normalize',
     construct: 'method',
     symbol: 'SessionReader.normalize',
@@ -107,7 +107,7 @@ const moduleComponents: SubsystemComponent[] = [
     layer: 3,
   },
   {
-    id: 'registry',
+    alias: 'registry',
     name: 'registerAgent',
     construct: 'function',
     symbol: 'registerAgent',
@@ -147,7 +147,7 @@ export const ModuleBoundaries: Story = {
 /** Process → module → export nesting (host / renderer). */
 const nestedComponents: SubsystemComponent[] = [
   {
-    id: 'boot',
+    alias: 'boot',
     name: 'boot',
     construct: 'function',
     symbol: 'boot',
@@ -160,7 +160,7 @@ const nestedComponents: SubsystemComponent[] = [
     layer: 1,
   },
   {
-    id: 'create-host',
+    alias: 'create-host',
     name: 'createHost',
     construct: 'function',
     symbol: 'createHost',
@@ -172,7 +172,7 @@ const nestedComponents: SubsystemComponent[] = [
     layer: 1,
   },
   {
-    id: 'session-store',
+    alias: 'session-store',
     name: 'SessionStore',
     construct: 'store',
     symbol: 'SessionStore',
@@ -184,7 +184,7 @@ const nestedComponents: SubsystemComponent[] = [
     layer: 2,
   },
   {
-    id: 'write-session',
+    alias: 'write-session',
     name: 'writeSession',
     construct: 'function',
     symbol: 'writeSession',
@@ -196,7 +196,7 @@ const nestedComponents: SubsystemComponent[] = [
     layer: 2,
   },
   {
-    id: 'bridge',
+    alias: 'bridge',
     name: 'bridge',
     construct: 'function',
     symbol: 'bridge',
@@ -209,7 +209,7 @@ const nestedComponents: SubsystemComponent[] = [
     layer: 3,
   },
   {
-    id: 'post-to-host',
+    alias: 'post-to-host',
     name: 'postToHost',
     construct: 'function',
     symbol: 'postToHost',
@@ -221,7 +221,7 @@ const nestedComponents: SubsystemComponent[] = [
     layer: 3,
   },
   {
-    id: 'trail-view',
+    alias: 'trail-view',
     name: 'TrailView',
     construct: 'function',
     symbol: 'TrailView',
@@ -235,7 +235,7 @@ const nestedComponents: SubsystemComponent[] = [
     layer: 4,
   },
   {
-    id: 'use-trail',
+    alias: 'use-trail',
     name: 'useTrail',
     construct: 'function',
     symbol: 'useTrail',
@@ -249,7 +249,7 @@ const nestedComponents: SubsystemComponent[] = [
     layer: 4,
   },
   {
-    id: 'telemetry',
+    alias: 'telemetry',
     name: 'telemetry',
     construct: 'external',
     role: 'service',