@principal-ai/subsystems-react 0.37.5 → 0.37.7

package/dist/subsystem/toC4.js

@@ -0,0 +1,196 @@
+/**
+ * toC4 — project a subsystem-model (or a composition of them) onto C4 levels.
+ *
+ * The stored document is flat: `components[]` carry `process` (runtime unit),
+ * `purl` (repo/package), `construct`, `role`, `module`, plus `relations[]`
+ * (static) and `walkthroughs[]` (dynamic). C4 wants a hierarchy above the
+ * component — system → container → component — with externals and actors
+ * outside it. This module derives that hierarchy without inventing data:
+ *
+ *   system     ← the repo key (purlRepoKey of the first grounded component)
+ *   container  ← component.process            (runtime/deployment boundary)
+ *   component  ← a grounded component
+ *   external   ← construct: 'external'
+ *   actor      ← construct: 'custom_entity'   (their authored actor/entity)
+ *
+ * Edges are rolled up to the owner of each endpoint at the chosen view, so the
+ * container view shows container↔container collaborations and the component
+ * view shows component↔component ones. Intra-owner edges (from === to) drop.
+ *
+ * Pure over the document so it is unit-testable and reusable by any renderer.
+ */
+const EXTERNAL_PURL = 'external';
+const UNASSIGNED = '(unassigned)';
+/** A code component (not an external, not an actor/entity). */
+export function isGroundedComponent(c) {
+    return c.construct !== 'external' && c.construct !== 'custom_entity';
+}
+/** `owner/name` from a purl, trimmed of scheme and fragment. */
+export function labelFromPurl(purl) {
+    const base = purl.replace(/^external:/, '').split('#')[0]?.trim() ?? '';
+    const parts = base.split('/').filter(Boolean);
+    return parts.slice(-2).join('/') || base || purl;
+}
+/** The repo key the system is derived from: first grounded component's purl. */
+export function deriveRepoKey(doc) {
+    for (const c of doc.components) {
+        const p = (c.purl ?? '').split('#')[0]?.trim();
+        if (p && p !== EXTERNAL_PURL && !p.startsWith('external:'))
+            return p;
+    }
+    return undefined;
+}
+/** Stable identity for an external: its real purl, else the model-local alias. */
+function externalKey(c) {
+    const purl = (c.purl ?? '').trim();
+    if (purl && purl !== EXTERNAL_PURL && purl !== 'external:proposed')
+        return purl;
+    return `alias:${c.alias}`;
+}
+function containerKey(c) {
+    return c.process?.trim() || UNASSIGNED;
+}
+/**
+ * Derive the C4 projection of a (possibly composed) subsystem document.
+ *
+ * @param doc - a portable document, or a composed one with canonical aliases.
+ * @param options - view + optional system naming + attribution.
+ */
+export function toC4(doc, options = {}) {
+    const view = options.view ?? 'container';
+    const repoKey = options.repoKey ?? deriveRepoKey(doc) ?? 'system';
+    const systemId = `system:${repoKey}`;
+    const system = {
+        id: systemId,
+        kind: 'system',
+        label: options.systemLabel ?? labelFromPurl(repoKey),
+        key: repoKey,
+        members: [],
+        constructs: [],
+        isStore: false,
+    };
+    const nodes = new Map();
+    const ownerOf = new Map();
+    const containerNodeId = (key) => `container:${key}`;
+    const componentNodeId = (alias) => `component:${alias}`;
+    for (const c of doc.components) {
+        let id;
+        let kind;
+        let label;
+        let parentId;
+        let key;
+        if (c.construct === 'external') {
+            key = externalKey(c);
+            id = `external:${key}`;
+            kind = 'external';
+            label = key.startsWith('alias:') ? c.name : labelFromPurl(key);
+        }
+        else if (c.construct === 'custom_entity') {
+            key = c.alias;
+            id = `actor:${c.alias}`;
+            kind = 'actor';
+            label = c.name;
+        }
+        else if (view === 'component') {
+            key = containerKey(c);
+            id = componentNodeId(c.alias);
+            kind = 'component';
+            label = c.name;
+            parentId = containerNodeId(key);
+        }
+        else {
+            key = containerKey(c);
+            id = containerNodeId(key);
+            kind = 'container';
+            label = key === UNASSIGNED ? 'Unassigned' : key;
+            parentId = systemId;
+        }
+        ownerOf.set(c.alias, id);
+        let node = nodes.get(id);
+        if (!node) {
+            node = {
+                id,
+                kind,
+                label,
+                parentId,
+                key,
+                members: [],
+                constructs: [],
+                isStore: false,
+                ...(kind === 'component' ? { component: c } : {}),
+            };
+            nodes.set(id, node);
+        }
+        node.members.push(c.alias);
+        if (!node.constructs.includes(c.construct))
+            node.constructs.push(c.construct);
+        if (c.construct === 'store')
+            node.isStore = true;
+        const models = options.modelsByAlias?.[c.alias];
+        if (models && models.length > 0) {
+            node.models = [...new Set([...(node.models ?? []), ...models])];
+        }
+    }
+    // --- Groups (compound frames) ------------------------------------------
+    const groups = [];
+    if (view === 'container') {
+        const containerIds = [...nodes.values()].filter((n) => n.kind === 'container').map((n) => n.id);
+        if (containerIds.length > 0) {
+            groups.push({ id: systemId, kind: 'system', label: system.label, memberIds: containerIds });
+        }
+    }
+    else {
+        const byContainer = new Map();
+        for (const n of nodes.values()) {
+            if (n.kind !== 'component' || !n.parentId)
+                continue;
+            const list = byContainer.get(n.parentId) ?? [];
+            list.push(n.id);
+            byContainer.set(n.parentId, list);
+        }
+        const containerIds = [];
+        for (const [id, memberIds] of byContainer) {
+            const label = id.slice('container:'.length);
+            groups.push({ id, kind: 'container', label: label === UNASSIGNED ? 'Unassigned' : label, parentId: systemId, memberIds });
+            containerIds.push(id);
+        }
+        if (containerIds.length > 0) {
+            groups.push({ id: systemId, kind: 'system', label: system.label, memberIds: containerIds });
+        }
+    }
+    // --- Edges: roll each endpoint up to its owner at this view -------------
+    const relEdges = new Map();
+    const flowEdges = new Map();
+    const addEdge = (bucket, source, target, kind, mechanism) => {
+        if (!source || !target || source === target)
+            return;
+        const key = `${source}\0${target}`;
+        let edge = bucket.get(key);
+        if (!edge) {
+            edge = { id: `${kind}:${key}`, source, target, kind, label: '', mechanisms: [], count: 0 };
+            bucket.set(key, edge);
+        }
+        edge.count += 1;
+        if (!edge.mechanisms.includes(mechanism))
+            edge.mechanisms.push(mechanism);
+    };
+    for (const r of doc.relations ?? []) {
+        addEdge(relEdges, ownerOf.get(r.from), ownerOf.get(r.to), 'relationship', r.relationType);
+    }
+    for (const w of doc.walkthroughs ?? []) {
+        for (const s of w.steps ?? []) {
+            addEdge(flowEdges, ownerOf.get(s.from), ownerOf.get(s.to), 'flow', s.mechanism);
+        }
+    }
+    const edges = [...relEdges.values(), ...flowEdges.values()];
+    for (const e of edges)
+        e.label = [...e.mechanisms].sort().join(' + ');
+    return {
+        view,
+        system,
+        nodes: [...nodes.values()].filter((n) => n.kind !== 'system'),
+        groups,
+        edges,
+    };
+}
+//# sourceMappingURL=toC4.js.map

