@principal-ai/subsystems-react 0.56.0 → 0.56.2

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

@@ -1,528 +0,0 @@
-import React, { useCallback, useMemo, 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 { Star } from 'lucide-react';
-import { SubsystemComponentGraph } from '../../../subsystem/SubsystemComponentGraph';
-import type { SubsystemComponent, SubsystemTrail } from '../../../subsystem/model';
-import {
-  buildStepEmphasisMap,
-  orphanedEmphasis,
-  stepClaimKey,
-  type StepEmphasisDocument,
-  type StepEmphasisRecord,
-} from '../../../subsystem/stepEmphasis';
-
-/**
- * PROTOTYPE: step emphasis as a separate augmentation document.
- *
- * The point of the story is to make the *data model* concrete before the store
- * lands. The marks below live in story state, keyed by trail + claim
- * fingerprint — not on the portable `SubsystemTrail`. Reorder the steps or edit
- * a claim and watch what the keys do.
- */
-const meta = {
-  title: 'Canvases/Subsystem/Step emphasis',
-  component: SubsystemComponentGraph,
-  parameters: {
-    layout: 'fullscreen',
-    docs: {
-      description: {
-        component:
-          'Prototype for the focus-guidance augmentation: star a walkthrough step with a kind + optional note, stored separately from the model document.',
-      },
-    },
-  },
-  decorators: [
-    (Story) => (
-      <ThemeProvider theme={defaultEditorTheme}>
-        <Story />
-      </ThemeProvider>
-    ),
-  ],
-} satisfies Meta<typeof SubsystemComponentGraph>;
-
-export default meta;
-type Story = StoryObj<typeof meta>;
-
-const STORY_PURL = 'pkg:github/principal-ai/desktop-app';
-const stepPurl = (file: string) => `${STORY_PURL}#${file}`;
-
-const components: SubsystemComponent[] = [
-  {
-    alias: 'panel',
-    name: 'DrawingsLeftPanel',
-    construct: 'class',
-    file: 'src/panels/DrawingsLeftPanel.tsx',
-    purl: STORY_PURL,
-    purpose: 'lists drawings; emits open/delete intents',
-    symbol: 'DrawingsLeftPanel',
-    process: 'draw-list',
-  },
-  {
-    alias: 'host',
-    name: 'useDrawingsHost',
-    construct: 'function',
-    file: 'src/hooks/useDrawingsHost.ts',
-    purl: STORY_PURL,
-    purpose: 'hosts drawing CRUD; dispatches to storage and shell',
-    symbol: 'useDrawingsHost',
-    process: 'draw-host',
-  },
-  {
-    alias: 'storage',
-    name: 'DrawingsStorage',
-    construct: 'class',
-    file: 'src/storage/drawingsStorage.ts',
-    purl: STORY_PURL,
-    purpose: 'persists drawings as files',
-    symbol: 'DrawingsStorage',
-    process: 'draw-host',
-  },
-  {
-    alias: 'fs',
-    name: 'FileSystemService',
-    construct: 'external',
-    file: 'src/services/fileSystem.ts',
-    purl: STORY_PURL,
-    purpose: 'sandboxed host fd/fs access',
-    symbol: 'FileSystemService',
-    role: 'service',
-  },
-  {
-    alias: 'shell',
-    name: 'WorkspaceShell',
-    construct: 'class',
-    file: 'src/workspace/WorkspaceShell.tsx',
-    purl: STORY_PURL,
-    purpose: 'mounts tabs for opened drawings',
-    symbol: 'WorkspaceShell',
-    process: 'draw-host',
-  },
-  {
-    alias: 'tab',
-    name: 'DrawingTabContent',
-    construct: 'class',
-    file: 'src/components/DrawingTabContent.tsx',
-    purl: STORY_PURL,
-    purpose: 'loads/saves an open drawing',
-    symbol: 'DrawingTabContent',
-    process: 'draw-host',
-  },
-];
-
-const seedTrails: SubsystemTrail[] = [
-  {
-    id: 'tl-open-drawing',
-    title: 'Open drawing',
-    steps: [
-      {
-        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',
-        annotation: 'Lists the drawings directory; each row feeds an open intent.',
-      },
-      {
-        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',
-        annotation: 'Host resolves the path and delegates to storage.',
-      },
-      {
-        from: 'host',
-        to: 'shell',
-        mechanism: 'produces',
-        file: 'src/workspace/WorkspaceShell.tsx',
-        span: { startLine: 369, endLine: 369, contentHash: 'fixture' },
-        purl: stepPurl('src/workspace/WorkspaceShell.tsx'),
-        symbol: 'WorkspaceShell.openTab',
-        annotation: 'Asks the shell to surface the drawing as a tab.',
-      },
-      {
-        from: 'shell',
-        to: 'tab',
-        mechanism: 'feeds',
-        file: 'src/workspace/WorkspaceShell.tsx',
-        span: { startLine: 372, endLine: 372, contentHash: 'fixture' },
-        purl: stepPurl('src/workspace/WorkspaceShell.tsx'),
-        symbol: 'WorkspaceShell.mountTab',
-      },
-      {
-        from: 'storage',
-        to: 'fs',
-        mechanism: 'calls',
-        file: 'src/storage/drawingsStorage.ts',
-        span: { startLine: 90, endLine: 90, contentHash: 'fixture' },
-        purl: stepPurl('src/storage/drawingsStorage.ts'),
-        symbol: 'DrawingsStorage.read',
-        annotation: 'Reads the file through the sandboxed fs service.',
-      },
-      {
-        from: 'tab',
-        to: 'fs',
-        mechanism: 'calls',
-        file: 'src/components/DrawingTabContent.tsx',
-        span: { startLine: 83, endLine: 83, contentHash: 'fixture' },
-        purl: stepPurl('src/components/DrawingTabContent.tsx'),
-        symbol: 'DrawingTabContent.load',
-      },
-    ],
-  },
-  {
-    id: 'tl-save-drawing',
-    title: 'Save drawing',
-    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: 'tab',
-        to: 'host',
-        mechanism: 'produces',
-        file: 'src/components/DrawingTabContent.tsx',
-        span: { startLine: 121, endLine: 121, contentHash: 'fixture' },
-        purl: stepPurl('src/components/DrawingTabContent.tsx'),
-        symbol: 'DrawingTabContent.emitSaved',
-      },
-      {
-        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',
-      },
-      {
-        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',
-      },
-    ],
-  },
-];
-
-const SEEDED_AT = '2026-10-19T12:00:00.000Z';
-
-function seedEmphasis(trails: SubsystemTrail[]): StepEmphasisRecord[] {
-  const trail = trails[0]!;
-  const at = (stepIndex: number, guidance: string): StepEmphasisRecord => ({
-    trailId: trail.id,
-    stepKey: stepClaimKey(trail.steps[stepIndex]!),
-    guidance,
-    provenance: { source: 'author', at: SEEDED_AT, author: 'you' },
-  });
-  return [
-    at(
-      0,
-      'The **scan** is where a drawing row becomes an open intent. Everything below depends on this hand-off.',
-    ),
-    at(
-      3,
-      'The shell is the **hinge**: the tab only exists after this call, so this is where the flow becomes visible.',
-    ),
-    at(
-      5,
-      '**Risky seam.** First filesystem touch — a sandbox denial lands here rather than in storage.',
-    ),
-  ];
-}
-
-const muted = '#9aa4b2';
-const border = '#2a2f3a';
-const panelBg = '#0f1115';
-
-function InspectorRow({
-  label,
-  value,
-  color,
-}: {
-  label: string;
-  value: string;
-  color?: string;
-}) {
-  return (
-    <div style={{ display: 'flex', gap: 8, fontSize: 11, lineHeight: 1.5 }}>
-      <span style={{ color: muted, minWidth: 74 }}>{label}</span>
-      <span style={{ color: color ?? '#e6edf3', overflowWrap: 'anywhere' }}>{value}</span>
-    </div>
-  );
-}
-
-function Prototype() {
-  const [trails, setTrails] = useState<SubsystemTrail[]>(seedTrails);
-  const [records, setRecords] = useState<StepEmphasisRecord[]>(() =>
-    seedEmphasis(seedTrails),
-  );
-  const emphasis = useMemo(() => buildStepEmphasisMap(records), [records]);
-  const orphans = useMemo(() => orphanedEmphasis(records, trails), [records, trails]);
-
-  const removeGuidance = useCallback(
-    (trail: SubsystemTrail, stepIndex: number) => {
-      const step = trail.steps[stepIndex];
-      if (!step) return;
-      const stepKey = stepClaimKey(step);
-      setRecords((prev) =>
-        prev.filter((r) => !(r.trailId === trail.id && r.stepKey === stepKey)),
-      );
-    },
-    [],
-  );
-
-  const swapFirstSteps = useCallback(() => {
-    setTrails((prev) =>
-      prev.map((trail, trailIndex) =>
-        trailIndex === 0 && trail.steps.length > 2
-          ? {
-              ...trail,
-              steps: [trail.steps[1]!, trail.steps[0]!, ...trail.steps.slice(2)],
-            }
-          : trail,
-      ),
-    );
-  }, []);
-
-  const editStepClaim = useCallback(() => {
-    setTrails((prev) =>
-      prev.map((trail, trailIndex) =>
-        trailIndex === 0
-          ? {
-              ...trail,
-              steps: trail.steps.map((step, stepIndex) =>
-                stepIndex === 1
-                  ? {
-                      ...step,
-                      span: step.span
-                        ? { ...step.span, startLine: step.span.startLine + 1, contentHash: 'edited' }
-                        : { startLine: 1, endLine: 1, contentHash: 'edited' },
-                    }
-                  : step,
-              ),
-            }
-          : trail,
-      ),
-    );
-  }, []);
-
-  const addAgentMark = useCallback(() => {
-    const trail = trails[1];
-    const step = trail?.steps[3];
-    if (!trail || !step) return;
-    const stepKey = stepClaimKey(step);
-    setRecords((prev) =>
-      prev.some((r) => r.trailId === trail.id && r.stepKey === stepKey)
-        ? prev
-        : [
-            ...prev,
-            {
-              trailId: trail.id,
-              stepKey,
-              guidance:
-                'Marked by **opencode** while tracing the save path. The panel scan runs again after the write to refresh the list.',
-              provenance: {
-                source: 'agent',
-                at: new Date().toISOString(),
-                author: 'opencode',
-              },
-            },
-          ],
-    );
-  }, [trails]);
-
-  const pruneOrphans = useCallback(() => {
-    setRecords((prev) => {
-      const dead = new Set(orphans.map((r) => `${r.trailId}:${r.stepKey}`));
-      return prev.filter((r) => !dead.has(`${r.trailId}:${r.stepKey}`));
-    });
-  }, [orphans]);
-
-  const documentModel: StepEmphasisDocument = {
-    version: 1,
-    modelId: 'sg-prototype',
-    emphasis: records,
-  };
-
-  const button = (label: string, onClick: () => void, disabled = false) => (
-    <button
-      type="button"
-      onClick={onClick}
-      disabled={disabled}
-      style={{
-        padding: '5px 9px',
-        borderRadius: 5,
-        border: `1px solid ${border}`,
-        background: '#171a21',
-        color: disabled ? '#5b636e' : '#e6edf3',
-        fontFamily: 'ui-monospace, SFMono-Regular, Menlo, monospace',
-        fontSize: 11,
-        cursor: disabled ? 'default' : 'pointer',
-      }}
-    >
-      {label}
-    </button>
-  );
-
-  return (
-    <div style={{ display: 'flex', height: '100vh', background: panelBg }}>
-      <div style={{ flex: 1, minWidth: 0, position: 'relative' }}>
-        <SubsystemComponentGraph
-          components={components}
-          trails={trails}
-          initialTrailId="tl-open-drawing"
-          persistKey="step-emphasis-prototype"
-          stepEmphasis={emphasis}
-          onRemoveStepEmphasis={removeGuidance}
-          title="Step emphasis prototype"
-          description="Key steps carry a star and markdown guidance. The mark lives in a separate augmentation document, keyed by the step's claim."
-        />
-      </div>
-
-      <aside
-        style={{
-          width: 380,
-          flexShrink: 0,
-          display: 'flex',
-          flexDirection: 'column',
-          borderLeft: `1px solid ${border}`,
-          background: '#0b0d11',
-          overflow: 'hidden',
-        }}
-      >
-        <header style={{ padding: '14px 16px 10px', borderBottom: `1px solid ${border}` }}>
-          <div
-            style={{
-              display: 'flex',
-              alignItems: 'center',
-              gap: 6,
-              fontFamily: 'ui-monospace, SFMono-Regular, Menlo, monospace',
-              fontSize: 12,
-              color: '#e6edf3',
-            }}
-          >
-            <Star size={13} fill="#f5a524" color="#f5a524" />
-            Step emphasis · prototype
-          </div>
-          <p style={{ margin: '6px 0 0', fontSize: 11, lineHeight: 1.5, color: muted }}>
-            A separate augmentation document, not the portable model. Marks key on the
-            step&apos;s <em>claim</em>, so reorder keeps them and a claim edit orphans them.
-          </p>
-        </header>
-
-        <div style={{ display: 'flex', flexWrap: 'wrap', gap: 6, padding: '10px 16px' }}>
-          {button('Reorder steps', swapFirstSteps)}
-          {button('Edit step 2 claim', editStepClaim)}
-          {button('Add agent mark', addAgentMark)}
-          {button(
-            `Prune ${orphans.length} orphan${orphans.length === 1 ? '' : 's'}`,
-            pruneOrphans,
-            orphans.length === 0,
-          )}
-        </div>
-
-        <div style={{ padding: '0 16px 10px', display: 'grid', gap: 3 }}>
-          <InspectorRow label="store" value="~/.principal/subsystem-model-augmentations/" />
-          <InspectorRow label="modelId" value={documentModel.modelId} />
-          <InspectorRow
-            label="marks"
-            value={`${records.length} total · ${orphans.length} orphaned`}
-            color={orphans.length > 0 ? '#e5534b' : undefined}
-          />
-        </div>
-
-        <div
-          style={{
-            display: 'flex',
-            alignItems: 'center',
-            gap: 6,
-            padding: '0 16px 10px',
-            fontSize: 10,
-            color: muted,
-          }}
-        >
-          <Star size={10} fill="#f5a524" color="#f5a524" />
-          A mark is a single star plus markdown guidance.
-        </div>
-
-        {orphans.length > 0 && (
-          <div style={{ padding: '0 16px 10px', display: 'grid', gap: 4 }}>
-            <span style={{ fontSize: 10, letterSpacing: '0.08em', color: '#e5534b' }}>
-              ORPHANED — the claim changed
-            </span>
-            {orphans.map((r) => (
-              <div
-                key={`${r.trailId}:${r.stepKey}`}
-                style={{ fontSize: 11, color: muted, fontFamily: 'ui-monospace, SFMono-Regular, Menlo, monospace' }}
-              >
-                <span style={{ color: '#f5a524' }}>Key</span> {r.trailId} · {r.stepKey}
-              </div>
-            ))}
-          </div>
-        )}
-
-        <div
-          style={{
-            flex: 1,
-            minHeight: 0,
-            overflow: 'auto',
-            borderTop: `1px solid ${border}`,
-            padding: '10px 16px 16px',
-          }}
-        >
-          <div
-            style={{
-              fontSize: 10,
-              letterSpacing: '0.08em',
-              color: muted,
-              marginBottom: 6,
-            }}
-          >
-            AUGMENTATION DOCUMENT
-          </div>
-          <pre
-            style={{
-              margin: 0,
-              fontSize: 10,
-              lineHeight: 1.45,
-              color: '#c9d1d9',
-              whiteSpace: 'pre-wrap',
-            }}
-          >
-            {JSON.stringify(documentModel, null, 2)}
-          </pre>
-        </div>
-      </aside>
-    </div>
-  );
-}
-
-export const Interactive: Story = {
-  render: () => <Prototype />,
-};

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

@@ -1,160 +0,0 @@
-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 />,
-};