@principal-ai/subsystems-react 0.55.3 → 0.56.1

package/src/subsystem/trailStack.ts

@@ -0,0 +1,229 @@
+/**
+ * Derive a call stack for one trail step.
+ *
+ * A trail is a timeline, not a stack frame dump: steps can return to an
+ * ancestor, take sibling calls, or describe a non-call seam (`uses`, `feeds`,
+ * …). This module links each `calls` step to the prior call that entered its
+ * caller construct, then renders that ancestry as a stack. Non-call steps are
+ * annotations on the nearest frame — they are not frames.
+ *
+ * The links use the resolved `site`/`target` when present, falling back to the
+ * component aliases. That keeps the view useful before every step has its
+ * construct refs captured.
+ */
+
+import type {
+  SubsystemTrail,
+  SubsystemTrailMechanism,
+  SubsystemTrailStep,
+} from './model';
+import {
+  trailComponentLabel,
+  type TrailComponentLabels,
+} from './trailStepDisplay';
+
+export interface TrailStackFrame {
+  /** The step whose call creates this frame. */
+  stepIndex: number;
+  /** Frame label — the caller construct, or the component alias. */
+  label: string;
+  /** Component alias of the caller (for focus/selection wiring). */
+  componentAlias: string;
+  /** The selected step's own frame (innermost). */
+  current: boolean;
+}
+
+export interface TrailStackAnnotation {
+  /** Non-call step attached to the current frame. */
+  stepIndex: number;
+  mechanism: SubsystemTrailMechanism;
+  label: string;
+  /** The selected step itself (vs context around it). */
+  selected: boolean;
+}
+
+export interface TrailStackView {
+  /** Outermost → innermost. Empty only for an out-of-range index. */
+  frames: TrailStackFrame[];
+  /** Non-call seams attached to the current frame. */
+  annotations: TrailStackAnnotation[];
+  /** True when the selected step is a call frame. */
+  isCall: boolean;
+  /** The selected call's target, shown as the next frame-to-be. */
+  callee?: string;
+}
+
+function callerSymbol(step: SubsystemTrailStep): string {
+  return step.site?.symbol?.trim() || step.symbol?.trim() || step.from;
+}
+
+function calleeSymbol(step: SubsystemTrailStep): string {
+  return step.target?.symbol?.trim() || step.to;
+}
+
+function callerLabel(
+  step: SubsystemTrailStep,
+  byAlias?: TrailComponentLabels,
+): string {
+  return callerSymbol(step) || trailComponentLabel(step.from, byAlias);
+}
+
+function calleeLabel(
+  step: SubsystemTrailStep,
+  byAlias?: TrailComponentLabels,
+): string {
+  return step.target?.symbol?.trim() || trailComponentLabel(step.to, byAlias);
+}
+
+function isCallStep(step: SubsystemTrailStep | undefined): boolean {
+  return step?.mechanism === 'calls';
+}
+
+/** Does call `a` lead into the caller of call `b`? */
+function leadsInto(a: SubsystemTrailStep, b: SubsystemTrailStep): boolean {
+  return a.to === b.from || calleeSymbol(a) === callerSymbol(b);
+}
+
+/** The nearest earlier call that entered this step's caller frame. */
+function parentCallIndex(
+  trail: SubsystemTrail,
+  stepIndex: number,
+): number | null {
+  const child = trail.steps[stepIndex];
+  if (!child) return null;
+  for (let i = stepIndex - 1; i >= 0; i--) {
+    const candidate = trail.steps[i];
+    if (!isCallStep(candidate)) continue;
+    if (leadsInto(candidate!, child)) return i;
+  }
+  return null;
+}
+
+/** The call chain ending at `stepIndex`, outermost first. */
+function callChain(trail: SubsystemTrail, stepIndex: number): number[] {
+  const chain: number[] = [];
+  const seen = new Set<number>();
+  let cursor: number | null = stepIndex;
+  while (cursor != null && !seen.has(cursor)) {
+    seen.add(cursor);
+    chain.unshift(cursor);
+    cursor = parentCallIndex(trail, cursor);
+  }
+  return chain;
+}
+
+function framesForChain(
+  trail: SubsystemTrail,
+  chain: number[],
+  selectedStepIndex: number | null,
+  byAlias?: TrailComponentLabels,
+): TrailStackFrame[] {
+  return chain.map((idx) => {
+    const step = trail.steps[idx]!;
+    return {
+      stepIndex: idx,
+      label: callerLabel(step, byAlias),
+      componentAlias: step.from,
+      current: idx === selectedStepIndex,
+    };
+  });
+}
+
+/**
+ * The nearest earlier call that shares this non-call step's source component.
+ * `uses`/`feeds`/… are dependencies of that frame, not new frames.
+ */
+function anchorCallIndex(
+  trail: SubsystemTrail,
+  stepIndex: number,
+): number | null {
+  const step = trail.steps[stepIndex];
+  if (!step) return null;
+  const source = callerSymbol(step);
+  for (let i = stepIndex - 1; i >= 0; i--) {
+    const candidate = trail.steps[i];
+    if (!isCallStep(candidate)) continue;
+    if (
+      candidate!.from === step.from ||
+      candidate!.to === step.from ||
+      callerSymbol(candidate!) === source ||
+      calleeSymbol(candidate!) === source
+    ) {
+      return i;
+    }
+  }
+  return null;
+}
+
+function annotationLabel(
+  step: SubsystemTrailStep,
+  byAlias?: TrailComponentLabels,
+): string {
+  return `${step.mechanism} ${calleeLabel(step, byAlias)}`;
+}
+
+/**
+ * Build the stack at one trail step.
+ *
+ * - `calls` → the chain of calls into the caller frame, plus the callee as the
+ *   next frame (not yet on the stack).
+ * - `uses` / data + event seams → the nearest call frame they attach to, with
+ *   the seam as an annotation.
+ */
+export function buildTrailStack(
+  trail: SubsystemTrail,
+  stepIndex: number,
+  byAlias?: TrailComponentLabels,
+): TrailStackView {
+  const step = trail.steps[stepIndex];
+  if (!step) {
+    return { frames: [], annotations: [], isCall: false };
+  }
+
+  if (isCallStep(step)) {
+    const chain = callChain(trail, stepIndex);
+    return {
+      frames: framesForChain(trail, chain, stepIndex, byAlias),
+      annotations: [],
+      isCall: true,
+      callee: calleeLabel(step, byAlias),
+    };
+  }
+
+  const anchor = anchorCallIndex(trail, stepIndex);
+  if (anchor != null) {
+    const chain = callChain(trail, anchor);
+    return {
+      frames: framesForChain(trail, chain, anchor, byAlias),
+      annotations: [
+        {
+          stepIndex,
+          mechanism: step.mechanism,
+          label: annotationLabel(step, byAlias),
+          selected: true,
+        },
+      ],
+      isCall: false,
+    };
+  }
+
+  return {
+    frames: [
+      {
+        stepIndex,
+        label: callerLabel(step, byAlias),
+        componentAlias: step.from,
+        current: true,
+      },
+    ],
+    annotations: [
+      {
+        stepIndex,
+        mechanism: step.mechanism,
+        label: annotationLabel(step, byAlias),
+        selected: true,
+      },
+    ],
+    isCall: false,
+  };
+}

