@peter.prib/renderengine 0.13.0 → 0.15.0

package/src/charting/Chart3D.js

@@ -72,8 +72,9 @@ export class Chart3D extends Chart {
 
     /**
      * Draw one 3D box through the orbit camera. Returns average corner depth.
+     * When `datum` is supplied (`{ label, series? }`), each face is recorded via `_datum()`.
      */
-    drawBox(renderer, x0, x1, y0, y1, z0, z1, color, toScreen) {
+    drawBox(renderer, x0, x1, y0, y1, z0, z1, color, toScreen, datum = null) {
         const camera = this.camera;
         const faceXSign = Math.sin(camera.theta) >= 0 ? 1 : -1;
         const faceZSign = Math.cos(camera.theta) >= 0 ? 1 : -1;
@@ -85,13 +86,17 @@ export class Chart3D extends Chart {
         const xSide = [c(xf, y0, z0), c(xf, y1, z0), c(xf, y1, z1), c(xf, y0, z1)];
         const zSide = [c(x0, y0, zf), c(x1, y0, zf), c(x1, y1, zf), c(x0, y1, zf)];
 
+        const faceEls = [];
         const drawFace = (pts, shade) => {
             const d = `M${pts[0].x},${pts[0].y} L${pts[1].x},${pts[1].y} L${pts[2].x},${pts[2].y} L${pts[3].x},${pts[3].y} Z`;
-            renderer.path(d, ColorPalette.lighten(color, shade), { color: '#333', width: 1 });
+            const el = renderer.path(d, ColorPalette.lighten(color, shade), { color: '#333', width: 1 });
+            if (datum) this._datum(el, datum);
+            if (el) faceEls.push(el);
         };
         drawFace(top, 0.15);
         drawFace(xSide, faceXSign > 0 ? -0.05 : -0.2);
         drawFace(zSide, faceZSign > 0 ? -0.1 : -0.25);
+        this._wireHoverTransform(faceEls, { dx: 0, dy: -5 });
 
         const allDepths = [...top, ...xSide, ...zSide].map(p => p.depth);
         return allDepths.reduce((s, d) => s + d, 0) / allDepths.length;

package/src/charting/ChartBox.js

@@ -48,11 +48,13 @@ export class ChartLabels {
      * @param {string} [options.title]
      * @param {string} [options.xAxisLabel]
      * @param {string} [options.yAxisLabel]
+     * @param {string} [options.secondaryYAxisLabel]
      */
-    constructor({ title, xAxisLabel, yAxisLabel }) {
+    constructor({ title, xAxisLabel, yAxisLabel, secondaryYAxisLabel } = {}) {
         this.title = title;
         this.xAxisLabel = xAxisLabel;
         this.yAxisLabel = yAxisLabel;
+        this.secondaryYAxisLabel = secondaryYAxisLabel;
     }
 
     /**
@@ -71,6 +73,11 @@ export class ChartLabels {
                 textAnchor: 'middle', rotation: -Math.PI / 2,
             });
         }
+        if (this.secondaryYAxisLabel) {
+            renderer.text(this.secondaryYAxisLabel, box.x + box.width + 45, box.y + box.height / 2, {
+                textAnchor: 'middle', rotation: Math.PI / 2,
+            });
+        }
         if (this.xAxisLabel) {
             renderer.text(this.xAxisLabel, box.x + box.width / 2, box.y + box.height + 45, {
                 textAnchor: 'middle', fontSize: '14px', fill: '#333',

package/src/charting/ColorPalette.js

@@ -35,6 +35,15 @@ export class ColorPalette {
         return ColorPalette.lighten(color, amount);
     }
 
+    /** Darken a hex color by `amount` in [0, 1]. */
+    static darken(color, amount) {
+        return ColorPalette.lighten(color, -Math.abs(amount));
+    }
+
+    darken(color, amount) {
+        return ColorPalette.darken(color, amount);
+    }
+
     /** Parse "#rrggbb" into {r, g, b}. */
     static hexToRgb(hex) {
         const num = parseInt(hex.replace('#', ''), 16);
@@ -60,8 +69,12 @@ export class ColorPalette {
     }
 
     /** Maps a value within [vMin, vMax] to a color along an N-stop scale
-     *  (linear interpolation between adjacent stops). */
-    static scaleColor(stops, vMin, vMax, v) {
+     *  (linear interpolation between adjacent stops). If midValue is provided,
+     *  it delegates to scaleDiverging. */
+    static scaleColor(stops, vMin, vMax, v, midValue) {
+        if (midValue !== undefined && stops.length >= 3) {
+            return ColorPalette.scaleDiverging(stops, vMin, vMax, v, midValue);
+        }
         if (stops.length === 1) return stops[0];
         const range = (vMax - vMin) || 1;
         const t = Math.min(1, Math.max(0, (v - vMin) / range));
@@ -72,8 +85,33 @@ export class ColorPalette {
         return ColorPalette.interpolate(stops[segIndex], stops[segIndex + 1], localT);
     }
 
-    scaleColor(stops, vMin, vMax, v) {
-        return ColorPalette.scaleColor(stops, vMin, vMax, v);
+    scaleColor(stops, vMin, vMax, v, midValue) {
+        return ColorPalette.scaleColor(stops, vMin, vMax, v, midValue);
+    }
+
+    /**
+     * Maps a value within [vMin, vMax] centered around a neutral midValue
+     * (e.g. 0) to a diverging color scale.
+     */
+    static scaleDiverging(stops, vMin, vMax, v, midValue = 0) {
+        if (!stops || stops.length === 0) return '#000000';
+        if (stops.length === 1) return stops[0];
+        const midIdx = Math.floor(stops.length / 2);
+        if (v <= midValue) {
+            const range = (midValue - vMin) || 1;
+            const t = Math.min(1, Math.max(0, (v - vMin) / range));
+            const subStops = stops.slice(0, midIdx + 1);
+            return ColorPalette.scaleColor(subStops, 0, 1, t);
+        } else {
+            const range = (vMax - midValue) || 1;
+            const t = Math.min(1, Math.max(0, (v - midValue) / range));
+            const subStops = stops.slice(midIdx);
+            return ColorPalette.scaleColor(subStops, 0, 1, t);
+        }
+    }
+
+    scaleDiverging(stops, vMin, vMax, v, midValue = 0) {
+        return ColorPalette.scaleDiverging(stops, vMin, vMax, v, midValue);
     }
 
     /** Perceptual-ish luma check for choosing readable text on a color. */

package/src/charting/DiagramEditor.js

@@ -38,7 +38,7 @@ import { Edge } from './Edge.js';
 import { PropertiesPanel } from './PropertiesPanel.js';
 import {
     MoveElementCommand, BringToFrontCommand, SendToBackCommand, RaiseCommand, LowerCommand,
-    ResizeCommand, RotateCommand, SetPropertiesCommand, DeleteTemplateCommand, CreateTemplateCommand,
+    ResizeCommand, RotateCommand, SetPropertiesCommand, DeleteTemplateCommand, CreateTemplateCommand, NestElementCommand,
 } from './DiagramEditorCommands.js';
 import { Arrangement, GroupCommand, UngroupCommand, LockCommand, arrangeMenuItems, align, distribute, matchSize, ALIGNMENTS, DISTRIBUTIONS, SIZE_MATCHES, layout, nestLayout, LAYOUTS } from './arrangement/index.js';
 import {
@@ -221,11 +221,15 @@ export class DiagramEditor {
                 const act = { c: () => this.copySelection(), x: () => this.cutSelection(), v: () => this.paste(), d: () => this.duplicateSelection() }[e.key.toLowerCase()];
                 if (act) { e.preventDefault(); act(); }
             }
-            // Ctrl+A selects every shape.
+            // Ctrl+A selects every shape, Ctrl+P prints the view.
             if ((e.ctrlKey || e.metaKey) && e.key.toLowerCase() === 'a') {
                 e.preventDefault();
                 this.selectTemplates(this.selectableIds());
             }
+            if ((e.ctrlKey || e.metaKey) && e.key.toLowerCase() === 'p') {
+                e.preventDefault();
+                this.print();
+            }
             // The arrow keys move the selection a grid step (one pixel without a grid; ten times with Shift).
             const ARROWS = { ArrowLeft: [-1, 0], ArrowRight: [1, 0], ArrowUp: [0, -1], ArrowDown: [0, 1] };
             if (ARROWS[e.key] && this.selectedTemplateId && !e.ctrlKey && !e.metaKey && !e.altKey) {
@@ -481,6 +485,8 @@ export class DiagramEditor {
         this._showMenu(x, y, [
             { label: '⚙ Properties', action: () => this._showEdgeProperties(edge) },
             { separator: true },
+            ...this.formatMenuItems(edgeId),
+            { separator: true },
             ...(at ? [{ label: 'Add waypoint here', action: () => this.addWaypoint(edgeId, at) }] : []),
             ...(bends ? [{ label: `Straighten (remove ${bends} waypoint${bends === 1 ? '' : 's'})`, action: () => this.clearWaypoints(edgeId) }] : []),
             { separator: true },
@@ -593,7 +599,13 @@ export class DiagramEditor {
      * @returns {Array<string>}
      */
     containedIn(templateId) {
-        return [];
+        const inner = [];
+        for (const [id, t] of this.templates) {
+            if (id !== templateId && this.parentOf(id) === templateId) {
+                inner.push(id);
+            }
+        }
+        return inner;
     }
 
     executeOrderCommand(elementId, operation) {
@@ -681,9 +693,9 @@ export class DiagramEditor {
         // Apply zoom and pan transform only to elements, not grid
         group.setAttribute('transform', `translate(${this.panX}, ${this.panY}) scale(${this.zoomLevel})`);
 
-        // Sort templates by z-index and render each
+        // Sort templates by z-index and render each (containers before contained children)
         const sorted = Array.from(this.templates.values())
-            .sort((a, b) => (a.zIndex || 0) - (b.zIndex || 0));
+            .sort((a, b) => (a.zIndex || 0) - (b.zIndex || 0) || (this.isAncestor(a.id, b.id) ? -1 : this.isAncestor(b.id, a.id) ? 1 : 0));
 
         for (const template of sorted) {
             if (template.visible === false) continue;
@@ -803,9 +815,76 @@ export class DiagramEditor {
             { label: 'Export image (PNG)', action: () => this.exportImage('png') },
             { label: 'Export image (SVG)', action: () => this.exportImage('svg') },
             { label: 'Copy image', action: () => this.exportImage('copy') },
+            { label: 'Print…', action: () => this.print() },
         ];
     }
 
+    /**
+     * Print the current view. Isolates the diagram SVG in a printable frame,
+     * scaled cleanly to fit page margins, and opens the print dialog.
+     * @param {{area?: 'drawing'|'view'}} [options]
+     * @returns {boolean|null} true when print was triggered, or null when unavailable
+     */
+    print({ area = 'drawing' } = {}) {
+        const doc = this.document ?? (typeof document !== 'undefined' ? document : null);
+        if (!doc) return null;
+        const host = this.drawingHost();
+        if (!host) return null;
+        const name = this.imageName();
+        let svgMarkup = null;
+        if (area === 'drawing' && host.tagName?.toLowerCase() === 'svg') {
+            const viewBox = this.drawingBounds();
+            if (viewBox) {
+                svgMarkup = this._withPlainDrawing(() => this._croppedSvg(host, viewBox));
+            }
+        }
+        if (!svgMarkup) {
+            svgMarkup = this._withPlainDrawing(() => prepareSvgMarkup(host));
+        }
+        if (!svgMarkup) return null;
+
+        const iframe = doc.createElement('iframe');
+        iframe.style.position = 'fixed';
+        iframe.style.right = '0';
+        iframe.style.bottom = '0';
+        iframe.style.width = '0';
+        iframe.style.height = '0';
+        iframe.style.border = '0';
+        doc.body?.appendChild(iframe);
+
+        const frameDoc = iframe.contentDocument || iframe.contentWindow?.document;
+        if (!frameDoc) {
+            iframe.remove?.();
+            return null;
+        }
+        frameDoc.open?.();
+        frameDoc.write?.(`<!DOCTYPE html><html><head><title>${name}</title>
+<style>
+  @page { size: auto; margin: 10mm; }
+  body { margin: 0; padding: 0; display: flex; flex-direction: column; align-items: center; justify-content: center; min-height: 100vh; }
+  svg { max-width: 100%; max-height: 100vh; height: auto; }
+</style>
+</head><body>${svgMarkup}</body></html>`);
+        frameDoc.close?.();
+
+        const triggerPrint = () => {
+            try {
+                iframe.contentWindow?.focus?.();
+                iframe.contentWindow?.print?.();
+            } finally {
+                setTimeout(() => iframe.remove?.(), 1000);
+            }
+        };
+
+        if (iframe.contentWindow) {
+            iframe.contentWindow.onload = triggerPrint;
+            setTimeout(triggerPrint, 250);
+        } else {
+            iframe.remove?.();
+        }
+        return true;
+    }
+
     /** Whether the drawing is on the page and not hidden (in a tab not selected, say). */
     isShown() {
         const host = this.drawingHost();
@@ -1404,6 +1483,7 @@ export class DiagramEditor {
             // A line that is only drawn (edge.editable false) takes no clicks; it still shows its tooltip.
             if (edge.editable !== false) hitArea.addEventListener('click', (e) => {
                 e.stopPropagation();
+                if (this.formatPainter) { this.formatPainterClick(edge.id); return; }
                 this.selectEdge(edge.id);
             });
             if (edge.editable !== false) hitArea.addEventListener('dblclick', (e) => {
@@ -2339,8 +2419,10 @@ export class DiagramEditor {
     deleteTemplatesCommand(templateIds) {
         const ids = new Set(templateIds);
         const lines = this.getAllEdges().filter(e => e.editable !== false && (ids.has(e.sourceId) || ids.has(e.targetId)));
+        const unnestSteps = [...ids].flatMap(id => this.containedIn(id).filter(cid => !ids.has(cid)).map(cid => this.nestCommand(cid, null))).filter(Boolean);
         return new CompositeCommand(this.deleteLabel([...ids]), [
             ...lines.map(edge => this.deleteEdgeCommand(edge.id)),
+            ...unnestSteps,
             ...[...ids].map(id => this.removeTemplateCommand(id)),
         ]);
     }
@@ -2635,26 +2717,55 @@ export class DiagramEditor {
     // ===== Format painter =====
 
     /**
-     * Pick up a shape's format (Template#format: paint and text style) for
-     * pasteFormat and the format painter. Returns it, or null.
+     * Pick up a shape's or line's format for pasteFormat and the format painter.
+     * Returns it, or null.
      */
-    copyFormat(templateId) {
-        const template = this.getTemplate(templateId);
-        if (!template) return null;
-        this.copiedFormat = template.format();
-        this._log?.(`Copied the format of ${template.name || 'the shape'}`);
-        return this.copiedFormat;
+    copyFormat(elementId) {
+        const template = this.getTemplate(elementId);
+        if (template) {
+            this.copiedFormat = { ...template.format(), _kind: 'shape' };
+            this._log?.(`Copied the format of ${template.name || 'the shape'}`);
+            return this.copiedFormat;
+        }
+        const edge = this.getEdge(elementId);
+        if (edge) {
+            this.copiedFormat = { ...edge.format(), _kind: 'edge' };
+            this._log?.(`Copied the line format of ${edge.label || 'connection'}`);
+            return this.copiedFormat;
+        }
+        return null;
     }
 
     /**
-     * Give shapes the copied format (each the keys it has among its
-     * `formatKeys`), as one undo step. Null when nothing changes or none is
-     * copied; a locked shape stops it.
+     * Give shapes or lines the copied format, as one undo step. Null when
+     * nothing changes or none is copied; a locked shape stops it.
      */
-    pasteFormat(templateIds = this.getSelectedIds()) {
+    pasteFormat(elementIds = this.getSelectedIds()) {
         const format = this.copiedFormat;
-        const templates = templateIds.map(id => this.getTemplate(id)).filter(Boolean);
-        if (!format || !templates.length) return null;
+        if (!format) return null;
+        const ids = Array.isArray(elementIds) ? elementIds : [elementIds];
+        const isEdgeFormat = format._kind === 'edge' || format.routing !== undefined || format.lineStyle !== undefined || format.startMarker !== undefined || format.endMarker !== undefined;
+
+        if (isEdgeFormat) {
+            const edges = ids.map(id => this.getEdge(id)).filter(Boolean);
+            if (!edges.length) return null;
+            const steps = edges.map(edge => {
+                const own = edge.format();
+                const patch = Object.fromEntries(
+                    (edge.constructor.formatKeys ?? EDGE_STYLE_PROPERTIES.map(p => p.key))
+                        .filter(k => k in format && own[k] !== format[k])
+                        .map(k => [k, format[k]])
+                );
+                return Object.keys(patch).length ? new SetStyleCommand(edge, patch, 'Paste line format') : null;
+            }).filter(Boolean);
+            if (!steps.length) return null;
+            const cmd = steps.length === 1 ? steps[0] : new CompositeCommand('Paste line format', steps);
+            this._executeCommand(cmd);
+            return cmd;
+        }
+
+        const templates = ids.map(id => this.getTemplate(id)).filter(Boolean);
+        if (!templates.length) return null;
         const locked = templates.find(t => this.isFixed(t.id));
         if (locked) { this.tellLocked(`"${locked.name || 'A shape'}"`, locked.id); return null; }
         const steps = templates.map(t => {
@@ -2663,40 +2774,46 @@ export class DiagramEditor {
             return Object.keys(patch).length ? new SetPropertiesCommand(t, patch, 'Paste format') : null;
         }).filter(Boolean);
         if (!steps.length) return null;
-        const cmd = new CompositeCommand('Paste format', steps);
+        const cmd = steps.length === 1 ? steps[0] : new CompositeCommand('Paste format', steps);
         this._executeCommand(cmd);
         return cmd;
     }
 
     /**
      * Turn the format painter on or off (Archi's Format Painter). While on, a
-     * click on a shape picks up its format when none is held, and gives the
-     * held one to each shape clicked after; Esc or the 🖌 button turns it off.
-     * Turned on with a shape selected, it starts with that shape's format.
+     * click on a shape or line picks up its format when none is held, and gives
+     * the held one to each shape or line clicked after; Esc or the 🖌 button
+     * turns it off.
      */
     setFormatPainter(on) {
         this.formatPainter = !!on;
         if (on) {
             this.copiedFormat = null;
-            if (this.selectedTemplateId) this.copyFormat(this.selectedTemplateId);
+            if (this.selectedTemplateId) {
+                this.copyFormat(this.selectedTemplateId);
+            } else if (this.selectedEdgeId) {
+                this.copyFormat(this.selectedEdgeId);
+            }
         }
         const host = this.drawingHost?.();
         if (host?.style) host.style.cursor = on ? 'copy' : '';
-        this._log?.(on ? 'Format painter: click shapes to give them the format' : 'Format painter off');
+        this._log?.(on ? 'Format painter: click shapes or lines to give them the format' : 'Format painter off');
     }
 
-    /** A click on a shape while the format painter is on. @protected */
-    formatPainterClick(templateId) {
-        if (!this.copiedFormat) { this.copyFormat(templateId); return null; }
-        return this.pasteFormat([templateId]);
+    /** A click on a shape or line while the format painter is on. @protected */
+    formatPainterClick(elementId) {
+        if (!this.copiedFormat) { this.copyFormat(elementId); return null; }
+        return this.pasteFormat([elementId]);
     }
 
-    /** Copy format, and Paste format when one is held (to the selection, when the shape is part of it). */
+    /** Copy format, and Paste format when one is held. */
     formatMenuItems(elementId) {
-        const targets = () => (this.selectedIds.has(elementId) ? this.getSelectedIds() : [elementId]);
+        const isEdge = !!this.getEdge(elementId);
+        const targets = () => (isEdge ? [elementId] : (this.selectedIds.has(elementId) ? this.getSelectedIds() : [elementId]));
+        const hasMatchingFormat = this.copiedFormat && (isEdge ? this.copiedFormat._kind === 'edge' : this.copiedFormat._kind !== 'edge');
         return [
             { label: '🖌 Copy format', action: () => this.copyFormat(elementId) },
-            ...(this.copiedFormat ? [{ label: 'Paste format', action: () => this.pasteFormat(targets()) }] : []),
+            ...(hasMatchingFormat ? [{ label: 'Paste format', action: () => this.pasteFormat(targets()) }] : []),
         ];
     }
 
@@ -3545,24 +3662,42 @@ export class DiagramEditor {
         return [...bounds].map(([id, b]) => ({ id, bounds: b }));
     }
 
-    /** Whether a shape dropped on another (its centre on it, sticking out) nests there. Never here; a subclass says when. */
-    nestsOnDrop(parentId, childId) {
+    /** Whether a shape is an ancestor of another in nesting containment hierarchy. */
+    isAncestor(ancestorId, descendantId) {
+        let curr = this.parentOf(descendantId);
+        while (curr) {
+            if (curr === ancestorId) return true;
+            curr = this.parentOf(curr);
+        }
         return false;
     }
 
-    /** The shape this one is drawn inside (nested in), or null. None here: a subclass with nesting says. */
+    /** Whether a shape dropped on another (its centre on it, sticking out) nests there. */
+    nestsOnDrop(parentId, childId) {
+        return typeof this.canHold === 'function' ? this.canHold(parentId, childId) : false;
+    }
+
+    /** The shape this one is drawn inside (nested in), or null. */
     parentOf(templateId) {
-        return null;
+        const t = this.getTemplate(templateId);
+        return t?.parentId ?? null;
     }
 
-    /** Whether a shape can be nested in another. Never here; a subclass with nesting says when. */
+    /** Whether a shape can be nested in another. */
     canHold(parentId, childId) {
-        return false;
+        if (!parentId || !childId || parentId === childId) return false;
+        const parent = this.getTemplate(parentId);
+        const child = this.getTemplate(childId);
+        if (!parent || !child) return false;
+        const isContainer = Boolean(parent.isContainer || parent.constructor.isContainer);
+        if (!isContainer) return false;
+        if (this.isAncestor(childId, parentId)) return false;
+        return true;
     }
 
     /** The command that nests a shape in another (or, with null, takes it out); null when it can't. */
     nestCommand(childId, parentId) {
-        return null;
+        return new NestElementCommand(this, childId, parentId);
     }
 
     /** After a move nested shapes or took them out (nestingChanges' list): a subclass's follow-up. None here. */

package/src/charting/DiagramEditorCommands.js

@@ -235,3 +235,31 @@ export class SetPropertiesCommand extends Command {
         }
     }
 }
+
+/**
+ * NestElementCommand — nest a child element in a parent container (or set parent to null).
+ * Works on any DiagramEditor or state with getTemplate/parentOf.
+ */
+export class NestElementCommand extends Command {
+    constructor(editor, childId, parentId) {
+        super(parentId ? 'Nest' : 'Unnest');
+        this.editor = editor;
+        this.childId = childId;
+        this.parentId = parentId;
+        this.previousParentId = typeof editor.parentOf === 'function' ? editor.parentOf(childId) : (editor.getTemplate(childId)?.parentId ?? null);
+    }
+
+    execute() {
+        const child = this.editor.getTemplate(this.childId);
+        if (child) {
+            child.parentId = this.parentId;
+        }
+    }
+
+    undo() {
+        const child = this.editor.getTemplate(this.childId);
+        if (child) {
+            child.parentId = this.previousParentId;
+        }
+    }
+}

package/src/charting/Edge.js

@@ -50,6 +50,8 @@ export class Edge {
         return true;
     }
 
+    static formatKeys = EDGE_STYLE_PROPERTIES.map(p => p.key);
+
     /** The style properties this line sets for itself (the properties dialog offers these): all of them here. */
     get styleProperties() {
         return EDGE_STYLE_PROPERTIES;
@@ -65,6 +67,11 @@ export class Edge {
         return Object.fromEntries(EDGE_STYLE_PROPERTIES.filter(p => this[p.key] !== undefined).map(p => [p.key, this[p.key]]));
     }
 
+    /** Picked-up line format for DiagramEditor#formatPainter. */
+    format() {
+        return this.styleOverrides();
+    }
+
     /**
      * Create a copy of this edge; waypoints are copied, not shared.
      */

package/src/charting/Hierarchy.js

@@ -145,6 +145,148 @@ export class Hierarchy {
         return result;
     }
 
+    /**
+     * Recursive rectangular partition (icicle / flame graph) layout over a node tree.
+     * Partitions `width` proportionally to node value at each level and steps down by `bandHeight` per depth.
+     * @returns {Array<{node: object, x: number, y: number, width: number, height: number, depth: number, isLeaf: boolean, topAncestor: object}>}
+     */
+    static icicleLayout(nodes, x, y, width, bandHeight, depth = 0, topAncestors = null) {
+        const items = (nodes ?? [])
+            .map(node => ({ node, value: Hierarchy.value(node) }))
+            .filter(it => it.value > 0);
+        const total = items.reduce((s, it) => s + it.value, 0) || 1;
+
+        const result = [];
+        let cursorX = x;
+        for (const it of items) {
+            const { node } = it;
+            const spanW = (it.value / total) * width;
+            const isLeaf = !node.children?.length;
+            const topAncestor = topAncestors ? topAncestors.get(node) : node;
+            result.push({ node, x: cursorX, y, width: spanW, height: bandHeight, depth, isLeaf, topAncestor });
+            if (!isLeaf) {
+                const childTopAncestors = new Map(node.children.map(c => [c, topAncestor]));
+                result.push(...Hierarchy.icicleLayout(node.children, cursorX, y + bandHeight, spanW, bandHeight, depth + 1, childTopAncestors));
+            }
+            cursorX += spanW;
+        }
+        return result;
+    }
+
+    /**
+     * Pack a list of circles with unscaled `radii` around the origin using a
+     * deterministic tangent-spiral placement, then normalize them into a unit
+     * enclosing disc `(0, 0, 1)`.
+     * @param {number[]} radii
+     * @param {number} [gap=0.04]
+     * @returns {Array<{x: number, y: number, r: number}>}
+     */
+    static packSiblingCircles(radii, gap = 0.04) {
+        if (!radii.length) return [];
+        if (radii.length === 1) return [{ x: 0, y: 0, r: 1 }];
+
+        const placed = [];
+        for (let i = 0; i < radii.length; i++) {
+            const r = radii[i];
+            if (i === 0) {
+                placed.push({ x: 0, y: 0, r });
+            } else if (i === 1) {
+                placed.push({ x: placed[0].r + r + gap, y: 0, r });
+            } else {
+                // Find the position closest to the centroid that does not overlap
+                // any already-placed circle, sampling tangent candidates around
+                // existing circles along golden-angle / angular rays.
+                let bestX = 0, bestY = 0, bestDist = Infinity;
+                const steps = 36;
+                for (let s = 0; s < steps; s++) {
+                    const angle = (s / steps) * Math.PI * 2 + i * 0.37;
+                    const ux = Math.cos(angle), uy = Math.sin(angle);
+                    let minProj = 0;
+                    for (const p of placed) {
+                        const minSep = p.r + r + gap;
+                        // Solve |(t*ux - p.x)^2 + (t*uy - p.y)^2| = minSep^2
+                        const b = ux * p.x + uy * p.y;
+                        const c = p.x * p.x + p.y * p.y - minSep * minSep;
+                        const disc = b * b - c;
+                        if (disc > 0) {
+                            const t = b + Math.sqrt(disc);
+                            if (t > minProj) minProj = t;
+                        }
+                    }
+                    if (minProj < bestDist) {
+                        bestDist = minProj;
+                        bestX = ux * minProj;
+                        bestY = uy * minProj;
+                    }
+                }
+                placed.push({ x: bestX, y: bestY, r });
+            }
+        }
+
+        // Compute bounding circle center and radius, then normalize to radius 1.
+        let minX = Infinity, maxX = -Infinity, minY = Infinity, maxY = -Infinity;
+        for (const p of placed) {
+            if (p.x - p.r < minX) minX = p.x - p.r;
+            if (p.x + p.r > maxX) maxX = p.x + p.r;
+            if (p.y - p.r < minY) minY = p.y - p.r;
+            if (p.y + p.r > maxY) maxY = p.y + p.r;
+        }
+        const midX = (minX + maxX) / 2;
+        const midY = (minY + maxY) / 2;
+        let boundR = 0;
+        for (const p of placed) {
+            const d = Math.hypot(p.x - midX, p.y - midY) + p.r;
+            if (d > boundR) boundR = d;
+        }
+        boundR = boundR || 1;
+        return placed.map(p => ({
+            x: (p.x - midX) / boundR,
+            y: (p.y - midY) / boundR,
+            r: p.r / boundR,
+        }));
+    }
+
+    /**
+     * Recursive nested-circle layout over a hierarchy node tree.
+     * @returns {Array<{node: object, cx: number, cy: number, r: number, depth: number, isLeaf: boolean, topAncestor: object}>}
+     */
+    static circlePackLayout(nodes, cx, cy, radius, depth = 0, topAncestors = null, padding = 3) {
+        const items = (nodes ?? [])
+            .map(node => ({ node, value: Hierarchy.value(node) }))
+            .filter(it => it.value > 0)
+            .sort((a, b) => b.value - a.value);
+        if (!items.length || radius <= 0) return [];
+
+        const maxVal = items[0].value || 1;
+        const rawRadii = items.map(it => Math.sqrt(it.value / maxVal));
+        const unitCircles = Hierarchy.packSiblingCircles(rawRadii, 0.06);
+        const usableRadius = Math.max(1, radius - padding);
+
+        const result = [];
+        for (let i = 0; i < items.length; i++) {
+            const { node, value } = items[i];
+            const u = unitCircles[i];
+            const nodeCx = cx + u.x * usableRadius;
+            const nodeCy = cy + u.y * usableRadius;
+            const nodeR = Math.max(1.5, u.r * usableRadius - padding * 0.5);
+            const isLeaf = !node.children?.length;
+            const topAncestor = topAncestors ? topAncestors.get(node) : node;
+
+            result.push({ node, value, cx: nodeCx, cy: nodeCy, r: nodeR, depth, isLeaf, topAncestor });
+            if (!isLeaf && nodeR > 8) {
+                const childTopAncestors = new Map(node.children.map(c => [c, topAncestor]));
+                // Reserve a small top band for the branch label when large enough
+                const labelReserve = nodeR > 26 ? Math.min(10, nodeR * 0.16) : 0;
+                const innerR = Math.max(2, nodeR - labelReserve * 0.65 - padding);
+                const innerCy = nodeCy + labelReserve * 0.35;
+                result.push(...Hierarchy.circlePackLayout(
+                    node.children, nodeCx, innerCy, innerR, depth + 1, childTopAncestors, Math.max(1.5, padding * 0.75)
+                ));
+            }
+        }
+        return result;
+    }
+
     /**
      * Flat, pre-order list of *visible* rows for an outline view. A branch
      * present in `collapsed` contributes its own row but none of its