@diagc/core 0.1.0

package/dist/view/compile.d.ts

@@ -0,0 +1,29 @@
+import { type DiagramModel, type DiagramPlane, type NotationId } from '../types.js';
+import type { CompiledView, ViewportState } from './types.js';
+/** which plane's containment edges a view of `planeId` uses (resolves containmentOf).
+ *  Kept here as the name the layout overlay is keyed by (see `layoutPlaneKey`);
+ *  the resolution itself lives with the hierarchy, which also needs it. */
+export declare function resolveContainmentPlane(m: DiagramModel, planeId?: string): string | undefined;
+/**
+ * The layers a host's own layer switch should START from: the plane's presets,
+ * with the plane resolved exactly as `compileView` resolves it (an absent id = the
+ * first-declared plane). Returns a fresh array, so host state never aliases the
+ * model's own `layers`.
+ *
+ * A host that shows layer toggles must seed with this — on load and on every
+ * plane change — and pass its state as `ViewportState.activeLayers` from then on.
+ * Seeding is what keeps "presets are the default" and "the user can turn a preset
+ * off" from being contradictory: the default arrives once, as state, instead of
+ * being re-applied underneath the user on every compile.
+ */
+export declare function presetLayers(planes: readonly DiagramPlane[], plane?: string): string[];
+/**
+ * The visual language of the view being shown: the resolved plane's `notation`
+ * (an absent id = the first-declared plane, matching `compileView`). An
+ * unrecognized id falls back to the default look (`undefined`) instead of
+ * erroring — both the studio and the published viewer resolve it this way, so
+ * an editable diagram and its published page always agree. `fallback` is the
+ * model-level notation, used when the resolved plane declares none.
+ */
+export declare function activeNotation(planes: readonly DiagramPlane[], plane?: string, fallback?: string): NotationId | undefined;
+export declare function compileView(m: DiagramModel, viewport: ViewportState): CompiledView;

package/dist/view/compile.js