package/src/subsystem/trailStepDisplay.ts

@@ -0,0 +1,68 @@
+/**
+ * How a trail step reads in the Trails panel.
+ *
+ * A step is one seam, but the panel shows the logical hop and the site in a
+ * single wrapping line:
+ *
+ * - `calls` — the caller frame (the site construct).
+ * - `uses` — `from uses to`, where `to` is the precise target when resolved.
+ * - Everything else — `from mechanism to`.
+ *
+ * The evidence site lives in the code view and the stack breadcrumb; the
+ * sidebar row stays one line so it can wrap instead of truncating.
+ */
+
+import type { SubsystemTrailStep, SubsystemTrailMechanism } from './model';
+
+/** The slice of a component the labels need — keeps fixtures light. */
+export interface TrailComponentLabelSource {
+  alias: string;
+  name?: string;
+  symbol?: string;
+}
+
+/** Alias → component, for turning model-local aliases into display names. */
+export type TrailComponentLabels = ReadonlyMap<string, TrailComponentLabelSource>;
+
+/** One row's primary text. */
+export interface TrailStepDisplay {
+  mechanism: SubsystemTrailMechanism;
+  /** The line that names the step: caller frame for `calls`, hop otherwise. */
+  primary: string;
+}
+
+/** Display label for a component alias; falls back to the alias. */
+export function trailComponentLabel(
+  alias: string,
+  byAlias?: TrailComponentLabels,
+): string {
+  const component = byAlias?.get(alias);
+  const label = component?.name?.trim() || component?.symbol?.trim();
+  return label || alias;
+}
+
+/**
+ * Build the single display line for one step.
+ *
+ * The resolved target (`step.target.symbol`) is the precise callee, while `to`
+ * is only a component alias and can be a whole class/store. Prefer the target.
+ */
+export function trailStepDisplay(
+  step: SubsystemTrailStep,
+  byAlias?: TrailComponentLabels,
+): TrailStepDisplay {
+  const from = trailComponentLabel(step.from, byAlias);
+  const to = step.target?.symbol?.trim() || trailComponentLabel(step.to, byAlias);
+  const siteSymbol = step.site?.symbol?.trim() || step.symbol?.trim() || from;
+
+  if (step.mechanism === 'calls') {
+    return { mechanism: step.mechanism, primary: siteSymbol };
+  }
+  if (step.mechanism === 'uses') {
+    return { mechanism: step.mechanism, primary: `${from} uses ${to}` };
+  }
+  return {
+    mechanism: step.mechanism,
+    primary: `${from} ${step.mechanism} ${to}`,
+  };
+}

