@rokkit/graph 1.6.0 → 1.7.0

package/dist/layout/squarify.js

@@ -0,0 +1,114 @@
+/* Squarified treemap — Bruls, Huizing & van Wijk (2000).
+ *
+ * Fills a rectangle with child rectangles whose areas are proportional to their values, laid
+ * out in rows chosen to keep each rectangle as square as possible.
+ *
+ * The naive alternative (slice-and-dice: split the rect by value along one axis, alternating
+ * per level) is far simpler and unusable here — it produces 1px-wide slivers at any real
+ * value spread, and a sliver holds no label. A box you cannot read is a box you cannot
+ * decide to click, which is the whole of drill-down navigation.
+ *
+ * Hand-written rather than taken from `d3-hierarchy`: the algorithm is small and naturally
+ * deterministic, and `@rokkit/graph` has no third-party runtime dependency — a property
+ * `dependencies.spec.js` asserts, so acquiring the first one should buy more than 80 lines.
+ */
+/**
+ * Worst aspect ratio in a row of areas laid along `side`. Lower is squarer.
+ *
+ * No zero guard: a side or total of 0 divides to Infinity in JS, which is exactly the answer —
+ * a row with no room is infinitely bad and the caller closes it. A guard here would be a
+ * statement no input can reach.
+ */
+function worst(areas, side, total) {
+    const max = Math.max(...areas);
+    const min = Math.min(...areas);
+    const s2 = side * side;
+    const t2 = total * total;
+    return Math.max((s2 * max) / t2, t2 / (s2 * min));
+}
+/** Lay one finished row along the short side of `rect`, and return what remains. */
+function placeRow(row, rect, out) {
+    const total = row.reduce((sum, r) => sum + r.area, 0);
+    const vertical = rect.w >= rect.h;
+    // Thickness of the band this row occupies, derived from its total area so the row exactly
+    // consumes the share of the rectangle its values earned.
+    const thickness = total / (vertical ? rect.h : rect.w);
+    let offset = vertical ? rect.y : rect.x;
+    for (const entry of row) {
+        const length = entry.area / thickness;
+        out.push({
+            item: entry.item,
+            rect: vertical
+                ? { x: rect.x, y: offset, w: thickness, h: length }
+                : { x: offset, y: rect.y, w: length, h: thickness }
+        });
+        offset += length;
+    }
+    return vertical
+        ? { x: rect.x + thickness, y: rect.y, w: rect.w - thickness, h: rect.h }
+        : { x: rect.x, y: rect.y + thickness, w: rect.w, h: rect.h - thickness };
+}
+/**
+ * Place `items` inside `rect`, area proportional to `value`.
+ *
+ * Largest first: the greedy row-closing rule only produces near-square boxes if the big ones
+ * are placed while there is room to choose. Ties break on the caller's order, which is already
+ * sorted, so the result is deterministic.
+ *
+ * A zero or negative value gets the same floor as a tiny one — "unknown" is a normal state in
+ * a partially-indexed graph, and a zero-area box is indistinguishable from a missing one.
+ */
+/**
+ * Does adding `area` make this row's worst aspect ratio worse?
+ *
+ * That comparison IS the algorithm — it trades row length against squareness, and closing the
+ * row at the moment the answer turns yes is what keeps boxes near-square instead of slivers.
+ */
+function shouldClose(areas, area, side) {
+    if (areas.length === 0)
+        return false;
+    const total = areas.reduce((sum, a) => sum + a, 0);
+    return worst([...areas, area], side, total + area) > worst(areas, side, total);
+}
+export function squarify(items, rect, minimum = 0) {
+    if (items.length === 0 || rect.w <= 0 || rect.h <= 0)
+        return [];
+    const ordered = [...items].sort((a, b) => b.value - a.value);
+    const floor = Math.max(minimum, 0);
+    const values = ordered.map((item) => Math.max(item.value, floor));
+    const total = values.reduce((sum, v) => sum + v, 0);
+    if (total <= 0)
+        return evenly(ordered, rect);
+    // Values are scaled into pixels ONCE, so every row shares one area currency.
+    const scale = (rect.w * rect.h) / total;
+    const out = [];
+    let remaining = rect;
+    let row = [];
+    ordered.forEach((item, i) => {
+        const area = values[i] * scale;
+        if (shouldClose(row.map((r) => r.area), area, Math.min(remaining.w, remaining.h))) {
+            remaining = placeRow(row, remaining, out);
+            row = [];
+        }
+        row.push({ item, area });
+    });
+    // `row` always holds at least the final item, so no guard: the loop pushes before it ends.
+    placeRow(row, remaining, out);
+    return out;
+}
+/** Equal shares, for when every value is zero and proportion means nothing. */
+function evenly(items, rect) {
+    const columns = Math.ceil(Math.sqrt(items.length));
+    const rows = Math.ceil(items.length / columns);
+    const w = rect.w / columns;
+    const h = rect.h / rows;
+    return items.map((item, i) => ({
+        item,
+        rect: {
+            x: rect.x + (i % columns) * w,
+            y: rect.y + Math.floor(i / columns) * h,
+            w,
+            h
+        }
+    }));
+}

package/dist/layout/structure.d.ts

@@ -0,0 +1,9 @@
+import type { LayoutFn } from './types.js';
+/**
+ * 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 declare const structure: LayoutFn;

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 }
+    };
+};