@principal-ai/subsystems-react 0.55.3 → 0.56.0

package/src/subsystem/decoration.test.ts

@@ -0,0 +1,72 @@
+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

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

package/src/subsystem/model.test.ts

@@ -98,7 +98,7 @@ describe('subsystem graph model', () => {
     const withExternal: SubsystemComponent[] = [
       ...comps,
       {
-        alias: "proposed-watcher",
+        alias: "external-watcher",
         name: "watchDir",
         construct: "external",
         // Intentionally omit file/purl — agents often leave these off for externals.
@@ -111,10 +111,10 @@ describe('subsystem graph model', () => {
       trails: [{
         id: 'w1',
         title: 'feed',
-        steps: [{ from: 'reader', to: 'proposed-watcher', mechanism: 'feeds', file: 'x.ts' }],
+        steps: [{ from: 'reader', to: 'external-watcher', mechanism: 'feeds', file: 'x.ts' }],
       }],
     });
-    expect(nodes.find((n) => n.id === 'proposed-watcher')).toBeDefined();
+    expect(nodes.find((n) => n.id === 'external-watcher')).toBeDefined();
   });
 
   test('buildSubsystemGraph creates external stub nodes for non-component targets', async () => {
@@ -223,33 +223,18 @@ describe('subsystem graph model', () => {
     });
     expect(withRole).toBeGreaterThan(stereotype);
 
-    const withProposed = nodeMinWidthForBadges({
-      construct: 'function',
-      proposed: true,
-    });
-    expect(withProposed).toBeGreaterThan(plain);
-
-    const withBoth = nodeMinWidthForBadges({
-      construct: 'function',
-      role: 'entry',
-      proposed: true,
-    });
-    // proposed-only label is shorter than entry · proposed; still wider than plain
-    expect(withBoth).toBe(withProposed);
-
     // The pair floor must leave a real gap between the left and right badge,
     // over and above both insets — regression: the node border was omitted from
     // the floor, and the char width was underestimated, so the two badges met.
     const left = estimateBadgeLabelWidth(constructBadgeLabel({ construct: 'function' }));
-    const right = estimateBadgeLabelWidth(rightBadgeLabel({ proposed: true })!);
-    expect(withBoth).toBeGreaterThan(left + right + 2 * BADGE_EDGE_INSET);
+    const right = estimateBadgeLabelWidth(rightBadgeLabel({ role: 'entry' })!);
+    expect(withRole).toBeGreaterThan(left + right + 2 * BADGE_EDGE_INSET);
   });
 
-  test('rightBadgeLabel prefers proposed over role', () => {
+  test('rightBadgeLabel reports the role', () => {
     expect(rightBadgeLabel({})).toBeNull();
-    expect(rightBadgeLabel({ proposed: true })).toBe('proposed');
     expect(rightBadgeLabel({ role: 'entry' })).toBe('entry');
-    expect(rightBadgeLabel({ role: 'service', proposed: true })).toBe('proposed');
+    expect(rightBadgeLabel({ role: 'service' })).toBe('service');
   });
 
   test('deriveNameFromSymbol falls back to existing name when no symbol', () => {

package/src/subsystem/model.ts

@@ -101,6 +101,8 @@ export type {
   SubsystemModelDocument,
   SubsystemTrail,
   SubsystemTrailStep,
+  SubsystemSiteConstruct,
+  SubsystemTargetConstruct,
   SubsystemComponentRole,
   SubsystemFramework,
   SubsystemStereotype,
@@ -1156,7 +1158,7 @@ export type SubsystemIssueRung =
   | 'signature';
 
 /**
- * Per-node diagnostics badge — the proposed issue overlay (severity ring +
+ * Per-node diagnostics badge — the issue overlay (severity ring +
  * earliest-rung corner chip). The graph derives one per component from the
  * audit issues whose component target resolves to that node. Absent when the
  * node has no rung-mapped findings.
@@ -1226,12 +1228,6 @@ export interface SubsystemGraphEdgeData extends Record<string, unknown> {
   /** True while another edge is selected — render this edge (and its label)
    *  dimmed to focus the selected relationship. */
   dimmed?: boolean;
-  /**
-   * A backing trail step declares itself `proposed` — a planned seam between
-   * otherwise-real components. The SVG edge and its label draw dashed;
-   * distinct from a proposed ENDPOINT, which dashes the node instead.
-   */
-  proposedStep?: boolean;
   /** ELK-computed label midpoint (from the actual edge path, not node centers). */
   labelX?: number;
   labelY?: number;
@@ -1522,9 +1518,6 @@ export const ROLE_LABEL: Record<SubsystemComponentRole, string> = {
   service: 'service',
 };
 
-/** Right-badge accent for `proposed: true` (no role, or combined with role). */
-export const PROPOSED_COLOR = '#b8860b'; // darkgoldenrod — not-yet-in-source
-
 /**
  * Border accent for `deprecated: true` — the claim was real, its source is gone.
  * A desaturated slate rather than true silver: role badges already own silver
@@ -1545,25 +1538,19 @@ export function deprecatedBadgeColor(component: {
 }
 
 /**
- * Top-right badge label: proposed wins over role when both are set
- * (proposed is the temporary exception to scan for; role stays on the model).
- * Returns null when neither applies.
+ * Top-right badge label: the role, when set. Returns null otherwise.
  */
 export function rightBadgeLabel(component: {
   role?: SubsystemComponentRole;
-  proposed?: boolean;
 }): string | null {
-  if (component.proposed) return 'proposed';
   if (component.role != null) return ROLE_LABEL[component.role];
   return null;
 }
 
-/** Color for the top-right badge (role and/or proposed). */
+/** Color for the top-right role badge. */
 export function rightBadgeColor(component: {
   role?: SubsystemComponentRole;
-  proposed?: boolean;
 }): string | null {
-  if (component.proposed) return PROPOSED_COLOR;
   if (component.role != null) return ROLE_COLOR[component.role];
   return null;
 }
@@ -1593,7 +1580,7 @@ function storeStorage(component: {
 
 /** Top-right storage badge for `construct: 'store'` nodes with an authored
  *  `storage` declaration — how the retained state is backed. Sits beside the
- *  role/proposed badge (storage is orthogonal to topology). Null otherwise. */
+ *  role badge (storage is orthogonal to topology). Null otherwise. */
 export function storageBadgeLabel(component: {
   construct: SubsystemComponentConstruct;
   declaration?: AnyComponentDetail;
@@ -1688,7 +1675,6 @@ export function nodeMinWidthForBadges(component: {
   framework?: string;
   stereotype?: string;
   role?: SubsystemComponentRole;
-  proposed?: boolean;
   deprecated?: boolean;
   entityKind?: string;
   declaration?: AnyComponentDetail;

package/src/subsystem/nodes.tsx

@@ -20,7 +20,6 @@ import {
   edgeColor,
   edgeStrokeStyle,
   DEPRECATED_COLOR,
-  PROPOSED_COLOR,
   deprecatedBadgeColor,
   deprecatedBadgeLabel,
   constructBadgeColor,
@@ -221,7 +220,7 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
   // `symbol` is the source of truth; `name` is derived from it consistently.
   const displayName = deriveNameFromSymbol(c.symbol, c.construct, c.name, c.file, c.stereotype);
   // Top badges are absolutely positioned — widen the node so they nowrap
-  // instead of wrapping, including when construct + role/proposed share the top.
+  // instead of wrapping, including when construct + role share the top.
   const badgeMinWidth = nodeMinWidthForBadges(c);
   const topRightLabel = rightBadgeLabel(c);
   const topRightColor = rightBadgeColor(c);
@@ -243,17 +242,14 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
   const nodeBg = theme.colors.backgroundSecondary ?? theme.colors.background;
   const hoverBg =
     theme.colors.backgroundHover ?? theme.colors.backgroundTertiary ?? nodeBg;
-  // Border: proposed uses the goldenrod accent (dashed), deprecated the slate
-  // accent (dotted, same family as issue) since both mean "not a live claim";
-  // construct color stays on the left badge. File-open spotlight still wins
-  // with primary.
+  // Border: deprecated uses the slate accent (dotted, same family as issue)
+  // since it means "not a live claim"; construct color stays on the left
+  // badge. File-open spotlight still wins with primary.
   const borderColor = fileMatch
     ? theme.colors.primary
-    : c.proposed
-      ? PROPOSED_COLOR
-      : c.deprecated
-        ? DEPRECATED_COLOR
-        : color;
+    : c.deprecated
+      ? DEPRECATED_COLOR
+      : color;
   // Selection is stamped into data by the graph component — React Flow's own
   // `selected` never updates because the node stops click propagation.
   const isSelected = selected || (data.isSelected as boolean | undefined) === true;
@@ -269,21 +265,19 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
   const borderW = isSelected || fileMatch ? 4 : 2;
   const badgeTop = -9 - borderW;
   const badgeEdge = -borderW;
-  // A node with diagnostics turns its border dotted — a "something's off"
-  // sibling of `proposed`'s dashed, but distinct so the two don't read alike.
-  // The border keeps its construct color; the severity rides on the chip.
-  // Verification skips `proposed` nodes, so the two rarely stack — issue wins.
+  // A node with diagnostics turns its border dotted — an "something's off"
+  // signal. The border keeps its construct color; the severity rides on the
+  // chip. Deprecated is also dotted, but slate rather than construct-colored:
+  // "this claim was retired" is closer to a diagnostic than to a placeholder.
   const hasIssue = data.issue != null;
   // Deprecated is dotted like issue but slate rather than construct-colored:
   // "this claim was retired" is closer to a diagnostic than to a placeholder,
   // and verification skips deprecated nodes so the two never stack in practice.
   const borderStyle = hasIssue
     ? 'dotted'
-    : c.proposed
-      ? 'dashed'
-      : c.deprecated
-        ? 'dotted'
-        : 'solid';
+    : c.deprecated
+      ? 'dotted'
+      : 'solid';
 
   return (
     <div
@@ -352,9 +346,9 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
         {constructBadgeLabel(c)}
       </div>
 
-      {/* Secondary badge cluster — proposed wins over role when both are set;
-          store storage (retention backing) sits beside, since it is
-          orthogonal to topology. Persistent; pointer-events pass through.
+      {/* Secondary badge cluster — the role badge, with store storage
+          (retention backing) beside it since it is orthogonal to topology.
+          Persistent; pointer-events pass through.
           Sits astride the bottom edge, centered (mirroring the top construct
           badge's straddle), so the top edge stays free for the construct tag. */}
       {(topRightLabel != null || storageLabel != null || deprecatedLabel != null) && (
@@ -869,11 +863,8 @@ export function SubsystemEdge({
   const edgeRef = { mechanism, provenance: data?.provenance };
   const color = edgeColor(edgeRef);
   // Dash style encodes provenance (graphify) and relationship kind (dashed =
-  // inverted-control or observational: hierarchy, registration, watches). A
-  // step-proposed edge also dashes — the seam itself is planned — matching
-  // the dashed edge label and a proposed node's dashed border.
-  const isDashed =
-    edgeStrokeStyle(edgeRef) === 'dashed' || data?.proposedStep === true;
+  // inverted-control or observational: hierarchy, registration, watches).
+  const isDashed = edgeStrokeStyle(edgeRef) === 'dashed';
   const dimmed = data?.dimmed === true;
   // Dim the stroke by color, never via path `opacity`. SVG markers are shared
   // by id; opacity on the referencing path paints every arrowhead that uses

package/src/subsystem/stepEmphasis.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, test } from 'bun:test';
+import type { SubsystemTrail } from './model';
+import {
+  buildStepEmphasisMap,
+  emphasisForTrail,
+  emphasisKey,
+  findStepEmphasis,
+  orphanedEmphasis,
+  stepClaimKey,
+  type StepEmphasisRecord,
+} from './stepEmphasis';
+
+function step(overrides: Partial<SubsystemTrail['steps'][number]> = {}): SubsystemTrail['steps'][number] {
+  return {
+    from: 'ui',
+    to: 'api',
+    mechanism: 'calls',
+    file: 'src/ui/login.tsx',
+    span: { startLine: 42, endLine: 42, contentHash: 'abc' },
+    purl: 'pkg:github/acme/app#src/ui/login.tsx',
+    symbol: 'Login.submit',
+    ...overrides,
+  };
+}
+
+function trail(id: string, steps: SubsystemTrail['steps']): SubsystemTrail {
+  return { id, title: id, steps };
+}
+
+function record(trailId: string, stepKey: string): StepEmphasisRecord {
+  return {
+    trailId,
+    stepKey,
+    guidance: 'Why this step matters.',
+    provenance: { source: 'author', at: '2026-10-19T00:00:00.000Z' },
+  };
+}
+
+describe('stepClaimKey', () => {
+  test('is stable for the same claim', () => {
+    expect(stepClaimKey(step())).toBe(stepClaimKey(step()));
+  });
+
+  test('ignores annotation, which is not the claim', () => {
+    expect(stepClaimKey(step({ annotation: 'why' }))).toBe(
+      stepClaimKey(step()),
+    );
+  });
+
+  test('changes when the claim changes', () => {
+    const base = stepClaimKey(step());
+    expect(base).not.toBe(stepClaimKey(step({ from: 'other' })));
+    expect(base).not.toBe(stepClaimKey(step({ to: 'other' })));
+    expect(base).not.toBe(stepClaimKey(step({ mechanism: 'feeds' })));
+    expect(base).not.toBe(stepClaimKey(step({ file: 'src/other.ts' })));
+    expect(base).not.toBe(stepClaimKey(step({ symbol: 'Other.submit' })));
+    expect(base).not.toBe(
+      stepClaimKey(step({ span: { startLine: 43, endLine: 43, contentHash: 'abc' } })),
+    );
+    expect(base).not.toBe(
+      stepClaimKey(step({ span: { startLine: 42, endLine: 42, contentHash: 'changed' } })),
+    );
+  });
+});
+
+describe('step emphasis lookup', () => {
+  test('resolves after steps are reordered', () => {
+    const first = step({ symbol: 'first' });
+    const second = step({ symbol: 'second' });
+    const map = buildStepEmphasisMap([record('flow', stepClaimKey(first))]);
+    const reordered = trail('flow', [second, first]);
+    expect(findStepEmphasis(map, 'flow', reordered.steps[1]!)).toBeDefined();
+    expect(findStepEmphasis(map, 'flow', reordered.steps[0]!)).toBeUndefined();
+  });
+
+  test('emphasisForTrail reports marks in current step order', () => {
+    const a = step({ symbol: 'a' });
+    const b = step({ symbol: 'b' });
+    const c = step({ symbol: 'c' });
+    const map = buildStepEmphasisMap([
+      record('flow', stepClaimKey(c)),
+      record('flow', stepClaimKey(a)),
+    ]);
+    expect(emphasisForTrail(map, trail('flow', [b, a, c])).map((r) => r.stepIndex)).toEqual([
+      1, 2,
+    ]);
+  });
+
+  test('an edited claim orphans its mark rather than re-binding it', () => {
+    const original = step();
+    const edited = step({ file: 'src/ui/login-v2.tsx' });
+    const records = [record('flow', stepClaimKey(original))];
+    const orphans = orphanedEmphasis(records, [trail('flow', [edited])]);
+    expect(orphans).toHaveLength(1);
+    expect(orphans[0]!.stepKey).toBe(stepClaimKey(original));
+  });
+
+  test('live marks are not reported as orphans', () => {
+    const live = step();
+    const records = [record('flow', stepClaimKey(live))];
+    expect(orphanedEmphasis(records, [trail('flow', [live])])).toEqual([]);
+  });
+
+  test('keys are scoped by trail id', () => {
+    const shared = step();
+    const map = buildStepEmphasisMap([record('flow-a', stepClaimKey(shared))]);
+    expect(emphasisKey('flow-b', shared)).not.toBe(emphasisKey('flow-a', shared));
+    expect(findStepEmphasis(map, 'flow-b', shared)).toBeUndefined();
+  });
+});