@diagc/core 0.1.0

package/dist/builder.js

@@ -0,0 +1,590 @@
+import { FB_CATEGORY_TYPE, FB_CAUSE_OF_KIND, FB_CAUSE_TYPE, FB_EFFECT_TYPE, FISHBONE_PRESETS, presetId } from './fishbone.js';
+import { GIT_STAGE_TYPE } from './git.js';
+import { SO_DECISION_TYPE, SO_LEADS_TO_KIND, consequenceTypeOf } from './second-order.js';
+import { TM_BOUNDARY_TYPE, TM_ENTITY_TYPE, TM_FLOW_KIND, TM_NOTATION, TM_PROCESS_TYPE, TM_STORE_TYPE, } from './threat-model.js';
+import { DiagramValidationError, validate } from './validate.js';
+export class NodeRef {
+    id;
+    builder;
+    constructor(id, builder) {
+        this.id = id;
+        this.builder = builder;
+    }
+    /** children, optionally followed by a trailing `{ plane }` options object */
+    contains(...args) {
+        const last = args[args.length - 1];
+        const opts = last !== undefined && !(last instanceof NodeRef) ? last : undefined;
+        for (const child of args) {
+            if (child instanceof NodeRef)
+                this.builder.addContainment(this.id, child.id, opts?.plane);
+        }
+        return this;
+    }
+    /** A STRIDE finding against this element. On every node ref, not just the
+     * threat-model ones: threat-modelling an existing C4 or ER diagram annotates
+     * the nodes it already has. */
+    threat(opts) {
+        this.builder.addThreat({ node: this.id }, opts);
+        return this;
+    }
+}
+export class CommitRef extends NodeRef {
+    branch;
+    constructor(id, builder, branch) {
+        super(id, builder);
+        this.branch = branch;
+    }
+}
+/** One lane of a git graph. `commit()` chains from the lane's last commit; `merge()`
+ * adds a commit that absorbs another lane's. Both hand back CommitRefs, which are
+ * NodeRefs — relate them, layer them, describe them like any node. */
+export class BranchRef extends NodeRef {
+    m;
+    count = 0;
+    latest;
+    constructor(id, m) {
+        super(id, m);
+        this.m = m;
+    }
+    commit(tagOrOpts = {}) {
+        const opts = typeof tagOrOpts === 'string' ? { tag: tagOrOpts } : tagOrOpts;
+        if (opts.from !== undefined && opts.from.branch === this) {
+            throw new Error(`branch '${this.id}': use commit() to continue a lane — 'from' must name a commit on another branch`);
+        }
+        const prev = this.latest;
+        const c = this.create(opts);
+        if (opts.from !== undefined)
+            this.m.relate(opts.from, c, { kind: 'branch' });
+        else if (prev !== undefined)
+            this.m.relate(prev, c, { kind: 'commit' });
+        return c;
+    }
+    merge(src, opts = {}) {
+        if (src.branch === this)
+            throw new Error(`branch '${this.id}': cannot merge a lane into itself`);
+        const prev = this.latest;
+        const c = this.create(opts);
+        this.m.relate(src, c, { kind: 'merge' });
+        if (prev !== undefined)
+            this.m.relate(prev, c, { kind: 'commit' });
+        return c;
+    }
+    create(opts) {
+        this.count += 1;
+        const id = opts.id ?? `${this.id}-${this.count}`;
+        this.m.node(id, {
+            type: 'commit',
+            name: opts.tag ?? '',
+            ...(opts.color !== undefined ? { color: opts.color } : {}),
+            ...(opts.gap !== undefined && opts.gap > 0 ? { metadata: { gap: opts.gap } } : {}),
+        });
+        this.m.addContainment(this.id, id);
+        const ref = new CommitRef(id, this.m, this);
+        this.latest = ref;
+        return ref;
+    }
+}
+export class GitGraphBuilder {
+    m;
+    constructor(m) {
+        this.m = m;
+    }
+    /** A named frame across every lane, spanning the columns of `from`…`to` —
+     * a phase of the history ("Development", "Release candidates"). Declare it
+     * after the commits it names. */
+    stage(id, opts) {
+        return this.m.node(id, {
+            type: GIT_STAGE_TYPE,
+            ...(opts.name !== undefined ? { name: opts.name } : {}),
+            ...(opts.color !== undefined ? { color: opts.color } : {}),
+            metadata: { from: opts.from.id, ...(opts.to !== undefined ? { to: opts.to.id } : {}) },
+        });
+    }
+    /** lanes are drawn top-to-bottom in the order they are declared */
+    branch(id, opts = {}) {
+        this.m.node(id, {
+            type: 'branch',
+            ...(opts.name !== undefined ? { name: opts.name } : {}),
+            ...(opts.color !== undefined ? { color: opts.color } : {}),
+        });
+        return new BranchRef(id, this.m);
+    }
+}
+/** A decision or a consequence. `then()` IS the method of second-order
+ * thinking — "and then what?" — so a chain of calls reads as the reasoning. */
+export class ConsequenceRef extends NodeRef {
+    m;
+    constructor(id, m) {
+        super(id, m);
+        this.m = m;
+    }
+    /** what follows from this: a new consequence, and the arrow that leads to it */
+    then(id, name, opts = {}) {
+        const { valence, label, ...rest } = opts;
+        this.m.node(id, { type: consequenceTypeOf(valence ?? '0'), ...(name !== undefined ? { name } : {}), ...rest });
+        const ref = new ConsequenceRef(id, this.m);
+        this.leadsTo(ref, label !== undefined ? { label } : {});
+        return ref;
+    }
+    /** join two branches: this also leads to a consequence declared elsewhere */
+    leadsTo(to, opts = {}) {
+        this.m.relate(this, to, { kind: SO_LEADS_TO_KIND, ...(opts.label !== undefined ? { label: opts.label } : {}) });
+        return this;
+    }
+}
+export class SecondOrderBuilder {
+    m;
+    constructor(m) {
+        this.m = m;
+    }
+    /** the root of a tree; several decisions share one set of bands */
+    decision(id, name, opts = {}) {
+        this.m.node(id, { type: SO_DECISION_TYPE, ...(name !== undefined ? { name } : {}), ...opts });
+        return new ConsequenceRef(id, this.m);
+    }
+}
+/** A cause (level 2) or a sub-cause (level 3). The level rides on the ref so a
+ * fourth `.cause()` fails at build time, where the author is, rather than as a
+ * validation issue at compile time. */
+export class CauseRef extends NodeRef {
+    m;
+    level;
+    constructor(id, m, level) {
+        super(id, m);
+        this.m = m;
+        this.level = level;
+    }
+    /** a sub-cause of this cause, and the arrow from it to here */
+    cause(id, name, opts = {}) {
+        if (this.level === 3) {
+            throw new Error(`fishbone: '${id}' would be a fourth level below the effect; three levels (category, cause, sub-cause) is the limit`);
+        }
+        this.m.node(id, { type: FB_CAUSE_TYPE, ...(name !== undefined ? { name } : {}), ...opts });
+        const ref = new CauseRef(id, this.m, 3);
+        this.m.relate(ref, this, { kind: FB_CAUSE_OF_KIND });
+        return ref;
+    }
+}
+export class CategoryRef extends NodeRef {
+    m;
+    constructor(id, m) {
+        super(id, m);
+        this.m = m;
+    }
+    /** a cause on this bone, and the arrow from it to here */
+    cause(id, name, opts = {}) {
+        this.m.node(id, { type: FB_CAUSE_TYPE, ...(name !== undefined ? { name } : {}), ...opts });
+        const ref = new CauseRef(id, this.m, 2);
+        this.m.relate(ref, this, { kind: FB_CAUSE_OF_KIND });
+        return ref;
+    }
+}
+export class FishboneBuilder {
+    m;
+    effect;
+    constructor(m, effect) {
+        this.m = m;
+        this.effect = effect;
+    }
+    /** a major bone, and the arrow from it to the effect */
+    category(id, name, opts = {}) {
+        this.m.node(id, { type: FB_CATEGORY_TYPE, ...(name !== undefined ? { name } : {}), ...opts });
+        const ref = new CategoryRef(id, this.m);
+        this.m.relate(ref, this.effect, { kind: FB_CAUSE_OF_KIND });
+        return ref;
+    }
+    /** the bones of a standard set, keyed by their slug ids (`presetId`) */
+    categories(preset) {
+        return Object.fromEntries(FISHBONE_PRESETS[preset].map((name) => {
+            const id = presetId(name);
+            return [id, this.category(id, name)];
+        }));
+    }
+}
+/** A data flow: a relation ref that takes threats, the way a NodeRef does. */
+export class FlowRef {
+    id;
+    m;
+    constructor(id, m) {
+        this.id = id;
+        this.m = m;
+    }
+    threat(opts) {
+        this.m.addThreat({ relation: this.id }, opts);
+        return this;
+    }
+}
+/** The four DFD element kinds plus flows. Everything it hands back is an
+ * ordinary NodeRef/FlowRef, so the rest of the builder — contains, relate,
+ * layers, threat — composes with it unchanged. */
+export class ThreatModelBuilder {
+    m;
+    constructor(m) {
+        this.m = m;
+    }
+    element(type, id, name, opts) {
+        return this.m.node(id, { type, ...(name !== undefined ? { name } : {}), ...opts });
+    }
+    /** an external entity: a user, a third party, anything outside the system */
+    entity(id, name, opts = {}) {
+        return this.element(TM_ENTITY_TYPE, id, name, opts);
+    }
+    /** a process: something the system does with the data */
+    process(id, name, opts = {}) {
+        return this.element(TM_PROCESS_TYPE, id, name, opts);
+    }
+    /** a data store: where the data rests */
+    store(id, name, opts = {}) {
+        return this.element(TM_STORE_TYPE, id, name, opts);
+    }
+    /** a trust boundary: nest elements with `.contains()` */
+    boundary(id, name, opts = {}) {
+        return this.element(TM_BOUNDARY_TYPE, id, name, opts);
+    }
+    /** a data flow; a string is its label */
+    flow(from, to, labelOrOpts = {}) {
+        const opts = typeof labelOrOpts === 'string' ? { label: labelOrOpts } : labelOrOpts;
+        return new FlowRef(this.m.addRelation(from, to, { kind: TM_FLOW_KIND, ...opts }), this.m);
+    }
+}
+/** Shared element surface of a lane and a region: each helper creates a typed
+ * node contained by this scope and hands back a plain NodeRef, so everything
+ * composes with the rest of the builder (relate, layers, contains). */
+export class ActivityScope extends NodeRef {
+    m;
+    counters = new Map();
+    constructor(id, m) {
+        super(id, m);
+        this.m = m;
+    }
+    /** `${scopeId}-<suffix>` for the first of a kind, `-<n>` after — deterministic
+     * from declaration order, so layout-overlay keys stay stable. */
+    autoId(suffix) {
+        const n = (this.counters.get(suffix) ?? 0) + 1;
+        this.counters.set(suffix, n);
+        return n === 1 ? `${this.id}-${suffix}` : `${this.id}-${suffix}-${n}`;
+    }
+    element(id, type, name, opts = {}) {
+        const ref = this.m.node(id, { type, name, ...(opts.color !== undefined ? { color: opts.color } : {}) });
+        this.m.addContainment(this.id, id);
+        return ref;
+    }
+    action(id, name, opts) {
+        return this.element(id, 'activity-action', name, opts);
+    }
+    object(id, name, opts) {
+        return this.element(id, 'activity-object', name, opts);
+    }
+    send(id, name, opts) {
+        return this.element(id, 'activity-send', name, opts);
+    }
+    receive(id, name, opts) {
+        return this.element(id, 'activity-receive', name, opts);
+    }
+    note(id, text) {
+        return this.element(id, 'activity-note', text);
+    }
+    decision(id, name = '') {
+        return this.element(id ?? this.autoId('decision'), 'activity-decision', name);
+    }
+    bar(id) {
+        return this.element(id ?? this.autoId('bar'), 'activity-bar', '');
+    }
+    start(id) {
+        return this.element(id ?? this.autoId('start'), 'activity-start', '');
+    }
+    end(id) {
+        return this.element(id ?? this.autoId('end'), 'activity-end', '');
+    }
+}
+export class RegionRef extends ActivityScope {
+}
+export class LaneRef extends ActivityScope {
+    /** interruptible region: a dashed container inside this lane */
+    region(id, name = '') {
+        const rid = id ?? this.autoId('region');
+        this.element(rid, 'activity-region', name);
+        return new RegionRef(rid, this.m);
+    }
+}
+/** One activity diagram: the frame node itself (this IS its NodeRef) plus lane
+ * and cross-lane flow helpers. Call m.activity() once per frame — several
+ * frames coexist on one canvas. */
+export class ActivityBuilder extends NodeRef {
+    b;
+    constructor(id, b) {
+        super(id, b);
+        this.b = b;
+    }
+    /** lanes are drawn top-to-bottom in the order they are declared */
+    lane(id, opts = {}) {
+        this.b.node(id, {
+            type: 'activity-lane',
+            ...(opts.name !== undefined ? { name: opts.name } : {}),
+            ...(opts.color !== undefined ? { color: opts.color } : {}),
+        });
+        this.b.addContainment(this.id, id);
+        return new LaneRef(id, this.b);
+    }
+    flow(from, to, label) {
+        this.b.relate(from, to, { kind: 'control', ...(label !== undefined ? { label } : {}) });
+        return this;
+    }
+    objectFlow(from, to, label) {
+        this.b.relate(from, to, { kind: 'object-flow', ...(label !== undefined ? { label } : {}) });
+        return this;
+    }
+    interrupt(from, to, label) {
+        this.b.relate(from, to, { kind: 'interrupt', ...(label !== undefined ? { label } : {}) });
+        return this;
+    }
+    noteLink(note, target) {
+        this.b.relate(note, target, { kind: 'note-link' });
+        return this;
+    }
+}
+export class ModelBuilder {
+    id;
+    name;
+    nodes = [];
+    containment = [];
+    relations = [];
+    layers = [];
+    planes = [];
+    legendConfig;
+    typeColorMap;
+    layerRuleList;
+    modelNotation;
+    modelStyle;
+    pairCounters = new Map();
+    git;
+    so;
+    fb;
+    tm;
+    constructor(id, name) {
+        this.id = id;
+        this.name = name;
+    }
+    node(id, opts = {}) {
+        const { name, ...rest } = opts;
+        this.nodes.push({ id, name: name ?? id, ...pruneUndefined(rest) });
+        return new NodeRef(id, this);
+    }
+    /** ER table: a node of type 'db-table' carrying `columns`. */
+    table(id, opts) {
+        return this.node(id, { type: 'db-table', ...opts });
+    }
+    /**
+     * Foreign key: a `kind:'fk'` relation from `from.fromColumn` to `to.toColumn`.
+     * `toColumn` defaults to the target table's single primary-key column; declare
+     * the target table (with its PK) before calling.
+     */
+    fk(from, fromColumn, to, toColumn, opts = {}) {
+        let resolved = toColumn;
+        if (resolved === undefined) {
+            const target = this.nodes.find((n) => n.id === to.id);
+            const pks = (target?.columns ?? []).filter((c) => c.pk === true);
+            if (pks.length !== 1) {
+                throw new Error(`m.fk: target table '${to.id}' must have exactly one primary-key column (or pass toColumn); found ${pks.length}`);
+            }
+            resolved = pks[0].name;
+        }
+        return this.relate(from, to, { kind: 'fk', ...opts, fromColumn, toColumn: resolved });
+    }
+    /** internal — used by NodeRef */
+    addContainment(parent, child, plane) {
+        const exists = this.containment.some((e) => e.parent === parent && e.child === child && e.plane === plane);
+        if (!exists)
+            this.containment.push({ parent, child, ...pruneUndefined({ plane }) });
+    }
+    /** internal — appends a threat to the node or relation `target` names; used by
+     * NodeRef.threat() and FlowRef.threat() */
+    addThreat(target, opts) {
+        const element = 'node' in target
+            ? this.nodes.find((n) => n.id === target.node)
+            : this.relations.find((r) => r.id === target.relation);
+        if (element === undefined) {
+            throw new Error('node' in target
+                ? `threat(): unknown node '${target.node}'`
+                : `threat(): unknown relation '${target.relation}'`);
+        }
+        const threats = element.threats ?? [];
+        const { id, category, title, ...rest } = opts;
+        // Synthesized from the list's length, not a model-wide counter: an id only
+        // has to be unique within its own element (see Threat.id), so two elements'
+        // first findings are both `t1` and neither shifts when the other changes.
+        const threat = { id: id ?? `t${threats.length + 1}`, category, title, ...pruneUndefined(rest) };
+        if (threats.some((t) => t.id === threat.id)) {
+            throw new Error(`threat(): duplicate threat id '${threat.id}' on '${element.id}'`);
+        }
+        element.threats = [...threats, threat];
+    }
+    relate(from, to, opts) {
+        this.addRelation(from, to, opts);
+        return this;
+    }
+    /** internal — like relate(), but returns the new relation's id (FlowRef needs
+     * it to hang threats off the flow) */
+    addRelation(from, to, opts) {
+        const pair = `${from.id}->${to.id}`;
+        const n = this.pairCounters.get(pair) ?? 0;
+        this.pairCounters.set(pair, n + 1);
+        const { kind, id, ...rest } = opts;
+        const relationId = id ?? `${pair}#${n}`;
+        this.relations.push({
+            id: relationId,
+            from: from.id,
+            to: to.id,
+            kind,
+            ...pruneUndefined(rest),
+        });
+        return relationId;
+    }
+    layer(id, opts = {}) {
+        this.layers.push({ id, name: opts.name ?? id, ...pruneUndefined({ tint: opts.tint }) });
+        return this;
+    }
+    plane(id, opts = {}) {
+        this.planes.push({
+            id,
+            name: opts.name ?? id,
+            ...pruneUndefined({
+                containmentOf: opts.containmentOf,
+                layers: opts.layers,
+                baseRelations: opts.baseRelations,
+                notation: opts.notation,
+                hides: opts.hides,
+                hidesTree: opts.hidesTree,
+            }),
+        });
+        return this;
+    }
+    /**
+     * Declare this model a git graph: a plane with the `git-graph` notation that
+     * must be the default (first-declared) plane, so the lanes' containment needs
+     * no plane tag. Returns the builder for lanes; see BranchRef.
+     */
+    gitGraph(opts = {}) {
+        if (this.git !== undefined)
+            throw new Error('gitGraph() already declared');
+        if (this.planes.length > 0) {
+            throw new Error('gitGraph() must come before plane(): the git plane has to be the default (first-declared) plane');
+        }
+        this.plane(opts.plane ?? 'git-graph', { name: opts.name ?? 'Git graph', notation: 'git-graph' });
+        this.git = new GitGraphBuilder(this);
+        return this.git;
+    }
+    /**
+     * Declare a second-order thinking diagram. With no `plane` the NOTATION is
+     * model-wide (nothing about it needs a plane — the notation is flat); name a
+     * plane to keep it beside other views of the same model.
+     */
+    secondOrder(opts = {}) {
+        if (this.so !== undefined)
+            throw new Error('secondOrder() already declared');
+        if (opts.plane !== undefined)
+            this.plane(opts.plane, { name: opts.name ?? 'Consequences', notation: 'second-order' });
+        else
+            this.notation('second-order');
+        this.so = new SecondOrderBuilder(this);
+        return this.so;
+    }
+    /**
+     * Declare a fishbone diagram: the effect at the head, then `.category()` /
+     * `.cause()` to hang bones on it. With no `plane` the NOTATION is model-wide
+     * (the notation is flat); name a plane to keep it beside other views of the
+     * same model. The effect's own options ride in `opts` too.
+     */
+    fishbone(id, name, opts = {}) {
+        if (this.fb !== undefined)
+            throw new Error('fishbone() already declared');
+        const { plane, planeName, ...rest } = opts;
+        if (plane !== undefined)
+            this.plane(plane, { name: planeName ?? 'Causes', notation: 'fishbone' });
+        else
+            this.notation('fishbone');
+        const effect = this.node(id, { type: FB_EFFECT_TYPE, ...(name !== undefined ? { name } : {}), ...rest });
+        this.fb = new FishboneBuilder(this, effect);
+        return this.fb;
+    }
+    /**
+     * Declare a threat model (STRIDE data-flow diagram). With no `plane` the
+     * NOTATION is model-wide; name a plane to threat-model an existing
+     * architecture beside its other views — the plane holds its own boundary
+     * containment over the same nodes.
+     */
+    threatModel(opts = {}) {
+        if (this.tm !== undefined)
+            throw new Error('threatModel() already declared');
+        if (opts.plane !== undefined)
+            this.plane(opts.plane, { name: opts.name ?? 'Threat model', notation: TM_NOTATION });
+        else
+            this.notation(TM_NOTATION);
+        this.tm = new ThreatModelBuilder(this);
+        return this.tm;
+    }
+    /** Declare an activity diagram: a framed swimlane flow. Repeatable — each
+     * call is one frame; frames are ordinary containers on whatever plane the
+     * model uses (no notation, no plane creation). */
+    activity(id, opts = {}) {
+        this.node(id, { type: 'activity-frame', ...(opts.name !== undefined ? { name: opts.name } : {}) });
+        return new ActivityBuilder(id, this);
+    }
+    /** Declare a legend. Bare `legend()` means derived sections only. */
+    legend(opts = {}) {
+        this.legendConfig = opts;
+        return this;
+    }
+    /** Default accent colour per node type; `*` is the fallback for the rest.
+     * The one way to colour nodes a composed diagram did not author. Successive
+     * calls merge, last wins per key; a node's own `color` still wins over both. */
+    typeColors(map) {
+        this.typeColorMap = { ...(this.typeColorMap ?? {}), ...map };
+        return this;
+    }
+    /** Put unlayered relations on layers by class (`kind` and/or `style.color`),
+     * first match wins. The one way a composed diagram can layer relations an
+     * include brought in. Successive calls append; an explicit relation `layer`
+     * still beats every rule. */
+    layerRules(rules) {
+        this.layerRuleList = [...(this.layerRuleList ?? []), ...rules];
+        return this;
+    }
+    /** pin the whole diagram's visual language (see DiagramModel.notation) */
+    notation(id) {
+        this.modelNotation = id;
+        return this;
+    }
+    /** pin the model-level renderer style preset (see DiagramModel.style) */
+    style(id) {
+        this.modelStyle = id;
+        return this;
+    }
+    toJSON() {
+        const json = {
+            version: 1,
+            id: this.id,
+            name: this.name,
+            nodes: this.nodes,
+            containment: this.containment,
+            relations: this.relations,
+            layers: this.layers,
+            planes: this.planes,
+            ...(this.legendConfig !== undefined ? { legend: this.legendConfig } : {}),
+            ...(this.typeColorMap !== undefined ? { typeColors: this.typeColorMap } : {}),
+            ...(this.layerRuleList !== undefined ? { layerRules: this.layerRuleList } : {}),
+            ...(this.modelNotation !== undefined ? { notation: this.modelNotation } : {}),
+            ...(this.modelStyle !== undefined ? { style: this.modelStyle } : {}),
+        };
+        const issues = validate(json);
+        if (issues.length > 0)
+            throw new DiagramValidationError(issues);
+        return json;
+    }
+}
+export function model(id, opts = {}) {
+    return new ModelBuilder(id, opts.name ?? id);
+}
+function pruneUndefined(obj) {
+    return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined));
+}

