@principal-ai/subsystems-react 0.56.0 → 0.56.1

package/src/subsystem/DecorationPanel.test.tsx

@@ -1,128 +0,0 @@
-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',
-    });
-  });
-});

package/src/subsystem/DecorationPanel.tsx

@@ -1,334 +0,0 @@
-/**
- * DecorationPanel — the reading surface for one `SubsystemDecoration`.
- *
- * A decoration is an additive, unverified layer over one or more subsystem
- * models: markdown prose, an ordered list of trails (each naming its own
- * model), and optional draft structure. This panel is the container's own
- * surface — it deliberately does not render the graph. Selecting a trail (or
- * a draft component) is handed back to the host, which decides whether to
- * focus a model, open a tab, or overlay the draft.
- *
- * Nothing here writes: the first prototype is read-only plus an on/off toggle.
- */
-
-import type { CSSProperties } from 'react';
-import { useTheme } from '@principal-ade/industry-theme';
-import { Box, Eye, EyeOff, Network, Route, Sparkles } from 'lucide-react';
-import { IndustryMarkdownSlide } from 'themed-markdown';
-import {
-  decorationTrailId,
-  groupDecorationTrailsByModel,
-  type DecorationDraftComponent,
-  type DecorationTrailRef,
-  type SubsystemDecoration,
-} from './decoration';
-
-export interface DecorationPanelTrailMeta {
-  title: string;
-  stepCount?: number;
-}
-
-export interface DecorationPanelProps {
-  decoration: SubsystemDecoration;
-  /** Whether the decoration overlay is currently on. */
-  active: boolean;
-  onToggleActive: (active: boolean) => void;
-  /** Click a trail row. The host focuses the owning model/trail. */
-  onSelectTrail?: (ref: DecorationTrailRef) => void;
-  /** Click a draft component. Omit to render the draft list read-only. */
-  onSelectDraftComponent?: (component: DecorationDraftComponent) => void;
-  /**
-   * Resolve a base trail's display title/step count from its owning model.
-   * Draft trails carry their content inline and need no resolver.
-   */
-  resolveTrail?: (ref: DecorationTrailRef) => DecorationPanelTrailMeta | undefined;
-  /** Friendly model names, keyed by `modelId`. Falls back to the id. */
-  modelLabels?: ReadonlyMap<string, string>;
-}
-
-export function DecorationPanel({
-  decoration,
-  active,
-  onToggleActive,
-  onSelectTrail,
-  onSelectDraftComponent,
-  resolveTrail,
-  modelLabels,
-}: DecorationPanelProps) {
-  const { theme } = useTheme();
-  const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
-  const secondary = theme.colors.textSecondary ?? muted;
-  const warning = theme.colors.warning ?? secondary;
-  const accent = theme.colors.accent ?? theme.colors.primary ?? theme.colors.text;
-  const groups = groupDecorationTrailsByModel(decoration.trails);
-  const draftComponents = decoration.draft?.components ?? [];
-  const draftEdges = decoration.draft?.edges ?? [];
-  const sectionLabel: CSSProperties = {
-    fontFamily: theme.fonts.monospace,
-    fontSize: theme.fontSizes[0],
-    fontWeight: theme.fontWeights.semibold,
-    letterSpacing: '0.06em',
-    textTransform: 'uppercase',
-  };
-
-  return (
-    <div
-      style={{
-        display: 'flex',
-        flexDirection: 'column',
-        width: '100%',
-        height: '100%',
-        minHeight: 0,
-        background: theme.colors.background,
-        color: theme.colors.text,
-      }}
-    >
-      <header
-        style={{
-          flexShrink: 0,
-          padding: '14px 16px 10px',
-          borderBottom: `1px solid ${theme.colors.border}`,
-        }}
-      >
-        <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
-          <Sparkles size={15} strokeWidth={2} color={accent} aria-hidden />
-          <h2
-            style={{
-              flex: 1,
-              minWidth: 0,
-              margin: 0,
-              overflowWrap: 'anywhere',
-              fontFamily: theme.fonts.monospace,
-              fontSize: theme.fontSizes[2],
-              fontWeight: theme.fontWeights.semibold,
-            }}
-          >
-            {decoration.title}
-          </h2>
-          <button
-            type="button"
-            aria-pressed={active}
-            aria-label={active ? 'Turn decoration off' : 'Turn decoration on'}
-            title={active ? 'Turn decoration off' : 'Turn decoration on'}
-            onClick={() => onToggleActive(!active)}
-            style={{
-              display: 'inline-flex',
-              alignItems: 'center',
-              gap: 4,
-              flexShrink: 0,
-              padding: '3px 8px',
-              borderRadius: 4,
-              border: `1px solid ${active ? accent : theme.colors.border}`,
-              background: active ? `${accent}18` : 'transparent',
-              color: active ? accent : muted,
-              fontFamily: theme.fonts.monospace,
-              fontSize: theme.fontSizes[0],
-              cursor: 'pointer',
-            }}
-          >
-            {active ? <Eye size={12} strokeWidth={2} /> : <EyeOff size={12} strokeWidth={2} />}
-            {active ? 'On' : 'Off'}
-          </button>
-        </div>
-      </header>
-
-      <div style={{ flex: 1, minHeight: 0, overflowY: 'auto', padding: '12px 16px 18px' }}>
-        {decoration.description && (
-          <div style={{ fontSize: theme.fontSizes[1], lineHeight: theme.lineHeights.body }}>
-            <IndustryMarkdownSlide
-              content={decoration.description}
-              slideIdPrefix={`decoration-${decoration.id}`}
-              slideIndex={0}
-              isVisible={true}
-              theme={theme}
-              disableScroll={true}
-              disableBasePadding
-              enableKeyboardScrolling={false}
-              autoFocusOnVisible={false}
-            />
-          </div>
-        )}
-
-        <section
-          style={{
-            marginTop: 16,
-            paddingTop: 14,
-            borderTop: `1px solid ${theme.colors.border}`,
-          }}
-        >
-          <div style={{ ...sectionLabel, color: secondary }}>
-            Trails · {decoration.trails.length}
-          </div>
-          {groups.map((group) => (
-            <div key={group.modelId}>
-              <div
-                style={{
-                  display: 'flex',
-                  alignItems: 'center',
-                  gap: 6,
-                  margin: '12px 0 3px',
-                }}
-              >
-                <Network size={14} strokeWidth={2} color={secondary} aria-hidden />
-                <span
-                  style={{
-                    minWidth: 0,
-                    overflow: 'hidden',
-                    textOverflow: 'ellipsis',
-                    whiteSpace: 'nowrap',
-                    fontFamily: theme.fonts.monospace,
-                    fontSize: theme.fontSizes[1],
-                    fontWeight: theme.fontWeights.semibold,
-                    color: theme.colors.text,
-                  }}
-                >
-                  {modelLabels?.get(group.modelId) ?? group.modelId}
-                </span>
-              </div>
-              {group.trails.map((ref) => {
-                const meta = resolveTrail?.(ref);
-                const title =
-                  meta?.title ??
-                  (ref.kind === 'draft' ? ref.trail.title : ref.trailId);
-                const stepCount =
-                  meta?.stepCount ??
-                  (ref.kind === 'draft' ? ref.trail.steps.length : undefined);
-                return (
-                  <button
-                    key={decorationTrailId(ref)}
-                    type="button"
-                    onClick={() => onSelectTrail?.(ref)}
-                    style={{
-                      display: 'flex',
-                      alignItems: 'center',
-                      gap: 8,
-                      width: '100%',
-                      minWidth: 0,
-                      padding: '6px 6px 6px 0',
-                      border: 'none',
-                      borderRadius: 4,
-                      background: 'transparent',
-                      color: theme.colors.text,
-                      textAlign: 'left',
-                      cursor: onSelectTrail ? 'pointer' : 'default',
-                    }}
-                  >
-                    <Route size={13} strokeWidth={2} color={muted} aria-hidden />
-                    <span
-                      style={{
-                        flex: 1,
-                        minWidth: 0,
-                        overflow: 'hidden',
-                        textOverflow: 'ellipsis',
-                        whiteSpace: 'nowrap',
-                        fontFamily: theme.fonts.monospace,
-                        fontSize: theme.fontSizes[1],
-                      }}
-                    >
-                      {title}
-                    </span>
-                    {ref.kind === 'draft' && (
-                      <span
-                        style={{
-                          flexShrink: 0,
-                          padding: '1px 5px',
-                          borderRadius: 3,
-                          border: `1px solid ${warning}`,
-                          color: warning,
-                          fontFamily: theme.fonts.monospace,
-                          fontSize: theme.fontSizes[0],
-                        }}
-                      >
-                        draft
-                      </span>
-                    )}
-                    {stepCount != null && (
-                      <span
-                        style={{
-                          flexShrink: 0,
-                          fontFamily: theme.fonts.monospace,
-                          fontSize: theme.fontSizes[0],
-                          color: secondary,
-                        }}
-                      >
-                        {stepCount}
-                      </span>
-                    )}
-                  </button>
-                );
-              })}
-            </div>
-          ))}
-        </section>
-
-        {(draftComponents.length > 0 || draftEdges.length > 0) && (
-          <section style={{ marginTop: 18 }}>
-            <div style={{ ...sectionLabel, color: secondary }}>
-              Draft structure · not verified
-            </div>
-            {draftComponents.map((component) => (
-              <button
-                key={component.alias}
-                type="button"
-                onClick={() => onSelectDraftComponent?.(component)}
-                style={{
-                  display: 'flex',
-                  alignItems: 'center',
-                  gap: 8,
-                  width: '100%',
-                  minWidth: 0,
-                  padding: '6px 6px 6px 0',
-                  border: 'none',
-                  borderRadius: 4,
-                  background: 'transparent',
-                  color: theme.colors.text,
-                  textAlign: 'left',
-                  cursor: onSelectDraftComponent ? 'pointer' : 'default',
-                }}
-              >
-                <Box size={13} strokeWidth={2} color={muted} aria-hidden />
-                <span
-                  style={{
-                    flex: 1,
-                    minWidth: 0,
-                    overflow: 'hidden',
-                    textOverflow: 'ellipsis',
-                    whiteSpace: 'nowrap',
-                    fontFamily: theme.fonts.monospace,
-                    fontSize: theme.fontSizes[1],
-                  }}
-                >
-                  {component.name}
-                </span>
-                {component.construct && (
-                  <span
-                    style={{
-                      flexShrink: 0,
-                      fontFamily: theme.fonts.monospace,
-                      fontSize: theme.fontSizes[0],
-                      color: secondary,
-                    }}
-                  >
-                    {component.construct}
-                  </span>
-                )}
-              </button>
-            ))}
-            {draftEdges.length > 0 && (
-              <div
-                style={{
-                  marginTop: 4,
-                  fontFamily: theme.fonts.monospace,
-                  fontSize: theme.fontSizes[0],
-                  color: secondary,
-                }}
-              >
-                + {draftEdges.length} draft edge{draftEdges.length === 1 ? '' : 's'}
-              </div>
-            )}
-          </section>
-        )}
-      </div>
-    </div>
-  );
-}