package/dist/subsystem/toC4.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toC4.js","sourceRoot":"","sources":["../../src/subsystem/toC4.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAsEH,MAAM,aAAa,GAAG,UAAU,CAAC;AACjC,MAAM,UAAU,GAAG,cAAc,CAAC;AAElC,+DAA+D;AAC/D,MAAM,UAAU,mBAAmB,CAAC,CAAqB;IACvD,OAAO,CAAC,CAAC,SAAS,KAAK,UAAU,IAAI,CAAC,CAAC,SAAS,KAAK,eAAe,CAAC;AACvE,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IACxE,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC9C,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,IAAI,IAAI,CAAC;AACnD,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,aAAa,CAAC,GAA2B;IACvD,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,UAAU,EAAE;QAC9B,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;QAC/C,IAAI,CAAC,IAAI,CAAC,KAAK,aAAa,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,WAAW,CAAC;YAAE,OAAO,CAAC,CAAC;KACtE;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,kFAAkF;AAClF,SAAS,WAAW,CAAC,CAAqB;IACxC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACnC,IAAI,IAAI,IAAI,IAAI,KAAK,aAAa,IAAI,IAAI,KAAK,mBAAmB;QAAE,OAAO,IAAI,CAAC;IAChF,OAAO,SAAS,CAAC,CAAC,KAAK,EAAE,CAAC;AAC5B,CAAC;AAED,SAAS,YAAY,CAAC,CAAqB;IACzC,OAAO,CAAC,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,UAAU,CAAC;AACzC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,IAAI,CAAC,GAA2B,EAAE,UAAuB,EAAE;IACzE,MAAM,IAAI,GAAW,OAAO,CAAC,IAAI,IAAI,WAAW,CAAC;IACjD,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,aAAa,CAAC,GAAG,CAAC,IAAI,QAAQ,CAAC;IAClE,MAAM,QAAQ,GAAG,UAAU,OAAO,EAAE,CAAC;IAErC,MAAM,MAAM,GAAW;QACrB,EAAE,EAAE,QAAQ;QACZ,IAAI,EAAE,QAAQ;QACd,KAAK,EAAE,OAAO,CAAC,WAAW,IAAI,aAAa,CAAC,OAAO,CAAC;QACpD,GAAG,EAAE,OAAO;QACZ,OAAO,EAAE,EAAE;QACX,UAAU,EAAE,EAAE;QACd,OAAO,EAAE,KAAK;KACf,CAAC;IAEF,MAAM,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;IACxC,MAAM,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;IAE1C,MAAM,eAAe,GAAG,CAAC,GAAW,EAAE,EAAE,CAAC,aAAa,GAAG,EAAE,CAAC;IAC5D,MAAM,eAAe,GAAG,CAAC,KAAa,EAAE,EAAE,CAAC,aAAa,KAAK,EAAE,CAAC;IAEhE,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,UAAU,EAAE;QAC9B,IAAI,EAAU,CAAC;QACf,IAAI,IAAY,CAAC;QACjB,IAAI,KAAa,CAAC;QAClB,IAAI,QAA4B,CAAC;QACjC,IAAI,GAAuB,CAAC;QAE5B,IAAI,CAAC,CAAC,SAAS,KAAK,UAAU,EAAE;YAC9B,GAAG,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;YACrB,EAAE,GAAG,YAAY,GAAG,EAAE,CAAC;YACvB,IAAI,GAAG,UAAU,CAAC;YAClB,KAAK,GAAG,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;SAChE;aAAM,IAAI,CAAC,CAAC,SAAS,KAAK,eAAe,EAAE;YAC1C,GAAG,GAAG,CAAC,CAAC,KAAK,CAAC;YACd,EAAE,GAAG,SAAS,CAAC,CAAC,KAAK,EAAE,CAAC;YACxB,IAAI,GAAG,OAAO,CAAC;YACf,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC;SAChB;aAAM,IAAI,IAAI,KAAK,WAAW,EAAE;YAC/B,GAAG,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;YACtB,EAAE,GAAG,eAAe,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;YAC9B,IAAI,GAAG,WAAW,CAAC;YACnB,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC;YACf,QAAQ,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;SACjC;aAAM;YACL,GAAG,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;YACtB,EAAE,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;YAC1B,IAAI,GAAG,WAAW,CAAC;YACnB,KAAK,GAAG,GAAG,KAAK,UAAU,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC;YAChD,QAAQ,GAAG,QAAQ,CAAC;SACrB;QAED,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAEzB,IAAI,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACzB,IAAI,CAAC,IAAI,EAAE;YACT,IAAI,GAAG;gBACL,EAAE;gBACF,IAAI;gBACJ,KAAK;gBACL,QAAQ;gBACR,GAAG;gBACH,OAAO,EAAE,EAAE;gBACX,UAAU,EAAE,EAAE;gBACd,OAAO,EAAE,KAAK;gBACd,GAAG,CAAC,IAAI,KAAK,WAAW,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAClD,CAAC;YACF,KAAK,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;SACrB;QACD,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QAC3B,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;YAAE,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QAC9E,IAAI,CAAC,CAAC,SAAS,KAAK,OAAO;YAAE,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACjD,MAAM,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QAChD,IAAI,MAAM,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE;YAC/B,IAAI,CAAC,MAAM,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;SACjE;KACF;IAED,0EAA0E;IAC1E,MAAM,MAAM,GAAc,EAAE,CAAC;IAC7B,IAAI,IAAI,KAAK,WAAW,EAAE;QACxB,MAAM,YAAY,GAAG,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAChG,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE;YAC3B,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC,CAAC;SAC7F;KACF;SAAM;QACL,MAAM,WAAW,GAAG,IAAI,GAAG,EAAoB,CAAC;QAChD,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,MAAM,EAAE,EAAE;YAC9B,IAAI,CAAC,CAAC,IAAI,KAAK,WAAW,IAAI,CAAC,CAAC,CAAC,QAAQ;gBAAE,SAAS;YACpD,MAAM,IAAI,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;YAC/C,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YAChB,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;SACnC;QACD,MAAM,YAAY,GAAa,EAAE,CAAC;QAClC,KAAK,MAAM,CAAC,EAAE,EAAE,SAAS,CAAC,IAAI,WAAW,EAAE;YACzC,MAAM,KAAK,GAAG,EAAE,CAAC,KAAK,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;YAC5C,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,CAAC;YAC1H,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;SACvB;QACD,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE;YAC3B,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC,CAAC;SAC7F;KACF;IAED,2EAA2E;IAC3E,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC3C,MAAM,SAAS,GAAG,IAAI,GAAG,EAAkB,CAAC;IAE5C,MAAM,OAAO,GAAG,CACd,MAA2B,EAC3B,MAA0B,EAC1B,MAA0B,EAC1B,IAAoB,EACpB,SAAiB,EACjB,EAAE;QACF,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,IAAI,MAAM,KAAK,MAAM;YAAE,OAAO;QACpD,MAAM,GAAG,GAAG,GAAG,MAAM,KAAK,MAAM,EAAE,CAAC;QACnC,IAAI,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC3B,IAAI,CAAC,IAAI,EAAE;YACT,IAAI,GAAG,EAAE,EAAE,EAAE,GAAG,IAAI,IAAI,GAAG,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,UAAU,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;YAC3F,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;SACvB;QACD,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC;QAChB,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,SAAS,CAAC;YAAE,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC5E,CAAC,CAAC;IAEF,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,SAAS,IAAI,EAAE,EAAE;QACnC,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC,YAAY,CAAC,CAAC;KAC3F;IACD,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,YAAY,IAAI,EAAE,EAAE;QACtC,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,IAAI,EAAE,EAAE;YAC7B,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC;SACjF;KACF;IAED,MAAM,KAAK,GAAG,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,EAAE,GAAG,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5D,KAAK,MAAM,CAAC,IAAI,KAAK;QAAE,CAAC,CAAC,KAAK,GAAG,CAAC,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAEtE,OAAO;QACL,IAAI;QACJ,MAAM;QACN,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC;QAC7D,MAAM;QACN,KAAK;KACN,CAAC;AACJ,CAAC"}

