@mstone6969/graph 0.0.0-stage → 0.2.0

package/dist/charts/threenetwork/Icicle3DChart.js

@@ -0,0 +1,87 @@
+import { ChartFamily, DataShape, Dimension, Orientation } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { Hierarchy3DBase } from "./Hierarchy3DBase.js";
+import { NetworkMarks3D } from "./NetworkMarks3D.js";
+import { partition } from "d3";
+import { BoxGeometry, Vector3 } from "three";
+// src/charts/threenetwork/Icicle3DChart.ts
+/** What block depth carries. */
+var IcicleDepth3D = /* @__PURE__ */ function(IcicleDepth3D) {
+	IcicleDepth3D["Share"] = "share";
+	IcicleDepth3D["Uniform"] = "uniform";
+	IcicleDepth3D["Receding"] = "receding";
+	return IcicleDepth3D;
+}({});
+var IcicleOrder3D = /* @__PURE__ */ function(IcicleOrder3D) {
+	IcicleOrder3D["Value"] = "value";
+	IcicleOrder3D["Input"] = "input";
+	return IcicleOrder3D;
+}({});
+var GAP = .012;
+/** Icicle as solid blocks: each level subdivides the one before, and depth can carry share or level. */
+var Icicle3DChart = class extends Hierarchy3DBase {
+	static meta = {
+		id: "icicle-3d",
+		name: "3D icicle",
+		family: ChartFamily.Hierarchy,
+		dimension: Dimension.Three,
+		shape: DataShape.Hierarchy,
+		description: "Splits a total level by level into adjacent blocks, so width always reads as share of the parent.",
+		tags: [
+			"icicle",
+			"partition",
+			"flame graph"
+		],
+		sample: (seed) => SampleData.tree(seed, 3, 5),
+		variants: {
+			orientation: Object.values(Orientation),
+			depthBy: Object.values(IcicleDepth3D),
+			order: Object.values(IcicleOrder3D),
+			hanging: [true, false]
+		}
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			orientation: Orientation.Vertical,
+			depthBy: "share",
+			order: "value",
+			hanging: true,
+			azimuth: 28,
+			elevation: 20,
+			distance: 4.3
+		};
+	}
+	build(ctx) {
+		const { orientation, depthBy, order, hanging } = this.options;
+		const root = partition().size([1, 1])(this.tree(order === "value"));
+		if (!root.value) return;
+		const marks = new NetworkMarks3D(ctx);
+		const levels = root.height + 1, vertical = orientation === Orientation.Vertical;
+		const thickness = (node) => depthBy === "uniform" ? .5 : depthBy === "receding" ? .9 * (1 - node.depth / (levels + .5)) : .12 + .8 * Math.sqrt((node.value ?? 0) / root.value);
+		marks.instances(new BoxGeometry(1, 1, 1), root.descendants().filter((node) => node.x1 > node.x0).map((node) => {
+			const across = (node.x1 - node.x0) * 1.9, along = (node.y1 - node.y0) * 1.7;
+			const a = (node.x0 + node.x1) * .95 - .95, b = (node.y0 + node.y1) / 2 * 1.7 - .85;
+			const signed = hanging ? -b : b;
+			return {
+				at: vertical ? new Vector3(a, signed, 0) : new Vector3(signed, a * .9, 0),
+				size: vertical ? new Vector3(Math.max(across - GAP, .002), along - GAP, thickness(node)) : new Vector3(along - GAP, Math.max(across * .9 - GAP, .002), thickness(node)),
+				color: this.branchColor(ctx, marks, node),
+				tip: this.tipOf(node)
+			};
+		}), { roughness: .6 });
+		for (const node of root.children ?? []) if (node.x1 - node.x0 > .12) {
+			const a = (node.x0 + node.x1) * .95 - .95, b = (node.y0 + node.y1) / 2 * 1.7 - .85, signed = hanging ? -b : b;
+			ctx.label(this.nameOf(node), vertical ? [
+				a,
+				signed,
+				thickness(node) / 2 + .03
+			] : [
+				signed,
+				a * .9,
+				thickness(node) / 2 + .03
+			], "ink", 10);
+		}
+	}
+};
+export { Icicle3DChart, IcicleDepth3D, IcicleOrder3D };