@@ -0,0 +1,78 @@
+import { BUILTIN_NOTATIONS } from '../types.js';
+import { buildHierarchy, containmentPlaneOf } from './hierarchy.js';
+import { computeLod } from './lod.js';
+import { buildViewTree } from './tree.js';
+import { resolveEdges } from './edges.js';
+import { scopeToRoot } from './scope.js';
+/** which plane's containment edges a view of `planeId` uses (resolves containmentOf).
+ *  Kept here as the name the layout overlay is keyed by (see `layoutPlaneKey`);
+ *  the resolution itself lives with the hierarchy, which also needs it. */
+export function resolveContainmentPlane(m, planeId) {
+    return containmentPlaneOf(m, planeId);
+}
+/**
+ * The layers a host's own layer switch should START from: the plane's presets,
+ * with the plane resolved exactly as `compileView` resolves it (an absent id = the
+ * first-declared plane). Returns a fresh array, so host state never aliases the
+ * model's own `layers`.
+ *
+ * A host that shows layer toggles must seed with this — on load and on every
+ * plane change — and pass its state as `ViewportState.activeLayers` from then on.
+ * Seeding is what keeps "presets are the default" and "the user can turn a preset
+ * off" from being contradictory: the default arrives once, as state, instead of
+ * being re-applied underneath the user on every compile.
+ */
+export function presetLayers(planes, plane) {
+    const p = plane !== undefined ? planes.find((x) => x.id === plane) : planes[0];
+    return [...(p?.layers ?? [])];
+}
+/**
+ * The visual language of the view being shown: the resolved plane's `notation`
+ * (an absent id = the first-declared plane, matching `compileView`). An
+ * unrecognized id falls back to the default look (`undefined`) instead of
+ * erroring — both the studio and the published viewer resolve it this way, so
+ * an editable diagram and its published page always agree. `fallback` is the
+ * model-level notation, used when the resolved plane declares none.
+ */
+export function activeNotation(planes, plane, fallback) {
+    const p = plane !== undefined ? planes.find((x) => x.id === plane) : planes[0];
+    const id = p?.notation ?? fallback;
+    return id !== undefined && BUILTIN_NOTATIONS.includes(id) ? id : undefined;
+}
+export function compileView(m, viewport) {
+    const planes = m.planes ?? [];
+    const plane = viewport.plane !== undefined ? planes.find((p) => p.id === viewport.plane) : planes[0];
+    // A plane's `layers` are the DEFAULT, not a floor: `activeLayers` undefined
+    // means the host has no opinion, so the plane's presets apply; an array — even
+    // an empty one — is the host's own choice and replaces them. Unioning the two
+    // (what this did until the layer switch existed) made a preset layer
+    // impossible to turn off, so a host with toggles seeds its state from
+    // `plane.layers` and owns it from then on.
+    const activeLayers = viewport.activeLayers ?? plane?.layers ?? [];
+    const activeLayerSet = new Set(activeLayers);
+    // The plane being viewed, not its containment donor: buildHierarchy resolves
+    // `containmentOf` itself, and needs the viewed plane to read its `hides`.
+    const hierarchy = buildHierarchy(m, viewport.plane, activeLayerSet);
+    // Isolated drill view: swap in a model scoped to root's interior (+ external
+    // stubs), then run the standard pipeline over it so LOD, promotion and edge
+    // aggregation all work unchanged.
+    if (viewport.root !== undefined && hierarchy.childrenOf.has(viewport.root)) {
+        const scoped = scopeToRoot(m, hierarchy, viewport.root);
+        const sh = buildHierarchy(scoped.model, undefined, activeLayerSet);
+        const lod = computeLod({ hierarchy: sh, focus: viewport.focus, pins: viewport.pins });
+        const tree = buildViewTree(scoped.model, sh, lod);
+        for (const [stubId, rep] of scoped.externals) {
+            const vn = tree.byId.get(stubId);
+            if (vn !== undefined)
+                vn.external = rep;
+        }
+        const edges = resolveEdges(scoped.model, tree, activeLayers, plane?.baseRelations ?? true);
+        const layoutEdges = resolveEdges(scoped.model, tree, scoped.model.layers.map((l) => l.id), true);
+        return { roots: tree.roots, edges, layoutEdges, lod, externals: scoped.externals };
+    }
+    const lod = computeLod({ hierarchy, focus: viewport.focus, pins: viewport.pins });
+    const tree = buildViewTree(m, hierarchy, lod);
+    const edges = resolveEdges(m, tree, activeLayers, plane?.baseRelations ?? true);
+    const layoutEdges = resolveEdges(m, tree, m.layers.map((l) => l.id), true);
+    return { roots: tree.roots, edges, layoutEdges, lod };
+}

package/dist/view/edges.d.ts

@@ -0,0 +1,4 @@
+import type { DiagramModel } from '../types.js';
+import type { ViewTree } from './tree.js';
+import type { ViewEdge } from './types.js';
+export declare function resolveEdges(m: DiagramModel, tree: ViewTree, activeLayers?: string[], includeBase?: boolean): ViewEdge[];

package/dist/view/edges.js