package/src/subsystem/decoration.test.ts

@@ -1,72 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-import type { SubsystemTrail } from './model';
-import {
-  decorationModelIds,
-  decorationTrailId,
-  decorationTrailKey,
-  findDecorationTrail,
-  groupDecorationTrailsByModel,
-  type DecorationTrailRef,
-} from './decoration';
-
-function ref(modelId: string, trailId: string): DecorationTrailRef {
-  return { kind: 'base', modelId, trailId };
-}
-
-const draftTrail: SubsystemTrail = {
-  id: 'planned-open',
-  title: 'Planned open',
-  steps: [],
-};
-
-describe('decoration trail refs', () => {
-  test('keys are scoped by model', () => {
-    expect(decorationTrailKey(ref('model-a', 'open'))).toBe('model-a:open');
-    expect(decorationTrailKey(ref('model-a', 'open'))).not.toBe(
-      decorationTrailKey(ref('model-b', 'open')),
-    );
-  });
-
-  test('a draft trail keys like a base trail', () => {
-    const draft: DecorationTrailRef = {
-      kind: 'draft',
-      modelId: 'model-a',
-      trail: draftTrail,
-    };
-    expect(decorationTrailKey(draft)).toBe('model-a:planned-open');
-    expect(decorationTrailId(draft)).toBe('planned-open');
-  });
-
-  test('groups trails by their own model, preserving authored order', () => {
-    const groups = groupDecorationTrailsByModel([
-      ref('web', 'open'),
-      ref('server', 'handle'),
-      ref('web', 'save'),
-      ref('worker', 'consume'),
-    ]);
-    expect(groups.map((g) => g.modelId)).toEqual(['web', 'server', 'worker']);
-    expect(groups[0]!.trails.map((t) => decorationTrailId(t))).toEqual([
-      'open',
-      'save',
-    ]);
-    expect(groups[1]!.trails.map((t) => decorationTrailId(t))).toEqual([
-      'handle',
-    ]);
-  });
-
-  test('lists distinct models in first-seen order', () => {
-    expect(
-      decorationModelIds([
-        ref('web', 'open'),
-        ref('server', 'handle'),
-        ref('web', 'save'),
-      ]),
-    ).toEqual(['web', 'server']);
-  });
-
-  test('finds a trail by model and trail id, not trail id alone', () => {
-    const refs = [ref('web', 'open'), ref('server', 'open')];
-    expect(findDecorationTrail(refs, 'server', 'open')?.modelId).toBe('server');
-    expect(findDecorationTrail(refs, 'worker', 'open')).toBeUndefined();
-  });
-});