package/dist/charts/threenetwork/LabelSpacer3D.js

@@ -0,0 +1,40 @@
+// src/charts/threenetwork/LabelSpacer3D.ts
+var FOV = 19 * (Math.PI / 180);
+var RAD = Math.PI / 180;
+/** Estimates label boxes at the opening camera and accepts only those that land clear of earlier ones. */
+var LabelSpacer3D = class {
+	taken = [];
+	pixels;
+	sinA;
+	cosA;
+	sinE;
+	cosE;
+	constructor({ azimuth = 38, elevation = 26, distance = 5.4 }, height) {
+		this.pixels = height / (2 * distance * Math.tan(FOV));
+		this.sinA = Math.sin(azimuth * RAD);
+		this.cosA = Math.cos(azimuth * RAD);
+		this.sinE = Math.sin(elevation * RAD);
+		this.cosE = Math.cos(elevation * RAD);
+	}
+	/** Reserves room for `text` centred at `point`; false when it would collide. `anchor` is the box's horizontal centre, 0 for left-aligned, 1 for right-aligned. */
+	keep(point, text, size = 10, anchor = .5) {
+		const [x, y, z] = Array.isArray(point) ? point : [
+			point.x,
+			point.y,
+			point.z
+		];
+		const across = (x * this.cosA - z * this.sinA) * this.pixels;
+		const up = (y * this.cosE - (x * this.sinA + z * this.cosA) * this.sinE) * this.pixels;
+		const wide = text.length * size * .66 + 6, tall = size + 3;
+		const box = [
+			across - wide * anchor,
+			across + wide * (1 - anchor),
+			up - tall / 2,
+			up + tall / 2
+		];
+		if (this.taken.some(([l, r, t, b]) => box[0] < r && l < box[1] && box[2] < b && t < box[3])) return false;
+		this.taken.push(box);
+		return true;
+	}
+};
+export { LabelSpacer3D };

package/dist/charts/threenetwork/Loft.js

@@ -0,0 +1,39 @@
+import { BufferGeometry, Color, Float32BufferAttribute } from "three";
+// src/charts/threenetwork/Loft.ts
+/** Skins a sequence of equal-length closed rings into a surface. Every ribbon, tube and ring segment in this module is a loft. */
+var Loft = class {
+	static geometry(rings, color, { end = color, sharp = false, caps = true } = {}) {
+		const positions = [], colors = [], index = [];
+		const count = rings[0].length, tint = new Color();
+		const stride = sharp ? count * 2 : count;
+		const push = (point) => {
+			positions.push(point.x, point.y, point.z);
+			colors.push(tint.r, tint.g, tint.b);
+		};
+		rings.forEach((ring, r) => {
+			tint.lerpColors(color, end, rings.length > 1 ? r / (rings.length - 1) : 0);
+			ring.forEach((point, j) => {
+				push(point);
+				if (sharp) push(ring[(j + 1) % count]);
+			});
+		});
+		for (let r = 0; r < rings.length - 1; r++) for (let j = 0; j < count; j++) {
+			const a = r * stride + (sharp ? j * 2 : j);
+			const b = r * stride + (sharp ? j * 2 + 1 : (j + 1) % count);
+			index.push(a, b, b + stride, a, b + stride, a + stride);
+		}
+		if (caps) for (const [r, ring] of [[0, rings[0]], [rings.length - 1, rings.at(-1)]]) {
+			tint.lerpColors(color, end, rings.length > 1 ? r / (rings.length - 1) : 0);
+			const base = positions.length / 3;
+			ring.forEach(push);
+			for (let j = 1; j < count - 1; j++) index.push(base, base + j, base + j + 1);
+		}
+		const geometry = new BufferGeometry();
+		geometry.setAttribute("position", new Float32BufferAttribute(positions, 3));
+		geometry.setAttribute("color", new Float32BufferAttribute(colors, 3));
+		geometry.setIndex(index);
+		geometry.computeVertexNormals();
+		return geometry;
+	}
+};
+export { Loft };

package/dist/charts/threenetwork/MatrixCube3D.js

