@diagc/core 0.1.0

package/dist/compose.d.ts

@@ -0,0 +1,19 @@
+import type { DiagramModel } from './types.js';
+export interface IncludeSource {
+    model: DiagramModel;
+    /** canonical resolved ref (absolute URL/path) — cycle detection compares these */
+    ref: string;
+}
+export type IncludeResolver = (spec: string, fromRef: string) => Promise<IncludeSource>;
+export declare class IncludeError extends Error {
+    readonly spec: string;
+    constructor(spec: string, message: string);
+}
+export declare const MAX_INCLUDE_DEPTH = 10;
+/** Compile-time include expansion: nodes with `include` become containers for
+ * the referenced diagram's content (namespaced), then keyed nodes unify
+ * model-wide. Pure — all IO goes through the injected resolver. */
+export declare function composeIncludes(model: DiagramModel, ref: string, resolve: IncludeResolver): Promise<{
+    model: DiagramModel;
+    warnings: string[];
+}>;

package/dist/compose.js

@@ -0,0 +1,246 @@
+import { validate } from './validate.js';
+import { resolveContainmentPlane } from './view/compile.js';
+import { errMessage } from './util.js';
+export class IncludeError extends Error {
+    spec;
+    constructor(spec, message) {
+        super(message);
+        this.spec = spec;
+        this.name = 'IncludeError';
+    }
+}
+export const MAX_INCLUDE_DEPTH = 10;
+/** Compile-time include expansion: nodes with `include` become containers for
+ * the referenced diagram's content (namespaced), then keyed nodes unify
+ * model-wide. Pure — all IO goes through the injected resolver. */
+export async function composeIncludes(model, ref, resolve) {
+    const warnings = [];
+    const rootIds = new Set(model.nodes.map((n) => n.id));
+    const expanded = await expand(model, ref, [ref], resolve);
+    const unified = unifyKeys(expanded, rootIds, warnings);
+    return { model: stripIncludes(unified), warnings };
+}
+/** Composed output must be includable itself: strip `include` from every node so
+ * that including a published composed artifact grafts its content once instead of
+ * re-expanding it (which would either ENOENT resolving relative specs against the
+ * artifact's new location, or double-graft into duplicate ids). Retained `key`
+ * fields carry transitive identity onward across further composes. `includePlane`
+ * and `includePlanes` are graft-time-only options that travel with `include` and
+ * are stripped alongside it. */
+function stripIncludes(model) {
+    const has = (n) => n.include !== undefined || n.includePlane !== undefined || n.includePlanes !== undefined;
+    if (!model.nodes.some(has))
+        return model;
+    return {
+        ...model,
+        nodes: model.nodes.map((n) => {
+            if (!has(n))
+                return n;
+            const { include: _i, includePlane: _p, includePlanes: _ps, ...rest } = n;
+            return rest;
+        }),
+    };
+}
+async function expand(model, ref, path, resolve) {
+    if (path.length > MAX_INCLUDE_DEPTH) {
+        throw new IncludeError(ref, `Include depth exceeds ${MAX_INCLUDE_DEPTH}: ${path.join(' -> ')}`);
+    }
+    let out = {
+        ...model,
+        nodes: [...model.nodes],
+        containment: [...model.containment],
+        relations: [...model.relations],
+        layers: [...model.layers],
+        planes: [...model.planes],
+    };
+    for (const node of model.nodes) {
+        if (node.include === undefined)
+            continue;
+        let src;
+        try {
+            src = await resolve(node.include, ref);
+        }
+        catch (e) {
+            throw new IncludeError(node.include, `Include '${node.include}' (from ${ref}): ${errMessage(e)}`);
+        }
+        if (path.includes(src.ref)) {
+            throw new IncludeError(node.include, `Include cycle: ${[...path, src.ref].join(' -> ')}`);
+        }
+        const issues = validate(src.model);
+        if (issues.length > 0) {
+            throw new IncludeError(node.include, `Include '${node.include}' (from ${ref}) is invalid: ${issues.map((i) => i.message).join('; ')}`);
+        }
+        const child = await expand(src.model, src.ref, [...path, src.ref], resolve);
+        out = graft(out, node, child);
+    }
+    return out;
+}
+/** merge `child`'s content into `host` under `into`, namespaced by its id.
+ * Same-id layers unify with the host's; see the note inside. */
+function graft(host, into, child) {
+    const p = (id) => `${into.id}/${id}`;
+    if (into.includePlane !== undefined && !child.planes.some((pl) => pl.id === into.includePlane)) {
+        throw new IncludeError(into.include ?? into.id, `Include '${into.id}': plane '${into.includePlane}' not found in the included diagram`);
+    }
+    const defaultPlane = resolveContainmentPlane(child, undefined);
+    // the structural plane: the named one (resolved through containmentOf) or the default
+    const structural = resolveContainmentPlane(child, into.includePlane);
+    // Layers: an included layer whose id the host already declares merges into the
+    // host's layer (host name/tint win, no duplicate row); every other layer is
+    // namespaced like the nodes. Node and relation `layer` refs follow the same map.
+    const hostLayerIds = new Set(host.layers.map((l) => l.id));
+    const layerId = (id) => (hostLayerIds.has(id) ? id : p(id));
+    const nodes = child.nodes.map((n) => ({
+        ...n,
+        id: p(n.id),
+        ...(n.layer !== undefined ? { layer: layerId(n.layer) } : {}),
+    }));
+    // only the selected plane's structure comes along, imported untagged (default:
+    // the include's default plane, reproducing today's behavior unchanged)
+    const containment = child.containment
+        .filter((e) => (e.plane ?? defaultPlane) === structural)
+        .map((e) => ({ parent: p(e.parent), child: p(e.child) }));
+    // included roots (parentless in the selected plane) hang under the include node
+    const hasParent = new Set(containment.map((e) => e.child));
+    for (const n of nodes) {
+        if (!hasParent.has(n.id))
+            containment.push({ parent: into.id, child: n.id });
+    }
+    const layers = child.layers
+        .filter((l) => !hostLayerIds.has(l.id))
+        .map((l) => ({ ...l, id: p(l.id), name: `${into.name}/${l.name}` }));
+    const relations = child.relations.map((r) => ({
+        ...r,
+        id: p(r.id),
+        from: p(r.from),
+        to: p(r.to),
+        ...(r.layer !== undefined ? { layer: layerId(r.layer) } : {}),
+    }));
+    // Carried planes (opt-in): the include's planes come over namespaced with
+    // notation intact, so switching to one shows the child's content standalone
+    // in its own visual language. The child's default-plane rows land twice —
+    // untagged (host structure, unchanged behavior) and tagged for the carried
+    // plane — while already-tagged rows land tagged only (they were dropped
+    // entirely before this feature).
+    const carriedPlanes = [];
+    const carriedContainment = [];
+    if (into.includePlanes === true) {
+        if (child.planes.length > 0) {
+            for (const pl of child.planes) {
+                carriedPlanes.push({
+                    ...pl,
+                    id: p(pl.id),
+                    name: `${into.name}/${pl.name}`,
+                    ...(pl.containmentOf !== undefined ? { containmentOf: p(pl.containmentOf) } : {}),
+                    ...(pl.layers !== undefined ? { layers: pl.layers.map(layerId) } : {}),
+                    ...(pl.hides !== undefined ? { hides: pl.hides.map(p) } : {}),
+                    ...(pl.hidesTree !== undefined ? { hidesTree: pl.hidesTree.map(p) } : {}),
+                });
+            }
+            for (const e of child.containment) {
+                const plane = e.plane ?? defaultPlane;
+                if (plane === undefined)
+                    continue;
+                carriedContainment.push({ parent: p(e.parent), child: p(e.child), plane: p(plane) });
+            }
+        }
+        else if (child.notation !== undefined) {
+            // zero-plane child: synthesize one plane to carry the model-level notation
+            carriedPlanes.push({ id: p('main'), name: into.name, notation: child.notation });
+            for (const e of child.containment) {
+                carriedContainment.push({ parent: p(e.parent), child: p(e.child), plane: p('main') });
+            }
+        }
+    }
+    // If carried planes are landing on a host that declares none of its own, the
+    // FIRST carried plane would take `planes[0]` — the model's DEFAULT view.
+    // Untagged containment resolves to `planes[0]` too (buildHierarchy/gitGraph:
+    // `defaultPlane = planes[0]?.id`, matched via `(e.plane ?? defaultPlane) ===
+    // active`), so an unguarded carry would both silently retarget the default
+    // view onto the carried plane's content and leak the host's own untagged
+    // rows into it — and corrupt a further include's structural resolution the
+    // same way, since ITS `defaultPlane` would then resolve to the carried plane
+    // instead of the host's real structure. Synthesizing an explicit host base
+    // plane ahead of the carried ones keeps `planes[0]` a plain view of untagged
+    // content, exactly like a plane-less host today; carried planes start at
+    // index 1+ and see only their own tagged rows. A later sibling include's
+    // graft sees `host.planes.length > 0` by then and skips this.
+    const basePlane = host.planes.length === 0 && carriedPlanes.length > 0 ? [{ id: 'main', name: host.name }] : [];
+    // Everything not listed below is the HOST's — `...host` carries its `legend`,
+    // `typeColors` and `layerRules` and the child's are never read. Deliberate:
+    // those are presentation, and the diagram being looked at owns the look.
+    return {
+        ...host,
+        nodes: [...host.nodes, ...nodes],
+        containment: [...host.containment, ...containment, ...carriedContainment],
+        relations: [...host.relations, ...relations],
+        layers: [...host.layers, ...layers],
+        planes: [...host.planes, ...basePlane, ...carriedPlanes],
+    };
+}
+/** Global key pass: every keyed node unifies under its key as the composed id;
+ * all references are rewritten. Display attributes: an umbrella-authored
+ * declaration wins over includes; among includes, first encountered wins. */
+function unifyKeys(model, rootIds, warnings) {
+    const byKey = new Map();
+    for (const n of model.nodes) {
+        if (n.key === undefined)
+            continue;
+        byKey.set(n.key, [...(byKey.get(n.key) ?? []), n]);
+    }
+    if (byKey.size === 0)
+        return model;
+    const rename = new Map(); // old id -> key
+    const winners = new Map(); // key -> display-attribute source
+    for (const [key, members] of byKey) {
+        const occupant = model.nodes.find((n) => n.id === key && n.key === undefined);
+        if (occupant !== undefined) {
+            throw new IncludeError(key, `Key '${key}' collides with unrelated node id '${occupant.id}'`);
+        }
+        const winner = members.find((m) => rootIds.has(m.id)) ?? members[0];
+        if (winner === undefined)
+            continue; // unreachable: members is non-empty
+        winners.set(key, winner);
+        const shownType = (t) => (t === undefined ? 'no type' : `type '${t}'`);
+        for (const m of members) {
+            rename.set(m.id, key);
+            if (m.type !== winner.type) {
+                warnings.push(`Key '${key}': ${shownType(m.type)} (node '${m.id}') differs from ${shownType(winner.type)} (node '${winner.id}') — using ${shownType(winner.type)}`);
+            }
+        }
+    }
+    const mapId = (id) => rename.get(id) ?? id;
+    const emitted = new Set();
+    const nodes = [];
+    for (const n of model.nodes) {
+        if (n.key === undefined) {
+            nodes.push(n);
+            continue;
+        }
+        if (emitted.has(n.key))
+            continue; // one composed node per key, at first position
+        emitted.add(n.key);
+        const w = winners.get(n.key);
+        if (w !== undefined)
+            nodes.push({ ...w, id: n.key });
+    }
+    const seenEdges = new Set();
+    const containment = model.containment
+        .map((e) => ({ ...e, parent: mapId(e.parent), child: mapId(e.child) }))
+        .filter((e) => {
+        if (e.parent === e.child)
+            return false; // a keyed container including itself flattens out
+        const sig = `${e.parent}>${e.child}@${e.plane ?? ''}`;
+        if (seenEdges.has(sig))
+            return false;
+        seenEdges.add(sig);
+        return true;
+    });
+    const relations = model.relations.map((r) => ({ ...r, from: mapId(r.from), to: mapId(r.to) }));
+    const planes = model.planes.map((pl) => ({
+        ...pl,
+        ...(pl.hides !== undefined ? { hides: pl.hides.map(mapId) } : {}),
+        ...(pl.hidesTree !== undefined ? { hidesTree: pl.hidesTree.map(mapId) } : {}),
+    }));
+    return { ...model, nodes, containment, relations, planes };
+}

