@rokkit/graph 1.6.0 → 1.8.0

package/dist/layout/structure.js

@@ -0,0 +1,367 @@
+/* The structure view: a codebase as a radial dendrogram with its calls bundled through it.
+ *
+ * The layout `CallTree` could not be. A call graph's own spanning tree has hundreds of roots
+ * over a real repo, so capping its depth prunes almost nothing and the rim comes out a grey
+ * smear. A codebase's structure is CONTAINMENT — crate, module, file — and that is a real
+ * tree with one root, which is what makes "show two levels, then drill" mean something.
+ *
+ * So the hierarchy here is `buildTree` over `path`, exactly the tree `world` and `sunburst`
+ * use, and the calls are drawn ON it rather than defining it:
+ *
+ *   - every LEAF sits on one rim, so leaves are comparable and the rim can hold labels
+ *   - each ancestor level gets an arc outside that rim, naming the region under it
+ *   - an edge is routed up to the two ends' lowest common ancestor and back down, then
+ *     relaxed toward the straight chord by `bundleTension`
+ *
+ * Bundling is the part that makes it readable at scale: edges travelling the same way through
+ * the tree are pulled together, so a few hundred chords become visible flows between parts of
+ * the structure instead of a solid disc of ink.
+ *
+ * Modelled on Sensei's Structure board (docs/mockups/Sensei, "Project window · Diagrams ·
+ * Structure"), which is d3.cluster + lineRadial + curveBundle over the same hierarchy.
+ */
+import { buildTree, findNode } from '../model/tree.js';
+import { bundlePath, commonDepth } from './bundle.js';
+import { nodeSizes } from './sizing.js';
+import { warnUnknownOptions } from './options.js';
+/** Smallest leaf rim. Everything inside is tree, everything outside is annotation. */
+const MIN_RIM = 300;
+/**
+ * Arc length reserved per leaf, which is what the rim's circumference has to satisfy.
+ *
+ * The rim GROWS with the leaf count rather than dividing a fixed circle into ever-thinner
+ * slices — 470 modules on a 300px rim is four pixels each, which is the grey smear this
+ * layout exists to replace.
+ */
+const LEAF_ARC = 22;
+/** Gap from the rim to the first band of ancestor arcs, leaving room for a leaf label. */
+const BAND_GAP = 58;
+/** Thickness of one ancestor band. */
+const BAND = 8;
+/** Space between bands, and the room a band's own label needs. */
+const BAND_STEP = 26;
+/** Margin outside the outermost band. */
+const PAD = 40;
+/**
+ * Cut the tree off at `limit`, making everything at that depth a leaf.
+ *
+ * This is what `levels` means here, and the thing that makes the view usable: the rim holds
+ * whatever level you asked for, so 1 is a dozen crates you can read and 3 is every file. Left
+ * uncut, a repo puts 470 leaves on one rim at a fraction of a degree each — unreadable at any
+ * zoom, with a depth control that appeared to do nothing because it only drew rings.
+ *
+ * `buildTree` has already summed each subtree, so a cut node keeps the weight of everything
+ * it now stands for.
+ */
+function truncate(node, limit) {
+    if (node.depth >= limit)
+        return { ...node, children: [] };
+    return { ...node, children: node.children.map((child) => truncate(child, limit)) };
+}
+/** Leaves in walk order, so a parent's children stay adjacent on the rim. */
+function leavesOf(root) {
+    const out = [];
+    const visit = (n) => {
+        if (n.children.length === 0) {
+            out.push(n);
+            return;
+        }
+        for (const child of n.children)
+            visit(child);
+    };
+    visit(root);
+    return out;
+}
+/**
+ * An angle for every node: leaves get equal slots, a parent sits at the mean of its children.
+ *
+ * The "cluster" in d3.cluster. Without the centring a parent sits at a fixed slot and every
+ * edge routed through it crosses the neighbouring subtrees to get there — which defeats the
+ * bundling, since the bundle follows exactly those parents.
+ */
+function place(root, step, rim) {
+    const placed = new Map();
+    const byPath = new Map();
+    const depth = maxDepthOf(root);
+    const visit = (node, slot) => {
+        const leaf = node.children.length === 0;
+        let angle;
+        if (leaf) {
+            angle = slot.next * step;
+            slot.next++;
+        }
+        else {
+            const kids = node.children.map((child) => visit(child, slot));
+            angle = kids.reduce((sum, a) => sum + a, 0) / kids.length;
+        }
+        // Every LEAF on the rim, whatever its depth — that is the dendrogram property, and what
+        // makes leaves comparable and the rim able to hold labels. A folded single-child
+        // wrapper leaves its leaf a level shallower than its neighbours, so a depth-derived
+        // radius would put two files on different rings for a reason about the TREE rather
+        // than about them. Ancestors sit proportionally inside, so a bundle bows inward.
+        // No zero guard on `depth`: the layout returns early for a root with no children, so a
+        // tree that reaches here is at least one level deep.
+        const radius = leaf ? rim : (node.depth / depth) * rim;
+        placed.set(node.id, { node, angle, radius });
+        byPath.set(node.path.join('/'), node);
+        return angle;
+    };
+    visit(root, { next: 0 });
+    return { placed, byPath };
+}
+function maxDepthOf(root) {
+    let deepest = 0;
+    const visit = (n) => {
+        deepest = Math.max(deepest, n.depth);
+        for (const child of n.children)
+            visit(child);
+    };
+    visit(root);
+    return deepest;
+}
+/** Polar to canvas coordinates. 0 is 12 o'clock, so the first leaf is at the top. */
+function at(centre, angle, radius) {
+    return {
+        x: centre + Math.sin(angle) * radius,
+        y: centre - Math.cos(angle) * radius
+    };
+}
+/**
+ * An ancestor band, drawn as a wedge outside the rim.
+ *
+ * Reuses `Cluster.wedge`, the same geometry a sunburst emits — so a renderer that can draw one
+ * can draw these, and the theme does not learn a second vocabulary for the same shape.
+ */
+function band(node, ctx, index) {
+    const leaves = leavesOf(node);
+    const first = ctx.placed.get(leaves[0].id);
+    const last = ctx.placed.get(leaves[leaves.length - 1].id);
+    // Half a slot of padding at each end, so adjacent bands read as separate regions rather
+    // than as one ring with hairlines in it.
+    const half = ctx.step * 0.48;
+    // Depth RELATIVE to the focus, the same convention `world` and `sunburst` use: the
+    // innermost band is always 0 whatever the reader has drilled into.
+    const depth = node.depth - ctx.origin - 1;
+    const inner = ctx.rim + BAND_GAP + depth * BAND_STEP;
+    return {
+        name: node.label,
+        caption: String(leaves.length),
+        depth,
+        // The enclosing band's PATH, not its label. Two crates can each hold a module called
+        // `lib`, and `clusterKey` is `depth:parent:name` — keyed by label alone that is a
+        // duplicate key, Svelte throws `each_key_duplicate` and the whole render aborts, so
+        // no band appears at all rather than one looking wrong.
+        parent: node.path.slice(0, -1).join('/'),
+        ramp: node.path[ctx.origin],
+        count: node.children.length,
+        list: node.children.map((c) => c.node).filter((n) => n !== undefined),
+        groupIndex: index,
+        wedge: { r0: inner, r1: inner + BAND, a0: first.angle - half, a1: last.angle + half },
+        x: 0,
+        y: 0,
+        w: 0,
+        h: 0
+    };
+}
+/** Every ancestor level below the focus, outermost band last. */
+function bands(root, ctx, levels) {
+    const out = [];
+    const limit = ctx.origin + levels;
+    const visit = (node) => {
+        if (node.depth > ctx.origin && node.children.length > 0 && node.depth <= limit) {
+            out.push(band(node, ctx, out.length));
+        }
+        if (node.depth < limit)
+            for (const child of node.children)
+                visit(child);
+    };
+    visit(root);
+    return out;
+}
+/** The route an edge takes through the tree: up to the common ancestor, then back down. */
+function route(a, b, ctx) {
+    const shared = commonDepth(a.path, b.path);
+    const spot = (path) => {
+        const node = ctx.byPath.get(path.join('/'));
+        const p = node && ctx.placed.get(node.id);
+        return p ? at(ctx.centre, p.angle, p.radius) : undefined;
+    };
+    const up = [];
+    const down = [];
+    for (let d = a.path.length; d >= shared; d--) {
+        const p = spot(a.path.slice(0, d));
+        if (p)
+            up.push(p);
+    }
+    for (let d = shared + 1; d <= b.path.length; d++) {
+        const p = spot(b.path.slice(0, d));
+        if (p)
+            down.push(p);
+    }
+    return [...up, ...down];
+}
+/**
+ * How far an edge travels in the TREE, which is what a reader filters on.
+ *
+ * `local` stays inside one module, `crate` crosses modules within a package, `cross` leaves
+ * the package. The same three the Sensei board toggles, and the reason is the same: "which
+ * calls leave this crate" is a different question from "how chatty is this module".
+ */
+function reach(a, b) {
+    const shared = commonDepth(a.path, b.path);
+    // Measured against each end's OWN depth rather than against a fixed level, because the
+    // tree folds single-child wrappers — `repo/site/ui/render` and `repo/ui/render` are the
+    // same file, and a rule counting absolute depth would classify it differently depending on
+    // how many siblings its module happened to have.
+    const sameParent = shared >= a.path.length - 1 && shared >= b.path.length - 1;
+    const sameGrandparent = shared >= a.path.length - 2 && shared >= b.path.length - 2;
+    if (sameParent)
+        return 'local';
+    return sameGrandparent ? 'crate' : 'cross';
+}
+function leafIndex(root, model) {
+    const byNode = new Map();
+    const leaves = leavesOf(root);
+    // By PATH, not by node: after a cut, a file's own node is no longer a leaf — the region
+    // standing for it is. An edge between two files in the same crate becomes an edge from
+    // that crate to itself, which is then dropped as a self-link. That is the aggregation
+    // that makes a cut view readable: only calls that actually cross the boundary survive.
+    const byPathKey = new Map(leaves.map((leaf) => [leaf.path.join('/'), leaf]));
+    for (const node of model.nodes) {
+        const path = node.path ?? [];
+        for (let d = path.length; d >= 0; d--) {
+            const leaf = byPathKey.get(path.slice(0, d).join('/'));
+            if (leaf) {
+                byNode.set(node.id, leaf);
+                break;
+            }
+        }
+    }
+    return byNode;
+}
+function routeAll(model, root, ctx, tension) {
+    const byNode = leafIndex(root, model);
+    const routed = [];
+    model.edges.forEach((edge, i) => {
+        const a = byNode.get(edge.source);
+        const b = byNode.get(edge.target);
+        // A self-call has no route through the tree, and an endpoint outside the materialised
+        // levels has no point to start from. Both are dropped rather than drawn to the centre.
+        if (!a || !b || a === b)
+            return;
+        // At least two points by construction: distinct leaves contribute one each, whatever
+        // the chain between them, so there is no degenerate route to guard against.
+        const points = route(a, b, ctx);
+        const from = points[0];
+        const to = points[points.length - 1];
+        routed.push({
+            i,
+            id: edge.id,
+            fromKey: edge.source,
+            toKey: edge.target,
+            kind: edge.kind,
+            relation: edge.relation ?? reach(a, b),
+            self: false,
+            x1: from.x,
+            y1: from.y,
+            x2: to.x,
+            y2: to.y,
+            s1: 1,
+            s2: -1,
+            // Pre-built, because the shape depends on the whole tree route rather than on the
+            // two endpoints — `edgePath` only ever sees the ends.
+            path: bundlePath(points, tension)
+        });
+    });
+    return routed;
+}
+/**
+ * How a label sits at this angle on the rim.
+ *
+ * Tangential, and flipped through the left half so nothing reads upside down — the same rule
+ * the Sensei board uses. Degrees, because that is what a CSS rotation takes.
+ */
+function labelAt(angle) {
+    const degrees = (angle * 180) / Math.PI;
+    const onLeft = degrees % 360 > 180;
+    return {
+        labelAngle: onLeft ? degrees + 90 : degrees - 90,
+        labelSide: onLeft ? 'end' : 'start'
+    };
+}
+/** A stand-in node for a cut leaf, which is a region rather than anything declared. */
+function region(leaf) {
+    return { id: leaf.id, label: leaf.label, rows: [], meta: {}, kind: 'module' };
+}
+/**
+ * How big a region's dot is.
+ *
+ * A cut leaf has no entry in the measure map — it is not a node anyone declared — so it takes
+ * a size from what it CONTAINS, which is the same question the measure answers for a real one.
+ */
+function sizeFor(leaf, ring) {
+    const scaled = Math.min(18, 5 + Math.sqrt(Math.max(0, leaf.value)) * 0.8);
+    return { w: scaled, h: scaled * (ring.rim > 0 ? 1 : 1) };
+}
+/** One dot per leaf, on the rim. Sized by the measure, as `points` and `radial` size theirs. */
+function dots(leaves, ring, ctx) {
+    const { placed, model } = ctx;
+    const sizeOf = nodeSizes(model, ctx.sizeBy ?? 'degree', ctx.sizeScale ?? 'linear');
+    const cards = {};
+    for (const leaf of leaves) {
+        // A CUT leaf is often a region rather than a declared node — `core` standing for the
+        // forty files under it. It still needs a dot and a label, so one is synthesised for
+        // it; the box IS the thing at this level.
+        const node = leaf.node ?? region(leaf);
+        const spot = placed.get(leaf.id);
+        const size = sizeOf.get(node.id) ?? sizeFor(leaf, ring);
+        const point = at(ring.centre, spot.angle, spot.radius);
+        const label = labelAt(spot.angle);
+        cards[node.id] = {
+            node,
+            vis: [],
+            more: node.rows.length,
+            w: size.w,
+            h: size.h,
+            x: point.x - size.w / 2,
+            y: point.y - size.h / 2,
+            groupIndex: 0,
+            ...label
+        };
+    }
+    return cards;
+}
+/**
+ * A codebase as a radial dendrogram, with its calls bundled through the structure.
+ *
+ * `levels` caps how many ancestor bands are drawn; `focusPath` scopes the whole canvas to a
+ * subtree, which is drilling. Both mean exactly what they mean in `world` and `sunburst`, so
+ * switching between the three views keeps your place.
+ */
+export const structure = (model, options) => {
+    warnUnknownOptions(options, 'structure');
+    const tree = buildTree(model, { measure: options.sizeBy ?? 'weight' });
+    const root = findNode(tree, options.focusPath ?? []);
+    if (!root || root.children.length === 0) {
+        return { clusters: [], cards: {}, edges: [], size: { w: 0, h: 0 } };
+    }
+    const origin = root.path.length;
+    const levels = Math.max(1, options.levels ?? 2);
+    // `levels` decides what sits ON the rim: 1 is a dozen crates, 3 is every file. The bands
+    // are then the levels ABOVE it, so at 1 there are none and the leaves label themselves.
+    const cut = truncate(root, origin + levels);
+    const leaves = leavesOf(cut);
+    const step = (Math.PI * 2) / Math.max(1, leaves.length);
+    const bandCount = Math.max(0, levels - 1);
+    const rim = Math.max(MIN_RIM, (LEAF_ARC * leaves.length) / (Math.PI * 2));
+    const extent = rim + BAND_GAP + Math.max(0, bandCount - 1) * BAND_STEP + BAND + PAD;
+    const ring = { rim, centre: extent };
+    const { placed, byPath } = place(cut, step, rim);
+    const ctx = { placed, byPath, centre: ring.centre };
+    return {
+        clusters: bands(cut, { placed, step, origin, rim }, bandCount),
+        cards: dots(leaves, ring, { placed, model, sizeBy: options.sizeBy, sizeScale: options.sizeScale }),
+        edges: routeAll(model, cut, ctx, options.bundleTension ?? 0.85),
+        size: { w: extent * 2, h: extent * 2 }
+    };
+};