package/src/subsystem/decoration.ts

@@ -1,151 +0,0 @@
-/**
- * Subsystem decoration — PROTOTYPE contract for the ephemeral, unverified layer.
- *
- * A decoration composes trails from one or more models, carries a markdown
- * description, and may add draft structure. The base model stays verified-only;
- * a decoration is never audited against source.
- *
- * **Each trail ref names its own model.** There is no decoration-level `base`
- * field: a decoration can mix models by construction, and a single-model
- * decoration is just the case where every ref happens to share a `modelId`.
- *
- * A trail can be either:
- * - `base` — a reference to a trail that already exists in a model; or
- * - `draft` — a trail that only exists in the decoration. This is what
- *   migration needs when a base trail depends on draft components: the whole
- *   trail moves into the decoration rather than dangling in the base.
- *
- * The contract is deliberately host-local and not part of the portable
- * subsystem document. If decorations become shareable, `modelId` needs a
- * portable identity key (the local `sg-...` ids are re-minted).
- */
-
-import type { SubsystemTrail, SubsystemTrailMechanism } from './model';
-
-export interface DecorationStepAnchor {
-  /** Claim fingerprint of the anchored step (see `stepClaimKey`). */
-  stepKey: string;
-  /** Optional per-anchor note. The decoration description carries the prose. */
-  note?: string;
-}
-
-interface DecorationTrailRefBase {
-  /** Store-local model id. The trail id is only unique within this model. */
-  modelId: string;
-  /** Optional step-level anchors inside this trail. */
-  stepAnchors?: DecorationStepAnchor[];
-}
-
-/** A trail that already exists in the base model. */
-export interface DecorationBaseTrailRef extends DecorationTrailRefBase {
-  kind: 'base';
-  trailId: string;
-}
-
-/** A speculative trail that exists only in the decoration. */
-export interface DecorationDraftTrailRef extends DecorationTrailRefBase {
-  kind: 'draft';
-  trail: SubsystemTrail;
-}
-
-export type DecorationTrailRef =
-  | DecorationBaseTrailRef
-  | DecorationDraftTrailRef;
-
-/**
- * Draft structure: a component that does not exist in source yet. No
- * `file`/`symbol` — those are the verification coordinates the base model
- * requires, and a draft component deliberately has none.
- */
-export interface DecorationDraftComponent {
-  alias: string;
-  name: string;
-  /** Intended construct shape (`class`, `function`, …). */
-  construct?: string;
-  purpose?: string;
-  module?: string;
-  process?: string;
-}
-
-/** A speculative edge between base or draft aliases. */
-export interface DecorationDraftEdge {
-  from: string;
-  to: string;
-  mechanism: SubsystemTrailMechanism;
-}
-
-export interface DecorationDraft {
-  components?: DecorationDraftComponent[];
-  edges?: DecorationDraftEdge[];
-}
-
-export interface DecorationProvenance {
-  source: 'author' | 'agent';
-  author?: string;
-  /** ISO timestamp. */
-  at: string;
-}
-
-export interface SubsystemDecoration {
-  version: 1;
-  id: string;
-  title: string;
-  /** Markdown, rendered like the model description. */
-  description: string;
-  /**
-   * Ordered trails the decoration cares about. Order is the reading order;
-   * `modelId` may vary from ref to ref. A trail is either a base ref or a
-   * draft trail that lives only here.
-   */
-  trails: DecorationTrailRef[];
-  /** Optional draft delta. Absent = a pure reading path. */
-  draft?: DecorationDraft;
-  provenance: DecorationProvenance;
-}
-
-/** The trail id for either kind of ref. */
-export function decorationTrailId(ref: DecorationTrailRef): string {
-  return ref.kind === 'base' ? ref.trailId : ref.trail.id;
-}
-
-/** Stable key for a trail ref across models. `trailId` alone is not enough. */
-export function decorationTrailKey(
-  ref: Pick<DecorationTrailRef, 'modelId'> & { trailId?: string; trail?: SubsystemTrail },
-): string {
-  const trailId = ref.trailId ?? ref.trail?.id ?? '';
-  return `${ref.modelId}:${trailId}`;
-}
-
-/**
- * Group trail refs by their owning model, preserving first-seen model order
- * and the authored trail order within each group. The UI uses this to render
- * "which trails it cares about" without a separate model list.
- */
-export function groupDecorationTrailsByModel(
-  refs: readonly DecorationTrailRef[],
-): Array<{ modelId: string; trails: DecorationTrailRef[] }> {
-  const groups = new Map<string, DecorationTrailRef[]>();
-  for (const ref of refs) {
-    const existing = groups.get(ref.modelId);
-    if (existing) existing.push(ref);
-    else groups.set(ref.modelId, [ref]);
-  }
-  return [...groups].map(([modelId, trails]) => ({ modelId, trails }));
-}
-
-/** The distinct models a decoration touches, in first-seen order. */
-export function decorationModelIds(
-  refs: readonly DecorationTrailRef[],
-): string[] {
-  return [...new Set(refs.map((ref) => ref.modelId))];
-}
-
-export function findDecorationTrail(
-  refs: readonly DecorationTrailRef[],
-  modelId: string,
-  trailId: string,
-): DecorationTrailRef | undefined {
-  return refs.find(
-    (ref) => ref.modelId === modelId && decorationTrailId(ref) === trailId,
-  );
-}