@diagc/core 0.1.0

package/dist/mutate.d.ts

@@ -0,0 +1,106 @@
+import { type Column, type DiagramLayer, type DiagramLegend, type DiagramModel, type DiagramNode, type DiagramPlane, type EdgeLabel, type FontScale, type Polarity, type RelationStyle, type StrideCategory, type TextAlign, type TextRun, type Threat, type ThreatSeverity, type ThreatStatus } from './types.js';
+import type { ThreatTarget } from './threat-model.js';
+export declare class CommandError extends Error {
+    constructor(message: string);
+}
+export declare function uniqueNodeId(m: DiagramModel, base: string): string;
+export declare function addNode(m: DiagramModel, node: DiagramNode): DiagramModel;
+export declare function renameNode(m: DiagramModel, id: string, name: string): DiagramModel;
+export declare function setNodeRich(m: DiagramModel, id: string, runs: TextRun[]): DiagramModel;
+export interface NodeDetails {
+    type?: string | null;
+    icon?: string | null;
+    image?: string | null;
+    shape?: string | null;
+    color?: string | null;
+    textColor?: string | null;
+    technology?: string | null;
+    link?: string | null;
+    textAlign?: TextAlign | null;
+    fontScale?: FontScale | null;
+    description?: string | null;
+    metadata?: Record<string, unknown> | null;
+    plane?: string | null;
+    layer?: string | null;
+}
+export declare function setNodeDetails(m: DiagramModel, id: string, details: NodeDetails): DiagramModel;
+/** Transitive containment descendants of `id` across every plane, plus `id`
+ * itself — the set a cascade delete destroys. */
+export declare function subtreeOf(m: DiagramModel, id: string): Set<string>;
+export declare function deleteNode(m: DiagramModel, id: string, cascade?: boolean): DiagramModel;
+export declare function setTableColumns(m: DiagramModel, id: string, columns: Column[]): DiagramModel;
+/** Patch for update-threat: `null` clears an optional field. `category` and
+ * `title` are required on a {@link Threat}, so they are set-only. */
+export interface ThreatPatch {
+    category?: StrideCategory;
+    title?: string;
+    description?: string | null;
+    severity?: ThreatSeverity | null;
+    status?: ThreatStatus | null;
+    mitigation?: string | null;
+}
+export declare function addThreat(m: DiagramModel, target: ThreatTarget, threat: Threat): DiagramModel;
+export declare function updateThreat(m: DiagramModel, target: ThreatTarget, id: string, patch: ThreatPatch): DiagramModel;
+export declare function removeThreat(m: DiagramModel, target: ThreatTarget, id: string): DiagramModel;
+export declare function addContainment(m: DiagramModel, parent: string, child: string, plane?: string): DiagramModel;
+/**
+ * Group existing nodes under a new abstract parent: add `node`, then nest each
+ * member under it. `plane` scopes both the containment edges and (via the
+ * caller setting `node.plane`) the abstract node, so the grouping can live in a
+ * single plane's view. Atomic: a bad member id throws before any partial model
+ * escapes (the intermediate is a local value, never returned).
+ */
+export declare function groupNodes(m: DiagramModel, node: DiagramNode, memberIds: readonly string[], plane?: string): DiagramModel;
+export declare function removeContainment(m: DiagramModel, parent: string, child: string, plane?: string): DiagramModel;
+/** Pin the diagram's visual style preset id, or clear it with null (the
+ * app-level preference applies again). Unknown ids are intentionally
+ * accepted — the renderer treats them as unpinned. */
+export declare function setDiagramStyle(m: DiagramModel, style: string | null): DiagramModel;
+/** Pin the diagram's notation id, or clear it with null. Unlike
+ * `setDiagramStyle`, unknown ids are rejected — a model-level notation drives
+ * structural validation rules the same way a plane's own notation does (e.g.
+ * `validateGit` in validate.ts resolves `plane.notation ?? model.notation`),
+ * so it must resolve to a known one. */
+export declare function setDiagramNotation(m: DiagramModel, notation: string | null): DiagramModel;
+/** Declare the diagram's legend, or clear it entirely with null. */
+export declare function setDiagramLegend(m: DiagramModel, legend: DiagramLegend | null): DiagramModel;
+export interface RelationOptsInput {
+    kind: string;
+    label?: string;
+    layer?: string;
+    description?: string;
+    style?: RelationStyle;
+    polarity?: Polarity;
+    delay?: boolean;
+    fromColumn?: string;
+    toColumn?: string;
+}
+export declare function addRelation(m: DiagramModel, from: string, to: string, opts: RelationOptsInput): {
+    model: DiagramModel;
+    id: string;
+};
+export interface RelationPatch {
+    /** move an endpoint (edge reconnection); the relation id is unchanged */
+    from?: string;
+    to?: string;
+    kind?: string;
+    label?: string | null;
+    labels?: EdgeLabel[] | null;
+    layer?: string | null;
+    description?: string | null;
+    style?: RelationStyle | null;
+    polarity?: Polarity | null;
+    delay?: boolean | null;
+    fromColumn?: string | null;
+    toColumn?: string | null;
+}
+export declare function updateRelation(m: DiagramModel, id: string, patch: RelationPatch): DiagramModel;
+export declare function deleteRelation(m: DiagramModel, id: string): DiagramModel;
+export declare function upsertLayer(m: DiagramModel, layer: DiagramLayer): DiagramModel;
+export declare function deleteLayer(m: DiagramModel, id: string): DiagramModel;
+export declare function mergeLayers(m: DiagramModel, sourceIds: string[], targetId?: string): DiagramModel;
+export declare function upsertPlane(m: DiagramModel, plane: DiagramPlane): DiagramModel;
+/** Add/remove a shared node from a plane's `hides`. A node already scoped to a
+ * plane is view-local, so hiding it is a no-op (validation flags a stray one). */
+export declare function setNodePlaneHidden(m: DiagramModel, nodeId: string, planeId: string, hidden: boolean): DiagramModel;
+export declare function deletePlane(m: DiagramModel, id: string): DiagramModel;