package/dist/children.d.ts

@@ -0,0 +1,21 @@
+import type { DiagramModel } from './types.js';
+import type { CompiledView } from './view/types.js';
+/**
+ * Build a parent → children index over a set of containment edges. Shared by the
+ * two cycle detectors — mutate's BFS-reachability guard (`wouldCycle`) and
+ * validate's DFS-coloring check (`findContainmentCycle`) — which agree on this
+ * map shape even though they walk it differently. Absent parents (nodes with no
+ * children) do not appear; callers read with `?? []`.
+ */
+export declare function childrenOf(edges: DiagramModel['containment']): Map<string, string[]>;
+/**
+ * Per-node hidden-descendant counts over a compiled view, for the collapse
+ * badge (`hiddenCount` on collapsed containers). A node's "hidden" set is
+ * exactly the model nodes that are not visible in the compiled view; each is
+ * attributed to the collapsed visible container that absorbed it. The compiled
+ * view does not expose anchors, so this approximates by subtree size: for a
+ * collapsed visible container, hidden descendants = reachable containment
+ * descendants that are not visible. Uses the shared `childrenOf` containment
+ * index — hierarchy knowledge lives in core, not the renderer.
+ */
+export declare function countAnchored(model: DiagramModel, view: CompiledView): Map<string, number>;

