@fnndsc/orrery 0.1.0

package/dist/scene/orrery.js

@@ -0,0 +1,1555 @@
+/**
+ * @file The orrery itself: one three.js space, composed of the layers.
+ *
+ * A surface hands in a graph — nodes with identity, parents and joins, a
+ * scalar metric, a multiplicity, and a LOOK it has read from its own domain
+ * (a state, a named paint, an ember, whether the finish wave passes) — and
+ * the orrery lays it out (`layout/`), draws it (`draw/`), and lets it be
+ * steered and picked (`controls/`). It knows nothing of what the nodes
+ * stand for: a surface says what a node looks like, and gets its own nodes
+ * back from every pick.
+ *
+ * Layout is a strategy seam:
+ * - `ranked`: deterministic tiers by graph depth; the same graph always
+ *   draws the same picture, the third dimension is presentation.
+ * - `molecule`: a d3-force-3d settle, radii scaled by the metric; a surface
+ *   that groups its nodes (a hand-off key) settles in a worker it provides.
+ *
+ * Colours come from the palette the surface hands in, read on every
+ * rebuild, so a theme change repaints the space like everything else.
+ *
+ * @module
+ */
+import * as THREE from 'three';
+import { NODE_RADIUS, PHYSICS_DEFAULT, molecule_prepare, moleculeRadii_of as orreryRadii_of, ranked_layout, layoutEngine_get, layoutInput_build, } from '../layout/index.js';
+import { STAR_GLOW, WAVE_STEP_MS, haloRadius_of, CensusField, HandoffField, SphereField, StarField, TubeField, LabelField, paint_resolve, } from '../draw/index.js';
+import { CameraRig, PointerGestures, ReplayClock, Picker, DRAG_THRESHOLD_PX, } from '../controls/index.js';
+import { PullSimulation } from '../layout/pull.js';
+export { PHYSICS_DEFAULT };
+/** How long one node's wave flare lasts (rise and fall). */
+const WAVE_FLARE_MS = 700;
+/** Rest between wave loops in the ambient miniature. */
+const WAVE_LOOP_GAP_MS = 2_500;
+/** How long a tap's name stays up after the finger lifts. */
+const TAP_TIP_MS = 1500;
+/**
+ * The palette used when a surface hands none in.
+ *
+ * @returns Warm status colours, a cool root and a cool pulse.
+ */
+export function palette_default() {
+    return {
+        running: new THREE.Color('#ff7700'),
+        done: new THREE.Color('#ffeecc'),
+        error: new THREE.Color('#ff2222'),
+        template: new THREE.Color('#ffaa44'),
+        unknown: new THREE.Color('#555555'),
+        edge: new THREE.Color('#cc5500'),
+        join: new THREE.Color('#ffcc99'),
+        root: new THREE.Color('#6fbfae'),
+        pulse: new THREE.Color('#48d8f0'),
+    };
+}
+/**
+ * Ranked placement is declared once in `./rankedLayout.js` and drawn twice
+ * — here, and as SVG in a preview card, which cannot hold a WebGL context.
+ * What this file adds is the third dimension: the tree is a sheet, every
+ * node at z = 0, so an orbit reads as turning the sheet and never scrambles
+ * the hierarchy (the earlier per-node depth jitter made a turned tree look
+ * like a different feed).
+ */
+/**
+ * A scene node as orrery's molecule reads it: its parents with its joins
+ * after them, and its metric.
+ *
+ * @param node - The scene node.
+ * @returns The molecule node.
+ */
+function moleculeNode_of(node) {
+    const out = { id: node.id, parents: [...node.parentIds, ...node.joinParentIds] };
+    if (node.metric !== undefined)
+        out.metric = node.metric;
+    return out;
+}
+/**
+ * The ranked layout, placed in the scene: orrery places the tiers, the scene
+ * holds them as vectors beside their nodes.
+ *
+ * @param nodes - The graph's nodes.
+ * @returns Every node placed.
+ */
+function layout_ranked(nodes) {
+    const places = ranked_layout(nodes.map((node) => {
+        const out = { id: node.id, parentIds: node.parentIds };
+        if (node.metric !== undefined)
+            out.metric = node.metric;
+        return out;
+    }));
+    return nodes.map((node, index) => {
+        const at = places[index];
+        return { node, position: new THREE.Vector3(...(at?.position ?? [0, 0, 0])), radius: at?.radius ?? NODE_RADIUS };
+    });
+}
+/**
+ * Each node's radius, as the molecule settle sizes it.
+ *
+ * @param nodes - The graph's nodes.
+ * @returns Radius by id.
+ */
+function moleculeRadii_of(nodes) {
+    return orreryRadii_of(nodes.map(moleculeNode_of));
+}
+/**
+ * Builds orrery's molecule settle over the scene's nodes and seeds.
+ *
+ * @param nodes - The graph's nodes.
+ * @param dimensions - 2 or 3.
+ * @param seed - Where nodes stood last.
+ * @param physics - The terms of this settle.
+ * @param frozen - Nodes that stand where their seed put them.
+ * @returns The settle, placing into the scene's vectors.
+ */
+function moleculeScene_prepare(nodes, dimensions = 3, seed = new Map(), physics = PHYSICS_DEFAULT, frozen = new Set()) {
+    const seeds = new Map([...seed].map(([id, at]) => [id, [at.x, at.y, at.z]]));
+    const settle = molecule_prepare(nodes.map(moleculeNode_of), dimensions, seeds, physics, frozen);
+    return {
+        total: settle.total,
+        moving: settle.moving,
+        step: settle.step,
+        place: () => settle.place().map((place, index) => ({
+            node: nodes[index],
+            position: new THREE.Vector3(...place.position),
+            radius: place.radius,
+        })),
+    };
+}
+/**
+ * Lays out a molecule in one go.
+ *
+ * @returns Every node placed.
+ */
+function layout_molecule(nodes, dimensions = 3, seed = new Map(), physics = PHYSICS_DEFAULT, frozen = new Set()) {
+    const settle = moleculeScene_prepare(nodes, dimensions, seed, physics, frozen);
+    settle.step(settle.total);
+    return settle.place();
+}
+/** Settles smaller than this many ticks × nodes run in one go. */
+const SLICE_MIN_WORK = 90 * 400;
+/** Time a settle may take from one frame before it yields to the next. */
+const SLICE_BUDGET_MS = 12;
+/**
+ * One live DAG rendering bound to a container element.
+ */
+export class Orrery {
+    container;
+    handlers;
+    paletteOf;
+    /** The replay under way, or null: its clock, the arrivals, and what is shown. */
+    replay = null;
+    layoutWorkerOf;
+    ambient;
+    renderer;
+    scene;
+    camera;
+    group = new THREE.Group();
+    /** What lies under a pointer, among everything drawn. */
+    picker;
+    /** The solid spheres, halos and plain edges. */
+    spheres = new SphereField(this.group);
+    /** Every drawn sphere and halo, by its node's id: the sphere field's own map. */
+    get meshes() {
+        return this.spheres.map;
+    }
+    /** The field's stars, threads and nebulae. */
+    starField = new StarField(this.group);
+    /** Captions pinned above nodes. */
+    labels = new LabelField(this.group);
+    /** Every solid molecule's tubes, and the lamps its stages wear. */
+    tubes = new TubeField({
+        parent: this.group,
+        node: (id) => this.tubeNode_of(id),
+        sphere: (id) => this.meshes.get(id),
+        palette: () => this.palette_read(),
+    });
+    /** Every molecule's place between stars and spheres. */
+    handoffField = new HandoffField({
+        spheres: this.spheres,
+        stars: this.starField,
+        tubes: this.tubes,
+        look: (id) => this.handoffLook_of(id),
+    });
+    /** Every job of every stage, when the scene draws a census. */
+    censusField = new CensusField({
+        parent: this.group,
+        stars: this.starField,
+        tubes: this.tubes,
+        starsView: () => ({ pixelRatio: window.devicePixelRatio, heightPx: this.renderer.domElement.height, fovDeg: this.camera.fov }),
+    });
+    /** Where the last projection left every node — the next settle's seed. */
+    lastPositions = new Map();
+    /** Nodes held still through the current settle. */
+    frozen = new Set();
+    /** Physics for the current settle alone, over the standing terms. */
+    physicsOnce = undefined;
+    /** CENSUS: render every member of every ×N group as an instanced point. */
+    census = false;
+    /** The molecule's physics terms (see PhysicsTerms). */
+    physics = { ...PHYSICS_DEFAULT };
+    /** Sets physics terms and re-settles (warm-started, so it morphs). */
+    physics_set(terms, resettle = true) {
+        this.physics = { ...this.physics, ...terms };
+        // A caller about to set a new graph anyway changes the terms without
+        // settling the old one first: the first paint of a space used to
+        // settle three thousand spheres twice.
+        if (resettle)
+            this.rebuild();
+    }
+    physics_get() {
+        return { ...this.physics };
+    }
+    /**
+     * Toggles the census projection: the full multiplicity of the graph as
+     * instanced members on analytic shells (spectacle), versus the semantic
+     * shape (work). Selection belongs to shape; census draws, never picks.
+     *
+     * @param on - Whether census is active.
+     */
+    census_set(on) {
+        if (this.census === on)
+            return;
+        this.census = on;
+        // The census shells what stands; it moves nothing.
+        this.rebuild(true, 'hold');
+    }
+    census_get() {
+        return this.census;
+    }
+    graph = { nodes: [] };
+    /** The grab in progress: which node, its drag plane, and travel so far. */
+    drag = null;
+    /** The live reaction simulation while (and shortly after) a grab. */
+    pull = null;
+    /** The pulse wave's schedule: node id to flare time (ms into the wave). */
+    waveTimes = new Map();
+    /** Wall-clock start of the running wave, or null when no wave runs. */
+    waveStartAt = null;
+    /**
+     * The camera and the world it turns: the focus, the flights, the hold
+     * inside a node, the idle spin, and whether the operator has placed the
+     * camera since the scene last framed itself.
+     */
+    rig;
+    /** How nodes are drawn: lit spheres (every pane), or stars (the universe's choice). */
+    drawMode = 'spheres';
+    /** Placed nodes by id, for the spheres a solid feed draws. */
+    placedById = new Map();
+    /**
+     * The pointer's intents on the canvas — the view drag, the fingers, the
+     * taps — or null for a miniature, which nobody steers.
+     */
+    gestures = null;
+    /** The pending hide of a tap's name. */
+    tapTipTimer = null;
+    /** The node the hover tip names, and where the pointer was. */
+    hovered = null;
+    /** Times the scene has framed the graph itself (`camera_fit`). */
+    fits = 0;
+    strategy = 'ranked';
+    selectedId = null;
+    frameHandle = null;
+    disposed = false;
+    /** The hover tip naming the node under the pointer (pane mode only). */
+    tip = null;
+    /** The wave's flare color, re-read from the palette on every rebuild. */
+    pulseColor = new THREE.Color('#48d8f0');
+    /**
+     * @param container - The element the canvas fills.
+     * @param handlers - Picking callbacks (ignored in ambient mode).
+     * @param options - Pane vs miniature behavior.
+     */
+    constructor(container, handlers = {}, options = {}) {
+        this.container = container;
+        this.handlers = handlers;
+        this.paletteOf = options.palette ?? palette_default;
+        this.layoutWorkerOf = options.layoutWorker;
+        this.ambient = options.ambient === true;
+        this.renderer = new THREE.WebGLRenderer({ antialias: true, alpha: true });
+        this.renderer.setPixelRatio(window.devicePixelRatio);
+        // The renderer sizes its canvas in DEVICE pixels and never writes the
+        // CSS size (`setSize(w, h, false)` below); the class pins the canvas to
+        // its mount so a HiDPI display cannot spill it sideways — one rule for
+        // every mount (a pane, a /bin diagram, the header's cycler), not a
+        // per-host stylesheet that a new host forgets.
+        this.renderer.domElement.classList.add('dag-scene-canvas');
+        this.scene = new THREE.Scene();
+        this.camera = new THREE.PerspectiveCamera(50, 1, 0.1, 200);
+        this.camera.position.set(0, 0, 14);
+        this.rig = new CameraRig(this.camera, this.group);
+        this.picker = new Picker(this.camera, this.group, this.renderer.domElement, {
+            meshes: () => this.meshes.values(),
+            stars: () => this.starField.list(),
+            nebulae: () => this.starField.nebulae(),
+            // A census is picked by its members only while it stands.
+            census: () => (this.census && this.censusField.drawn() ? this.censusField : null),
+        }, STAR_GLOW);
+        this.scene.add(new THREE.AmbientLight(0xffffff, 0.9));
+        const key = new THREE.DirectionalLight(0xffffff, 1.2);
+        key.position.set(4, 6, 8);
+        this.scene.add(key);
+        this.scene.add(this.group);
+        container.appendChild(this.renderer.domElement);
+        this.size_fit();
+        if (!this.ambient) {
+            // Hovering names the node: a small tip follows the pointer over a
+            // sphere, so identity does not cost a click.
+            this.tip = document.createElement('div');
+            this.tip.className = 'dag-node-tip';
+            this.tip.hidden = true;
+            container.appendChild(this.tip);
+            this.gestures = new PointerGestures(this.renderer.domElement, this.rig, {
+                grab_begin: (event) => this.grab_begin(event),
+                grab_move: (event) => this.drag_move(event),
+                grab_end: () => this.grab_end(),
+                hover: (event) => this.hover_handle(event),
+                leave: (event) => this.leave_handle(event),
+                tap: (event, kind) => this.pick_handle(event, kind),
+                tip_hide: () => { if (this.tip)
+                    this.tip.hidden = true; },
+                gesture_end: () => this.handlers.gesture_end?.(),
+            }, {
+                flat: () => this.projection === '2d',
+                // Census is a place: the camera parks off the focus.
+                untethered: () => this.census,
+            });
+        }
+        // A pane resize (a collapsed console, a divider drag) reshapes the box
+        // without a window resize; an unfitted canvas would stretch the graph.
+        new ResizeObserver(() => this.size_fit()).observe(container);
+        const animate = () => {
+            if (this.disposed)
+                return;
+            if (this.ambient) {
+                this.rig.tumble_step();
+                this.wave_animate();
+            }
+            else {
+                // A touched graph holds still; the idle spin resumes after the wait.
+                // A flight or a stay inside a node holds it unconditionally.
+                this.rig.spin_step(!(this.gestures?.pointerOver() ?? false) && this.projection === '3d');
+                // The reaction simulation runs while hot: during a grab, and cooling
+                // after release until it settles.
+                if (this.pull !== null) {
+                    if (this.pull.step(this.drag !== null)) {
+                        this.positions_sync();
+                    }
+                    else {
+                        this.pull = null;
+                    }
+                }
+                if (this.dragReturns.length > 0) {
+                    const now = Date.now();
+                    this.dragReturns = this.dragReturns.filter((entry) => {
+                        const t = Math.min(1, (now - entry.startedAt) / 300);
+                        const eased = t * t * (3 - 2 * t);
+                        entry.mesh.position.lerpVectors(entry.from, entry.to, eased);
+                        return t < 1;
+                    });
+                    this.positions_sync();
+                }
+                this.wave_animate();
+                this.rig.flight_step();
+            }
+            this.starField.scale_update(this.renderer.domElement.height, this.camera.fov);
+            this.handoff_step();
+            this.replay_step();
+            this.tubes.frame(performance.now());
+            this.labels.declutter(this.camera);
+            this.renderer.render(this.scene, this.camera);
+            this.frameHandle = window.requestAnimationFrame(animate);
+        };
+        animate();
+    }
+    /**
+     * Replaces the rendered graph. Layout runs under the current strategy.
+     *
+     * @param graph - The normalized graph.
+     */
+    graph_set(graph, options = {}) {
+        this.graph = graph;
+        // Nodes to hold still through this settle, and physics for it alone:
+        // a descent settles one feed while the field around it stands, with
+        // no gravity — gravity pulls to the origin, and a feed unfolding far
+        // from it would stream there instead of opening where it stood.
+        this.frozen = new Set(options.frozen ?? []);
+        this.physicsOnce = options.physics;
+        // A graph arriving under a flight keeps the camera where the flight
+        // put it (`fit: false`); every other arrival is framed whole.
+        this.rebuild(options.fit !== false, options.settle ?? 'full');
+        // An ARRIVING graph gets one wave; a local re-projection (a scale or
+        // layout flip) must not fire one — an unasked pulse reads as a glitch.
+        if (options.wave !== false)
+            this.wave_start();
+    }
+    /** Whether the pane's wave loops continuously (the PULSE ON state). */
+    waveLooping = false;
+    /** Sets continuous wave looping; enabling fires a wave immediately. */
+    waveLoop_set(on) {
+        this.waveLooping = on;
+        if (on)
+            this.wave_start();
+        // Turning it off lets the current wave finish and simply not renew.
+    }
+    /** @returns Whether the wave is looping. */
+    waveLoop_get() {
+        return this.waveLooping;
+    }
+    /**
+     * Where every node settled last, by id, for a caller that remembers.
+     *
+     * @returns Rounded positions, node id to [x, y, z].
+     */
+    positions_get() {
+        const out = {};
+        for (const [id, position] of this.lastPositions) {
+            out[id] = [Math.round(position.x * 100) / 100, Math.round(position.y * 100) / 100, Math.round(position.z * 100) / 100];
+        }
+        return out;
+    }
+    /**
+     * Seeds the next settle from remembered positions: a node that was here
+     * before starts where it stood, a new one starts fresh. Takes effect on
+     * the next `graph_set`.
+     *
+     * @param positions - Node id to [x, y, z].
+     */
+    positions_seed(positions) {
+        this.lastPositions = new Map(Object.entries(positions).map(([id, [x, y, z]]) => [id, new THREE.Vector3(x, y, z)]));
+    }
+    /**
+     * Starts the pulse wave: nodes flare in dependency order, a join waiting
+     * for its last parent. History-honest — only nodes that actually executed
+     * (terminal success or error, or an authored template node) fire, so on a
+     * running feed the wave halts at the execution frontier.
+     */
+    wave_start() {
+        this.waveTimes = this.waveSchedule_compute();
+        this.waveStartAt = this.waveTimes.size > 0 ? Date.now() : null;
+    }
+    /**
+     * Flies the camera into a node: a dolly toward the sphere until it fills
+     * the frame. The idle spin holds for the whole stay; `flight_back` reverses.
+     *
+     * @param nodeId - The node to fly into.
+     * @param onArrived - Called once the camera is inside the node.
+     */
+    flight_into(nodeId, onArrived) {
+        const mesh = this.meshes.get(nodeId);
+        // In census there is no mesh per node: fly to the group's first member.
+        const censusIndex = mesh === undefined ? this.censusField.ids().indexOf(nodeId) : -1;
+        if ((mesh === undefined && censusIndex < 0) || this.rig.flying() || this.rig.holding_get()) {
+            return;
+        }
+        // The dive leaves the graph exactly as the operator has it — no reset
+        // snap. World position: the camera flies in world space, and the group
+        // may be rotated.
+        this.group.updateMatrixWorld(true);
+        const target = mesh !== undefined
+            ? mesh.getWorldPosition(new THREE.Vector3())
+            : this.group.localToWorld((this.censusField.positions()[censusIndex] ?? new THREE.Vector3()).clone());
+        this.rig.flyInto(target, onArrived);
+    }
+    /**
+     * Flies the camera to frame a set of nodes: the fit `camera_fit` would
+     * give those nodes alone, reached by a flight from where the camera
+     * stands rather than a cut. A descent into one feed frames that feed;
+     * the climb back frames everything. Never holds: picking goes on.
+     *
+     * @param ids - The nodes to frame; every drawn node when empty.
+     * @param durationMs - The flight's length.
+     * @param onDone - Called when the camera arrives.
+     * @param bulk - The share of the nodes the frame must hold, 0..1: at 1
+     *   every outlier is inside the frame; at 0.85 the farthest few spill,
+     *   and the bulk is close enough to touch. A large feed's settle throws
+     *   a few nodes far out, and a frame that held them all put the feed at
+     *   the centre as a starburst of two-pixel spheres nobody could click.
+     */
+    camera_flyToFit(ids, durationMs, onDone, bulk = 1, margin = 1.15) {
+        const wanted = new Set(ids);
+        const reaches = [];
+        this.group.updateMatrixWorld(true);
+        for (const id of this.drawnIds()) {
+            if (wanted.size > 0 && !wanted.has(id))
+                continue;
+            const drawn = this.nodeWorld_of(id);
+            if (drawn !== null)
+                reaches.push(drawn);
+        }
+        this.rig.flyToFit(reaches, durationMs, onDone, bulk, margin);
+    }
+    /**
+     * How far the camera stands from what it looks at.
+     *
+     * @returns The distance from the eye to the focus, in scene units.
+     */
+    camera_distance() {
+        return this.rig.eyeDistance();
+    }
+    /**
+     * Whether the operator has placed the camera since the scene last framed
+     * the graph: a wheel or a drag. A repaint of the same space keeps a
+     * placed camera; a fresh space is framed whole.
+     *
+     * @returns True once the operator has wheeled or dragged since the last fit.
+     */
+    camera_touched() {
+        return this.rig.touched_get();
+    }
+    /**
+     * Draws the nodes as lit spheres or as stars. Moves nothing: the scene
+     * is redrawn where it stands, the camera where the operator put it.
+     *
+     * @param mode - The draw mode.
+     */
+    draw_set(mode) {
+        if (mode === this.drawMode)
+            return;
+        this.drawMode = mode;
+        this.rebuild(false, 'hold');
+    }
+    /**
+     * Shows or hides the nodes' captions; nothing is redrawn.
+     *
+     * @param on - Shown.
+     */
+    captions_set(on) {
+        this.labels.shown_set(on);
+    }
+    /** @returns How nodes are drawn. */
+    draw_get() {
+        return this.drawMode;
+    }
+    /**
+     * What the scene holds, for a surface asked to say so: how it draws,
+     * how many nodes are solid spheres and how many stars, which of the
+     * graph's solid-marked nodes are drawn solid, and the hand-off's state.
+     *
+     * @returns A plain summary.
+     */
+    state_get() {
+        const solidMarked = this.graph.nodes.filter((node) => node.solid === true).map((node) => node.id);
+        const solidDrawn = solidMarked.filter((id) => this.meshes.has(id)).length;
+        return {
+            draw: this.drawMode,
+            arrangement: this.arrangement,
+            captions: this.labels.shown_get() ? this.labels.count() : 'off',
+            // How many nodes the scene knows a place for: what a hold can hold.
+            known: this.lastPositions.size,
+            census: this.census,
+            nodes: this.graph.nodes.length,
+            meshes: this.meshes.size,
+            stars: this.starField.count(),
+            solidMarked: solidMarked.length,
+            solidDrawn,
+            tubes: this.tubes.materialCount(),
+            censusTubes: this.tubes.censusCount(),
+            handoffGroups: this.handoffField.size(),
+            handoffSolid: this.handoffField.solidCount(),
+            camera: this.rig.eyeDistance().toFixed(1),
+            settling: this.slicing,
+        };
+    }
+    /**
+     * Flies the camera toward one node, along the line it already looks
+     * down, to a distance where its neighbourhood fills the view: the zoom
+     * into the star the operator clicked, not a framing of all it belongs to.
+     *
+     * @param id - The node.
+     * @param distance - How far from it to stop, in scene units.
+     * @param durationMs - The flight's length.
+     * @param onDone - Called on arrival (at once when the node is not drawn).
+     */
+    camera_flyToward(id, distance, durationMs, onDone) {
+        const drawn = this.nodeWorld_of(id);
+        if (drawn === null) {
+            onDone();
+            return;
+        }
+        this.rig.flyToward(drawn, distance, durationMs, onDone);
+    }
+    /**
+     * Whether the camera is parked inside a node.
+     *
+     * The fly-in dollies to just shy of a node's surface, so while this is
+     * true the pane is filled by the inside of one sphere. Anything that can
+     * leave an operator there without an overlay on top has to be able to ask
+     * this and fly them back.
+     *
+     * @returns True while the camera is held inside a node.
+     */
+    holding_get() {
+        return this.rig.holding_get();
+    }
+    /**
+     * Flies the camera back out to its pre-dive stance and releases the hold.
+     *
+     * @param onDone - Called once the camera is home.
+     */
+    flight_back(onDone) {
+        this.rig.flyBack(onDone);
+    }
+    /** Computes each fireable node's flare time, in ms into the wave. */
+    waveSchedule_compute() {
+        const times = new Map();
+        const present = new Set(this.graph.nodes.map((n) => n.id));
+        const fired = (node) => node.look.waved;
+        // Relaxation to a fixpoint: cheap at feed scale, and immune to input order.
+        let settled = false;
+        while (!settled) {
+            settled = true;
+            for (const node of this.graph.nodes) {
+                if (times.has(node.id) || !fired(node))
+                    continue;
+                const parents = [...node.parentIds, ...node.joinParentIds].filter((id) => present.has(id));
+                if (!parents.every((id) => times.has(id)))
+                    continue;
+                const latest = parents.reduce((max, id) => Math.max(max, times.get(id) ?? 0), -WAVE_STEP_MS);
+                times.set(node.id, latest + WAVE_STEP_MS);
+                settled = false;
+            }
+        }
+        return times;
+    }
+    /** Applies the wave's flares for this frame; loops in ambient mode. */
+    wave_animate() {
+        if (this.waveStartAt === null)
+            return;
+        const elapsed = Date.now() - this.waveStartAt;
+        let peak = 0;
+        if (this.census && this.censusField.drawn()) {
+            // The wave rides the cloud: every job flares with its stage's fire time.
+            peak = this.censusField.flare((id) => this.waveTimes.get(id), elapsed, this.pulseColor, WAVE_FLARE_MS);
+            if (elapsed > peak + WAVE_FLARE_MS) {
+                this.waveStartAt = this.ambient || this.waveLooping ? Date.now() + WAVE_LOOP_GAP_MS : null;
+            }
+            return;
+        }
+        for (const [id, fireAt] of this.waveTimes) {
+            peak = Math.max(peak, fireAt);
+            const mesh = this.meshes.get(id);
+            if (mesh === undefined || !(mesh.material instanceof THREE.MeshStandardMaterial))
+                continue;
+            const dt = elapsed - fireAt;
+            const flare = dt >= 0 && dt <= WAVE_FLARE_MS ? Math.sin((dt / WAVE_FLARE_MS) * Math.PI) : 0;
+            // The flare pops in two channels at once: a cool color (white died on
+            // the butter of finished nodes) and a size swell.
+            mesh.scale.setScalar(1 + flare * 0.45);
+            if (flare > 0) {
+                mesh.material.emissive.copy(this.pulseColor);
+                mesh.material.emissiveIntensity = flare * 1.2;
+            }
+            else {
+                mesh.material.emissive.setScalar(id === this.selectedId ? 1 : 0);
+                mesh.material.emissiveIntensity = id === this.selectedId ? 0.35 : 0;
+            }
+        }
+        if (elapsed > peak + WAVE_FLARE_MS) {
+            // A future start leaves the graph quiet through the gap, then loops.
+            this.waveStartAt = this.ambient || this.waveLooping ? Date.now() + WAVE_LOOP_GAP_MS : null;
+        }
+    }
+    /**
+     * Switches the layout strategy and re-lays the current graph.
+     *
+     * @param strategy - Ranked tiers or the force-settled molecule.
+     */
+    strategy_set(strategy) {
+        this.strategy = strategy;
+        this.rebuild();
+    }
+    /** Clears the node selection (a new graph owes nothing to the old one). */
+    selection_clear() {
+        this.selectedId = null;
+        this.selection_paint();
+    }
+    /**
+     * Lights the selected sphere and dims the rest, touching materials only.
+     * Selection used to rebuild the scene: every click re-ran the settle of
+     * every node (seconds, on three thousand) and refitted the camera to
+     * the whole graph, so a click on a sphere the operator had dollied up
+     * to threw them back out to the whole space before anything else
+     * happened, and a double click could never land. A selection is paint.
+     */
+    selection_paint() {
+        this.spheres.select(this.selectedId);
+    }
+    /** @returns The active layout strategy. */
+    strategy_get() {
+        return this.strategy;
+    }
+    /** The active projection: the sculpted 3D stage, or the flat schematic. */
+    projection = '3d';
+    /**
+     * Switches projection. 2D is the schematic reading: the layout flattens
+     * to the plane, the view squares up face-on, the idle spin rests, and an
+     * empty-space drag pans (there is no depth to orbit). 3D restores the
+     * sculpted stage.
+     *
+     * @param projection - The projection to show.
+     */
+    projection_set(projection) {
+        this.projection = projection;
+        if (projection === '2d') {
+            this.group.quaternion.identity();
+        }
+        this.rebuild();
+    }
+    /** @returns The active projection. */
+    projection_get() {
+        return this.projection;
+    }
+    /**
+     * Updates one node's look in place (its state changed on the progress
+     * channel) without re-laying the graph.
+     *
+     * @param nodeId - The node.
+     * @param look - How it looks now.
+     */
+    look_update(nodeId, look) {
+        const node = this.graph.nodes.find((n) => n.id === nodeId);
+        if (!node)
+            return;
+        node.look = look;
+        this.spheres.recolor(nodeId, paint_resolve(look.paint, this.palette_read()));
+        // A stage that started or finished changes what its tubes carry: a
+        // stream, a replay, or nothing.
+        if (this.tubes.holds(nodeId))
+            this.tubes.stale_mark();
+    }
+    /** @returns The colours to draw with now. */
+    palette_read() {
+        return this.paletteOf();
+    }
+    /** Re-reads the palette (the THEME pill changed) and repaints. */
+    palette_refresh() {
+        this.rebuild(true, 'hold');
+    }
+    /** Fits the renderer to the container's current box. */
+    size_fit() {
+        const width = Math.max(1, this.container.clientWidth);
+        const height = Math.max(1, this.container.clientHeight);
+        this.renderer.setSize(width, height, false);
+        this.camera.aspect = width / height;
+        this.camera.updateProjectionMatrix();
+    }
+    /** Tears the scene down and releases the GL context. */
+    dispose() {
+        this.disposed = true;
+        this.layoutWorker?.terminate();
+        this.layoutWorker = null;
+        if (this.frameHandle !== null)
+            window.cancelAnimationFrame(this.frameHandle);
+        this.gestures?.detach();
+        this.renderer.dispose();
+        this.renderer.domElement.remove();
+        this.spheres.dispose();
+    }
+    /**
+     * Fits the camera to the placed graph: distance from the bounding sphere
+     * so a sprawling molecule (or a wide 2D settle) sits inside the frustum
+     * instead of clipping through the near plane as black voids — or leaving
+     * the view entirely.
+     */
+    /**
+     * Builds the census: one instanced member per collapsed count, on a
+     * fibonacci shell around its group's anchor; equal-count parent/child
+     * groups pair members by index, so chains of ×N groups render as
+     * branched filaments over the shell — the cell-surface reading.
+     */
+    censusBuild(placed, palette, fit = true) {
+        // A ghost (a cluster's anchor) is nobody's job; it still counts in the
+        // cloud's centre and in how deep a stage lies.
+        const nodes = placed.map((item) => {
+            const node = item.node;
+            return {
+                id: node.id,
+                position: item.position,
+                radius: item.radius,
+                count: Math.max(1, node.count ?? 1),
+                color: paint_resolve(node.look.paint, palette),
+                dim: node.dim === true,
+                ember: node.look.ember,
+                state: node.look.state,
+                parents: node.parentIds,
+                ghost: node.ghost === true,
+            };
+        });
+        const cloud = this.censusField.build(nodes, this.drawMode === 'stars', palette);
+        const center = cloud.center;
+        const cloudRadius = cloud.radius;
+        // The census parks the camera only when a framing was asked for: a
+        // descent redraws under a camera the flight has placed, and re-parking
+        // it there was the view resetting under every click.
+        if (!this.ambient && fit) {
+            // A census cloud grown from near-planar anchors reads edge-on from
+            // the axis; open on a three-quarter orbit so the shells read as
+            // volume from the first frame.
+            this.rig.frame(center, cloudRadius, { stance: 'threeQuarter', farScale: 2.5 });
+        }
+    }
+    camera_fit(placed) {
+        if (placed.length === 0)
+            return;
+        this.rig.touch_clear();
+        // How many times the scene has framed the graph itself, on the canvas:
+        // a smoke reads it to prove a click did not refit a placed camera.
+        this.fits += 1;
+        this.renderer.domElement.dataset['fits'] = String(this.fits);
+        const center = new THREE.Vector3();
+        for (const item of placed)
+            center.add(item.position);
+        center.divideScalar(placed.length);
+        // A space of molecules (a host that names them) is framed by its bulk:
+        // a few bodies flung far out would otherwise shrink the galaxies to a
+        // speck. A single graph is framed whole.
+        const reaches = placed.map((item) => center.distanceTo(item.position) + item.radius).sort((a, b) => a - b);
+        const share = this.handlers.handoffKey !== undefined ? 0.95 : 1;
+        const radius = Math.max(1, reaches[Math.max(0, Math.ceil(reaches.length * share) - 1)] ?? 1);
+        // The far plane always clears the framed graph: a fixed 200 clipped
+        // sprawling molecules into black voids (and swallowed 2D whole).
+        this.rig.frame(center, radius);
+    }
+    /** Counts rebuilds, so a sliced settle overtaken by a newer one stops. */
+    rebuildGen = 0;
+    /** Whether a settle is running in slices, its readout up. */
+    slicing = false;
+    /**
+     * Rebuilds meshes and edges from the current graph and strategy.
+     *
+     * @param fit - Frame the result.
+     * @param mode - How the graph settles; see {@link SettleMode}.
+     */
+    rebuild(fit = true, mode = 'full') {
+        const generation = ++this.rebuildGen;
+        // A settle in slices overtaken by this rebuild ends here: its readout
+        // closes, or a quick rebuild after it would leave the bar standing at
+        // whatever it last said.
+        if (this.slicing) {
+            this.slicing = false;
+            this.handlers.progress?.(1, 1, 0);
+        }
+        if (this.strategy !== 'molecule') {
+            this.draw(layout_ranked(this.graph.nodes), fit);
+            return;
+        }
+        let frozen = this.frozen;
+        if (mode !== 'full' && frozen.size === 0) {
+            const standing = this.graph.nodes.map((node) => node.id).filter((id) => this.lastPositions.has(id));
+            if (standing.length > 0)
+                frozen = new Set(standing);
+        }
+        const settle = moleculeScene_prepare(this.graph.nodes, this.projection === '2d' ? 2 : 3, this.lastPositions, this.physicsOnce !== undefined ? { ...this.physics, ...this.physicsOnce } : this.physics, frozen);
+        // A settle too big for one frame runs in slices when someone is told
+        // how far it has come: the page keeps drawing the scene that stands,
+        // the operator sees a bar move, and the new scene replaces it at the
+        // end. Without a listener, and for a small settle, it runs in one go.
+        // Nothing to move (a repaint under `hold` or `new` with every node
+        // standing: a plugin lit, a palette changed): draw where they stand.
+        // Any engine would only spend its ticks on bodies that cannot move.
+        if (settle.moving === 0) {
+            this.draw(settle.place(), fit);
+            return;
+        }
+        const nodes = this.graph.nodes.length;
+        const progress = this.handlers.progress;
+        // The work is the ticks times the nodes that move: a descent settles a
+        // handful among thousands and must land in the same call, since the
+        // flight that follows reads the meshes it draws.
+        const small = settle.total * settle.moving < SLICE_MIN_WORK;
+        // A host that names its molecules (the universe) settles a big space
+        // as a hierarchy in a worker: molecules alone, then molecules as bodies.
+        // SPOKES and CLUMPS exist only there, at any size; a small galaxy
+        // settles on the page as it always has.
+        if ((!small || this.arrangement !== 'galaxy') && progress !== undefined && this.handlers.handoffKey !== undefined && this.frozen.size === 0) {
+            this.hierarchy_run(generation, fit, frozen, progress);
+            return;
+        }
+        if (progress === undefined || small) {
+            settle.step(settle.total);
+            this.draw(settle.place(), fit);
+            return;
+        }
+        let done = 0;
+        this.slicing = true;
+        progress(0, settle.total, nodes);
+        const slice = () => {
+            if (generation !== this.rebuildGen || this.disposed)
+                return;
+            const started = performance.now();
+            while (done < settle.total && performance.now() - started < SLICE_BUDGET_MS) {
+                settle.step(1);
+                done += 1;
+            }
+            if (done < settle.total) {
+                progress(done, settle.total, nodes);
+                window.requestAnimationFrame(slice);
+                return;
+            }
+            this.slicing = false;
+            this.draw(settle.place(), fit);
+            progress(settle.total, settle.total, nodes);
+        };
+        window.requestAnimationFrame(slice);
+    }
+    /** The layout worker, made on the first big settle and kept. */
+    layoutWorker = null;
+    /** How a hierarchy sits molecules around their anchor. */
+    arrangement = 'galaxy';
+    /** Where each arrangement's spheres stood, for a return to it. */
+    arrangementMemory = new Map();
+    /**
+     * Arranges molecules as clumps or spokes. The space is laid out afresh:
+     * a remembered shape would keep the old arrangement.
+     *
+     * @param arrangement - The arrangement: a registered engine's name.
+     * @param remembered - Where its spheres stood, from a host's memory.
+     * @param redraw - Redraw at once; false when the host is about to hand
+     *   in the graph the arrangement needs (constellations bring their stars).
+     */
+    arrangement_set(arrangement, remembered, redraw = true) {
+        if (arrangement === this.arrangement)
+            return;
+        // Each arrangement keeps where its spheres stood: going back to one
+        // already seen redraws it, and only a first visit pays its settle.
+        this.arrangementMemory.set(this.arrangement, new Map(this.lastPositions));
+        this.arrangement = arrangement;
+        let kept = this.arrangementMemory.get(arrangement);
+        if (kept === undefined && remembered !== undefined && Object.keys(remembered).length > 0) {
+            kept = new Map(Object.entries(remembered).map(([id, [x, y, z]]) => [id, new THREE.Vector3(x, y, z)]));
+        }
+        this.lastPositions = kept ?? new Map();
+        if (redraw)
+            this.rebuild(true, kept === undefined ? 'full' : 'hold');
+    }
+    /** @returns How a hierarchy sits molecules round their hubs. */
+    arrangement_get() {
+        return this.arrangement;
+    }
+    /**
+     * Settles the graph as a hierarchy in the worker, reporting progress, and
+     * draws the answer if no newer rebuild has overtaken it.
+     */
+    hierarchy_run(generation, fit, frozen, progress) {
+        const keyOf = this.handlers.handoffKey;
+        if (keyOf === undefined)
+            return;
+        const radii = moleculeRadii_of(this.graph.nodes);
+        // Built as a session builds it, so a place the session keeps is a place this settle would find.
+        const seeds = new Map([...this.lastPositions].map(([id, at]) => [id, [at.x, at.y, at.z]]));
+        const nodes = layoutInput_build(this.graph.nodes, keyOf, seeds, frozen);
+        const total = 1000;
+        const count = nodes.length;
+        this.slicing = true;
+        progress(0, total, count);
+        const physics = this.physicsOnce !== undefined ? { ...this.physics, ...this.physicsOnce } : this.physics;
+        const placeAll = (positions) => {
+            const placed = this.graph.nodes.map((node) => {
+                const at = positions[node.id] ?? [0, 0, 0];
+                return { node, position: new THREE.Vector3(at[0], at[1], at[2]), radius: radii.get(node.id) ?? NODE_RADIUS };
+            });
+            this.slicing = false;
+            this.draw(placed, fit);
+            progress(total, total, count);
+        };
+        if (this.layoutWorker === null) {
+            const make = this.layoutWorkerOf;
+            if (make === undefined) {
+                // No worker from the surface: the engine settles on the page.
+                const engine = layoutEngine_get(this.arrangement);
+                if (engine === undefined) {
+                    console.error(`layout: no engine named ${this.arrangement}`);
+                    this.slicing = false;
+                    progress(total, total, count);
+                    return;
+                }
+                placeAll(engine.run({ nodes, physics }, (fraction) => progress(Math.min(total - 1, Math.floor(fraction * total)), total, count)).positions);
+                return;
+            }
+            this.layoutWorker = make();
+        }
+        const worker = this.layoutWorker;
+        worker.onmessage = (event) => {
+            const answer = event.data;
+            if (answer.generation !== this.rebuildGen || this.disposed)
+                return;
+            if (answer.type === 'progress') {
+                progress(Math.min(total - 1, Math.floor((answer.fraction ?? 0) * total)), total, count);
+                return;
+            }
+            if (answer.type === 'failed') {
+                // An engine the host does not know: the space stays as it stood,
+                // and the reason is said, never drawn as every node at the origin.
+                console.error(`layout: ${answer.reason ?? 'the engine failed'}`);
+                this.slicing = false;
+                progress(total, total, count);
+                return;
+            }
+            placeAll(answer.positions ?? {});
+        };
+        worker.postMessage({ generation, nodes, physics, arrangement: this.arrangement });
+    }
+    /** Draws placed nodes as the scene: meshes, edges, census, the frame. */
+    draw(placed, fit) {
+        this.group.clear();
+        this.spheres.clear();
+        this.censusField.clear();
+        this.pull = null;
+        this.drag = null;
+        this.starField.clear();
+        this.labels.clear();
+        this.handoffField.clear();
+        this.placedById = new Map();
+        this.tubes.clear();
+        const palette = this.palette_read();
+        this.pulseColor = palette.pulse;
+        this.lastPositions = new Map(placed.map((p) => [p.node.id, p.position.clone()]));
+        if (this.projection === '2d') {
+            // The molecule already settled in-plane; ranked drops only its
+            // parallax hash — its layout was two-dimensional by construction.
+            for (const item of placed)
+                item.position.z = 0;
+        }
+        if (this.census) {
+            // The census shells every job but the feed the operator is at: an
+            // entered feed stays solid spheres in its tubes, whatever the density.
+            const solidOnes = placed.filter((item) => item.node.solid === true && item.node.ghost !== true);
+            this.censusBuild(placed.filter((item) => item.node.solid !== true), palette, fit);
+            if (solidOnes.length > 0)
+                this.solid_draw(solidOnes, palette);
+            return;
+        }
+        if (!this.ambient && fit)
+            this.camera_fit(placed);
+        const byId = new Map(placed.map((p) => [p.node.id, p]));
+        const childrenOf = new Map();
+        for (const item of placed) {
+            for (const parentId of item.node.parentIds)
+                childrenOf.set(parentId, [...(childrenOf.get(parentId) ?? []), item]);
+        }
+        const heldCentre_of = (id) => {
+            const children = childrenOf.get(id) ?? [];
+            if (children.length === 0)
+                return null;
+            const centre = new THREE.Vector3();
+            for (const child of children)
+                centre.add(child.position);
+            return centre.divideScalar(children.length);
+        };
+        // Stars: every node but a solid one is a point of light, a halo a
+        // nebula; they are drawn in batches after this loop.
+        const starring = this.drawMode === 'stars';
+        const starred = [];
+        // A replay shows every node as a star: nothing turns solid under it.
+        const handoffKey = starring && this.replay === null ? this.handlers.handoffKey : undefined;
+        for (const { node, position, radius } of placed) {
+            if (node.caption !== undefined) {
+                // A ghost's words stand over what it holds: the layout parks the
+                // anchor itself wherever its pulls cancel, often between clouds.
+                const held = node.ghost === true ? heldCentre_of(node.id) : null;
+                const reach = held !== null ? 0 : node.halo === true ? haloRadius_of(node.count ?? 1) : radius;
+                this.labels.caption_add(node.id, node.caption, held ?? position, reach, palette.done, node.dim === true, node.count ?? 1);
+            }
+            if (node.ghost === true && node.halo !== true)
+                continue;
+            if (starring && node.solid !== true) {
+                if (node.halo === true) {
+                    this.nebula_add(node, position, palette);
+                    continue;
+                }
+                starred.push({
+                    id: node.id,
+                    position: position.clone(),
+                    radius,
+                    color: paint_resolve(node.look.paint, palette).clone(),
+                    dim: node.dim === true,
+                    ember: node.look.ember,
+                    ...(node.ring === true ? { ring: true } : {}),
+                });
+                continue;
+            }
+            if (node.halo === true) {
+                this.spheres.halo_add(node.id, position, haloRadius_of(node.count ?? 1), palette.edge, node.dim === true);
+                continue;
+            }
+            // 2D is drawn flat: discs, not lit spheres — the schematic reading
+            // all the way down; status colour, selection and flare carry over.
+            this.spheres.sphere_add(node.id, position, radius, {
+                color: paint_resolve(node.look.paint, palette),
+                dim: node.dim === true,
+                selected: node.id === this.selectedId,
+                flat: this.projection === '2d',
+            });
+        }
+        if (starred.length > 0)
+            this.starField.draw(starred, window.devicePixelRatio, this.renderer.domElement.height, this.camera.fov);
+        for (const item of placed)
+            this.placedById.set(item.node.id, item);
+        if (handoffKey !== undefined) {
+            const byNode = new Map(this.graph.nodes.map((node) => [node.id, node]));
+            this.handoffField.gather(starred, (id) => {
+                const node = byNode.get(id);
+                return node === undefined ? null : handoffKey(node);
+            });
+        }
+        // An edge between two solid nodes is a line as ever; an edge touching a
+        // star is a thread, all of them one batch.
+        const threads = [];
+        const threadColors = [];
+        const solid = (item) => !starring || item.node.solid === true;
+        const threadEnds = [];
+        const thread_add = (from, to, color, dim, owner, fromId) => {
+            const k = dim ? 0.35 : 1;
+            const segment = threads.length / 6;
+            threads.push(from.x, from.y, from.z, to.x, to.y, to.z);
+            threadEnds.push(fromId, owner.id);
+            threadColors.push(color.r * k, color.g * k, color.b * k, color.r * k, color.g * k, color.b * k);
+            // A placed node is one of the graph's own: the surface's node, typed wide.
+            const key = dim || handoffKey === undefined ? null : handoffKey(owner);
+            if (key !== null)
+                this.handoffField.thread_note(key, segment);
+        };
+        for (const item of placed) {
+            const { node, position } = item;
+            if (node.ghost === true)
+                continue;
+            for (const parentId of node.parentIds) {
+                const parent = byId.get(parentId);
+                if (!parent || parent.node.ghost === true)
+                    continue;
+                const dim = node.dim === true || parent.node.dim === true;
+                if (solid(item) && solid(parent)) {
+                    if (!starring && dim)
+                        this.spheres.edge_add(parentId, node.id, parent.position, position, palette.edge, false, dim);
+                }
+                else
+                    thread_add(parent.position, position, palette.edge, dim, node, parentId);
+            }
+            for (const joinId of node.joinParentIds) {
+                const parent = byId.get(joinId);
+                if (!parent)
+                    continue;
+                if (node.joinFaint === true) {
+                    thread_add(parent.position, position, palette.join, true, node, joinId);
+                    continue;
+                }
+                const dim = node.dim === true || parent.node.dim === true;
+                if (solid(item) && solid(parent)) {
+                    if (!starring && dim)
+                        this.spheres.edge_add(joinId, node.id, parent.position, position, palette.join, true, dim);
+                }
+                else
+                    thread_add(parent.position, position, palette.join, dim, node, joinId);
+            }
+        }
+        // Solid spheres are joined by tubes: under stars, the nodes marked solid
+        // (a feed the operator entered); drawn as spheres, every node not dimmed
+        // — the DAG pane's graph and the universe's SPHERES alike. Dimmed
+        // scenery keeps its faint lines.
+        {
+            const solidIds = placed
+                .filter((item) => item.node.ghost !== true && item.node.halo !== true && (starring ? item.node.solid === true : item.node.dim !== true))
+                .map((item) => item.node.id);
+            if (solidIds.length > 0) {
+                const entered = { tubes: null, mix: 1 };
+                this.tubes.build(entered, solidIds, new Set(solidIds));
+            }
+        }
+        this.starField.threads_draw(threads, threadColors, threadEnds);
+        // A redraw during a replay keeps what has not arrived hidden.
+        if (this.replay !== null)
+            this.replay_paintAll();
+    }
+    /**
+     * Plays the space's history: every node with an arrival hidden until it
+     * arrives, then shown with a flash, at its final place, the camera
+     * untouched. Nodes without one stand throughout. Nothing turns solid
+     * while it plays; stars only.
+     *
+     * @param arrivals - When each node arrived (epoch ms for dates).
+     * @param speed - 1 crosses the whole history in {@link REPLAY_WALL_MS}.
+     */
+    replay_begin(arrivals, speed = 1) {
+        const clock = new ReplayClock(arrivals);
+        this.replay = { clock, arrivals, shown: new Set() };
+        // Redrawn with the hand-off off: a solid feed would stand before it arrived.
+        this.rebuild(false, 'hold');
+        this.replay_paintAll();
+        clock.play(speed);
+    }
+    /**
+     * Plays on (or again from the start, at the end).
+     *
+     * @param speed - A new speed, or the one it had.
+     */
+    replay_play(speed) {
+        this.replay?.clock.play(speed);
+    }
+    /** Holds the replay where it is. */
+    replay_pause() {
+        this.replay?.clock.pause();
+    }
+    /**
+     * Moves the replay to a moment: what had arrived by then shown, the rest hidden.
+     *
+     * @param at - The moment, in the arrivals' units.
+     */
+    replay_seek(at) {
+        if (this.replay === null)
+            return;
+        this.replay_apply(this.replay.clock.seek(at));
+    }
+    /** Ends the replay: the space redrawn whole, the hand-off back. */
+    replay_stop() {
+        if (this.replay === null)
+            return;
+        this.replay = null;
+        this.rebuild(false, 'hold');
+    }
+    /**
+     * Where the replay stands, or null when none runs.
+     *
+     * @returns Whether it plays, its moment, and its span.
+     */
+    replay_state() {
+        if (this.replay === null)
+            return null;
+        return { playing: this.replay.clock.playing(), at: this.replay.clock.at(), span: this.replay.clock.span() };
+    }
+    /** One frame of the replay: arrivals shown, departures hidden, flashes faded. */
+    replay_step() {
+        const replay = this.replay;
+        if (replay === null)
+            return;
+        const wasPlaying = replay.clock.playing();
+        const frame = replay.clock.step();
+        this.replay_apply(frame);
+        for (const [id, strength] of replay.clock.flashing())
+            this.starField.flash_set(id, strength);
+        this.starField.flush();
+        if (wasPlaying || frame.arrived.length > 0)
+            this.handlers.replay?.(frame.at, replay.clock.playing());
+    }
+    /** Shows what arrived and hides what left, threads following. */
+    replay_apply(frame) {
+        const replay = this.replay;
+        if (replay === null || (frame.arrived.length === 0 && frame.departed.length === 0))
+            return;
+        for (const id of frame.arrived)
+            replay.shown.add(id);
+        for (const id of frame.departed) {
+            replay.shown.delete(id);
+            this.starField.flash_set(id, 0);
+        }
+        this.starField.presence_set(frame.arrived, 1);
+        this.starField.presence_set(frame.departed, 0);
+        this.starField.threads_present((id) => replay.shown.has(id) || !replay.arrivals.has(id));
+        this.starField.flush();
+    }
+    /** Paints every dated node as the replay has it: shown if arrived, else hidden. */
+    replay_paintAll() {
+        const replay = this.replay;
+        if (replay === null)
+            return;
+        const hidden = [...replay.arrivals.keys()].filter((id) => !replay.shown.has(id));
+        this.starField.presence_set(hidden, 0);
+        this.starField.presence_set(replay.shown, 1);
+        this.starField.threads_present((id) => replay.shown.has(id) || !replay.arrivals.has(id));
+        this.starField.flush();
+    }
+    /**
+     * Steps the hand-off once a frame: a feed whose largest sphere spans
+     * more than a few pixels turns solid, crossfading, its threads rising
+     * to edges; one that shrinks back goes to stars and its spheres are let go.
+     */
+    handoff_step() {
+        if (this.handoffField.size() === 0)
+            return;
+        const height = this.renderer.domElement.clientHeight || 1;
+        const perUnit = height / (2 * Math.tan((this.camera.fov * Math.PI) / 360));
+        this.group.updateMatrixWorld(true);
+        this.camera.updateMatrixWorld();
+        const view = new THREE.Matrix4().multiplyMatrices(this.camera.matrixWorldInverse, this.group.matrixWorld);
+        this.handoffField.step(view, perUnit, performance.now());
+    }
+    /**
+     * How a placed node's sphere is drawn when its molecule turns solid.
+     *
+     * @param id - The node.
+     * @returns Where it stands, how large, what hue.
+     */
+    handoffLook_of(id) {
+        const placed = this.placedById.get(id);
+        if (placed === undefined)
+            return undefined;
+        return { position: placed.position, radius: placed.radius, color: paint_resolve(placed.node.look.paint, this.palette_read()) };
+    }
+    /**
+     * A placed node as the tubes read it.
+     *
+     * @param id - The node.
+     * @returns Where it stands, how large, what it hangs from, its state.
+     */
+    tubeNode_of(id) {
+        const placed = this.placedById.get(id);
+        if (placed === undefined)
+            return undefined;
+        return {
+            position: placed.position,
+            radius: placed.radius,
+            parents: placed.node.parentIds,
+            // A faint join is a thread, never a tube.
+            joins: placed.node.joinFaint === true ? [] : placed.node.joinParentIds,
+            state: placed.node.look.state,
+        };
+    }
+    /**
+     * A cluster's handle while the scene draws stars: a soft glow at its
+     * anchor, facing the camera, sized as its halo would be.
+     */
+    nebula_add(node, position, palette) {
+        this.starField.nebula_add(node.id, position, haloRadius_of(node.count ?? 1), palette.edge, node.dim === true);
+    }
+    /**
+     * Where a drawn node stands in the world and how big it is — a sphere,
+     * a star or a census member alike — for flights and framing.
+     *
+     * @param id - The node.
+     * @returns Its world position and radius, or null when it is not drawn.
+     */
+    nodeWorld_of(id) {
+        const mesh = this.meshes.get(id);
+        if (mesh !== undefined) {
+            const sphere = mesh.geometry;
+            if (sphere.boundingSphere === null)
+                sphere.computeBoundingSphere();
+            return { position: mesh.getWorldPosition(new THREE.Vector3()), radius: sphere.boundingSphere?.radius ?? NODE_RADIUS };
+        }
+        const star = this.starField.entry(id);
+        if (star !== undefined)
+            return { position: this.group.localToWorld(star.position.clone()), radius: star.radius };
+        return null;
+    }
+    /** Every drawn node's id: spheres and stars. */
+    drawnIds() {
+        return [...this.meshes.keys(), ...this.starField.ids()];
+    }
+    /** Copies simulation positions onto meshes and re-anchors every edge. */
+    positions_sync() {
+        for (const { id, position } of this.pull?.positions() ?? []) {
+            this.meshes.get(id)?.position.set(...position);
+            // Where a pulled node comes to rest is where it stands: a later
+            // redraw starts from here instead of snapping it back.
+            this.lastPositions.set(id, new THREE.Vector3(...position));
+        }
+        this.tubes.follow();
+        this.spheres.edges_follow();
+    }
+    /**
+     * A press the gestures could not place: when it landed on a node it
+     * begins a pull (the structure reacts through a live force simulation
+     * anchored at the grabbed node) and the press is the scene's to follow.
+     *
+     * @param event - The press.
+     * @returns True when a node was taken hold of.
+     */
+    grab_begin(event) {
+        const hit = this.picker.mesh_under(event);
+        const nodeId = hit?.userData['nodeId'];
+        if (hit === null || typeof nodeId !== 'string')
+            return false;
+        // Drag in the plane through the node, facing the camera: intuitive
+        // pull, no depth surprises.
+        const normal = this.camera.getWorldDirection(new THREE.Vector3()).negate();
+        // The plane runs through the node where it stands in the WORLD: the ray
+        // it is cut with is in world space, and the group may be moved and
+        // turned (the universe turns about its focus).
+        this.group.updateMatrixWorld(true);
+        const plane = new THREE.Plane().setFromNormalAndCoplanarPoint(normal, hit.getWorldPosition(new THREE.Vector3()));
+        this.drag = {
+            nodeId, plane, startX: event.clientX, startY: event.clientY, moved: false,
+            // Ranked is deterministic truth: a pull peeks at ONE node and the
+            // release returns it home. The whole-graph elastic reaction belongs
+            // to the molecule — heating it under ranked dissolved the tiers.
+            solo: this.strategy === 'ranked',
+            home: hit.position.clone(),
+        };
+        return true;
+    }
+    /**
+     * Builds the reaction simulation, from the meshes' current positions with
+     * the grabbed node fixed. Deferred to the first real pointer movement: a
+     * heated simulation on a mere press would shift nodes out from under the
+     * click and dblclick raycasts. Links and charge only — no centering
+     * force, or the pull would fight a recentering spring.
+     */
+    dragSim_begin(nodeId) {
+        const radii = moleculeRadii_of(this.graph.nodes);
+        const nodes = [...this.meshes].map(([id, mesh]) => ({
+            id,
+            position: [mesh.position.x, mesh.position.y, mesh.position.z],
+            radius: radii.get(id) ?? NODE_RADIUS,
+            dim: mesh.userData['dim'] === true,
+            halo: mesh.userData['halo'] === true,
+        }));
+        const edges = [];
+        for (const node of this.graph.nodes) {
+            for (const parentId of [...node.parentIds, ...node.joinParentIds])
+                edges.push({ from: parentId, to: node.id });
+        }
+        this.pull = new PullSimulation({ grabbed: nodeId, nodes, edges, dimensions: this.projection === '2d' ? 2 : 3, baseRadius: NODE_RADIUS });
+    }
+    /** Follows the pointer during a pull: the grabbed node tracks the drag plane. */
+    drag_move(event) {
+        if (this.drag === null)
+            return;
+        this.rig.spin_pause();
+        if (!this.drag.moved &&
+            Math.abs(event.clientX - this.drag.startX) + Math.abs(event.clientY - this.drag.startY) >
+                DRAG_THRESHOLD_PX) {
+            this.drag.moved = true;
+            if (!this.drag.solo)
+                this.dragSim_begin(this.drag.nodeId);
+        }
+        if (!this.drag.moved)
+            return;
+        const point = new THREE.Vector3();
+        if (this.picker.ray_aim(event).ray.intersectPlane(this.drag.plane, point) === null)
+            return;
+        // Back into the group's own space, where the node and the simulation
+        // live: pinned to a world point, the node leapt away and dragged its
+        // whole molecule after it.
+        this.group.worldToLocal(point);
+        if (this.drag.solo) {
+            const mesh = this.meshes.get(this.drag.nodeId);
+            if (mesh !== undefined) {
+                mesh.position.copy(point);
+                this.positions_sync();
+            }
+            return;
+        }
+        this.pull?.pin([point.x, point.y, point.z]);
+    }
+    /** Nodes easing home after a ranked peek: mesh, from, to, start time. */
+    dragReturns = [];
+    /**
+     * Releases a pull: the grip opens and the simulation cools to rest.
+     *
+     * @returns Whether the pull had moved, so its click is swallowed.
+     */
+    grab_end() {
+        if (this.drag === null)
+            return false;
+        const moved = this.drag.moved;
+        if (this.drag.solo && this.drag.moved) {
+            const mesh = this.meshes.get(this.drag.nodeId);
+            if (mesh !== undefined) {
+                this.dragReturns.push({
+                    mesh, from: mesh.position.clone(), to: this.drag.home.clone(), startedAt: Date.now(),
+                });
+            }
+        }
+        this.pull?.release();
+        this.drag = null;
+        return moved;
+    }
+    /**
+     * Draws nodes as lit spheres joined by tubes, among a census: the feed the
+     * operator entered, which the census's points would otherwise swallow.
+     *
+     * @param solidOnes - The nodes to draw solid.
+     * @param palette - The palette.
+     */
+    solid_draw(solidOnes, palette) {
+        for (const item of solidOnes) {
+            this.placedById.set(item.node.id, item);
+            this.spheres.sphere_add(item.node.id, item.position, item.radius, { color: paint_resolve(item.node.look.paint, palette) });
+        }
+        const ids = solidOnes.map((item) => item.node.id);
+        const entered = { tubes: null, mix: 1 };
+        this.tubes.build(entered, ids, new Set(ids));
+    }
+    /**
+     * The pointer left the field. A finger lifting leaves at once, so its
+     * name stays up a moment to be read; a cursor's goes with it.
+     *
+     * @param event - The leave.
+     */
+    leave_handle(event) {
+        this.hovered = null;
+        if (event.pointerType === 'touch' && this.tip !== null && !this.tip.hidden) {
+            if (this.tapTipTimer !== null)
+                window.clearTimeout(this.tapTipTimer);
+            this.tapTipTimer = window.setTimeout(() => {
+                this.tapTipTimer = null;
+                if (this.tip !== null && (this.gestures?.fingersDown() ?? 0) === 0)
+                    this.tip.hidden = true;
+            }, TAP_TIP_MS);
+            return;
+        }
+        if (this.tip)
+            this.tip.hidden = true;
+    }
+    /** Names the node under the pointer in the hover tip, or hides it. */
+    hover_handle(event) {
+        if (this.tip === null)
+            return;
+        // In census the spheres are members of one instanced mesh: the group
+        // under the pointer is what the tip names, as a click would pick.
+        const nodeId = this.picker.node_under(event, this.gestures?.pressKind() === 'touch');
+        const node = typeof nodeId === 'string'
+            ? this.graph.nodes.find((n) => n.id === nodeId)
+            : undefined;
+        if (node === undefined) {
+            this.tip.hidden = true;
+            this.renderer.domElement.style.cursor = '';
+            this.hovered = null;
+            return;
+        }
+        this.hovered = { id: node.id, x: event.clientX, y: event.clientY };
+        const bounds = this.renderer.domElement.getBoundingClientRect();
+        this.tip.textContent = this.handlers.tip?.(node) ?? node.label;
+        this.tip.style.left = `${event.clientX - bounds.left + 14}px`;
+        this.tip.style.top = `${event.clientY - bounds.top + 10}px`;
+        this.tip.hidden = false;
+        this.renderer.domElement.style.cursor = 'pointer';
+    }
+    /** Resolves a pointer event to a node and fires the matching handler. */
+    pick_handle(event, kind) {
+        // What the tip names is what a click takes, when the pointer has not
+        // moved off it: the operator aimed at the node they read.
+        const held = this.hovered;
+        const nodeId = held !== null && Math.hypot(event.clientX - held.x, event.clientY - held.y) <= 6
+            ? held.id
+            : this.picker.node_under(event, this.gestures?.pressKind() === 'touch');
+        if (nodeId === null) {
+            // Empty space is the natural off switch for the node detail.
+            if (kind === 'select' && this.selectedId !== null) {
+                this.selection_clear();
+                this.handlers.deselect?.();
+            }
+            return;
+        }
+        const node = this.graph.nodes.find((n) => n.id === nodeId);
+        if (!node)
+            return;
+        if (kind === 'select') {
+            this.selectedId = nodeId;
+            if (!this.census)
+                this.selection_paint();
+            this.handlers.select?.(node);
+        }
+        else {
+            this.handlers.activate?.(node);
+        }
+    }
+}
+//# sourceMappingURL=orrery.js.map