@@ -0,0 +1,145 @@
+import { Chart3D } from "../../core/Chart3D.js";
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { LabelSpacer3D } from "./LabelSpacer3D.js";
+import { NetworkMarks3D } from "./NetworkMarks3D.js";
+import { ascending, extent, group, max, scaleBand, sum } from "d3";
+import { BoxGeometry, OctahedronGeometry, SphereGeometry, Vector3 } from "three";
+// src/charts/threenetwork/MatrixCube3D.ts
+var MatrixCubeForm3D = /* @__PURE__ */ function(MatrixCubeForm3D) {
+	MatrixCubeForm3D["Solid"] = "solid";
+	MatrixCubeForm3D["Exploded"] = "exploded";
+	MatrixCubeForm3D["Floors"] = "floors";
+	return MatrixCubeForm3D;
+}({});
+var MatrixCubeMark3D = /* @__PURE__ */ function(MatrixCubeMark3D) {
+	MatrixCubeMark3D["Block"] = "block";
+	MatrixCubeMark3D["Sphere"] = "sphere";
+	MatrixCubeMark3D["Octahedron"] = "octahedron";
+	return MatrixCubeMark3D;
+}({});
+var MatrixCubeSizing3D = /* @__PURE__ */ function(MatrixCubeSizing3D) {
+	MatrixCubeSizing3D["Volume"] = "volume";
+	MatrixCubeSizing3D["Uniform"] = "uniform";
+	return MatrixCubeSizing3D;
+}({});
+var MatrixCubeFilter3D = /* @__PURE__ */ function(MatrixCubeFilter3D) {
+	MatrixCubeFilter3D["All"] = "all";
+	MatrixCubeFilter3D["TopQuarter"] = "top-quarter";
+	return MatrixCubeFilter3D;
+}({});
+var MatrixCubeOrder3D = /* @__PURE__ */ function(MatrixCubeOrder3D) {
+	MatrixCubeOrder3D["Input"] = "input";
+	MatrixCubeOrder3D["Total"] = "total";
+	return MatrixCubeOrder3D;
+}({});
+/** Three crossed categories as a cube of cells: a time-varying adjacency matrix, or any value with three keys. */
+var MatrixCube3D = class extends Chart3D {
+	static meta = {
+		id: "matrix-cube-3d",
+		name: "Matrix cube",
+		family: ChartFamily.Matrix,
+		dimension: Dimension.Three,
+		shape: DataShape.Table,
+		description: "Stacks matrices into a cube so a value crossed by three dimensions can be scanned along any of them.",
+		tags: [
+			"matrix cube",
+			"space-time cube",
+			"adjacency",
+			"tensor"
+		],
+		sample: (seed) => Array.from({ length: 5 }, (_, l) => SampleData.categories(seed + l, 8, 6).map(({ category, series, value }) => ({
+			row: category,
+			column: series,
+			layer: `Q${l + 1}`,
+			value
+		}))).flat(),
+		variants: {
+			form: Object.values(MatrixCubeForm3D),
+			mark: Object.values(MatrixCubeMark3D),
+			sizing: Object.values(MatrixCubeSizing3D),
+			filter: Object.values(MatrixCubeFilter3D),
+			order: Object.values(MatrixCubeOrder3D)
+		}
+	};
+	defaults() {
+		return {
+			row: "row",
+			column: "column",
+			layer: "layer",
+			value: "value",
+			form: "solid",
+			mark: "block",
+			sizing: "volume",
+			filter: "all",
+			order: "input",
+			distance: 5.2
+		};
+	}
+	keys(rows, column, measure) {
+		const totals = group(rows, (row) => String(row[column]));
+		const keys = [...totals.keys()];
+		if (this.options.order === "input") return keys;
+		return keys.sort((a, b) => ascending(sum(totals.get(b), (row) => +row[measure] || 0), sum(totals.get(a), (row) => +row[measure] || 0)));
+	}
+	geometry() {
+		const { mark } = this.options;
+		if (mark === "sphere") return new SphereGeometry(.5, 16, 12);
+		if (mark === "octahedron") return new OctahedronGeometry(.62);
+		return new BoxGeometry(1, 1, 1);
+	}
+	build(ctx) {
+		const { data, row, column, layer, value, form, sizing, filter } = this.options;
+		const rows = (data ?? []).filter((item) => Number.isFinite(+item[value]) && item[value] != null);
+		if (!rows.length) return;
+		const marks = new NetworkMarks3D(ctx);
+		const x = scaleBand(this.keys(rows, column, value), [-.95, .95]).padding(.1);
+		const z = scaleBand(this.keys(rows, row, value), [-.95, .95]).padding(.1);
+		const layers = [...new Set(rows.map((item) => String(item[layer])))];
+		const spread = form === "solid" ? .1 : form === "exploded" ? .62 : .8;
+		const y = scaleBand(layers, [-.9, .9]).padding(spread);
+		const [low = 0, high = 1] = extent(rows, (item) => +item[value]);
+		const signed = low < 0;
+		const peak = Math.max(Math.abs(low), Math.abs(high)) || 1;
+		const cut = [...rows].map((item) => Math.abs(+item[value])).sort(ascending)[Math.floor(rows.length * .75)] ?? 0;
+		const shown = filter === "all" ? rows : rows.filter((item) => Math.abs(+item[value]) >= cut);
+		const width = x.bandwidth(), depth = z.bandwidth();
+		const tall = form === "floors" ? Math.min(y.bandwidth(), .02) : y.bandwidth();
+		marks.instances(this.geometry(), shown.map((item) => {
+			const amount = +item[value], share = Math.abs(amount) / peak;
+			const flat = form === "floors";
+			const edge = sizing === "volume" ? Math.max(.12, flat ? Math.sqrt(share) : Math.cbrt(share)) : .92;
+			const color = signed ? ctx.palette.diverging(amount / peak) : ctx.palette.sequential(.12 + .88 * (amount - low) / (high - low || 1));
+			return {
+				at: new Vector3(x(String(item[column])) + width / 2, y(String(item[layer])) + y.bandwidth() / 2, z(String(item[row])) + depth / 2),
+				size: new Vector3(width * edge, tall * (flat ? 1 : edge), depth * edge),
+				color,
+				tip: {
+					title: `${item[row]} · ${item[column]}`,
+					rows: [[String(item[layer]), amount]]
+				}
+			};
+		}), { roughness: .5 });
+		const top = max(layers.map((name) => y(name))) ?? 0;
+		const spacer = new LabelSpacer3D(this.options, this.size.height);
+		const side = (name, spot, tone, anchor) => {
+			if (spacer.keep(spot, name, 10, anchor)) ctx.label(name, spot, tone, 10).center.x = anchor;
+		};
+		layers.forEach((name) => side(name, [
+			1.04,
+			y(name) + y.bandwidth() / 2,
+			-1.04
+		], "muted", 0));
+		x.domain().forEach((name, i) => side(name, [
+			x(name) + width / 2,
+			top + y.bandwidth() + (i % 2 ? .26 : .1),
+			-1.04
+		], "secondary", .5));
+		z.domain().forEach((name) => side(name, [
+			1.04,
+			-.96,
+			z(name) + depth / 2
+		], "secondary", 0));
+	}
+};
+export { MatrixCube3D, MatrixCubeFilter3D, MatrixCubeForm3D, MatrixCubeMark3D, MatrixCubeOrder3D, MatrixCubeSizing3D };