@@ -0,0 +1,118 @@
+import { relationLabels } from '../labels.js';
+import { relationLayer } from './layers.js';
+/** the shared polarity of a set of relations: that sign iff every relation is
+ *  defined and agrees; otherwise undefined (any missing or disagreeing sign) */
+function combinePolarity(rels) {
+    let result;
+    for (const r of rels) {
+        if (r.polarity === undefined)
+            return undefined;
+        if (result === undefined)
+            result = r.polarity;
+        else if (result !== r.polarity)
+            return undefined;
+    }
+    return result;
+}
+/**
+ * Width budget, in characters, for the joined labels of an AGGREGATE edge (one
+ * arrow standing for several relations). Above it the edge reports how many
+ * relations it rolled up instead of naming them.
+ *
+ * The budget is on the joined text, not on a label count, because what makes a
+ * folded view unreadable is text WIDTH on many edges at once: measured on
+ * a production C4 landscape (17 folded systems, ~400 relations), the
+ * old "first three joined, then +N" policy put 40-70 characters on hundreds of
+ * arrows. 32 characters is about two ordinary labels ("reads / writes",
+ * "publishes / consumes") — the case where naming both is genuinely more useful
+ * than counting them. Nothing is lost above it: the constituents are one fold, or
+ * one click on the edge, away.
+ */
+const AGG_LABEL_BUDGET = 32;
+export function resolveEdges(m, tree, activeLayers, includeBase = true) {
+    const active = new Set(activeLayers ?? []);
+    const tintOf = new Map(m.layers.map((l) => [l.id, l.tint]));
+    const anchorFor = (id) => tree.byId.has(id) ? id : tree.anchorOf.get(id);
+    // Effective layer: the relation's own, else what `layerRules` assigns.
+    const layerOf = (r) => relationLayer(m, r);
+    const groups = new Map();
+    for (const r of m.relations) {
+        const layer = layerOf(r);
+        if (layer === undefined ? !includeBase : !active.has(layer))
+            continue;
+        const from = anchorFor(r.from);
+        const to = anchorFor(r.to);
+        if (from === undefined || to === undefined)
+            continue;
+        const isOriginalSelfLoop = r.from === r.to;
+        if (from === to && !(isOriginalSelfLoop && tree.byId.has(r.from)))
+            continue;
+        // Two arrows between the same pair pinned to *different* border sides are
+        // visually distinct, so keep them apart (like opposite directions already
+        // are). Pins only count when the relation attaches directly to the anchor —
+        // a relation rolled up to a container was pinned on its child, not the
+        // container, so it must still aggregate into the one boundary edge.
+        const direct = from === r.from && to === r.to;
+        const fromSide = direct ? r.style?.fromSide : undefined;
+        const toSide = direct ? r.style?.toSide : undefined;
+        const pinKey = fromSide !== undefined || toSide !== undefined ? `:${fromSide ?? ''}>${toSide ?? ''}` : '';
+        const key = `${from}=>${to}:${layer ?? ''}${pinKey}`;
+        const group = groups.get(key) ?? { from, to, layer, rels: [] };
+        group.rels.push(r);
+        groups.set(key, group);
+    }
+    return [...groups.entries()].map(([key, g]) => {
+        const kinds = new Set(g.rels.map((r) => r.kind));
+        const single = g.rels.length === 1 ? g.rels[0] : undefined;
+        const edge = {
+            id: key,
+            from: g.from,
+            to: g.to,
+            kind: kinds.size === 1 ? g.rels[0].kind : 'mixed',
+            constituents: g.rels,
+        };
+        if (single !== undefined) {
+            const labels = relationLabels(single);
+            if (labels.length > 0)
+                edge.labels = labels;
+        }
+        else {
+            // Multi-relation aggregate: name the constituents while that is still
+            // cheaper to read than counting them, and count them once it is not.
+            const seen = new Set();
+            const distinct = [];
+            for (const r of g.rels) {
+                for (const l of relationLabels(r)) {
+                    const t = l.text.trim();
+                    if (t !== '' && !seen.has(t)) {
+                        seen.add(t);
+                        distinct.push(t);
+                    }
+                }
+            }
+            const joined = distinct.join(' / ');
+            // ONE distinct label is the edge's own meaning however long it is (the
+            // renderer ellipsises it), so it always survives; several only earn their
+            // width while the join stays inside AGG_LABEL_BUDGET. An aggregate here
+            // always holds at least two relations, so the plural is always right.
+            edge.label =
+                distinct.length === 1 || (distinct.length > 1 && joined.length <= AGG_LABEL_BUDGET)
+                    ? joined
+                    : `${g.rels.length} relations`;
+        }
+        if (single?.style !== undefined)
+            edge.style = single.style;
+        const polarity = combinePolarity(g.rels);
+        if (polarity !== undefined)
+            edge.polarity = polarity;
+        if (single?.delay !== undefined)
+            edge.delay = single.delay;
+        if (g.layer !== undefined) {
+            edge.layer = g.layer;
+            const tint = tintOf.get(g.layer);
+            if (tint !== undefined)
+                edge.tint = tint;
+        }
+        return edge;
+    });
+}