package/src/stories/Canvases/Subsystem/Proposed.stories.tsx

@@ -1,256 +0,0 @@
-import React, { useState } from 'react';
-import '@xyflow/react/dist/style.css';
-import type { Meta, StoryObj } from '@storybook/react';
-import { ReactFlowProvider, type NodeProps } from '@xyflow/react';
-import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
-import { SubsystemComponentGraph } from '../../../subsystem/SubsystemComponentGraph';
-import { SubsystemComponentNode } from '../../../subsystem/nodes';
-import type {
-  SubsystemComponent,
-  SubsystemGraphNode,
-} from '../../../subsystem/model';
-import { trailFromSteps } from './fixtures';
-
-const meta = {
-  title: 'Canvases/Subsystem/Proposed',
-  parameters: { layout: 'fullscreen' },
-  tags: ['autodocs'],
-  decorators: [
-    (Story) => (
-      <ThemeProvider theme={defaultEditorTheme}>
-        <ReactFlowProvider>
-          <Story />
-        </ReactFlowProvider>
-      </ThemeProvider>
-    ),
-  ],
-} satisfies Meta;
-
-export default meta;
-type Story = StoryObj<typeof meta>;
-
-const PURL = 'pkg:github/principal-ai/subsystem-modeling';
-
-function nodeProps(c: SubsystemComponent): NodeProps<SubsystemGraphNode> {
-  return {
-    data: { component: c },
-    selected: false,
-    width: 230,
-    height: 84,
-  } as unknown as NodeProps<SubsystemGraphNode>;
-}
-
-/** Side-by-side single-node spotlights — proposed vs normal vs role combos. */
-function NodeSpotlight({
-  label,
-  component,
-}: {
-  label: string;
-  component: SubsystemComponent;
-}) {
-  return (
-    <div style={{ display: 'flex', flexDirection: 'column', gap: 8, width: 260 }}>
-      <div
-        style={{
-          fontFamily: 'ui-monospace, monospace',
-          fontSize: 11,
-          color: '#888',
-          minHeight: 32,
-        }}
-      >
-        {label}
-      </div>
-      <div style={{ position: 'relative', height: 110, width: 240 }}>
-        <SubsystemComponentNode {...nodeProps(component)} />
-      </div>
-      <pre
-        style={{
-          margin: 0,
-          fontSize: 10,
-          fontFamily: 'ui-monospace, monospace',
-          background: '#1a1a1a',
-          color: '#ccc',
-          padding: 8,
-          borderRadius: 4,
-          overflow: 'auto',
-        }}
-      >
-        {JSON.stringify(
-          {
-            construct: component.construct,
-            proposed: component.proposed || undefined,
-            role: component.role,
-            symbol: component.symbol || undefined,
-            file: component.file || undefined,
-          },
-          null,
-          2,
-        )}
-      </pre>
-    </div>
-  );
-}
-
-const spotlightRows: Array<{ label: string; component: SubsystemComponent }> = [
-  {
-    label: 'normal function (baseline)',
-    component: {
-      alias: 'live-fn',
-      name: 'ensureOpencode',
-      construct: 'function',
-      file: 'src/bun/opencode-v2.ts',
-      purl: PURL,
-      symbol: 'ensureOpencode',
-      purpose: 'Detect / install / update the OpenCode CLI',
-    },
-  },
-  {
-    label: 'proposed function — dashed border + right badge',
-    component: {
-      alias: 'prop-fn',
-      name: 'OpenCodeV2Lifecycle',
-      construct: 'function',
-      file: '',
-      purl: PURL,
-      symbol: 'OpenCodeV2Lifecycle',
-      purpose: 'Studio-managed OpenCode V2 detect / install / update',
-      proposed: true,
-    },
-  },
-  {
-    label: 'proposed class',
-    component: {
-      alias: 'prop-class',
-      name: 'MaintainModelAgent',
-      construct: 'class',
-      file: 'src/bun/maintain-model-agent.ts',
-      purl: PURL,
-      symbol: 'MaintainModelAgent',
-      purpose: 'Planned host agent that drives model maintenance',
-      proposed: true,
-    },
-  },
-  {
-    label: 'proposed + role: entry (badge shows proposed only)',
-    component: {
-      alias: 'prop-entry',
-      name: 'startMaintainFlow',
-      construct: 'function',
-      file: '',
-      purl: PURL,
-      symbol: 'startMaintainFlow',
-      purpose: 'Planned RPC entry for maintain',
-      proposed: true,
-      role: 'entry',
-    },
-  },
-  {
-    label: 'external (contrast — real outside system)',
-    component: {
-      alias: 'ext',
-      name: 'OpenCode CLI',
-      construct: 'external',
-      file: '',
-      purl: 'pkg:npm/@opencode-ai/cli',
-      symbol: '',
-      purpose: 'External OpenCode product',
-      role: 'service',
-    },
-  },
-];
-
-/** Spotlights: proposed badge + dashed border vs normal and external. */
-export const Spotlights: Story = {
-  render: () => (
-    <div
-      style={{
-        padding: 24,
-        display: 'flex',
-        flexWrap: 'wrap',
-        gap: 28,
-        alignItems: 'flex-start',
-        minHeight: '100vh',
-        boxSizing: 'border-box',
-      }}
-    >
-      {spotlightRows.map((row) => (
-        <NodeSpotlight key={row.component.alias} {...row} />
-      ))}
-    </div>
-  ),
-};
-
-// ---------------------------------------------------------------------------
-// Full graph: live seam calling a proposed host lifecycle + real external
-// ---------------------------------------------------------------------------
-const migrationComponents: SubsystemComponent[] = [
-  {
-    alias: 'audit',
-    name: 'auditSubsystemModel',
-    construct: 'function',
-    file: 'src/bun/verify-subsystem-component.ts',
-    purl: PURL,
-    symbol: 'auditSubsystemModel',
-    purpose: 'Deterministic dry-run audit of a stored model',
-    role: 'entry',
-  },
-  {
-    alias: 'lifecycle',
-    name: 'OpenCodeV2Lifecycle',
-    construct: 'function',
-    file: '',
-    purl: PURL,
-    symbol: 'OpenCodeV2Lifecycle',
-    purpose: 'Proposed Studio host: detect / install / update / Service.ensure',
-    proposed: true,
-  },
-  {
-    alias: 'maintain',
-    name: 'runMaintainModel',
-    construct: 'function',
-    file: 'src/bun/maintain-model.ts',
-    purl: PURL,
-    symbol: 'runMaintainModel',
-    purpose: 'Existing maintain agent runner',
-  },
-  {
-    alias: 'cli',
-    name: '@opencode-ai/cli',
-    construct: 'external',
-    file: '',
-    purl: 'pkg:npm/@opencode-ai/cli@beta',
-    symbol: '',
-    purpose: 'Real external OpenCode CLI',
-    role: 'service',
-  },
-];
-
-const migrationTrails = [
-  trailFromSteps('migration-steps', 'Migration steps', [
-    ['audit', 'maintain', 'calls', 'src/bun/verify-subsystem-component.ts', 1],
-    ['maintain', 'lifecycle', 'uses', 'src/bun/maintain-model.ts', 1],
-    ['lifecycle', 'cli', 'calls', 'src/bun/opencode-v2.ts', 1],
-  ]),
-];
-
-function MigrationDemo() {
-  const [selected, setSelected] = useState<string | null>(null);
-  return (
-    <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
-      <SubsystemComponentGraph
-        components={migrationComponents}
-        trails={migrationTrails}
-        onSelect={(id) => setSelected(id)}
-      />
-      <div style={{ marginTop: 8, padding: '0 12px', fontFamily: 'monospace', fontSize: 12, color: '#aaa' }}>
-        proposed OpenCodeV2Lifecycle between live maintain code and real external CLI
-        {selected ? ` · selected: ${selected}` : ''}
-      </div>
-    </div>
-  );
-}
-
-/** Full graph: proposed node between live code and a true external. */
-export const MigrationPlaceholder: Story = {
-  render: () => <MigrationDemo />,
-};