package/dist/mutate.js

@@ -0,0 +1,547 @@
+import { BUILTIN_NOTATIONS, } from './types.js';
+import { normalizeRuns, runsToPlainText } from './text.js';
+import { childrenOf } from './children.js';
+export class CommandError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CommandError';
+    }
+}
+const requireNode = (m, id) => {
+    const n = m.nodes.find((x) => x.id === id);
+    if (n === undefined)
+        throw new CommandError(`Unknown node '${id}'`);
+    return n;
+};
+export function uniqueNodeId(m, base) {
+    const slug = base
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '') || 'node';
+    const taken = new Set(m.nodes.map((n) => n.id));
+    if (!taken.has(slug))
+        return slug;
+    for (let i = 2;; i++) {
+        if (!taken.has(`${slug}-${i}`))
+            return `${slug}-${i}`;
+    }
+}
+export function addNode(m, node) {
+    if (m.nodes.some((n) => n.id === node.id))
+        throw new CommandError(`Duplicate node id '${node.id}'`);
+    return { ...m, nodes: [...m.nodes, node] };
+}
+export function renameNode(m, id, name) {
+    requireNode(m, id);
+    return {
+        ...m,
+        nodes: m.nodes.map((n) => {
+            if (n.id !== id)
+                return n;
+            const { rich: _rich, ...rest } = n;
+            return { ...rest, name };
+        }),
+    };
+}
+export function setNodeRich(m, id, runs) {
+    requireNode(m, id);
+    const norm = normalizeRuns(runs);
+    const name = runsToPlainText(norm);
+    const first = norm[0];
+    const isPlain = norm.length <= 1 && (first === undefined || (first.bold === undefined && first.italic === undefined));
+    return {
+        ...m,
+        nodes: m.nodes.map((n) => {
+            if (n.id !== id)
+                return n;
+            const { rich: _rich, ...rest } = n;
+            return isPlain ? { ...rest, name } : { ...rest, name, rich: norm };
+        }),
+    };
+}
+/** Whitelist of {@link NodeDetails} fields wired through the loop below. Every
+ * field is flat (optional, null-clearable), so one typed pass replaces the
+ * hand-rolled `applyNullable` chain. */
+const NODE_DETAIL_KEYS = [
+    'type',
+    'icon',
+    'image',
+    'shape',
+    'color',
+    'textColor',
+    'technology',
+    'link',
+    'textAlign',
+    'fontScale',
+    'description',
+    'metadata',
+    'plane',
+    'layer',
+];
+const _assertNodeKeyCoverage = true;
+void _assertNodeKeyCoverage;
+const applyNullable = (obj, key, value) => {
+    if (value === undefined)
+        return obj;
+    const next = { ...obj };
+    if (value === null)
+        delete next[key];
+    else
+        next[key] = value;
+    return next;
+};
+export function setNodeDetails(m, id, details) {
+    requireNode(m, id);
+    if (details.layer != null && !m.layers.some((l) => l.id === details.layer)) {
+        throw new CommandError(`Unknown layer '${details.layer}'`);
+    }
+    const nodes = m.nodes.map((n) => {
+        if (n.id !== id)
+            return n;
+        let next = { ...n };
+        // One typed loop over the field whitelist (see NODE_DETAIL_KEYS) instead of
+        // 12 hand-written applyNullable calls — adding a field wires automatically
+        // and the coverage const above makes an omission a compile error.
+        for (const key of NODE_DETAIL_KEYS) {
+            next = applyNullable(next, key, details[key]);
+        }
+        return next;
+    });
+    let next = { ...m, nodes };
+    // Scoping a node to a plane makes it view-local; drop it from every plane's
+    // `hides`/`hidesTree` so a formerly-hidden shared node doesn't linger there
+    // with no way to clear it via the UI (and to avoid tripping `redundant-hide`).
+    if (typeof details.plane === 'string') {
+        next = { ...next, planes: prunePlaneHides(next.planes, (h) => h === id) };
+    }
+    return next;
+}
+/** Drop every id satisfying `drop` from each plane's `hides`/`hidesTree`,
+ * omitting emptied lists; a plane with no change keeps its reference. */
+function prunePlaneHides(planes, drop) {
+    const without = (list) => list === undefined ? undefined : list.filter((h) => !drop(h));
+    return planes.map((p) => {
+        const hides = without(p.hides);
+        const hidesTree = without(p.hidesTree);
+        if (hides?.length === p.hides?.length && hidesTree?.length === p.hidesTree?.length)
+            return p;
+        const { hides: _h, hidesTree: _t, ...rest } = p;
+        return {
+            ...rest,
+            ...(hides !== undefined && hides.length > 0 ? { hides } : {}),
+            ...(hidesTree !== undefined && hidesTree.length > 0 ? { hidesTree } : {}),
+        };
+    });
+}
+/** Transitive containment descendants of `id` across every plane, plus `id`
+ * itself — the set a cascade delete destroys. */
+export function subtreeOf(m, id) {
+    const children = childrenOf(m.containment);
+    const doomed = new Set();
+    const stack = [id];
+    while (stack.length > 0) {
+        const cur = stack.pop();
+        if (cur === undefined || doomed.has(cur))
+            continue;
+        doomed.add(cur);
+        stack.push(...(children.get(cur) ?? []));
+    }
+    return doomed;
+}
+export function deleteNode(m, id, cascade = false) {
+    requireNode(m, id);
+    const doomed = cascade ? subtreeOf(m, id) : new Set([id]);
+    return {
+        ...m,
+        nodes: m.nodes.filter((n) => !doomed.has(n.id)),
+        containment: m.containment.filter((e) => !doomed.has(e.parent) && !doomed.has(e.child)),
+        relations: m.relations.filter((r) => !doomed.has(r.from) && !doomed.has(r.to)),
+        // A destroyed node must not linger in any plane's hides/hidesTree — the
+        // stale entry would fail `unknown-hidden-node` validation on the next save.
+        planes: prunePlaneHides(m.planes, (h) => doomed.has(h)),
+    };
+}
+export function setTableColumns(m, id, columns) {
+    requireNode(m, id);
+    // Deliberately NOT rejecting duplicate names: edit-mode inputs commit per
+    // keystroke, so a transient collision must not throw. `validate` reports
+    // duplicate-column at publish time.
+    return { ...m, nodes: m.nodes.map((n) => (n.id === id ? { ...n, columns } : n)) };
+}
+/** Whitelist of the null-clearable {@link ThreatPatch} fields, applied through
+ * `applyNullable` below — same shape as RELATION_NULLABLE_KEYS. */
+const THREAT_NULLABLE_KEYS = ['description', 'severity', 'status', 'mitigation'];
+const _assertThreatKeyCoverage = true;
+void _assertThreatKeyCoverage;
+/**
+ * Apply `fn` to the threat list of the element `target` names. Threats hang off
+ * nodes and relations alike and the list is identical on both, so one seam
+ * serves the two; only the named element is replaced, every sibling keeps its
+ * reference. A result with no threats drops the key entirely, keeping saved
+ * files free of empty arrays.
+ */
+function mapThreats(m, target, fn) {
+    const next = (items, id, what) => {
+        if (!items.some((x) => x.id === id))
+            throw new CommandError(`Unknown ${what} '${id}'`);
+        return items.map((x) => {
+            if (x.id !== id)
+                return x;
+            const threats = fn(x.threats ?? []);
+            const { threats: _dropped, ...rest } = x;
+            return (threats.length === 0 ? rest : { ...rest, threats });
+        });
+    };
+    return 'node' in target
+        ? { ...m, nodes: next(m.nodes, target.node, 'node') }
+        : { ...m, relations: next(m.relations, target.relation, 'relation') };
+}
+export function addThreat(m, target, threat) {
+    return mapThreats(m, target, (threats) => {
+        if (threats.some((t) => t.id === threat.id))
+            throw new CommandError(`Duplicate threat id '${threat.id}'`);
+        return [...threats, threat];
+    });
+}
+export function updateThreat(m, target, id, patch) {
+    return mapThreats(m, target, (threats) => {
+        if (!threats.some((t) => t.id === id))
+            throw new CommandError(`Unknown threat '${id}'`);
+        return threats.map((t) => {
+            if (t.id !== id)
+                return t;
+            let out = { ...t };
+            if (patch.category !== undefined)
+                out.category = patch.category;
+            if (patch.title !== undefined)
+                out.title = patch.title;
+            for (const key of THREAT_NULLABLE_KEYS) {
+                out = applyNullable(out, key, patch[key]);
+            }
+            return out;
+        });
+    });
+}
+export function removeThreat(m, target, id) {
+    return mapThreats(m, target, (threats) => {
+        if (!threats.some((t) => t.id === id))
+            throw new CommandError(`Unknown threat '${id}'`);
+        return threats.filter((t) => t.id !== id);
+    });
+}
+function wouldCycle(m, parent, child, plane) {
+    const defaultPlane = (m.planes ?? [])[0]?.id;
+    const key = plane ?? defaultPlane;
+    // Children index over this plane's edges, plus the candidate edge being added.
+    const children = childrenOf(m.containment.filter((e) => (e.plane ?? defaultPlane) === key));
+    children.set(parent, [...(children.get(parent) ?? []), child]);
+    // child must not reach parent
+    const stack = [child];
+    const seen = new Set();
+    while (stack.length > 0) {
+        const cur = stack.pop();
+        if (cur === undefined || seen.has(cur))
+            continue;
+        if (cur === parent && seen.size > 0)
+            return true;
+        seen.add(cur);
+        stack.push(...(children.get(cur) ?? []));
+    }
+    return false;
+}
+/**
+ * Resolve a plane argument to its canonical containment form: undefined stays
+ * undefined; a declared plane resolves its `containmentOf` borrow (one hop) and,
+ * if that lands on the first-declared (default) plane, collapses to `undefined`
+ * so edges are stored/compared in the untagged base form. Throws on unknowns.
+ */
+function canonicalPlane(m, plane) {
+    if (plane === undefined)
+        return undefined;
+    const planes = m.planes ?? [];
+    const p = planes.find((x) => x.id === plane);
+    if (p === undefined)
+        throw new CommandError(`Unknown plane '${plane}'`);
+    const resolved = p.containmentOf ?? p.id;
+    return resolved === planes[0]?.id ? undefined : resolved;
+}
+export function addContainment(m, parent, child, plane) {
+    requireNode(m, parent);
+    requireNode(m, child);
+    if (parent === child)
+        throw new CommandError(`Node '${parent}' cannot contain itself`);
+    const canon = canonicalPlane(m, plane);
+    if (m.containment.some((e) => e.parent === parent && e.child === child && e.plane === canon))
+        return m;
+    if (wouldCycle(m, parent, child, canon)) {
+        throw new CommandError(`'${parent}' > '${child}' would create a containment cycle`);
+    }
+    return { ...m, containment: [...m.containment, { parent, child, ...(canon !== undefined ? { plane: canon } : {}) }] };
+}
+/**
+ * Group existing nodes under a new abstract parent: add `node`, then nest each
+ * member under it. `plane` scopes both the containment edges and (via the
+ * caller setting `node.plane`) the abstract node, so the grouping can live in a
+ * single plane's view. Atomic: a bad member id throws before any partial model
+ * escapes (the intermediate is a local value, never returned).
+ */
+export function groupNodes(m, node, memberIds, plane) {
+    let next = addNode(m, node);
+    for (const child of memberIds) {
+        next = addContainment(next, node.id, child, plane);
+    }
+    return next;
+}
+export function removeContainment(m, parent, child, plane) {
+    const canon = canonicalPlane(m, plane);
+    return {
+        ...m,
+        containment: m.containment.filter((e) => !(e.parent === parent && e.child === child && e.plane === canon)),
+    };
+}
+/** Pin the diagram's visual style preset id, or clear it with null (the
+ * app-level preference applies again). Unknown ids are intentionally
+ * accepted — the renderer treats them as unpinned. */
+export function setDiagramStyle(m, style) {
+    if (style === null) {
+        const { style: _dropped, ...rest } = m;
+        return rest;
+    }
+    return { ...m, style };
+}
+/** Pin the diagram's notation id, or clear it with null. Unlike
+ * `setDiagramStyle`, unknown ids are rejected — a model-level notation drives
+ * structural validation rules the same way a plane's own notation does (e.g.
+ * `validateGit` in validate.ts resolves `plane.notation ?? model.notation`),
+ * so it must resolve to a known one. */
+export function setDiagramNotation(m, notation) {
+    if (notation === null) {
+        if (m.notation === undefined)
+            return m;
+        const { notation: _dropped, ...rest } = m;
+        return rest;
+    }
+    if (!BUILTIN_NOTATIONS.includes(notation)) {
+        throw new CommandError(`Unknown notation '${notation}'`);
+    }
+    return m.notation === notation ? m : { ...m, notation };
+}
+/** Declare the diagram's legend, or clear it entirely with null. */
+export function setDiagramLegend(m, legend) {
+    if (legend === null) {
+        const { legend: _dropped, ...rest } = m;
+        return rest;
+    }
+    return { ...m, legend };
+}
+export function addRelation(m, from, to, opts) {
+    requireNode(m, from);
+    requireNode(m, to);
+    if (opts.layer !== undefined && !m.layers.some((l) => l.id === opts.layer)) {
+        throw new CommandError(`Unknown layer '${opts.layer}'`);
+    }
+    // First free suffix — counting existing pairs collides after a middle delete
+    // (delete `a->b#0`, then adding again would reuse `#1`).
+    let i = 0;
+    while (m.relations.some((r) => r.id === `${from}->${to}#${i}`))
+        i++;
+    const id = `${from}->${to}#${i}`;
+    const { kind, ...rest } = opts;
+    const relation = {
+        id,
+        from,
+        to,
+        kind,
+        ...Object.fromEntries(Object.entries(rest).filter(([, v]) => v !== undefined)),
+    };
+    return { model: { ...m, relations: [...m.relations, relation] }, id };
+}
+/** Whitelist of {@link RelationPatch} fields that are null-clearable and applied
+ * through the loop below. `from`/`to`/`kind` are excluded — they are required
+ * relation keys set with a plain `!== undefined` guard, never null-cleared. */
+const RELATION_NULLABLE_KEYS = [
+    'label',
+    'labels',
+    'layer',
+    'description',
+    'style',
+    'polarity',
+    'delay',
+    'fromColumn',
+    'toColumn',
+];
+const _assertRelationKeyCoverage = true;
+void _assertRelationKeyCoverage;
+export function updateRelation(m, id, patch) {
+    if (!m.relations.some((r) => r.id === id))
+        throw new CommandError(`Unknown relation '${id}'`);
+    if (patch.layer != null && !m.layers.some((l) => l.id === patch.layer)) {
+        throw new CommandError(`Unknown layer '${patch.layer}'`);
+    }
+    for (const end of [patch.from, patch.to]) {
+        if (end !== undefined && !m.nodes.some((n) => n.id === end)) {
+            throw new CommandError(`Unknown node '${end}'`);
+        }
+    }
+    return {
+        ...m,
+        relations: m.relations.map((r) => {
+            if (r.id !== id)
+                return r;
+            let next = { ...r };
+            if (patch.from !== undefined)
+                next.from = patch.from;
+            if (patch.to !== undefined)
+                next.to = patch.to;
+            if (patch.kind !== undefined)
+                next.kind = patch.kind;
+            // The null-clearable fields go through one typed loop over the whitelist
+            // (see RELATION_NULLABLE_KEYS), preserving the same behavior as the prior
+            // hand-written chain.
+            for (const key of RELATION_NULLABLE_KEYS) {
+                next = applyNullable(next, key, patch[key]);
+            }
+            // `labels` supersedes the legacy single `label`: any labels write drops the
+            // legacy string, so removing the last label truly removes it (relationLabels
+            // won't re-synthesize) and upgraded models don't persist a redundant `label`.
+            if (patch.labels !== undefined)
+                next = applyNullable(next, 'label', null);
+            return next;
+        }),
+    };
+}
+export function deleteRelation(m, id) {
+    if (!m.relations.some((r) => r.id === id))
+        throw new CommandError(`Unknown relation '${id}'`);
+    return { ...m, relations: m.relations.filter((r) => r.id !== id) };
+}
+export function upsertLayer(m, layer) {
+    const exists = m.layers.some((l) => l.id === layer.id);
+    return {
+        ...m,
+        layers: exists ? m.layers.map((l) => (l.id === layer.id ? layer : l)) : [...m.layers, layer],
+    };
+}
+export function deleteLayer(m, id) {
+    if (!m.layers.some((l) => l.id === id))
+        throw new CommandError(`Unknown layer '${id}'`);
+    // Destructive: remove the layer's tagged nodes + relations. Cascade like
+    // deleteNode — a destroyed node's containment is severed (untagged children
+    // survive top-level) and relations touching it are dropped.
+    const doomed = new Set(m.nodes.filter((n) => n.layer === id).map((n) => n.id));
+    return {
+        ...m,
+        layers: m.layers.filter((l) => l.id !== id),
+        nodes: m.nodes.filter((n) => n.layer !== id),
+        relations: m.relations.filter((r) => r.layer !== id && !doomed.has(r.from) && !doomed.has(r.to)),
+        containment: m.containment.filter((e) => !doomed.has(e.parent) && !doomed.has(e.child)),
+        planes: (m.planes ?? []).map((p) => {
+            const touchesHides = [...(p.hides ?? []), ...(p.hidesTree ?? [])].some((h) => doomed.has(h));
+            if (p.layers === undefined && !touchesHides)
+                return p;
+            return {
+                ...p,
+                ...(p.layers !== undefined ? { layers: p.layers.filter((l) => l !== id) } : {}),
+                ...(p.hides !== undefined ? { hides: p.hides.filter((h) => !doomed.has(h)) } : {}),
+                ...(p.hidesTree !== undefined ? { hidesTree: p.hidesTree.filter((h) => !doomed.has(h)) } : {}),
+            };
+        }),
+    };
+}
+export function mergeLayers(m, sourceIds, targetId) {
+    if (targetId !== undefined && !m.layers.some((l) => l.id === targetId)) {
+        throw new CommandError(`Unknown layer '${targetId}'`);
+    }
+    for (const id of sourceIds) {
+        if (!m.layers.some((l) => l.id === id))
+            throw new CommandError(`Unknown layer '${id}'`);
+        if (id === targetId)
+            throw new CommandError('Cannot merge a layer into itself');
+    }
+    if (sourceIds.length === 0)
+        return m;
+    const sources = new Set(sourceIds);
+    // Retag a source-tagged node/relation onto the target, or drop the tag
+    // entirely when merging to the base sheet (targetId omitted).
+    const retag = (x) => {
+        if (x.layer === undefined || !sources.has(x.layer))
+            return x;
+        if (targetId === undefined) {
+            const { layer: _layer, ...rest } = x;
+            return rest;
+        }
+        return { ...x, layer: targetId };
+    };
+    return {
+        ...m,
+        layers: m.layers.filter((l) => !sources.has(l.id)),
+        nodes: m.nodes.map(retag),
+        relations: m.relations.map(retag),
+        planes: (m.planes ?? []).map((p) => {
+            if (p.layers === undefined)
+                return p;
+            const layers = targetId === undefined
+                ? p.layers.filter((l) => !sources.has(l))
+                : [...new Set(p.layers.map((l) => (sources.has(l) ? targetId : l)))];
+            return { ...p, layers };
+        }),
+    };
+}
+export function upsertPlane(m, plane) {
+    if (plane.notation !== undefined && !BUILTIN_NOTATIONS.includes(plane.notation)) {
+        throw new CommandError(`Unknown notation '${plane.notation}'`);
+    }
+    if (plane.containmentOf !== undefined) {
+        if (plane.containmentOf === plane.id) {
+            throw new CommandError(`Plane '${plane.id}' cannot borrow containment from itself`);
+        }
+        const target = (m.planes ?? []).find((p) => p.id === plane.containmentOf);
+        if (target === undefined) {
+            throw new CommandError(`Unknown plane '${plane.containmentOf}'`);
+        }
+        if (target.containmentOf !== undefined) {
+            throw new CommandError(`Plane '${plane.containmentOf}' itself borrows containment — chains are not allowed`);
+        }
+    }
+    const planes = m.planes ?? [];
+    const exists = planes.some((p) => p.id === plane.id);
+    return { ...m, planes: exists ? planes.map((p) => (p.id === plane.id ? plane : p)) : [...planes, plane] };
+}
+/** Add/remove a shared node from a plane's `hides`. A node already scoped to a
+ * plane is view-local, so hiding it is a no-op (validation flags a stray one). */
+export function setNodePlaneHidden(m, nodeId, planeId, hidden) {
+    const node = requireNode(m, nodeId);
+    if (hidden && node.plane !== undefined)
+        return m;
+    return {
+        ...m,
+        planes: (m.planes ?? []).map((p) => {
+            if (p.id !== planeId)
+                return p;
+            const set = new Set(p.hides ?? []);
+            if (hidden)
+                set.add(nodeId);
+            else
+                set.delete(nodeId);
+            const { hides: _drop, ...rest } = p;
+            return set.size > 0 ? { ...rest, hides: [...set] } : rest;
+        }),
+    };
+}
+export function deletePlane(m, id) {
+    const planes = m.planes ?? [];
+    if (!planes.some((p) => p.id === id))
+        throw new CommandError(`Unknown plane '${id}'`);
+    const borrower = planes.find((p) => p.containmentOf === id);
+    if (borrower !== undefined) {
+        throw new CommandError(`Plane '${borrower.id}' borrows containment from '${id}' — delete or repoint it first`);
+    }
+    // The first-declared plane owns the untagged (base) edges; drop them with it so
+    // structure doesn't silently migrate to whichever plane becomes first next.
+    const isFirst = planes[0]?.id === id;
+    return {
+        ...m,
+        planes: planes.filter((p) => p.id !== id),
+        containment: m.containment.filter((e) => e.plane !== id && !(isFirst && e.plane === undefined)),
+    };
+}