package/dist/view/hierarchy.d.ts

@@ -0,0 +1,41 @@
+import type { DiagramModel } from '../types.js';
+export interface HierarchyIndex {
+    parentsOf: Map<string, string[]>;
+    childrenOf: Map<string, string[]>;
+    roots: string[];
+}
+/** Which plane's containment edges a view of `planeId` uses (resolves
+ *  `containmentOf`, one hop — chains are a validation error). */
+export declare function containmentPlaneOf(m: DiagramModel, planeId?: string): string | undefined;
+/**
+ * Containment indexes for one plane, over the plane's VISIBLE nodes only.
+ * Visibility is explicit: a node is shared (`node.plane` unset) and shown unless
+ * the plane hides it, or it is scoped to exactly this plane. Re-nesting via a
+ * plane-tagged containment edge never changes membership. `plane` = the plane
+ * being VIEWED; omitted = the model's default (first-declared) plane, or
+ * all-shared for models without planes.
+ *
+ * A plane with `containmentOf` borrows the donor's containment edges, and
+ * `node.plane` scopes are matched against the DONOR (a node pinned to the
+ * borrowing plane is not in the donor's hierarchy — see the how-to). `hides` and
+ * `hidesTree` are the exception: they are visibility choices, not structure, so
+ * each is the borrower's own when it declares that field, and the donor's when it
+ * does not (declare `hidesTree: []` to borrow a hierarchy and keep the detail the
+ * donor drops).
+ *
+ * The two hide lists differ in what happens to the contents:
+ *   - `hides` promotes them. A hidden box's children take its place, each with
+ *     its own nesting intact. Composition depends on this: an umbrella hides the
+ *     `include` wrapper to lift a whole service model into position.
+ *   - `hidesTree` takes them with it, however deep — unless another still-visible
+ *     box also contains a child, which keeps that child (containment is a DAG).
+ * A node with no parent on this plane is a root and neither list can reach it
+ * except by naming it.
+ *
+ * A node tagged with a transparent-sheet `layer` is visible only while that layer
+ * is active; untagged nodes are the always-on base sheet. `activeLayers` omitted =
+ * no layer filtering (every layer treated as on). Layers deliberately do NOT
+ * cascade: a layer is an overlay you flip, and its children keep their own
+ * visibility, so a layered box still promotes its interior when it is off.
+ */
+export declare function buildHierarchy(m: DiagramModel, plane?: string, activeLayers?: ReadonlySet<string>): HierarchyIndex;

package/dist/view/hierarchy.js