package/dist/subsystem/walkthroughBrief.d.ts

@@ -0,0 +1,18 @@
+/**
+ * walkthroughBrief — build a paste-ready markdown brief for a single
+ * walkthrough step so a reviewer can hand one hop to an agent without
+ * transcribing it by hand.
+ *
+ * The unit of handoff is one hop, not the whole flow. A bare hop is ambiguous
+ * on its own — the same `from`/`to`/`mechanism` can repeat across flows — so the
+ * brief also carries the flow it belongs to and its position within it, plus
+ * the exact seam site (`symbol`, `file:line`, `purl`) that resolves the
+ * checkout.
+ */
+import type { SubsystemWalkthrough } from './model';
+/**
+ * Markdown brief for `walkthrough.steps[stepIndex]`. Returns `''` when the
+ * index is out of range so a caller can treat it as "nothing to copy".
+ */
+export declare function buildStepBrief(walkthrough: SubsystemWalkthrough, stepIndex: number): string;
+//# sourceMappingURL=walkthroughBrief.d.ts.map

package/dist/subsystem/walkthroughBrief.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"walkthroughBrief.d.ts","sourceRoot":"","sources":["../../src/subsystem/walkthroughBrief.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAEpD;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,WAAW,EAAE,oBAAoB,EACjC,SAAS,EAAE,MAAM,GAChB,MAAM,CAkBR"}