package/dist/second-order.d.ts

@@ -0,0 +1,39 @@
+import type { DiagramModel } from './types.js';
+/** The notation id a plane (or the model) declares to be drawn as a consequence tree. */
+export declare const SECOND_ORDER_NOTATION: "second-order";
+export declare const SO_DECISION_TYPE: "so-decision";
+/** Valence is a TYPE VARIANT, not a field: a registry and palette entry, no
+ * schema change — the same trick C4 uses for its `-external` stencils. */
+export declare const SO_CONSEQUENCE_TYPES: readonly ["so-consequence-positive", "so-consequence-negative", "so-consequence-neutral"];
+/** The kind the builder and the studio create. The derivation below does NOT
+ * filter by it (see consequenceOrders). */
+export declare const SO_LEADS_TO_KIND: "leads-to";
+/** good, bad, neutral */
+export type Valence = '+' | '-' | '0';
+export declare const consequenceTypeOf: (v: Valence) => string;
+export declare function valenceOf(type: string | undefined): Valence | undefined;
+export declare const isSecondOrderNode: (n: {
+    type?: string;
+}) => boolean;
+export interface ConsequenceOrders {
+    /** node id → order. A decision nothing leads to is 0. */
+    orders: ReadonlyMap<string, number>;
+    /** ids ON a loop, in declaration order, when there is one — `orders` is then empty */
+    cycle?: string[];
+    /** consequences no decision leads to, in declaration order — they get no order */
+    unreachable: string[];
+}
+/**
+ * Which band each decision and consequence belongs to. This is the ONE place
+ * that answers it, so the layout's partitions, the band overlay, the studio
+ * panel and validation cannot disagree.
+ *
+ * The order is the LONGEST path from a decision: every cause then sits in an
+ * earlier band than its effect, and no arrow ever runs inside a band — which is
+ * also exactly what lets elk take the orders as layer partitions.
+ *
+ * Reads the MODEL's relations, never drawn edges: toggling a layer must not
+ * move a box. Any kind of relation between two second-order nodes counts, so
+ * restyling an arrow can never drop a node out of its band. Never throws.
+ */
+export declare function consequenceOrders(model: DiagramModel): ConsequenceOrders;