package/dist/charts/threenetwork/MultilayerNetwork3D.js

@@ -0,0 +1,139 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { ForceLayout3D } from "./ForceLayout3D.js";
+import { Graph3DBase } from "./Graph3DBase.js";
+import { NetworkMarks3D } from "./NetworkMarks3D.js";
+import { Path3D } from "./Path3D.js";
+import { BoxGeometry, Quaternion, Vector3 } from "three";
+// src/charts/threenetwork/MultilayerNetwork3D.ts
+var LayerStack3D = /* @__PURE__ */ function(LayerStack3D) {
+	LayerStack3D["Tower"] = "tower";
+	LayerStack3D["Stairs"] = "stairs";
+	LayerStack3D["Pages"] = "pages";
+	return LayerStack3D;
+}({});
+/** How nodes sit within their own plate. */
+var LayerPlacement3D = /* @__PURE__ */ function(LayerPlacement3D) {
+	LayerPlacement3D["Force"] = "force";
+	LayerPlacement3D["Circle"] = "circle";
+	LayerPlacement3D["Grid"] = "grid";
+	return LayerPlacement3D;
+}({});
+var LayerBridge3D = /* @__PURE__ */ function(LayerBridge3D) {
+	LayerBridge3D["Straight"] = "straight";
+	LayerBridge3D["Arc"] = "arc";
+	return LayerBridge3D;
+}({});
+var PLATE = .62;
+/** One plate per group: for multiplex networks where links inside a layer and links between layers mean different things. */
+var MultilayerNetwork3D = class extends Graph3DBase {
+	static meta = {
+		id: "multilayer-network-3d",
+		name: "Multilayer network",
+		family: ChartFamily.Network,
+		dimension: Dimension.Three,
+		shape: DataShape.Graph,
+		description: "Separates groups onto stacked plates, so links within a layer read apart from links crossing between layers.",
+		tags: [
+			"multiplex",
+			"multilayer",
+			"network",
+			"layers"
+		],
+		sample: (seed) => SampleData.graph(seed, 60, 4),
+		variants: {
+			stack: Object.values(LayerStack3D),
+			placement: Object.values(LayerPlacement3D),
+			bridge: Object.values(LayerBridge3D),
+			plates: [true, false]
+		}
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			stack: "tower",
+			placement: "force",
+			bridge: "straight",
+			plates: true,
+			azimuth: 34,
+			elevation: 22,
+			distance: 4.5
+		};
+	}
+	/** Position of a plate-space point (`u`, `v` in -1..1) on layer `g`. */
+	onPlate(g, groups, u, v) {
+		const { stack } = this.options;
+		const f = groups > 1 ? g / (groups - 1) : .5;
+		if (stack === "stairs") return new Vector3(u * PLATE * .72 + (f - .5) * 1, (f - .5) * 1.5, v * PLATE * .72 - (f - .5) * 1);
+		if (stack === "pages") {
+			const angle = (f - .5) * Math.PI * 1.1;
+			const r = (u + 1) * .5 * PLATE * 1.3 + .12;
+			return new Vector3(Math.sin(angle) * r, v * PLATE * 1.05, -Math.cos(angle) * r + .5);
+		}
+		return new Vector3(u * PLATE * 1.2, (f - .5) * 1.75, v * PLATE * 1.2);
+	}
+	seats(members, links) {
+		const { placement } = this.options;
+		const count = members.length;
+		if (placement === "circle") return new Map(members.map((node, i) => [node, [Math.cos(i / count * Math.PI * 2) * .86, Math.sin(i / count * Math.PI * 2) * .86]]));
+		if (placement === "grid") {
+			const side = Math.ceil(Math.sqrt(count));
+			return new Map(members.map((node, i) => [node, [side > 1 ? i % side / (side - 1) * 1.7 - .85 : 0, side > 1 ? Math.floor(i / side) / (side - 1) * 1.7 - .85 : 0]]));
+		}
+		const slot = new Map(members.map((node, i) => [node, i]));
+		const inner = links.filter((link) => slot.has(link.source) && slot.has(link.target)).map((link) => [slot.get(link.source), slot.get(link.target)]);
+		const flat = ForceLayout3D.run({
+			count,
+			links: inner,
+			squash: .4,
+			ticks: 160
+		});
+		const reach = Math.max(.001, ...flat.flatMap((p) => [Math.abs(p.x), Math.abs(p.z)]));
+		return new Map(members.map((node, i) => [node, [flat[i].x / reach * .86, flat[i].z / reach * .86]]));
+	}
+	build(ctx) {
+		const { nodes, links, groups } = this.model();
+		if (!nodes.length) return;
+		const { bridge, plates, stack } = this.options;
+		const marks = new NetworkMarks3D(ctx);
+		const seats = /* @__PURE__ */ new Map();
+		groups.forEach((group, g) => {
+			const members = nodes.filter((node) => node.group === group);
+			for (const [node, [u, v]] of this.seats(members, links)) seats.set(node, this.onPlate(g, groups.length, u, v));
+		});
+		const at = (node) => seats.get(node);
+		const route = (link) => {
+			const a = at(link.source), b = at(link.target);
+			if (link.source.group === link.target.group || bridge === "straight") return [a, b];
+			return Path3D.quadratic(a, a.clone().add(b).multiplyScalar(.5).multiply(new Vector3(1.75, 1, 1.75)), b, 16);
+		};
+		if (plates) marks.instances(new BoxGeometry(1, 1, 1), groups.map((group, g) => this.plateOf(ctx, marks, group, g, groups.length)), {
+			opacity: .5,
+			shadow: false,
+			roughness: .9
+		});
+		this.drawLinks(ctx, marks, links, route);
+		this.drawNodes(ctx, marks, nodes, at);
+		if (stack !== "pages") groups.forEach((group, g) => {
+			const corner = this.onPlate(g, groups.length, -1, 1);
+			ctx.label(group, [
+				corner.x,
+				corner.y + .05,
+				corner.z
+			], "secondary", 10);
+		});
+	}
+	plateOf(ctx, marks, group, g, groups) {
+		const { stack } = this.options;
+		const center = this.onPlate(g, groups, 0, 0);
+		const f = groups > 1 ? g / (groups - 1) : .5;
+		const spin = stack === "pages" ? new Quaternion().setFromAxisAngle(new Vector3(0, 1, 0), Math.PI / 2 - (f - .5) * Math.PI * 1.1) : void 0;
+		return {
+			at: center,
+			size: stack === "pages" ? new Vector3(PLATE * 1.3, PLATE * 2.1, .008) : stack === "stairs" ? new Vector3(PLATE * 1.44 * 1.1, .008, PLATE * 1.44 * 1.1) : new Vector3(PLATE * 2.4 * 1.05, .008, PLATE * 2.4 * 1.05),
+			color: marks.faded(ctx.palette.color(group), .72),
+			...spin ? { spin } : {}
+		};
+	}
+};
+export { LayerBridge3D, LayerPlacement3D, LayerStack3D, MultilayerNetwork3D };