package/dist/subsystem/walkthroughBrief.js

@@ -0,0 +1,34 @@
+/**
+ * walkthroughBrief — build a paste-ready markdown brief for a single
+ * walkthrough step so a reviewer can hand one hop to an agent without
+ * transcribing it by hand.
+ *
+ * The unit of handoff is one hop, not the whole flow. A bare hop is ambiguous
+ * on its own — the same `from`/`to`/`mechanism` can repeat across flows — so the
+ * brief also carries the flow it belongs to and its position within it, plus
+ * the exact seam site (`symbol`, `file:line`, `purl`) that resolves the
+ * checkout.
+ */
+/**
+ * Markdown brief for `walkthrough.steps[stepIndex]`. Returns `''` when the
+ * index is out of range so a caller can treat it as "nothing to copy".
+ */
+export function buildStepBrief(walkthrough, stepIndex) {
+    const step = walkthrough.steps[stepIndex];
+    if (!step)
+        return '';
+    const lines = [];
+    lines.push(`Walkthrough: ${walkthrough.title} (${walkthrough.id}) — step ${stepIndex + 1}/${walkthrough.steps.length}`);
+    lines.push('');
+    lines.push(`- from: \`${step.from}\``);
+    lines.push(`- to: \`${step.to}\``);
+    lines.push(`- mechanism: \`${step.mechanism}\``);
+    lines.push(`- symbol: \`${step.symbol}\``);
+    lines.push(`- site: \`${step.file}:${step.line}\``);
+    lines.push(`- purl: \`${step.purl}\``);
+    if (step.annotation != null && step.annotation.length > 0) {
+        lines.push(`- note: ${step.annotation}`);
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=walkthroughBrief.js.map

package/dist/subsystem/walkthroughBrief.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"walkthroughBrief.js","sourceRoot":"","sources":["../../src/subsystem/walkthroughBrief.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH;;;GAGG;AACH,MAAM,UAAU,cAAc,CAC5B,WAAiC,EACjC,SAAiB;IAEjB,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAC1C,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,CAAC;IACrB,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CACR,gBAAgB,WAAW,CAAC,KAAK,KAAK,WAAW,CAAC,EAAE,YAAY,SAAS,GAAG,CAAC,IAAI,WAAW,CAAC,KAAK,CAAC,MAAM,EAAE,CAC5G,CAAC;IACF,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,aAAa,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC;IACvC,KAAK,CAAC,IAAI,CAAC,WAAW,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;IACnC,KAAK,CAAC,IAAI,CAAC,kBAAkB,IAAI,CAAC,SAAS,IAAI,CAAC,CAAC;IACjD,KAAK,CAAC,IAAI,CAAC,eAAe,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC;IAC3C,KAAK,CAAC,IAAI,CAAC,aAAa,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC;IACpD,KAAK,CAAC,IAAI,CAAC,aAAa,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC;IACvC,IAAI,IAAI,CAAC,UAAU,IAAI,IAAI,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE;QACzD,KAAK,CAAC,IAAI,CAAC,WAAW,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;KAC1C;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@principal-ai/subsystems-react",
-  "version": "0.37.5",
+  "version": "0.37.7",
   "description": "React UI for Subsystem Models — graph, Pierre code views, and session-event feeds",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/index.ts

@@ -174,8 +174,13 @@ export type {
 } from './subsystem/paths';
 export { SubsystemFileTree } from './subsystem/SubsystemFileTree';
 export type { SubsystemFileTreeProps } from './subsystem/SubsystemFileTree';
-export { WalkthroughsPanel, WALKTHROUGH_PLAY_PAUSE_MS } from './subsystem/WalkthroughsPanel';
+export {
+  WalkthroughsPanel,
+  WALKTHROUGH_PLAY_PAUSE_MS,
+  STEP_COPY_FEEDBACK_MS,
+} from './subsystem/WalkthroughsPanel';
 export type { WalkthroughsPanelProps } from './subsystem/WalkthroughsPanel';
+export { buildStepBrief } from './subsystem/walkthroughBrief';
 export { GraphLayoutCover } from './subsystem/GraphLayoutCover';
 export type { GraphLayoutCoverProps } from './subsystem/GraphLayoutCover';
 export {

package/src/stories/Subsystem/C4Graph/C4Container.stories.tsx

@@ -0,0 +1,104 @@
+import React, { 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 { C4Graph } from '../../../subsystem/C4Graph';
+import { toC4, type C4View } from '../../../subsystem/toC4';
+import { c4FixtureModel } from './c4Fixture';
+
+const meta = {
+  title: 'Subsystem/C4Graph/C4Container',
+  component: C4Graph,
+  parameters: {
+    layout: 'fullscreen',
+  },
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <ThemeProvider theme={defaultEditorTheme}>
+        <Story />
+      </ThemeProvider>
+    ),
+  ],
+} satisfies Meta<typeof C4Graph>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+// C4 projection of a real composite: 60 stored subsystem models over one repo,
+// merged by the host, then derived into system → container/component boxes with
+// externals + actors outside. Toggle the C4 level; click a box to see the
+// source components it rolled up.
+// ---------------------------------------------------------------------------
+
+function C4Demo() {
+  const [view, setView] = useState<C4View>('container');
+  const [selected, setSelected] = useState<string | null>(null);
+  const model = useMemo(() => toC4(c4FixtureModel, { view, systemLabel: 'Subsystem Modeling' }), [view]);
+
+  const counts = {
+    containers: model.nodes.filter((n) => n.kind === 'container').length,
+    components: model.nodes.filter((n) => n.kind === 'component').length,
+    externals: model.nodes.filter((n) => n.kind === 'external').length,
+    actors: model.nodes.filter((n) => n.kind === 'actor').length,
+    relationships: model.edges.filter((e) => e.kind === 'relationship').length,
+    flows: model.edges.filter((e) => e.kind === 'flow').length,
+  };
+
+  const button = (label: string, value: C4View) => (
+    <button
+      type="button"
+      onClick={() => setView(value)}
+      style={{
+        fontFamily: 'monospace',
+        fontSize: 12,
+        padding: '2px 10px',
+        borderRadius: 4,
+        cursor: 'pointer',
+        border: '1px solid #555',
+        background: view === value ? '#1D9E75' : 'transparent',
+        color: view === value ? '#020B12' : '#ddd',
+      }}
+    >
+      {label}
+    </button>
+  );
+
+  return (
+    <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
+      <div style={{ flex: 1, minHeight: 0, position: 'relative' }}>
+        <C4Graph model={model} title="Subsystem Modeling" onSelectNode={setSelected} />
+      </div>
+      <div
+        style={{
+          padding: '6px 12px',
+          display: 'flex',
+          alignItems: 'center',
+          gap: 16,
+          fontFamily: 'monospace',
+          fontSize: 12,
+          color: '#aaa',
+          borderTop: '1px solid #333',
+        }}
+      >
+        <span style={{ display: 'flex', gap: 6 }}>
+          view: {button('container', 'container')} {button('component', 'component')}
+        </span>
+        <span>
+          {counts.containers} containers · {counts.components} components · {counts.externals} externals ·{' '}
+          {counts.actors} actors
+        </span>
+        <span>
+          {counts.relationships} relationship edges · {counts.flows} flow edges
+        </span>
+        <span>selected: {selected ?? '(none)'}</span>
+      </div>
+    </div>
+  );
+}
+
+export const C4: Story = {
+  args: { model: toC4(c4FixtureModel, { view: 'container', systemLabel: 'Subsystem Modeling' }) },
+  render: () => <C4Demo />,
+};