package/dist/drawings.d.ts

@@ -0,0 +1,13 @@
+import type { Drawings, Stroke } from './types.js';
+export declare const emptyDrawings: () => Drawings;
+/** `k1`, `k2`, … — first free id in this plane's bucket. A deterministic scan
+ * rather than a random id: stroke ids only need to be unique within one file,
+ * and a counter keeps the sidecar diff readable and the tests mock-free. */
+export declare function uniqueStrokeId(d: Drawings, key: string): string;
+export declare function addStroke(d: Drawings, key: string, stroke: Stroke): Drawings;
+/** An emptied bucket is dropped, mirroring set-layout-settings hygiene, so
+ * "does this plane have drawings?" stays a plain key lookup. */
+export declare function deleteStroke(d: Drawings, key: string, id: string): Drawings;
+/** Mirror hygiene for delete-plane. Returns the input unchanged when the
+ * plane had no bucket, so unrelated state stays referentially stable. */
+export declare function pruneDrawingsPlane(d: Drawings, plane: string): Drawings;

package/dist/drawings.js

@@ -0,0 +1,36 @@
+import { CommandError } from './mutate.js';
+export const emptyDrawings = () => ({ version: 1, planes: {} });
+/** `k1`, `k2`, … — first free id in this plane's bucket. A deterministic scan
+ * rather than a random id: stroke ids only need to be unique within one file,
+ * and a counter keeps the sidecar diff readable and the tests mock-free. */
+export function uniqueStrokeId(d, key) {
+    const taken = new Set((d.planes[key] ?? []).map((s) => s.id));
+    for (let i = 1;; i++) {
+        if (!taken.has(`k${i}`))
+            return `k${i}`;
+    }
+}
+export function addStroke(d, key, stroke) {
+    const bucket = d.planes[key] ?? [];
+    if (bucket.some((s) => s.id === stroke.id))
+        throw new CommandError(`Duplicate stroke id '${stroke.id}'`);
+    return { ...d, planes: { ...d.planes, [key]: [...bucket, stroke] } };
+}
+/** An emptied bucket is dropped, mirroring set-layout-settings hygiene, so
+ * "does this plane have drawings?" stays a plain key lookup. */
+export function deleteStroke(d, key, id) {
+    const bucket = d.planes[key];
+    if (bucket === undefined || !bucket.some((s) => s.id === id))
+        throw new CommandError(`Unknown stroke '${id}'`);
+    const kept = bucket.filter((s) => s.id !== id);
+    const { [key]: _drop, ...rest } = d.planes;
+    return { ...d, planes: kept.length > 0 ? { ...rest, [key]: kept } : rest };
+}
+/** Mirror hygiene for delete-plane. Returns the input unchanged when the
+ * plane had no bucket, so unrelated state stays referentially stable. */
+export function pruneDrawingsPlane(d, plane) {
+    if (!(plane in d.planes))
+        return d;
+    const { [plane]: _drop, ...rest } = d.planes;
+    return { ...d, planes: rest };
+}