@@ -0,0 +1,103 @@
+/** Which plane's containment edges a view of `planeId` uses (resolves
+ *  `containmentOf`, one hop — chains are a validation error). */
+export function containmentPlaneOf(m, planeId) {
+    const planes = m.planes ?? [];
+    const plane = planeId !== undefined ? planes.find((p) => p.id === planeId) : planes[0];
+    return plane?.containmentOf ?? plane?.id;
+}
+/**
+ * Containment indexes for one plane, over the plane's VISIBLE nodes only.
+ * Visibility is explicit: a node is shared (`node.plane` unset) and shown unless
+ * the plane hides it, or it is scoped to exactly this plane. Re-nesting via a
+ * plane-tagged containment edge never changes membership. `plane` = the plane
+ * being VIEWED; omitted = the model's default (first-declared) plane, or
+ * all-shared for models without planes.
+ *
+ * A plane with `containmentOf` borrows the donor's containment edges, and
+ * `node.plane` scopes are matched against the DONOR (a node pinned to the
+ * borrowing plane is not in the donor's hierarchy — see the how-to). `hides` and
+ * `hidesTree` are the exception: they are visibility choices, not structure, so
+ * each is the borrower's own when it declares that field, and the donor's when it
+ * does not (declare `hidesTree: []` to borrow a hierarchy and keep the detail the
+ * donor drops).
+ *
+ * The two hide lists differ in what happens to the contents:
+ *   - `hides` promotes them. A hidden box's children take its place, each with
+ *     its own nesting intact. Composition depends on this: an umbrella hides the
+ *     `include` wrapper to lift a whole service model into position.
+ *   - `hidesTree` takes them with it, however deep — unless another still-visible
+ *     box also contains a child, which keeps that child (containment is a DAG).
+ * A node with no parent on this plane is a root and neither list can reach it
+ * except by naming it.
+ *
+ * A node tagged with a transparent-sheet `layer` is visible only while that layer
+ * is active; untagged nodes are the always-on base sheet. `activeLayers` omitted =
+ * no layer filtering (every layer treated as on). Layers deliberately do NOT
+ * cascade: a layer is an overlay you flip, and its children keep their own
+ * visibility, so a layered box still promotes its interior when it is off.
+ */
+export function buildHierarchy(m, plane, activeLayers) {
+    const planes = m.planes ?? [];
+    const defaultPlane = planes[0]?.id;
+    // `?? plane` keeps an unknown plane id behaving as it always did (an empty
+    // view) instead of falling back to every containment edge in the model.
+    const active = containmentPlaneOf(m, plane) ?? plane ?? defaultPlane;
+    const viewDef = plane !== undefined ? planes.find((p) => p.id === plane) : planes[0];
+    const donorDef = active !== undefined ? planes.find((p) => p.id === active) : undefined;
+    const hides = new Set(viewDef?.hides ?? donorDef?.hides ?? []);
+    const hidesTree = new Set(viewDef?.hidesTree ?? donorDef?.hidesTree ?? []);
+    // This plane's containment BEFORE any visibility filtering: the cascade has to
+    // see the edges that point into a hidden box to know what it contained.
+    const planeEdges = active === undefined ? m.containment : m.containment.filter((e) => (e.plane ?? defaultPlane) === active);
+    // The `hidesTree` closure. Only `hidesTree` ids SEED it, but a parent hidden
+    // either way counts as hidden when deciding whether a child has any visible
+    // parent left. Ids of plane-scoped nodes are dropped: such a node ignores
+    // `hides` (validate.ts reports that as `redundant-hide`), so it must not seed
+    // the closure either. Derived hiding applies to every node, scoped ones
+    // included — "nothing visible contains me any more".
+    const scopedIds = new Set(m.nodes.filter((n) => n.plane !== undefined).map((n) => n.id));
+    const shared = (id) => !scopedIds.has(id);
+    const hidden = new Set([...hides, ...hidesTree].filter(shared));
+    const parentsAll = new Map();
+    const childrenAll = new Map();
+    const push = (map, key, value) => {
+        const list = map.get(key);
+        if (list === undefined)
+            map.set(key, [value]);
+        else
+            list.push(value);
+    };
+    for (const e of planeEdges) {
+        push(parentsAll, e.child, e.parent);
+        push(childrenAll, e.parent, e.child);
+    }
+    const queue = [...hidesTree].filter(shared);
+    for (let i = 0; i < queue.length; i++) {
+        for (const child of childrenAll.get(queue[i]) ?? []) {
+            if (hidden.has(child))
+                continue;
+            if ((parentsAll.get(child) ?? []).every((p) => hidden.has(p))) {
+                hidden.add(child);
+                queue.push(child);
+            }
+        }
+    }
+    const layerOn = (n) => n.layer === undefined || activeLayers === undefined || activeLayers.has(n.layer);
+    const isVisible = (n) => (n.plane === undefined || n.plane === active) && !hidden.has(n.id) && layerOn(n);
+    const visible = new Set(m.nodes.filter(isVisible).map((n) => n.id));
+    const edges = planeEdges.filter((e) => visible.has(e.parent) && visible.has(e.child));
+    const parentsOf = new Map();
+    const childrenOf = new Map();
+    for (const id of visible) {
+        parentsOf.set(id, []);
+        childrenOf.set(id, []);
+    }
+    for (const e of edges) {
+        childrenOf.get(e.parent)?.push(e.child);
+        parentsOf.get(e.child)?.push(e.parent);
+    }
+    const roots = m.nodes
+        .filter((n) => visible.has(n.id) && (parentsOf.get(n.id)?.length ?? 0) === 0)
+        .map((n) => n.id);
+    return { parentsOf, childrenOf, roots };
+}

