@principal-ai/subsystems-react 0.56.12 → 0.56.14

package/src/subsystem/__fixtures__/c4Sketch.ts

@@ -0,0 +1,94 @@
+/**
+ * Storybook fixture for an authored C4 sketch.
+ *
+ * A standalone hypothesis: containers, a component, an external, a person,
+ * and two authored lines. No model or grounding is involved.
+ */
+
+import type { C4Sketch } from '../c4Sketch';
+
+const PURL = 'pkg:github/acme/widget';
+
+export const SKETCH_FIXTURE: C4Sketch = {
+  id: 'c4s-story',
+  title: 'Acme widget architecture',
+  repoKeys: [PURL],
+  author: 'storybook',
+  notes:
+    '## About this sketch\n\nThis is an **authored hypothesis** for the Acme widget. It describes the host and worker containers, the store inside the host, and the GitHub integration.\n\n- The worker calls the host over RPC.\n- The host calls GitHub over HTTPS.\n- Nothing here is verified or promoted.',
+  createdAt: '2026-10-25T00:00:00.000Z',
+  updatedAt: '2026-10-25T00:00:00.000Z',
+  model: {
+    view: 'container',
+    system: { id: 'system:acme', label: 'Acme' },
+    nodes: [
+      {
+        kind: 'container',
+        id: 'container:host',
+        label: 'Host',
+        containerKind: 'application',
+        technology: 'Bun',
+        process: 'acme/host',
+        state: 'proposed',
+        description: 'The long-lived host process.',
+      },
+      {
+        kind: 'container',
+        id: 'container:worker',
+        label: 'Worker',
+        containerKind: 'application',
+        technology: 'Bun',
+        process: 'acme/worker',
+        state: 'proposed',
+        description: 'The background worker.',
+      },
+      {
+        kind: 'component',
+        id: 'component:store',
+        label: 'Store',
+        container: 'container:host',
+        technology: 'Postgres',
+        members: ['store', 'ghost'],
+        state: 'proposed',
+        description: 'Persistence inside the host.',
+      },
+      {
+        kind: 'external-system',
+        id: 'external:github',
+        label: 'GitHub',
+        technology: 'REST',
+        members: ['github'],
+        state: 'proposed',
+        description: 'External source control.',
+      },
+      {
+        kind: 'person',
+        id: 'person:dev',
+        label: 'Developer',
+        state: 'proposed',
+        description: 'Uses the system.',
+      },
+    ],
+    edges: [
+      {
+        id: 'e:host-github',
+        source: 'container:host',
+        target: 'external:github',
+        label: 'HTTPS',
+        protocol: 'HTTPS',
+        mechanisms: ['calls'],
+        count: 1,
+      },
+      {
+        id: 'e:worker-host',
+        source: 'container:worker',
+        target: 'container:host',
+        label: 'RPC',
+        protocol: 'RPC',
+        mechanisms: ['calls'],
+        count: 1,
+      },
+    ],
+  },
+};
+

package/src/subsystem/c4Sketch.ts

@@ -0,0 +1,78 @@
+/**
+ * Authored C4 sketches — the types shared by the sketch view and the host
+ * stores.
+ *
+ * These live in `subsystems-react` so the pure view and its Storybook fixtures
+ * can use them without importing Studio's cross-process contract.
+ */
+
+import type { C4Model } from './c4';
+
+/**
+ * A C4 sketch — an authored, unverified architecture hypothesis.
+ *
+ * Unlike the accepted element store (approved containers only) and a model
+ * projection (derived from `process` keys), a sketch carries containers,
+ * components, externals, persons, AND edges. It can exist before any subsystem
+ * model does. Element state is forced to `proposed` by the host store: a sketch
+ * never claims acceptance.
+ */
+export interface C4Sketch {
+  id: string;
+  title: string;
+  /** Repos the sketch claims to describe; can be empty for greenfield. */
+  repoKeys: string[];
+  /** Authored nodes + edges. */
+  model: C4Model;
+  author?: string;
+  notes?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** Lightweight row for listing sketches without their nodes/edges. */
+export interface C4SketchSummary {
+  id: string;
+  title: string;
+  repoKeys: string[];
+  author?: string;
+  createdAt: string;
+  updatedAt: string;
+  counts: {
+    containers: number;
+    components: number;
+    externals: number;
+    persons: number;
+    edges: number;
+  };
+}
+
+/** Which C4 source a model projection or tab reads. */
+export type SubsystemC4Source = 'auto' | 'accepted' | 'draft';
+
+/**
+ * A drawable C4 projection for one subsystem model.
+ *
+ * `accepted` uses the repo's approved containers; `draft` derives provisional
+ * containers from the model's `process` keys. `memberships` is element id →
+ * component aliases, so a view can build construct graphs without re-deriving
+ * the join.
+ */
+export interface SubsystemC4Projection {
+  model: C4Model;
+  source: 'accepted' | 'draft';
+  memberships: Record<string, string[]>;
+  counts: {
+    containers: number;
+    externals: number;
+    edges: number;
+    components: number;
+    unassignedComponents: number;
+    unbackedProcesses: number;
+  };
+  repos: string[];
+  /** Aliases of components that state no `process`. */
+  unassignedComponents: string[];
+  /** Container-shaped process keys no accepted container claims (accepted source only). */
+  unbackedProcesses: string[];
+}

package/src/subsystem/c4TrailFocus.ts

@@ -0,0 +1,62 @@
+/**
+ * C4 trail focus — the pure read-side helpers shared by the C4 projection view
+ * and its stories.
+ *
+ * These do not own state: a host decides which trail/step is focused and asks
+ * which elements and lines that focus touches.
+ */
+
+import type { C4Edge } from './c4';
+import type { SubsystemTrailStep } from './model';
+
+/**
+ * The C4 elements a trail touches — every element that owns a step endpoint.
+ *
+ * Because a container's process-claim membership AND the authored components
+ * nested inside it can both claim an alias, both end up in the set: the
+ * container is the visible card at container view, its components are the
+ * visible cards when it is open, so either view stays honest.
+ */
+export function deriveTrailPlayerElements(
+  steps: readonly SubsystemTrailStep[],
+  members: Readonly<Record<string, readonly string[]>>,
+): Set<string> {
+  const byAlias = new Map<string, string[]>();
+  for (const [elementId, aliases] of Object.entries(members)) {
+    for (const alias of aliases) {
+      const list = byAlias.get(alias);
+      if (list) list.push(elementId);
+      else byAlias.set(alias, [elementId]);
+    }
+  }
+  const players = new Set<string>();
+  for (const step of steps) {
+    for (const id of byAlias.get(step.from) ?? []) players.add(id);
+    for (const id of byAlias.get(step.to) ?? []) players.add(id);
+  }
+  return players;
+}
+
+/**
+ * The C4 edges that carry a focus — a whole trail, or one specific step.
+ *
+ * An edge is lit iff its authored `trailRefs` cover the source. A step entirely
+ * internal to a container folds into no C4 line, so its focus lights nothing —
+ * which is honest: no drawn edge represents that hop.
+ */
+export function deriveLitC4Edges(
+  source: { trailId: string; stepIndex?: number },
+  edges: readonly C4Edge[],
+): Set<string> {
+  const lit = new Set<string>();
+  for (const edge of edges) {
+    for (const ref of edge.trailRefs ?? []) {
+      if (ref.trailId !== source.trailId) continue;
+      if (source.stepIndex == null || ref.stepIndices.includes(source.stepIndex)) {
+        lit.add(edge.id);
+        break;
+      }
+    }
+  }
+  return lit;
+}