package/dist/eject.d.ts

@@ -0,0 +1,20 @@
+import type { DiagramModel } from './types.js';
+/**
+ * Deterministic node-id → TS identifier assignment, first-come order.
+ * Separators camelCase the following segment; an id that cannot start an
+ * identifier is prefixed with 'n'; collisions and reserved words take the
+ * first free numeric suffix starting at 2.
+ */
+export declare function identifiersFor(ids: readonly string[]): Map<string, string>;
+/**
+ * A model value as TS source. Strings single-quoted; objects/arrays inline
+ * while their one-line form fits INLINE_LIMIT, multi-line (two-space steps,
+ * trailing commas) beyond it. Deterministic: key order is the object's own.
+ */
+export declare function tsLiteral(value: unknown, indent: number): string;
+/**
+ * The model as an idiomatic builder module. Sections in a fixed order, each in
+ * model-array order — exactly what ModelBuilder.toJSON() reassembles, so the
+ * emitted file reproduces the model through the builder.
+ */
+export declare function ejectSource(model: DiagramModel): string;

package/dist/eject.js

@@ -0,0 +1,260 @@
+/** JS reserved words plus the two bindings the emitted file itself declares. */
+const RESERVED = new Set([
+    'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger', 'default',
+    'delete', 'do', 'else', 'enum', 'export', 'extends', 'false', 'finally', 'for',
+    'function', 'if', 'import', 'in', 'instanceof', 'new', 'null', 'return',
+    'super', 'switch', 'this', 'throw', 'true', 'try', 'typeof', 'var', 'void',
+    'while', 'with', 'let', 'static', 'yield', 'await',
+    'm', 'model',
+]);
+/**
+ * Deterministic node-id → TS identifier assignment, first-come order.
+ * Separators camelCase the following segment; an id that cannot start an
+ * identifier is prefixed with 'n'; collisions and reserved words take the
+ * first free numeric suffix starting at 2.
+ */
+export function identifiersFor(ids) {
+    const taken = new Set();
+    const out = new Map();
+    for (const id of ids) {
+        const segments = id.split(/[^A-Za-z0-9]+/).filter((s) => s !== '');
+        let base = segments
+            .map((s, i) => (i === 0 ? s : (s[0] ?? '').toUpperCase() + s.slice(1)))
+            .join('');
+        if (base === '' || /^[0-9]/.test(base))
+            base = `n${base}`;
+        let ident = base;
+        for (let n = 2; RESERVED.has(ident) || taken.has(ident); n++)
+            ident = `${base}${n}`;
+        taken.add(ident);
+        out.set(id, ident);
+    }
+    return out;
+}
+const IDENT_KEY = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+/** How wide an inline object/array may render before it breaks across lines. */
+const INLINE_LIMIT = 72;
+function quote(s) {
+    return `'${s
+        .replace(/\\/g, '\\\\')
+        .replace(/'/g, "\\'")
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r')}'`;
+}
+/**
+ * A model value as TS source. Strings single-quoted; objects/arrays inline
+ * while their one-line form fits INLINE_LIMIT, multi-line (two-space steps,
+ * trailing commas) beyond it. Deterministic: key order is the object's own.
+ */
+export function tsLiteral(value, indent) {
+    if (typeof value === 'string')
+        return quote(value);
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    if (value === null)
+        return 'null';
+    const pad = '  '.repeat(indent);
+    const inner = '  '.repeat(indent + 1);
+    if (Array.isArray(value)) {
+        const items = value.map((v) => tsLiteral(v, indent + 1));
+        const inline = `[${items.join(', ')}]`;
+        if (inline.length <= INLINE_LIMIT && !inline.includes('\n'))
+            return inline;
+        return `[\n${items.map((i) => `${inner}${i},`).join('\n')}\n${pad}]`;
+    }
+    if (typeof value === 'object' && value !== null) {
+        const entries = Object.entries(value).map(([k, v]) => `${IDENT_KEY.test(k) ? k : quote(k)}: ${tsLiteral(v, indent + 1)}`);
+        if (entries.length === 0)
+            return '{}';
+        const inline = `{ ${entries.join(', ')} }`;
+        if (inline.length <= INLINE_LIMIT && !inline.includes('\n'))
+            return inline;
+        return `{\n${entries.map((e) => `${inner}${e},`).join('\n')}\n${pad}}`;
+    }
+    // null is handled above — it round-trips: pruneUndefined (builder.ts) strips
+    // only `undefined`, so a null survives the object spread and deep-equal
+    // holds. undefined never round-trips (JSON has no undefined), so it still
+    // throws here; a caller that can legitimately produce it (e.g. a missing
+    // required field in hand-edited JSON) must guard before calling tsLiteral.
+    throw new Error(`ejectSource: cannot emit a ${typeof value} literal`);
+}
+function quoted(s) {
+    return tsLiteral(s, 0);
+}
+/** NodeOpts emission order — mirrors the interface declaration in builder.ts. */
+const NODE_OPT_KEYS = [
+    'type', 'name', 'icon', 'shape', 'image', 'color', 'textColor', 'technology',
+    'link', 'description', 'rich', 'textAlign', 'fontScale', 'metadata', 'key', 'include',
+    'includePlane', 'includePlanes', 'plane', 'layer', 'columns', 'threats',
+];
+// Drift guard: a field added to DiagramNode without a matching entry above
+// fails this line at `pnpm typecheck` — a future model field silently
+// dropped by the emitter used to surface only as a runtime verify mismatch
+// (or, pre-I2b, a crash) at eject time. `id` is emitted explicitly, ahead of
+// the opts object, so it is excluded here.
+const _nodeOptCoverage = true;
+void _nodeOptCoverage;
+/** RelateOpts emission order (after the always-first `kind` and conditional `id`)
+ * — mirrors the interface declaration in builder.ts. */
+const RELATE_OPT_KEYS = [
+    'label', 'labels', 'style', 'description', 'layer', 'polarity', 'delay',
+    'fromColumn', 'toColumn', 'threats',
+];
+// Drift guard, same shape as _nodeOptCoverage above. `id` and `kind` are
+// emitted explicitly ahead of the opts object; `from`/`to` are the node refs
+// the call is built from, never opts entries — all four are excluded here.
+const _relateOptCoverage = true;
+void _relateOptCoverage;
+/** plane() opts emission order — mirrors ModelBuilder.plane's opts parameter. */
+const PLANE_OPT_KEYS = [
+    'name', 'containmentOf', 'layers', 'baseRelations', 'notation', 'hides', 'hidesTree',
+];
+// Drift guard, same shape as _nodeOptCoverage above. `id` is emitted
+// explicitly, ahead of the opts object.
+const _planeOptCoverage = true;
+void _planeOptCoverage;
+/** layer() opts emission order — mirrors ModelBuilder.layer's opts parameter. */
+const LAYER_OPT_KEYS = ['name', 'tint'];
+// Drift guard, same shape as _nodeOptCoverage above. `id` is emitted
+// explicitly, ahead of the opts object.
+const _layerOptCoverage = true;
+void _layerOptCoverage;
+/** Renders a trailing options object for a call, eliding it entirely when empty. */
+function opts(entries) {
+    if (entries.length === 0)
+        return '';
+    const rendered = entries.map(([k, v]) => `${k}: ${tsLiteral(v, 1)}`);
+    const inline = `{ ${rendered.join(', ')} }`;
+    if (inline.length <= INLINE_LIMIT && !inline.includes('\n'))
+        return `, ${inline}`;
+    return `, {\n${rendered.map((r) => `  ${r},`).join('\n')}\n}`;
+}
+function nodeOpts(n) {
+    const out = [];
+    for (const k of NODE_OPT_KEYS) {
+        if (k === 'name') {
+            // A validate-clean node can lack `name` (validate() does not require
+            // it, even though DiagramNode's TS type does) — a hand-edited JSON,
+            // typically. Emit without a name opt rather than pushing `undefined`;
+            // the builder then rebuilds `name: id`, and the deep-compare refuses
+            // honestly instead of the emitter crashing.
+            if (n.name !== undefined && n.name !== n.id)
+                out.push(['name', n.name]);
+            continue;
+        }
+        const v = n[k];
+        if (v !== undefined)
+            out.push([k, v]);
+    }
+    return out;
+}
+/**
+ * The model as an idiomatic builder module. Sections in a fixed order, each in
+ * model-array order — exactly what ModelBuilder.toJSON() reassembles, so the
+ * emitted file reproduces the model through the builder.
+ */
+export function ejectSource(model) {
+    const referenced = new Set();
+    for (const c of model.containment) {
+        referenced.add(c.parent);
+        referenced.add(c.child);
+    }
+    for (const r of model.relations) {
+        referenced.add(r.from);
+        referenced.add(r.to);
+    }
+    const idents = identifiersFor(model.nodes.filter((n) => referenced.has(n.id)).map((n) => n.id));
+    const sections = [];
+    if (model.planes.length > 0)
+        sections.push(model.planes.map((p) => {
+            const o = [];
+            for (const k of PLANE_OPT_KEYS) {
+                if (k === 'name') {
+                    if (p.name !== p.id)
+                        o.push(['name', p.name]);
+                    continue;
+                }
+                const v = p[k];
+                if (v !== undefined)
+                    o.push([k, v]);
+            }
+            return `m.plane(${quoted(p.id)}${opts(o)});`;
+        }));
+    if (model.layers.length > 0)
+        sections.push(model.layers.map((l) => {
+            const o = [];
+            for (const k of LAYER_OPT_KEYS) {
+                if (k === 'name') {
+                    if (l.name !== l.id)
+                        o.push(['name', l.name]);
+                    continue;
+                }
+                const v = l[k];
+                if (v !== undefined)
+                    o.push([k, v]);
+            }
+            return `m.layer(${quoted(l.id)}${opts(o)});`;
+        }));
+    if (model.nodes.length > 0)
+        sections.push(model.nodes.map((n) => {
+            const ident = idents.get(n.id);
+            const call = `m.node(${quoted(n.id)}${opts(nodeOpts(n))});`;
+            return ident !== undefined ? `const ${ident} = ${call}` : call;
+        }));
+    if (model.containment.length > 0) {
+        const groups = [];
+        for (const c of model.containment) {
+            const last = groups[groups.length - 1];
+            if (last !== undefined && last.parent === c.parent && last.plane === c.plane)
+                last.children.push(c.child);
+            else
+                groups.push({ parent: c.parent, plane: c.plane, children: [c.child] });
+        }
+        sections.push(groups.map((g) => {
+            const kids = g.children.map((c) => idents.get(c)).join(', ');
+            const plane = g.plane !== undefined ? `, { plane: ${quoted(g.plane)} }` : '';
+            return `${idents.get(g.parent)}.contains(${kids}${plane});`;
+        }));
+    }
+    if (model.relations.length > 0) {
+        const counters = new Map();
+        sections.push(model.relations.map((r) => {
+            const pair = `${r.from}->${r.to}`;
+            const n = counters.get(pair) ?? 0;
+            counters.set(pair, n + 1);
+            const o = [['kind', r.kind]];
+            if (r.id !== `${pair}#${n}`)
+                o.push(['id', r.id]);
+            for (const k of RELATE_OPT_KEYS) {
+                const v = r[k];
+                if (v !== undefined)
+                    o.push([k, v]);
+            }
+            // relate() requires opts (kind is mandatory), so opts() never returns ''.
+            return `m.relate(${idents.get(r.from)}, ${idents.get(r.to)}${opts(o)});`;
+        }));
+    }
+    const setters = [];
+    if (model.typeColors !== undefined)
+        setters.push(`m.typeColors(${tsLiteral(model.typeColors, 0)});`);
+    if (model.layerRules !== undefined)
+        setters.push(`m.layerRules(${tsLiteral(model.layerRules, 0)});`);
+    if (model.legend !== undefined)
+        setters.push(`m.legend(${tsLiteral(model.legend, 0)});`);
+    if (model.notation !== undefined)
+        setters.push(`m.notation(${quoted(model.notation)});`);
+    if (model.style !== undefined)
+        setters.push(`m.style(${quoted(model.style)});`);
+    if (setters.length > 0)
+        sections.push(setters);
+    const header = `const m = model(${quoted(model.id)}${model.name !== model.id ? `, { name: ${tsLiteral(model.name, 0)} }` : ''});`;
+    return [
+        ["import { model } from '@diagc/core';"],
+        [header],
+        ...sections,
+        ['export default m;'],
+    ]
+        .map((s) => s.join('\n'))
+        .join('\n\n')
+        .concat('\n');
+}