package/dist/view/layers.d.ts

@@ -0,0 +1,7 @@
+import type { DiagramModel, DiagramRelation } from '../types.js';
+/** The layer a relation is drawn on: its own `layer`, else the first
+ * `layerRules` entry whose every named field (`kind`, `style.color`) matches,
+ * else undefined (the base sheet). Rules exist so a host can layer relations
+ * that arrived through an include; they never override an explicit layer.
+ * One function, so the view compiler and the legend cannot disagree. */
+export declare function relationLayer(m: DiagramModel, r: DiagramRelation): string | undefined;

package/dist/view/layers.js

@@ -0,0 +1,17 @@
+/** The layer a relation is drawn on: its own `layer`, else the first
+ * `layerRules` entry whose every named field (`kind`, `style.color`) matches,
+ * else undefined (the base sheet). Rules exist so a host can layer relations
+ * that arrived through an include; they never override an explicit layer.
+ * One function, so the view compiler and the legend cannot disagree. */
+export function relationLayer(m, r) {
+    if (r.layer !== undefined)
+        return r.layer;
+    for (const rule of m.layerRules ?? []) {
+        if (rule.kind !== undefined && rule.kind !== r.kind)
+            continue;
+        if (rule.color !== undefined && rule.color !== r.style?.color)
+            continue;
+        return rule.layer;
+    }
+    return undefined;
+}

package/dist/view/lod.d.ts

@@ -0,0 +1,15 @@
+import type { HierarchyIndex } from './hierarchy.js';
+import type { LodState } from './types.js';
+export interface LodInput {
+    hierarchy: HierarchyIndex;
+    /** ids of the containers the user is zoomed into (an ancestor chain, but any set works) */
+    focus?: string[];
+    pins?: Record<string, 'expanded' | 'collapsed'>;
+}
+/**
+ * Focus-driven LOD: the diagram rests fully folded — every container renders
+ * as a single box — and only pinned-expanded containers plus the focus chain
+ * (what the viewer is zoomed into, computed by the renderer from the actual
+ * viewport) expand. Pins always win over focus.
+ */
+export declare function computeLod(input: LodInput): LodState;

package/dist/view/lod.js

@@ -0,0 +1,17 @@
+/**
+ * Focus-driven LOD: the diagram rests fully folded — every container renders
+ * as a single box — and only pinned-expanded containers plus the focus chain
+ * (what the viewer is zoomed into, computed by the renderer from the actual
+ * viewport) expand. Pins always win over focus.
+ */
+export function computeLod(input) {
+    const out = {};
+    const focus = new Set(input.focus ?? []);
+    for (const [id, kids] of input.hierarchy.childrenOf) {
+        if (kids.length === 0)
+            continue;
+        const pin = input.pins?.[id];
+        out[id] = pin ?? (focus.has(id) ? 'expanded' : 'collapsed');
+    }
+    return out;
+}

package/dist/view/scope.d.ts

@@ -0,0 +1,23 @@
+import type { DiagramModel } from '../types.js';
+import type { HierarchyIndex } from './hierarchy.js';
+/** Reserved id prefix for external stub nodes (the off-frame node a boundary-
+ *  crossing edge points to in an isolated drill view). The `__ext__:` prefix keeps it from
+ *  ever colliding with a real, author-authored node id. */
+export declare const EXTERNAL_STUB_PREFIX = "__ext__:";
+export interface ScopedModel {
+    /** synthetic model: the drill root's descendants + external stubs, with
+     *  boundary-crossing relations re-pointed to those stubs */
+    model: DiagramModel;
+    /** stub node id -> the real off-frame node it stands in for */
+    externals: Map<string, string>;
+}
+/**
+ * Scope a model to the INTERIOR of `root` for an isolated drill view: keep only
+ * root's descendants (root's own children become the parentless top level), drop
+ * relations wholly outside, keep internal ones, and re-point each boundary-crossing
+ * relation to a stub node standing in for the off-frame endpoint's outermost
+ * ancestor OUTSIDE the drill root's own ancestor chain (so "a class uses the
+ * database" stays visible as class → ⟨Database⟩, and a sibling of the root stands
+ * for itself rather than collapsing into the ancestor both sides share).
+ */
+export declare function scopeToRoot(m: DiagramModel, h: HierarchyIndex, root: string): ScopedModel;