package/dist/layout/sunburst.d.ts

@@ -0,0 +1,8 @@
+import type { LayoutFn } from './types.js';
+/**
+ * Containment as angle, depth as radius.
+ *
+ * `focusPath` and `levels` mean exactly what they mean in `world`, so a reader switching
+ * between the two views keeps their place.
+ */
+export declare const sunburst: LayoutFn;

package/dist/layout/sunburst.js

@@ -0,0 +1,126 @@
+/* The sunburst: the treemap's question asked radially.
+ *
+ * Same tree, same measure, same captions as `world` — deliberately, so the two are one dataset
+ * drawn twice rather than two features that drift. What changes is which channel carries what:
+ *
+ *   treemap   area = measure, depth = nesting you have to look for
+ *   sunburst  ANGLE = measure, RADIUS = depth, which you read at a glance
+ *
+ * A treemap spends its pixels better; a sunburst tells you how deep the tree goes before you
+ * have read a single label. Neither is the right one, which is why both exist.
+ *
+ * Geometry only — a wedge is `{ r0, r1, a0, a1 }` and the renderer turns that into an arc.
+ * That keeps this a pure `LayoutFn` like every other: DOM-free, synchronous, unit-testable to
+ * exact radians.
+ */
+import { buildTree, findNode } from '../model/tree.js';
+import { warnUnknownOptions } from './options.js';
+/** Outer radius of the deepest materialised ring. The canvas is derived from it. */
+const RADIUS = 380;
+/** Margin outside the rim. */
+const PAD = 16;
+/**
+ * Angular floor, as a share of one child's EQUAL slice of its parent.
+ *
+ * The same reasoning as the treemap's area floor, and the same trap avoided: a per-child floor
+ * measured against the TOTAL sums with the child count, so it is negligible at two children and
+ * swamps the circle at 470. Against the equal slice the total floor caps at this constant
+ * whatever the child count.
+ */
+const MIN_EQUAL_SHARE = 0.12;
+/** Compact enough to sit in a label strip: 1200 reads as 1.2k. */
+function compact(value) {
+    if (value >= 1_000_000)
+        return `${(value / 1_000_000).toFixed(1)}M`;
+    if (value >= 1000)
+        return `${(value / 1000).toFixed(1)}k`;
+    return String(Math.round(value));
+}
+/**
+ * Divide a parent's angular span among its children, proportional to measure.
+ *
+ * Recurses `levels` deep and no further — the same refusal the treemap makes, and for the same
+ * reason: the cost of a large tree is in building it, not in drawing it.
+ */
+function split(node, span, ctx) {
+    const { levels, out, parent, origin, ramp } = ctx;
+    if (levels <= 0 || node.children.length === 0)
+        return;
+    const total = node.children.reduce((sum, c) => sum + Math.max(c.value, 0), 0);
+    const floor = (total / node.children.length) * MIN_EQUAL_SHARE;
+    // Equal slices when nothing is measured. Returning early instead drew NOTHING for a tree
+    // whose measure happens to be zero everywhere — a codebase under `sizeBy: 'degree'` where
+    // no module imports another, which is a blank canvas rather than a visible "unmeasured".
+    // `squarify` makes the same fallback for the treemap, so the two views agree.
+    const values = total > 0 ? node.children.map((c) => Math.max(c.value, floor)) : node.children.map(() => 1);
+    const sum = values.reduce((a, b) => a + b, 0);
+    let a = span.a0;
+    const width = span.a1 - span.a0;
+    node.children.forEach((child, i) => {
+        const slice = (values[i] / sum) * width;
+        const range = { a0: a, a1: a + slice };
+        // Depth is RELATIVE to the focus, so the innermost rendered ring is always 0 whatever
+        // the reader has drilled into — the same convention `world` uses.
+        // The outermost wedge names the ramp entry and its whole subtree inherits it, so a
+        // package reads as one coloured sector rather than a bright inner ring above a grey
+        // outer one.
+        const key = ramp ?? child.label;
+        out.push({ tree: child, depth: node.path.length - origin, parent, ramp: key, ...range });
+        split(child, range, { levels: levels - 1, out, parent: child.id, origin, ramp: key });
+        a += slice;
+    });
+}
+function wedgeOf(entry, groupIndex, ring) {
+    const leaf = entry.tree.children.length === 0 ? entry.tree.node : undefined;
+    return {
+        name: entry.tree.label,
+        caption: compact(entry.tree.value),
+        parent: entry.parent,
+        depth: entry.depth,
+        ramp: entry.ramp,
+        nodeId: leaf?.id,
+        kind: leaf?.kind,
+        list: entry.tree.children.map((c) => c.node).filter((n) => n !== undefined),
+        count: entry.tree.children.length,
+        groupIndex,
+        wedge: {
+            r0: entry.depth * ring,
+            r1: (entry.depth + 1) * ring,
+            a0: entry.a0,
+            a1: entry.a1
+        },
+        // A wedge is drawn from its own polar geometry, but the box still reports where it sits
+        // so selection, hit-testing and anything measuring the canvas keep working unchanged.
+        x: RADIUS + PAD + Math.cos((entry.a0 + entry.a1) / 2) * ((entry.depth + 0.5) * ring),
+        y: RADIUS + PAD + Math.sin((entry.a0 + entry.a1) / 2) * ((entry.depth + 0.5) * ring),
+        w: 0,
+        h: 0
+    };
+}
+/**
+ * Containment as angle, depth as radius.
+ *
+ * `focusPath` and `levels` mean exactly what they mean in `world`, so a reader switching
+ * between the two views keeps their place.
+ */
+export const sunburst = (model, options) => {
+    warnUnknownOptions(options, 'sunburst');
+    const tree = buildTree(model, { measure: options.sizeBy ?? 'weight' });
+    const root = findNode(tree, options.focusPath ?? []);
+    if (!root || root.children.length === 0) {
+        return { clusters: [], cards: {}, edges: [], size: { w: 0, h: 0 } };
+    }
+    const levels = options.levels ?? 2;
+    const placed = [];
+    split(root, { a0: 0, a1: Math.PI * 2 }, { levels, out: placed, origin: root.path.length });
+    const ring = RADIUS / Math.max(1, levels);
+    const extent = (RADIUS + PAD) * 2;
+    return {
+        clusters: placed.map((entry, i) => wedgeOf(entry, i, ring)),
+        cards: {},
+        // Edges are absent for the same reason as the treemap: containment IS the relationship,
+        // and an adjacency graph cannot be drawn at this scale.
+        edges: [],
+        size: { w: extent, h: extent }
+    };
+};

