@principal-ai/subsystems-react 0.55.2 → 0.56.0

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

@@ -170,7 +170,6 @@ function TrailsDemo() {
       trail,
       stepIndex,
       onOpenFile,
-      proposedAliases,
       resolveSymbol,
       onSymbolClick,
       onVisibleStepChange,
@@ -181,7 +180,6 @@ function TrailsDemo() {
         readFile={readStoryFile}
         contextLines={4}
         onOpenFile={onOpenFile}
-        proposedAliases={proposedAliases}
         resolveSymbol={resolveSymbol}
         onSymbolClick={onSymbolClick}
         onVisibleStepChange={onVisibleStepChange}
@@ -223,189 +221,6 @@ export const ThreeTrails: Story = {
   render: () => <TrailsDemo />,
 };
 
-/**
- * The proposed-seam failure mode: a trail step whose component is
- * `proposed` points at a file that isn't in the checkout yet (no story
- * fixture). The step must render an inline "Proposed — … isn't in the local
- * checkout yet." placeholder with no Open-file affordance, while the live steps
- * around it still render their snippets — one bad step must not blank the flow.
- */
-const proposedComponents: SubsystemComponent[] = [
-  ...drawingComponents,
-  {
-    alias: 'runs',
-    name: 'SubsystemModelRunStore',
-    construct: 'store',
-    file: 'src/runs/subsystemModelRuns.ts',
-    purl: 'pkg:github/principal-ai/desktop-app',
-    symbol: 'SubsystemModelRunStore',
-    purpose: 'proposed store associating maintain runs with a model',
-    proposed: true,
-    process: 'draw-host',
-  },
-];
-
-const proposedTrails: SubsystemTrail[] = [
-  {
-    id: 'tl-associate-run',
-    title: 'Associate a finished run with its model (proposed)',
-    steps: [
-      {
-        from: 'host',
-        to: 'storage',
-        mechanism: 'calls',
-        file: 'src/hooks/useDrawingsHost.ts',
-        span: { startLine: 45, endLine: 45, contentHash: 'fixture' },
-        purl: stepPurl('src/hooks/useDrawingsHost.ts'),
-        symbol: 'useDrawingsHost.openDrawing',
-        annotation: 'Live step — its snippet still renders.',
-      },
-      {
-        from: 'storage',
-        to: 'runs',
-        mechanism: 'writes',
-        file: 'src/runs/subsystemModelRuns.ts',
-        span: { startLine: 1, endLine: 1, contentHash: 'fixture' },
-        purl: stepPurl('src/runs/subsystemModelRuns.ts'),
-        symbol: 'SubsystemModelRunStore.write',
-        annotation: 'Proposed seam — the file is not in the checkout yet.',
-      },
-    ],
-  },
-  // Neighbours for the wrapped title above: a couple of one-line titles and
-  // one that wraps to two, so the header's padding reads against the rows on
-  // either side of it rather than in isolation.
-  {
-    id: 'tl-open-drawing',
-    title: 'Open drawing',
-    steps: [
-      {
-        from: 'panel',
-        to: 'host',
-        mechanism: 'produces',
-        file: 'src/panels/DrawingsLeftPanel.tsx',
-        span: { startLine: 85, endLine: 85, contentHash: 'fixture' },
-        purl: stepPurl('src/panels/DrawingsLeftPanel.tsx'),
-        symbol: 'DrawingsLeftPanel.openDrawing',
-        annotation: 'Emits the open intent up to the host.',
-      },
-      {
-        from: 'host',
-        to: 'storage',
-        mechanism: 'calls',
-        file: 'src/hooks/useDrawingsHost.ts',
-        span: { startLine: 45, endLine: 45, contentHash: 'fixture' },
-        purl: stepPurl('src/hooks/useDrawingsHost.ts'),
-        symbol: 'useDrawingsHost.openDrawing',
-      },
-    ],
-  },
-  {
-    id: 'tl-save-drawing',
-    title: 'Save the drawing and refresh the list',
-    steps: [
-      {
-        from: 'tab',
-        to: 'fs',
-        mechanism: 'calls',
-        file: 'src/components/DrawingTabContent.tsx',
-        span: { startLine: 112, endLine: 112, contentHash: 'fixture' },
-        purl: stepPurl('src/components/DrawingTabContent.tsx'),
-        symbol: 'DrawingTabContent.save',
-      },
-      {
-        from: 'host',
-        to: 'panel',
-        mechanism: 'produces',
-        file: 'src/hooks/useDrawingsHost.ts',
-        span: { startLine: 64, endLine: 64, contentHash: 'fixture' },
-        purl: stepPurl('src/hooks/useDrawingsHost.ts'),
-        symbol: 'useDrawingsHost.onSaved',
-      },
-    ],
-  },
-  {
-    id: 'tl-delete-drawing',
-    title: 'Delete drawing',
-    steps: [
-      {
-        from: 'host',
-        to: 'fs',
-        mechanism: 'calls',
-        file: 'src/hooks/useDrawingsHost.ts',
-        span: { startLine: 66, endLine: 66, contentHash: 'fixture' },
-        purl: stepPurl('src/hooks/useDrawingsHost.ts'),
-        symbol: 'useDrawingsHost.deleteDrawing',
-      },
-      {
-        from: 'panel',
-        to: 'storage',
-        mechanism: 'calls',
-        file: 'src/panels/DrawingsLeftPanel.tsx',
-        span: { startLine: 56, endLine: 56, contentHash: 'fixture' },
-        purl: stepPurl('src/panels/DrawingsLeftPanel.tsx'),
-        symbol: 'DrawingsLeftPanel.scan',
-      },
-    ],
-  },
-];
-
-function ProposedMissingStepDemo() {
-  const renderTrailViewer = useCallback(
-    ({
-      trail,
-      stepIndex,
-      onOpenFile,
-      proposedAliases,
-      resolveSymbol,
-      onSymbolClick,
-      onVisibleStepChange,
-    }: TrailViewerContext) => (
-      <PierreTrailCodeView
-        trail={trail}
-        stepIndex={stepIndex}
-        readFile={readStoryFile}
-        contextLines={4}
-        onOpenFile={onOpenFile}
-        proposedAliases={proposedAliases}
-        resolveSymbol={resolveSymbol}
-        onSymbolClick={onSymbolClick}
-        onVisibleStepChange={onVisibleStepChange}
-      />
-    ),
-    [],
-  );
-
-  return (
-    <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
-      <SubsystemComponentGraph
-        components={proposedComponents}
-        trails={proposedTrails}
-        title="proposed seam with a missing file"
-        description="The **Trails** panel lists four flows so the long, wrapped title (*Associate a finished run with its model (proposed)*) reads against its neighbours — two one-line titles and one (*Save the drawing and refresh the list*) that also wraps. Expand **Associate a finished run with its model** and click either step: the proposed step has no file in the checkout, so its snippet shows an inline *Proposed — … isn't in the local checkout yet.* placeholder instead of failing the whole flow."
-        renderTrailViewer={renderTrailViewer}
-        renderFileViewer={(file) => (
-          <div
-            style={{
-              padding: 12,
-              fontFamily: 'monospace',
-              fontSize: 12,
-              color: '#bbb',
-              whiteSpace: 'pre',
-            }}
-          >
-            {`// ${file}\n  …`}
-          </div>
-        )}
-      />
-    </div>
-  );
-}
-
-export const ProposedMissingStep: Story = {
-  render: () => <ProposedMissingStepDemo />,
-};
-
 // --- Clickable constructs -------------------------------------------------
 //
 // A trail step's line is an edge between two constructs. When the host
@@ -554,7 +369,6 @@ function ClickableConstructsDemo() {
       trail,
       stepIndex,
       onOpenFile,
-      proposedAliases,
       resolveSymbol,
       onSymbolClick,
       onVisibleStepChange,
@@ -565,7 +379,6 @@ function ClickableConstructsDemo() {
         readFile={readClickableFile}
         contextLines={4}
         onOpenFile={onOpenFile}
-        proposedAliases={proposedAliases}
         resolveSymbol={resolveSymbol}
         onSymbolClick={onSymbolClick}
         onVisibleStepChange={onVisibleStepChange}

package/src/stories/Components/DecorationPanel.stories.tsx

@@ -0,0 +1,160 @@
+import React, { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
+import {
+  DecorationPanel,
+  type DecorationPanelProps,
+} from '../../subsystem/DecorationPanel';
+import {
+  decorationTrailKey,
+  type SubsystemDecoration,
+} from '../../subsystem/decoration';
+
+/**
+ * PROTOTYPE: the decoration container as a reading surface.
+ *
+ * The fixture deliberately spans two models (desktop + sync service) and
+ * includes one draft trail + draft structure, to show that a decoration is
+ * additive and unverified — the base models stay untouched.
+ */
+const meta = {
+  title: 'Components/DecorationPanel',
+  component: DecorationPanel,
+  parameters: { layout: 'fullscreen' },
+  decorators: [
+    (Story) => (
+      <ThemeProvider theme={defaultEditorTheme}>
+        <Story />
+      </ThemeProvider>
+    ),
+  ],
+} satisfies Meta<typeof DecorationPanel>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const decoration: SubsystemDecoration = {
+  version: 1,
+  id: 'dec-local-first-sync',
+  title: 'Local-first sync',
+  description: [
+    'How a drawing reaches disk **and** the sync service, in the order a reader should follow it.',
+    '',
+    '- The desktop stays the source of truth for the open tab.',
+    '- The service is a projection; it never blocks the save.',
+    '',
+    '> This is a reading path, not a verified model claim.',
+  ].join('\n'),
+  trails: [
+    {
+      kind: 'base',
+      modelId: 'sg-desktop',
+      trailId: 'tl-save',
+      stepAnchors: [{ stepKey: 'fixture', note: 'Write first; the sync hop is optional.' }],
+    },
+    { kind: 'base', modelId: 'sg-server', trailId: 'tl-persist' },
+    {
+      kind: 'draft',
+      modelId: 'sg-desktop',
+      trail: {
+        id: 'tl-planned-sync',
+        title: 'Planned sync (draft)',
+        steps: [
+          {
+            from: 'tab',
+            to: 'sync-agent',
+            mechanism: 'produces',
+            file: 'src/components/DrawingTabContent.tsx',
+            purl: 'pkg:github/principal-ai/desktop-app#src/components/DrawingTabContent.tsx',
+            symbol: 'DrawingTabContent.emitSaved',
+          },
+          {
+            from: 'sync-agent',
+            to: 'sync-service',
+            mechanism: 'calls',
+            file: 'src/sync/syncAgent.ts',
+            purl: 'pkg:github/principal-ai/desktop-app#src/sync/syncAgent.ts',
+            symbol: 'SyncAgent.push',
+          },
+        ],
+      },
+    },
+  ],
+  draft: {
+    components: [
+      {
+        alias: 'sync-agent',
+        name: 'SyncAgent',
+        construct: 'class',
+        purpose: 'queues a saved drawing for the sync service',
+        process: 'draw-host',
+      },
+      {
+        alias: 'sync-service',
+        name: 'SyncService',
+        construct: 'external',
+        purpose: 'remote projection of saved drawings',
+      },
+    ],
+    edges: [
+      { from: 'tab', to: 'sync-agent', mechanism: 'produces' },
+      { from: 'sync-agent', to: 'sync-service', mechanism: 'calls' },
+    ],
+  },
+  provenance: {
+    source: 'author',
+    author: 'you',
+    at: '2026-10-20T12:00:00.000Z',
+  },
+};
+
+const resolveTrail: NonNullable<DecorationPanelProps['resolveTrail']> = (ref) => {
+  if (ref.kind === 'draft') return undefined;
+  const key = decorationTrailKey(ref);
+  if (key === 'sg-desktop:tl-save') return { title: 'Save drawing', stepCount: 4 };
+  if (key === 'sg-server:tl-persist') return { title: 'Persist file', stepCount: 5 };
+  return undefined;
+};
+
+const modelLabels = new Map([
+  ['sg-desktop', 'desktop-app'],
+  ['sg-server', 'sync-service'],
+]);
+
+function Demo() {
+  const [active, setActive] = useState(true);
+  const [selected, setSelected] = useState<string>('none');
+
+  return (
+    <div style={{ display: 'flex', height: '100vh', background: '#0f1115' }}>
+      <div style={{ width: 420, height: '100%', borderRight: '1px solid #2a2f3a' }}>
+        <DecorationPanel
+          decoration={decoration}
+          active={active}
+          onToggleActive={setActive}
+          resolveTrail={resolveTrail}
+          modelLabels={modelLabels}
+          onSelectTrail={(ref) => setSelected(decorationTrailKey(ref))}
+          onSelectDraftComponent={(component) => setSelected(component.alias)}
+        />
+      </div>
+      <div
+        style={{
+          flex: 1,
+          padding: 24,
+          color: '#9aa4b2',
+          fontFamily: 'ui-monospace, SFMono-Regular, Menlo, monospace',
+          fontSize: 12,
+          lineHeight: 1.6,
+        }}
+      >
+        <div>active: {String(active)}</div>
+        <div>selected: {selected}</div>
+      </div>
+    </div>
+  );
+}
+
+export const TwoModels: Story = {
+  render: () => <Demo />,
+};

package/src/subsystem/C4Graph.tsx

@@ -2711,7 +2711,6 @@ function Inner({ model, onSelectNode, onSelectEdge, onTrailClick, onToggleContai
           >
             {selectedConstruct.component.alias}
             {selectedConstruct.role ? ` · ${selectedConstruct.role}` : ''}
-            {selectedConstruct.component.proposed ? ' · proposed' : ''}
           </div>
         </div>
       )}

package/src/subsystem/DecorationPanel.test.tsx

@@ -0,0 +1,128 @@
+import { afterEach, describe, expect, mock, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import { cleanup, fireEvent, render } from '@testing-library/react/pure';
+import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
+import { DecorationPanel, type DecorationPanelProps } from './DecorationPanel';
+import { decorationTrailKey, type SubsystemDecoration } from './decoration';
+
+// Same DOM shim as TrailsPanel.test: happy-dom lacks ResizeObserver, which
+// themed-markdown uses to measure its slide container.
+const dom = new Window();
+const globals = globalThis as unknown as Record<string, unknown>;
+globals.window = dom;
+globals.document = dom.document;
+globals.navigator = dom.navigator;
+globals.HTMLElement = dom.HTMLElement;
+globals.Node = dom.Node;
+globals.Element = dom.Element;
+globals.Event = dom.Event;
+globals.MouseEvent = dom.MouseEvent;
+globals.FocusEvent = dom.FocusEvent;
+globals.KeyboardEvent = dom.KeyboardEvent;
+globals.getComputedStyle = dom.getComputedStyle.bind(dom);
+globals.requestAnimationFrame = dom.requestAnimationFrame.bind(dom);
+globals.cancelAnimationFrame = dom.cancelAnimationFrame.bind(dom);
+globals.localStorage = dom.localStorage;
+globals.sessionStorage = dom.sessionStorage;
+globals.matchMedia = dom.matchMedia.bind(dom);
+globals.ResizeObserver = class {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+};
+
+afterEach(cleanup);
+
+const decoration: SubsystemDecoration = {
+  version: 1,
+  id: 'dec-sync',
+  title: 'Local-first sync',
+  description: 'A **reading path** for the save flow.',
+  trails: [
+    { kind: 'base', modelId: 'sg-desktop', trailId: 'tl-save' },
+    { kind: 'base', modelId: 'sg-server', trailId: 'tl-persist' },
+    {
+      kind: 'draft',
+      modelId: 'sg-desktop',
+      trail: { id: 'tl-planned', title: 'Planned sync', steps: [] },
+    },
+  ],
+  draft: {
+    components: [
+      { alias: 'sync-agent', name: 'SyncAgent', construct: 'class' },
+    ],
+    edges: [{ from: 'tab', to: 'sync-agent', mechanism: 'produces' }],
+  },
+  provenance: { source: 'author', at: '2026-10-20T00:00:00.000Z' },
+};
+
+const resolveTrail: NonNullable<DecorationPanelProps['resolveTrail']> = (ref) => {
+  if (ref.kind === 'draft') return undefined;
+  const key = decorationTrailKey(ref);
+  if (key === 'sg-desktop:tl-save') return { title: 'Save drawing', stepCount: 4 };
+  if (key === 'sg-server:tl-persist') return { title: 'Persist file', stepCount: 5 };
+  return undefined;
+};
+
+function renderPanel(overrides: Partial<DecorationPanelProps> = {}) {
+  const props: DecorationPanelProps = {
+    decoration,
+    active: true,
+    onToggleActive: () => {},
+    resolveTrail,
+    modelLabels: new Map([
+      ['sg-desktop', 'desktop-app'],
+      ['sg-server', 'sync-service'],
+    ]),
+    ...overrides,
+  };
+  return render(
+    <ThemeProvider theme={defaultEditorTheme}>
+      <DecorationPanel {...props} />
+    </ThemeProvider>,
+  );
+}
+
+describe('DecorationPanel', () => {
+  test('renders the description, grouped trails, and draft structure', () => {
+    const { getByText, container } = renderPanel();
+    expect(container.textContent).toContain('reading path');
+    expect(getByText('desktop-app')).not.toBeNull();
+    expect(getByText('sync-service')).not.toBeNull();
+    expect(getByText('Save drawing')).not.toBeNull();
+    expect(getByText('Persist file')).not.toBeNull();
+    expect(getByText('Planned sync')).not.toBeNull();
+    expect(getByText('draft')).not.toBeNull();
+    expect(getByText('SyncAgent')).not.toBeNull();
+    expect(getByText('+ 1 draft edge')).not.toBeNull();
+  });
+
+  test('the toggle reports the next active state', () => {
+    const onToggleActive = mock(() => {});
+    const { getByLabelText } = renderPanel({ onToggleActive });
+    fireEvent.click(getByLabelText('Turn decoration off'));
+    expect(onToggleActive).toHaveBeenCalledWith(false);
+  });
+
+  test('selecting a trail hands the ref back to the host', () => {
+    const onSelectTrail = mock(() => {});
+    const { getByText } = renderPanel({ onSelectTrail });
+    fireEvent.click(getByText('Save drawing'));
+    expect(onSelectTrail).toHaveBeenCalledWith({
+      kind: 'base',
+      modelId: 'sg-desktop',
+      trailId: 'tl-save',
+    });
+  });
+
+  test('selecting a draft component hands the component back', () => {
+    const onSelectDraftComponent = mock(() => {});
+    const { getByText } = renderPanel({ onSelectDraftComponent });
+    fireEvent.click(getByText('SyncAgent'));
+    expect(onSelectDraftComponent).toHaveBeenCalledWith({
+      alias: 'sync-agent',
+      name: 'SyncAgent',
+      construct: 'class',
+    });
+  });
+});