package/dist/children.js

@@ -0,0 +1,45 @@
+/**
+ * Build a parent → children index over a set of containment edges. Shared by the
+ * two cycle detectors — mutate's BFS-reachability guard (`wouldCycle`) and
+ * validate's DFS-coloring check (`findContainmentCycle`) — which agree on this
+ * map shape even though they walk it differently. Absent parents (nodes with no
+ * children) do not appear; callers read with `?? []`.
+ */
+export function childrenOf(edges) {
+    const children = new Map();
+    for (const e of edges) {
+        children.set(e.parent, [...(children.get(e.parent) ?? []), e.child]);
+    }
+    return children;
+}
+/**
+ * Per-node hidden-descendant counts over a compiled view, for the collapse
+ * badge (`hiddenCount` on collapsed containers). A node's "hidden" set is
+ * exactly the model nodes that are not visible in the compiled view; each is
+ * attributed to the collapsed visible container that absorbed it. The compiled
+ * view does not expose anchors, so this approximates by subtree size: for a
+ * collapsed visible container, hidden descendants = reachable containment
+ * descendants that are not visible. Uses the shared `childrenOf` containment
+ * index — hierarchy knowledge lives in core, not the renderer.
+ */
+export function countAnchored(model, view) {
+    const visible = new Set();
+    const walk = (n) => {
+        visible.add(n.id);
+        n.children.forEach(walk);
+    };
+    view.roots.forEach(walk);
+    const counts = new Map();
+    const children = childrenOf(model.containment);
+    const countHidden = (id) => {
+        let n = 0;
+        for (const c of children.get(id) ?? []) {
+            if (!visible.has(c))
+                n += 1 + countHidden(c);
+        }
+        return n;
+    };
+    for (const id of visible)
+        counts.set(id, countHidden(id));
+    return counts;
+}