package/dist/view/scope.js

@@ -0,0 +1,106 @@
+/** Reserved id prefix for external stub nodes (the off-frame node a boundary-
+ *  crossing edge points to in an isolated drill view). The `__ext__:` prefix keeps it from
+ *  ever colliding with a real, author-authored node id. */
+export const EXTERNAL_STUB_PREFIX = '__ext__:';
+/**
+ * Scope a model to the INTERIOR of `root` for an isolated drill view: keep only
+ * root's descendants (root's own children become the parentless top level), drop
+ * relations wholly outside, keep internal ones, and re-point each boundary-crossing
+ * relation to a stub node standing in for the off-frame endpoint's outermost
+ * ancestor OUTSIDE the drill root's own ancestor chain (so "a class uses the
+ * database" stays visible as class → ⟨Database⟩, and a sibling of the root stands
+ * for itself rather than collapsing into the ancestor both sides share).
+ */
+export function scopeToRoot(m, h, root) {
+    const sub = new Set();
+    const stack = [...(h.childrenOf.get(root) ?? [])];
+    while (stack.length > 0) {
+        const id = stack.pop();
+        if (sub.has(id))
+            continue;
+        sub.add(id);
+        stack.push(...(h.childrenOf.get(id) ?? []));
+    }
+    // the drill root and everything containing it (first-parent chain) — a stub
+    // representing a box that CONTAINS the frame would say nothing about the edge
+    const rootAncestors = new Set([root]);
+    for (let cur = root;;) {
+        const p = (h.parentsOf.get(cur) ?? [])[0];
+        if (p === undefined || rootAncestors.has(p))
+            break;
+        rootAncestors.add(p);
+        cur = p;
+    }
+    // outermost ancestor of `id` outside the root's ancestor chain (following the
+    // first-parent chain; containment is a DAG); undefined when `id` is itself on
+    // that chain — the relation touches the frame, not a peer
+    const repOf = (id) => {
+        if (rootAncestors.has(id))
+            return undefined;
+        const seen = new Set([id]);
+        let cur = id;
+        for (;;) {
+            const p = (h.parentsOf.get(cur) ?? [])[0];
+            if (p === undefined || rootAncestors.has(p) || seen.has(p))
+                return cur;
+            seen.add(p);
+            cur = p;
+        }
+    };
+    const nodeOf = new Map(m.nodes.map((n) => [n.id, n]));
+    const externals = new Map();
+    const stubFor = (offFrame) => {
+        const rep = repOf(offFrame);
+        if (rep === undefined || sub.has(rep))
+            return undefined; // a relation on the frame itself — skip
+        const id = `${EXTERNAL_STUB_PREFIX}${rep}`;
+        externals.set(id, rep);
+        return id;
+    };
+    const relations = [];
+    for (const r of m.relations) {
+        const fromIn = sub.has(r.from);
+        const toIn = sub.has(r.to);
+        if (fromIn && toIn) {
+            relations.push(r);
+        }
+        else if (fromIn) {
+            const stub = stubFor(r.to);
+            if (stub !== undefined)
+                relations.push({ ...r, to: stub });
+        }
+        else if (toIn) {
+            const stub = stubFor(r.from);
+            if (stub !== undefined)
+                relations.push({ ...r, from: stub });
+        }
+    }
+    // The subtree is already within one resolved plane; the synthetic model is
+    // plane-less, so strip each node's `plane` scope (else buildHierarchy would
+    // filter a plane-scoped node out when no plane is active).
+    const nodes = m.nodes
+        .filter((n) => sub.has(n.id))
+        .map(({ plane: _plane, ...rest }) => rest);
+    // a stub keeps the represented node's visual identity (type/shape/color/icon)
+    // so it renders like the original entity; the renderer adds the ghost look
+    for (const [stubId, rep] of externals) {
+        const src = nodeOf.get(rep);
+        nodes.push({
+            id: stubId,
+            name: src?.name ?? rep,
+            ...(src?.type !== undefined ? { type: src.type } : {}),
+            ...(src?.icon !== undefined ? { icon: src.icon } : {}),
+            ...(src?.image !== undefined ? { image: src.image } : {}),
+            ...(src?.shape !== undefined ? { shape: src.shape } : {}),
+            ...(src?.color !== undefined ? { color: src.color } : {}),
+            ...(src?.textColor !== undefined ? { textColor: src.textColor } : {}),
+        });
+    }
+    const containment = m.containment
+        .filter((e) => sub.has(e.parent) && sub.has(e.child))
+        .map(({ plane: _plane, ...rest }) => rest);
+    // Drill happens within one already-resolved plane; the synthetic model is
+    // plane-less so buildHierarchy uses its raw containment (root's children +
+    // stubs are the parentless roots).
+    return { model: { ...m, nodes, containment, relations, planes: [] }, externals };
+}