package/dist/charts/threenetwork/NetworkMarks3D.js

@@ -0,0 +1,130 @@
+import { Loft } from "./Loft.js";
+import { BufferGeometry, CircleGeometry, Color, DoubleSide, Float32BufferAttribute, Fog, InstancedMesh, LineBasicMaterial, LineSegments, Mesh, MeshStandardMaterial, Object3D, PlaneGeometry, Scene, Vector3 } from "three";
+import { mergeGeometries } from "three/addons/utils/BufferGeometryUtils.js";
+// src/charts/threenetwork/NetworkMarks3D.ts
+var STAGGER = .6;
+/** Module drawing kit: instanced marks, lofted surfaces, ground plates and depth fog, all wired for reveal and picking. */
+var NetworkMarks3D = class {
+	ctx;
+	constructor(ctx) {
+		this.ctx = ctx;
+		const scene = ctx.root.parent;
+		if (!(scene instanceof Scene)) return;
+		const fog = scene.fog = new Fog(ctx.theme.surface, 4, 9);
+		scene.onBeforeRender = (_renderer, _scene, camera) => {
+			const distance = camera.position.length();
+			fog.near = distance - .9;
+			fog.far = distance + 4.2;
+		};
+	}
+	/** Mixes a colour towards the surface so links and shells sit behind the nodes they connect. */
+	faded(color, amount) {
+		return `#${new Color(color).lerp(new Color(this.ctx.theme.surface), amount).getHexString()}`;
+	}
+	surface(finish, vertexColors) {
+		const { opacity = 1, roughness = .55 } = finish;
+		const glass = opacity < 1;
+		return new MeshStandardMaterial({
+			roughness,
+			metalness: 0,
+			vertexColors,
+			side: DoubleSide,
+			transparent: glass,
+			opacity,
+			depthWrite: !glass
+		});
+	}
+	/** One instanced mark per item. Size is a uniform scale or per-axis scale of `geometry`. */
+	instances(geometry, items, finish = {}) {
+		if (!items.length) {
+			geometry.dispose();
+			return null;
+		}
+		const { rise = false, shadow = true, delay = 0, duration = .9 } = finish;
+		const mesh = new InstancedMesh(geometry, this.surface(finish, false), items.length);
+		mesh.frustumCulled = false;
+		mesh.castShadow = shadow;
+		const dummy = new Object3D(), full = new Vector3();
+		const place = (progress) => {
+			items.forEach((item, i) => {
+				const p = Math.max(1e-4, Math.min(1, progress * 1.6 - STAGGER * i / items.length));
+				typeof item.size === "number" ? full.setScalar(item.size) : full.copy(item.size);
+				dummy.position.copy(item.at);
+				if (item.spin) dummy.quaternion.copy(item.spin);
+				else dummy.quaternion.identity();
+				if (rise) {
+					dummy.scale.set(full.x, full.y * p, full.z);
+					dummy.position.y -= full.y * (1 - p) / 2;
+				} else dummy.scale.copy(full).multiplyScalar(p);
+				dummy.updateMatrix();
+				mesh.setMatrixAt(i, dummy.matrix);
+			});
+			mesh.instanceMatrix.needsUpdate = true;
+			mesh.boundingSphere = null;
+		};
+		items.forEach((item, i) => mesh.setColorAt(i, this.ctx.color(item.color)));
+		this.ctx.reveal(place, duration, delay);
+		this.ctx.root.add(mesh);
+		if (items.some((item) => item.tip)) this.ctx.pick(mesh, (i) => items[i].tip ?? {});
+		return mesh;
+	}
+	/** Hoverable lofted marks, one mesh each. Use for up to a few hundred marks that need tooltips. */
+	lofts(items, style = {}, finish = {}) {
+		const { shadow = true, delay = 0, duration = .9 } = finish;
+		const material = this.surface(finish, true);
+		items.forEach((item, i) => {
+			const mesh = new Mesh(this.skin(item, style), material);
+			mesh.castShadow = shadow;
+			this.ctx.root.add(mesh);
+			this.draw(mesh.geometry, duration, delay + i / items.length * duration * .5);
+			if (item.tip) this.ctx.pick(mesh, () => item.tip);
+		});
+	}
+	/** Thousands of lofted marks merged into one draw call; not individually hoverable. */
+	batch(items, style = {}, finish = {}) {
+		if (!items.length) return;
+		const { shadow = false, delay = 0, duration = 1.1 } = finish;
+		const parts = items.map((item) => this.skin(item, style));
+		const merged = mergeGeometries(parts);
+		parts.forEach((part) => part.dispose());
+		const mesh = new Mesh(merged, this.surface(finish, true));
+		mesh.castShadow = shadow;
+		this.ctx.root.add(mesh);
+		this.draw(merged, duration, delay);
+	}
+	skin({ rings, color, end }, style) {
+		return Loft.geometry(rings, this.ctx.color(color), {
+			...style,
+			...end ? { end: this.ctx.color(end) } : {}
+		});
+	}
+	draw(geometry, duration, delay) {
+		const count = geometry.index.count;
+		this.ctx.reveal((progress) => geometry.setDrawRange(0, Math.ceil(count * progress)), duration, delay);
+	}
+	/** Thin plate under a chart: quiet enough to read as ground, solid enough to catch shadows. */
+	ground(y, half = 1.15, round = false) {
+		const plate = new Mesh(round ? new CircleGeometry(half, 96) : new PlaneGeometry(half * 2, half * 2), new MeshStandardMaterial({
+			color: this.ctx.theme.grid,
+			roughness: .9
+		}));
+		plate.rotation.x = -Math.PI / 2;
+		plate.position.y = y;
+		plate.receiveShadow = true;
+		this.ctx.root.add(plate);
+		return plate;
+	}
+	/** Hairline segments for recessive guides. `points` come in pairs. */
+	lines(points, tone = "axis") {
+		const geometry = new BufferGeometry();
+		geometry.setAttribute("position", new Float32BufferAttribute(points.flatMap((p) => [
+			p.x,
+			p.y,
+			p.z
+		]), 3));
+		const segments = new LineSegments(geometry, new LineBasicMaterial({ color: this.ctx.theme[tone] }));
+		this.ctx.root.add(segments);
+		return segments;
+	}
+};
+export { NetworkMarks3D };