package/dist/layout/types.d.ts

@@ -21,6 +21,17 @@ export type Card = {
      * hardcoded oklch angle baked into the layout.
      */
     groupIndex?: number;
+    /**
+     * Degrees to rotate this node's label so it reads outward from a rim, already flipped on
+     * the left half so nothing is upside down.
+     *
+     * The layout knows the angle it placed the node at; the renderer would have to re-derive
+     * it from x/y and the canvas centre, which is the kind of geometry a component should not
+     * be doing. Absent on every layout that is not radial.
+     */
+    labelAngle?: number;
+    /** Which way the label runs from the dot — `end` on the left half of the circle. */
+    labelSide?: 'start' | 'end';
 };
 export type Cluster = {
     name: string;
@@ -47,6 +58,51 @@ export type Cluster = {
     depth?: number;
     /** Name of the enclosing cluster, for a depth-1 box. */
     parent?: string;
+    /**
+     * What to show after the name, when the layout has something better than a child count.
+     *
+     * A number beside a box reads as the thing driving its size, so in a layout where AREA
+     * encodes a measure the count is actively misleading — `components · 63` was 63 files in a
+     * box sized by 63 declarations, and the two being equal was a coincidence. A layout that
+     * sizes by a measure says so here; one that does not leaves it unset and the count stands.
+     */
+    caption?: string;
+    /**
+     * The node this box IS, when it is one. Set on a childless box in a containment layout;
+     * absent on a region, which is not selectable because it is not a thing.
+     *
+     * A treemap is a hierarchy of ONE shape — a box with a label and an area — so a leaf is a
+     * cluster too rather than a node card. Emitting the card put two structures in one nesting
+     * and dragged the card's furniture in with it: a codebase module has no rows, so every leaf
+     * rendered a literal `0` beside its name. Identity survives here instead.
+     */
+    nodeId?: string;
+    /** The node's kind, for colour, when this box is a node. */
+    kind?: string;
+    /**
+     * Which entry of the group ramp this box takes its colour from, when that is not its own
+     * name.
+     *
+     * A containment layout nests boxes many levels deep, and only the outermost ones are group
+     * names the ramp knows. Looked up by its own name, every descendant falls through to the
+     * default — which is how a sunburst's outer ring came out uniformly grey while the inner
+     * ring was correctly coloured. Inheriting the outermost ancestor's key makes a whole
+     * subtree read as one region, which is the thing the reader is tracing.
+     */
+    ramp?: string;
+    /**
+     * Polar geometry, when the layout draws this box as a WEDGE rather than a rectangle.
+     *
+     * Angles are radians from 3 o'clock, radii are from the canvas centre. Kept as numbers
+     * rather than a path string so the layout stays DOM-free and unit-testable to exact
+     * radians — building the arc is the renderer's job.
+     */
+    wedge?: {
+        r0: number;
+        r1: number;
+        a0: number;
+        a1: number;
+    };
 };
 /**
  * Which node property a layout groups on. Both already exist on `GraphNode`, so nesting
@@ -63,6 +119,17 @@ export type RoutedEdge = {
     /** GraphEdge.relation — the consumer's own verb, carried through for theming. */
     relation?: string;
     self: boolean;
+    /**
+     * Set when a layered layout had to reverse this edge to rank the graph — a mutual foreign
+     * key, which a real schema has. It is still drawn, and still leaves right and enters left,
+     * so it is the one connector that visibly doubles back. A theme distinguishes it rather
+     * than the reader wondering why one link behaves differently.
+     */
+    back?: boolean;
+    /** GraphEdge.overlay — routed after the layout ran, over a picture it did not shape. */
+    overlay?: boolean;
+    /** GraphEdge.weight, raw. `GraphState.edgeWeight` normalises it for drawing. */
+    weight?: number;
     x1: number;
     y1: number;
     x2: number;
@@ -70,6 +137,30 @@ export type RoutedEdge = {
     /** 1 = right side of the card, -1 = left. */
     s1: number;
     s2: number;
+    /**
+     * A ready-made path, when the shape depends on more than the two endpoints.
+     *
+     * `edgePath` only ever sees the ends, which is enough for a curve or a right-angle route.
+     * A bundled edge follows the whole chain of ancestors between its endpoints, so the layout
+     * that knows that chain builds the path and the renderer draws what it is given.
+     */
+    path?: string;
+};
+/**
+ * One column of a multi-column layout, with the heading it needs to be readable.
+ *
+ * Three columns get away with none — the focus is visibly central, so the sides are obvious.
+ * Five do not: without headings a depth-2 portrait is ambiguous about which direction is
+ * which, and the reader has to trace an arrow to find out.
+ */
+export type Column = {
+    x: number;
+    /** Carried here so the view needs no layout constant to size a heading. */
+    w: number;
+    depth: number;
+    /** `in` = things that reach the focus, `out` = things it reaches, `focus` = the centre. */
+    side: 'in' | 'out' | 'focus';
+    label: string;
 };
 export type Cards = Record<string, Card>;
 export type Size = {
@@ -100,11 +191,65 @@ export type LayoutOptions = {
      * and the layout runs its original single-level path untouched.
      */
     nestBy?: NodeAxis;
+    /**
+     * What `points` sizes a node by. `degree` (the default) counts edges; `weight` reads
+     * `GraphNode.weight`.
+     *
+     * Degree is a good default and is not always the measure the reader is asking about — a
+     * 40-file module with few cross-edges should not render smaller than a 2-file one that
+     * happens to be chatty.
+     */
+    sizeBy?: string;
+    /**
+     * How the measure maps onto area. `linear` (the default), or `log` for a measure spanning
+     * orders of magnitude — declaration counts across a real repo span three or four, and
+     * linear flattens everything below the top few onto the minimum.
+     */
+    sizeScale?: 'linear' | 'log';
+    /**
+     * `neighborhood` only — how many hops out from the focus. Defaults to 1.
+     *
+     * One hop answers "what touches this". Two answers "what does changing this reach", which
+     * is the question a reader has before editing something.
+     */
+    depth?: number;
+    /**
+     * `world` only — the subtree to render as the whole canvas. `[]` is the root.
+     *
+     * This is DRILLING, not zooming: it re-runs the layout with a new root so the subtree gets
+     * the full canvas and its own children become visible. Zoom magnifies what is already
+     * there, which at world scale is a field of sub-pixel boxes.
+     */
+    focusPath?: string[];
+    /** `world` only — how many levels below the focus to MATERIALISE. Defaults to 2. */
+    levels?: number;
+    /**
+     * `radial` only — `tree` (the default) reads radius as DEPTH; `dendrogram` pins every
+     * leaf to the rim so leaves are compared against each other.
+     */
+    radialMode?: 'tree' | 'dendrogram';
+    /**
+     * `structure` only — how hard edges are pulled onto the tree, 0..1.
+     *
+     * 0 is a straight chord and 1 is the full route through the hierarchy. The default of 0.85
+     * is Holten's, and what the Sensei board's Straight/Bundled toggle switches between.
+     */
+    bundleTension?: number;
+    /**
+     * `radial` only — the node to treat as the centre, which is what drilling into a crate
+     * does. Its subtree becomes the whole picture.
+     *
+     * Deliberately NOT `focus`: that one defaults to the SELECTION, so clicking a node to
+     * highlight it would silently re-root the diagram.
+     */
+    root?: string | null;
 };
 export type LayoutResult = {
     clusters: Cluster[];
     cards: Cards;
     edges: RoutedEdge[];
+    /** Column headings, when the layout has columns. Empty for the grid layouts. */
+    columns?: Column[];
     size: Size;
 };
 /**