package/dist/fishbone.d.ts

@@ -0,0 +1,66 @@
+import type { DiagramModel } from './types.js';
+/** The notation id a plane (or the model) declares to be drawn as a fish. */
+export declare const FISHBONE_NOTATION: "fishbone";
+export declare const FB_EFFECT_TYPE: "fb-effect";
+export declare const FB_CATEGORY_TYPE: "fb-category";
+/** A cause and a sub-cause are ONE type: which it is comes from where it hangs
+ * (see fishboneTree), so promoting a sub-cause is a relation edit, not a type
+ * change, and nothing about a node can disagree with its place on the fish. */
+export declare const FB_CAUSE_TYPE: "fb-cause";
+export declare const FISHBONE_TYPES: readonly string[];
+/** The kind the builder and the studio create — from the cause TO what it
+ * explains. The derivation below does NOT filter by it (see fishboneTree). */
+export declare const FB_CAUSE_OF_KIND: "cause-of";
+export declare const isFishboneNode: (n: {
+    type?: string;
+}) => boolean;
+export type FishbonePreset = 'Software' | '6M' | '4S';
+/** Category sets an author can start from. Software first: it is what this
+ * tool is mostly used for; the classic manufacturing (6M) and service (4S) sets
+ * follow. The order of names is the order of bones. */
+export declare const FISHBONE_PRESETS: Record<FishbonePreset, readonly string[]>;
+export declare const FISHBONE_PRESET_NAMES: readonly FishbonePreset[];
+/** node id for a preset category name: 'Infrastructure' → 'infrastructure' */
+export declare const presetId: (name: string) => string;
+export interface FishboneCause {
+    id: string;
+    /** sub-causes, in relation order */
+    subs: string[];
+}
+export interface FishboneCategory {
+    id: string;
+    /** causes, in relation order */
+    causes: FishboneCause[];
+}
+export interface FishboneTree {
+    /** the head; absent when the model has none — with several, the first in node order (validation flags the rest) */
+    effect?: string;
+    /** major bones, in relation order */
+    categories: FishboneCategory[];
+    /** fishbone nodes NOT on the fish, in node order: no parent, a chain that never
+     * reaches the effect (a cycle included), a wrong-typed parent, a fourth level,
+     * a second effect. Validation says which; the layout only needs "on or off". */
+    unattached: string[];
+}
+/**
+ * The one definition of "hangs on": a fishbone node's parent is the `to` of
+ * its FIRST relation (declaration order) whose other end is also a fishbone
+ * node — any kind, so restyling an arrow can never drop a cause off its bone.
+ * Self-loops are skipped, and a relation whose ends aren't both fishbone
+ * nodes doesn't count as a parent pick. Shared by fishboneTree and
+ * validateFishbone (validate.ts) so the rule is defined exactly once.
+ */
+export declare function fishboneParents(model: DiagramModel): ReadonlyMap<string, string>;
+/**
+ * What hangs where. This is the ONE place that answers it, so the layout, the
+ * colour hooks, the studio panel and validation cannot disagree.
+ *
+ * Reads a node's parent via fishboneParents, then reads the fish top-down from
+ * the effect with the types checked at each level: only a category hangs on
+ * the effect, only a cause on a category, only a cause on a cause, and a
+ * sub-cause has no children.
+ *
+ * Reads the MODEL's relations, never drawn edges: toggling a layer must not
+ * move a box. Never throws.
+ */
+export declare function fishboneTree(model: DiagramModel): FishboneTree;