package/dist/view/size.d.ts

@@ -0,0 +1,8 @@
+import type { HierarchyIndex } from './hierarchy.js';
+import type { Size } from './types.js';
+export declare const LEAF_SIZE: Size;
+export declare const CONTAINER_PADDING = 24;
+export declare const CONTAINER_HEADER = 32;
+/** Rough intrinsic (world-unit) sizes for LOD decisions; Plan 3 swaps in
+ * renderer-measured sizes through the same Map shape. */
+export declare function estimateSizes(h: HierarchyIndex): Map<string, Size>;

package/dist/view/size.js

@@ -0,0 +1,34 @@
+export const LEAF_SIZE = { width: 160, height: 80 };
+export const CONTAINER_PADDING = 24;
+export const CONTAINER_HEADER = 32;
+/** Rough intrinsic (world-unit) sizes for LOD decisions; Plan 3 swaps in
+ * renderer-measured sizes through the same Map shape. */
+export function estimateSizes(h) {
+    const sizes = new Map();
+    const visit = (id) => {
+        const memo = sizes.get(id);
+        if (memo)
+            return memo;
+        const kids = h.childrenOf.get(id) ?? [];
+        let size;
+        if (kids.length === 0) {
+            size = { ...LEAF_SIZE };
+        }
+        else {
+            const kidSizes = kids.map(visit);
+            const cols = Math.ceil(Math.sqrt(kidSizes.length));
+            const rows = Math.ceil(kidSizes.length / cols);
+            const cellW = Math.max(...kidSizes.map((s) => s.width));
+            const cellH = Math.max(...kidSizes.map((s) => s.height));
+            size = {
+                width: cols * cellW + (cols + 1) * CONTAINER_PADDING,
+                height: rows * cellH + (rows + 1) * CONTAINER_PADDING + CONTAINER_HEADER,
+            };
+        }
+        sizes.set(id, size);
+        return size;
+    };
+    for (const id of h.parentsOf.keys())
+        visit(id);
+    return sizes;
+}

package/dist/view/tree.d.ts

@@ -0,0 +1,12 @@
+import type { DiagramModel } from '../types.js';
+import type { HierarchyIndex } from './hierarchy.js';
+import type { LodState, ViewNode } from './types.js';
+export interface ViewTree {
+    roots: ViewNode[];
+    byId: Map<string, ViewNode>;
+    /** hidden node id -> its unique visible absorber */
+    anchorOf: Map<string, string>;
+    /** visible node id -> placement parent (null = top level) */
+    hostOf: Map<string, string | null>;
+}
+export declare function buildViewTree(m: DiagramModel, h: HierarchyIndex, lod: LodState): ViewTree;