@expofp/renderer 0.0.0-experimental.cf063fc

package/dist/events/def-culling.js

@@ -0,0 +1,69 @@
+import { Frustum, Matrix4, Sphere, Vector3 } from 'three';
+import { isImageDef, isTextDef } from '../types/guards';
+/**
+ * Encloses a def's bounds in a sphere the frustum can test, rotation-invariant by construction.
+ *
+ * Ported from the imperative renderer's `computeBoundingSphere` (fp-engine
+ * `renderer/src/util/geometry.ts`), which the legacy `UpdatesSystem` culled its update queue with.
+ * The sphere is centered at `bounds.center` — the rotation pivot — with a radius reaching the
+ * furthest corner of the rendered content, so no rotation can swing the content outside it. An
+ * `origin` (an image's anchor) shifts which part of the content hangs off the pivot, which widens
+ * the radius but never moves the center.
+ * @param bounds - The def's bounds.
+ * @param origin - The image anchor in `[0..1, 0..1]`, when the def has one; centered otherwise.
+ * @param out - Receives the result.
+ * @returns The sphere, in plan space.
+ */
+export function boundingSphereOf(bounds, origin, out) {
+    const originX = origin?.[0] ?? 0.5;
+    const originY = origin?.[1] ?? 0.5;
+    const reachX = Math.max(originX, 1 - originX) * bounds.size.x;
+    const reachY = Math.max(originY, 1 - originY) * bounds.size.y;
+    _center.set(bounds.center.x, bounds.center.y, bounds.elevation);
+    out.set(_center, Math.hypot(reachX, reachY));
+    return out;
+}
+/**
+ * Whether a def is entirely off screen, for the drain that lays visible defs out first.
+ *
+ * Only text and image defs are tested — the def kinds with one cheap `bounds` enclosure, and the
+ * bulk of any plan's re-layout targets (labels, dots, icons, markers). Everything else answers
+ * "not culled" and takes the priority pass, exactly as the legacy `UpdatesSystem` treated it.
+ * A `true` is a **priority** signal, never a correctness one: a culled def must still be laid out,
+ * just after the ones the camera can see.
+ * @param def - The def to test.
+ * @param frustum - The camera's frustum, in plan space — see {@link planFrustum}.
+ * @returns Whether the def can wait.
+ */
+export function culledBy(def, frustum) {
+    if (isTextDef(def)) {
+        return !frustum.intersectsSphere(boundingSphereOf(def.bounds, undefined, _sphere));
+    }
+    if (isImageDef(def)) {
+        return !frustum.intersectsSphere(boundingSphereOf(def.bounds, def.origin, _sphere));
+    }
+    return false;
+}
+/**
+ * The camera's frustum brought into plan space, where def bounds live.
+ *
+ * The same composition the imperative renderer's `computeFrustumInModelSpace` used, with the
+ * scene's plan → world matrix standing in for the scene's `matrixWorld`: projecting through
+ * `projection · viewInverse · plan` makes the frustum's planes answer for plan coordinates
+ * directly, so a def is tested where it is authored and nothing per-def is transformed.
+ * @param camera - The camera in use.
+ * @param planMatrix - The plan → world matrix, from the scene's `Space`.
+ * @param out - A frustum to write into. Omit it and each call allocates, which is what makes the
+ *   result safe to keep.
+ * @returns The frustum.
+ */
+export function planFrustum(camera, planMatrix, out = new Frustum()) {
+    _frustumMatrix
+        .multiplyMatrices(camera.projectionMatrix, camera.matrixWorldInverse)
+        .multiply(planMatrix);
+    return out.setFromProjectionMatrix(_frustumMatrix, camera.coordinateSystem);
+}
+// Scratch, each filled and consumed within one synchronous call.
+const _center = new Vector3();
+const _sphere = new Sphere();
+const _frustumMatrix = new Matrix4();

package/dist/events/layout-targets.d.ts

@@ -0,0 +1,151 @@
+import { type Frustum } from 'three';
+import { type LayerDef, type RenderableDef } from '../types/defs';
+import { type PlacementContext } from './placement';
+/**
+ * The defs a renderer re-lays out when the camera moves: the pixel size and the roll are the two
+ * layout axes.
+ *
+ * Every def here declares its own `onScale` or `onRoll` — the registry never holds a handler, only
+ * the value each def's rule last ran at, per axis. One registry per renderer, reached through
+ * {@link LayoutTargetsContext}, so two renderers showing the same defs at different zooms do not lay
+ * each other's out.
+ *
+ * A move splits in two. **The rules all run at once**, in the frame that noticed it: they are the
+ * cheap half — arithmetic over a def's own fields — and running them together is what lets every
+ * def's *decision*, a dot's "show me now" included, exist the moment the camera moves. **The writes
+ * are a sweep**: what the rules reported changed is queued and {@link drain} carries it to the GPU a
+ * frame's budget at a time — defs whose visibility flipped first, then the rest the camera can see,
+ * then the culled. The queue's shape is the legacy renderer's `UpdatesSystem` (fp-engine
+ * `core/updates.ts`); its unit is a def whose fields moved.
+ */
+export interface LayoutTargets {
+    /**
+     * The pixel size the registered defs are laid out at, which is what the driver's epsilon compares
+     * against.
+     */
+    readonly pixelSize: number;
+    /**
+     * The roll the registered defs are laid out at, in radians clockwise from north — the second
+     * layout axis, compared the way {@link pixelSize} is.
+     */
+    readonly roll: number;
+    /** Whether writes are still queued — what makes a caller keep frames coming. */
+    readonly hasWork: boolean;
+    /**
+     * Whether a pass is owed because a participant registered, unregistered or was passed to
+     * `update()` since the last one ran.
+     *
+     * The driver also runs a pass when the camera moves, which this does not report: a camera move is
+     * the driver's own observation, not the registry's.
+     */
+    readonly needsPlacement: boolean;
+    /**
+     * Whether a participant's box moved since the last pass, through `update()`.
+     *
+     * The driver runs the pass at once for this, as for {@link needsPlacement}: the verdicts the def
+     * earned were earned at its old position.
+     */
+    readonly placementDrifted: boolean;
+    /**
+     * Registers defs for re-layout, and lays out and writes the ones that are not current — so a def
+     * is current from the moment it is registered, and a membership change re-lays out only what it
+     * added.
+     * @param layer - The layer registering them, which is what places its participants in a collision
+     *   scope: its own, or the one its {@link LayerDef.collisionGroup} names.
+     * @param defs - The defs to lay out; every one of them declares an `onScale`, an `onRoll` or a
+     *   `placement`.
+     * @returns An unregister function; it also drops whatever of these defs a sweep still queued.
+     */
+    register(layer: LayerDef, defs: readonly RenderableDef[]): () => void;
+    /**
+     * Records the new pixel size and runs every registered scale rule against it, queueing what they
+     * report changed. Nothing is written here — that is {@link drain}'s job. Applying again before
+     * the queue drains re-runs the rules at the newer size, and a queued def is written once, with
+     * whatever its fields hold by then: the writes coalesce by construction.
+     * @param pixelSize - The new pixel size.
+     */
+    applyScale(pixelSize: number): void;
+    /**
+     * {@link applyScale}'s counterpart on the other axis, running only the rules that declare an
+     * `onRoll`. Both axes feed the one write queue.
+     * @param roll - The new roll, in radians clockwise from north.
+     */
+    applyRoll(roll: number): void;
+    /**
+     * Runs the placement pass over every registered participant and queues what the reports change:
+     * what each `onPlace` returns, then what each clustering layer's `onCluster` returns, through the
+     * same queue — a layer among them is written at once, as from any rule.
+     *
+     * The third `apply*`, and the one that is not an axis: placement depends on the whole camera
+     * rather than on one quantity, so the driver decides when to call this rather than comparing a
+     * number. The pass itself is synchronous and complete; only the writes it produces are budgeted,
+     * through the same queue {@link drain} works off.
+     *
+     * A registered def that no longer participates, because its `placement` was removed or it stopped
+     * being screen-space, is forgotten by the pass: it has no handler left to tell, and forgetting
+     * means that participating again reports its verdict afresh. A caller that removes `placement`
+     * owns restoring the def's appearance: one left shrunk or faded by its last `onPlace(false)`
+     * stays that way, because the handler left with the options and nothing can report to it.
+     *
+     * A known gap follows from the same removal: the defs it was holding down stay stood down, until
+     * something else owes a pass, because removing an option is a plain mutation that notifies
+     * nobody. Their room is free, and nothing re-offers it.
+     * @param context - What the camera shows this pass.
+     */
+    applyPlacement(context: PlacementContext): void;
+    /**
+     * Writes queued defs within a frame's budget, and says whether any remain — the caller's cue to
+     * ask for another frame.
+     *
+     * Three passes, in priority order: defs whose rule flipped them between hidden and shown, then
+     * every other queued def, then the ones an earlier pass deferred because the frustum rejects
+     * them. A flip matters most because it is what the user sees change — a label vanishing or a dot
+     * appearing — while a resize of something already shown can wait a frame.
+     *
+     * **A drain always takes at least one def**, however little budget is left — including none,
+     * which is what a worker descheduled before the first check leaves. That is what makes a sweep
+     * unable to stall: each drain shortens the queue, so the frames the driver keeps asking for
+     * eventually end it.
+     * @param frustum - The camera's frustum in plan space, when the caller has one; without it
+     *   nothing is deferred.
+     * @param budgetMs - How much of the frame a call may spend. Non-positive means no limit.
+     * @returns Whether defs remain for a later drain.
+     */
+    drain(frustum?: Frustum, budgetMs?: number): boolean;
+}
+/**
+ * The renderer's re-layout registry. Absent outside a renderer, where a layer simply registers
+ * nothing — which is what lets `Layer` be rendered bare in a spec.
+ */
+export declare const LayoutTargetsContext: import("react").Context<LayoutTargets | undefined>;
+/**
+ * Registers a layer's re-layout targets for as long as the layer is mounted: the defs it holds that
+ * declare an `onScale`, an `onRoll` or a `placement`, and the layer itself when it declares a
+ * layout rule.
+ *
+ * A child *layer* is never registered here even when it declares a handler — it registers itself, and
+ * it has to: a handler assigned to a layer after mount re-renders that layer alone, so a registration
+ * held by its parent would never learn of it. Self-registration also covers the root, which has no
+ * parent layer to be registered by.
+ *
+ * Called from the layer rather than from its containers or their instances, because this is where
+ * both halves are already at hand. It also means a def is laid out whether or not its instance has
+ * mounted — defs are the source of truth, and a staged mount picks up whatever they hold when it
+ * admits them.
+ *
+ * Outside a renderer there is no registry and this does nothing, which is what lets a `Layer` be
+ * rendered bare in a spec.
+ * @param layer - The layer registering; itself a target when it declares a handler, which is how a
+ *   layer whose *membership* depends on the camera re-derives it.
+ * @param children - The layer's children snapshot.
+ */
+export declare function useLayoutTargets(layer: LayerDef, children: readonly RenderableDef[]): void;
+/**
+ * Builds a renderer's re-layout registry.
+ * @param invalidate - Requests a frame, for layouts that happen outside the frame loop.
+ * @param pixelSize - The pixel size defs are laid out at until the first frame moves it.
+ * @param roll - The roll defs are laid out at until the first frame moves it, in radians.
+ * @returns The registry.
+ */
+export declare function createLayoutTargets(invalidate: () => void, pixelSize: number, roll?: number): LayoutTargets;
+//# sourceMappingURL=layout-targets.d.ts.map

package/dist/events/layout-targets.js

@@ -0,0 +1,397 @@
+import { createContext, use, useEffect } from 'react';
+import { isImageDef, isLayerDef, isPlacementTarget } from '../types/guards';
+import { subscribeDef, writeChanged } from '../update';
+import { createLogger } from '../utils/logging';
+import { culledBy } from './def-culling';
+import { createPlacement } from './placement';
+const logger = createLogger('layout');
+/**
+ * The renderer's re-layout registry. Absent outside a renderer, where a layer simply registers
+ * nothing — which is what lets `Layer` be rendered bare in a spec.
+ */
+export const LayoutTargetsContext = createContext(undefined);
+/**
+ * Registers a layer's re-layout targets for as long as the layer is mounted: the defs it holds that
+ * declare an `onScale`, an `onRoll` or a `placement`, and the layer itself when it declares a
+ * layout rule.
+ *
+ * A child *layer* is never registered here even when it declares a handler — it registers itself, and
+ * it has to: a handler assigned to a layer after mount re-renders that layer alone, so a registration
+ * held by its parent would never learn of it. Self-registration also covers the root, which has no
+ * parent layer to be registered by.
+ *
+ * Called from the layer rather than from its containers or their instances, because this is where
+ * both halves are already at hand. It also means a def is laid out whether or not its instance has
+ * mounted — defs are the source of truth, and a staged mount picks up whatever they hold when it
+ * admits them.
+ *
+ * Outside a renderer there is no registry and this does nothing, which is what lets a `Layer` be
+ * rendered bare in a spec.
+ * @param layer - The layer registering; itself a target when it declares a handler, which is how a
+ *   layer whose *membership* depends on the camera re-derives it.
+ * @param children - The layer's children snapshot.
+ */
+export function useLayoutTargets(layer, children) {
+    const targets = use(LayoutTargetsContext);
+    useEffect(() => {
+        if (!targets)
+            return undefined;
+        const defs = children.filter((def) => (def.onScale !== undefined || def.onRoll !== undefined || declaresPlacement(def)) &&
+            !isLayerDef(def));
+        if (layer.onScale || layer.onRoll)
+            defs.push(layer);
+        if (!defs.length)
+            return undefined;
+        return targets.register(layer, defs);
+    }, [targets, layer, children]);
+}
+/**
+ * Builds a renderer's re-layout registry.
+ * @param invalidate - Requests a frame, for layouts that happen outside the frame loop.
+ * @param pixelSize - The pixel size defs are laid out at until the first frame moves it.
+ * @param roll - The roll defs are laid out at until the first frame moves it, in radians.
+ * @returns The registry.
+ */
+export function createLayoutTargets(invalidate, pixelSize, roll = 0) {
+    /**
+     * Every registered def array, with the layer that registered it. Map entries are exactly what
+     * the placement pass takes, so a pass is handed the registry itself.
+     */
+    const groups = new Map();
+    const placement = createPlacement();
+    /** Whether a participant registered since the last pass, so one is owed. */
+    let placementDirty = false;
+    /** Whether a participant's box moved since the last pass, so one is owed. */
+    let placementDrifted = false;
+    /**
+     * The pixel size each def was last laid out at — the registry's layout state, because the rule
+     * that lays a def out is the def's own. Keyed by def rather than by group, so a membership change
+     * re-lays out only the defs that joined.
+     *
+     * A def whose `onScale` is *replaced* after it was laid out is not noticed: the record says only
+     * "laid out at this size". Reassigning a handler is a thing nothing does — a def is built with its
+     * rule — and a caller that does it lays the def out itself.
+     */
+    const layouts = new WeakMap();
+    /**
+     * The roll each def's `onRoll` last ran at — the other axis's record, kept apart from
+     * {@link layouts} because the two move independently.
+     */
+    const rolls = new WeakMap();
+    /**
+     * Whether each def was hidden when it was last written — what tells a visibility flip from a
+     * resize. Seeded at registration, which is when the def's instance wrote what it held.
+     */
+    const drawnHidden = new WeakMap();
+    /**
+     * The write queue, in priority order: defs a rule flipped between hidden and shown, then every
+     * other def a rule changed, then the ones a drain found outside the frustum. Sets, not arrays,
+     * because a def re-reported before its write must still be written once — with whatever its
+     * fields hold by then.
+     */
+    const flipped = new Set();
+    const queued = new Set();
+    const deferred = new Set();
+    /** What the sweep in flight has cost so far, for the log line that closes it. */
+    let sweep;
+    let current = pixelSize;
+    let currentRoll = roll;
+    /**
+     * The view every rule is handed — one instance for the registry's lifetime, mutated as the axes
+     * move, which is what keeps a ten-thousand-label sweep allocation-free. `LayoutView` documents
+     * the flip side: valid during the call, so a rule destructures rather than retains it.
+     */
+    const view = { pixelSize: current, roll: currentRoll };
+    /**
+     * Runs whatever of a def's rules are stale by their records, scale before roll so a rule that
+     * turns a label re-fits it at the size just applied. Each rule is recorded as run before anything
+     * it reported is handled, because handling can reach back in here.
+     *
+     * A rule reporting nothing is still recorded as run, so a membership change does not run it over
+     * the def again — reporting nothing is how a rule skips the write, which is the half that costs.
+     * @param def - The def to lay out.
+     * @param report - Receives what each rule reported changed.
+     */
+    function layOutStale(def, report) {
+        // Hidden defs are laid out too. Whether a def draws at all can be exactly what its rule decides
+        // — a booth's dot appears only once the plan is far enough out for its label to stop fitting —
+        // so a registry that skipped them would never run the rule that would bring them back.
+        if (def.onScale && layouts.get(def) !== current) {
+            const changed = def.onScale(view);
+            layouts.set(def, current);
+            if (changed?.length)
+                report(changed);
+        }
+        if (def.onRoll && rolls.get(def) !== currentRoll) {
+            const changed = def.onRoll(view);
+            rolls.set(def, currentRoll);
+            if (changed?.length)
+                report(changed);
+        }
+    }
+    /**
+     * Writes a def now — the layer path or the slot path, per `writeChanged` — and records whether
+     * what it drew was hidden.
+     * @param def - The def to write.
+     */
+    function write(def) {
+        drawnHidden.set(def, def.hidden === true);
+        writeChanged([def]);
+    }
+    /**
+     * Queues what a rule reported changed. A layer is written at once: its change is a membership
+     * change, which only React reconciles, and React already defers the sweep behind it.
+     * @param changed - The defs the rule reported.
+     */
+    function enqueue(changed) {
+        for (const def of changed) {
+            if (isLayerDef(def)) {
+                write(def);
+                continue;
+            }
+            const drawn = drawnHidden.get(def);
+            if (drawn !== undefined && drawn !== (def.hidden === true)) {
+                queued.delete(def);
+                deferred.delete(def);
+                flipped.add(def);
+            }
+            else {
+                // Flipped and flipped back before its write: against what the slot holds it is a resize.
+                flipped.delete(def);
+                deferred.delete(def);
+                queued.add(def);
+            }
+        }
+    }
+    /**
+     * Runs the stale rules of every registered def the moved axis concerns, queueing their writes.
+     * @param axis - The axis that moved, for the log line.
+     * @param handler - The moved axis's handler, `onScale` or `onRoll`.
+     */
+    function runHandlers(axis, handler) {
+        const start = performance.now();
+        const before = flipped.size + queued.size + deferred.size;
+        let ran = 0;
+        for (const defs of groups.keys()) {
+            for (const def of defs) {
+                if (!def[handler])
+                    continue;
+                ran++;
+                layOutStale(def, enqueue);
+            }
+        }
+        const pending = flipped.size + queued.size + deferred.size;
+        if (pending > before) {
+            sweep ??= { defs: 0, drains: 0, writeMs: 0 };
+            sweep.defs += pending - before;
+        }
+        logger.debug(`${axis}: ran ${ran} ${handler} handlers in ${(performance.now() - start).toFixed(2)}ms, ` +
+            `${pending} defs to write (${flipped.size} visibility flips)`);
+    }
+    return {
+        get pixelSize() {
+            return current;
+        },
+        get roll() {
+            return currentRoll;
+        },
+        get hasWork() {
+            return flipped.size > 0 || queued.size > 0 || deferred.size > 0;
+        },
+        get needsPlacement() {
+            return placementDirty;
+        },
+        get placementDrifted() {
+            return placementDrifted;
+        },
+        register(layer, defs) {
+            groups.set(defs, layer);
+            let wrote = false;
+            for (const def of defs) {
+                if (!drawnHidden.has(def))
+                    drawnHidden.set(def, def.hidden === true);
+                // Written at once, not queued: a def is current from the moment it registers, so one
+                // mounting mid-zoom draws at the size the plan is at.
+                layOutStale(def, (changed) => {
+                    for (const each of changed)
+                        write(each);
+                    wrote = true;
+                });
+            }
+            // A verdict cannot be computed for one def alone, because it depends on every other box, and
+            // the registry holds no camera. So registration only marks a pass owed; the frame the
+            // `invalidate` below asks for is what runs it, and it runs before that frame draws.
+            //
+            // Owed on any `placement`, not only on a participant: a flat def that carries one is exactly
+            // the mistake the pass's development warning exists to catch, and the pass has to run to say so.
+            if (defs.some(declaresPlacement)) {
+                placementDirty = true;
+                wrote = true;
+            }
+            // Registration happens in an effect rather than inside the frame loop, so anything written here
+            // needs a frame asking for it.
+            if (wrote)
+                invalidate();
+            // A participant that moves owes a pass as one that joins does: its verdict, and those of the
+            // defs it used to block or be blocked by, were earned at the old position. Only participants
+            // are watched, so a write to anything else costs nothing, and only a change to what the pass
+            // measures owes one: an `update()` that moved no box, such as a fade writing `opacity` on every
+            // animation frame, would otherwise run the pass at frame rate on a still camera, past the rate
+            // gate that is there for the camera. The registry's own writes (`onPlace` returns, which go
+            // through `syncNow`) never notify, so a verdict flip cannot owe the pass that would flip it
+            // again.
+            const unsubscribes = defs.filter(isPlacementTarget).map((def) => {
+                const seen = measuredBy(def);
+                return subscribeDef(def, () => {
+                    if (!remeasure(def, seen))
+                        return;
+                    placementDrifted = true;
+                    invalidate();
+                });
+            });
+            return () => {
+                for (const unsubscribe of unsubscribes)
+                    unsubscribe();
+                groups.delete(defs);
+                // A participant that leaves frees its room, so the defs it beat may now fit: owe a pass, and
+                // ask for the frame that runs it, as registration does.
+                if (defs.some(isPlacementTarget)) {
+                    placementDirty = true;
+                    invalidate();
+                }
+                // A queued def whose layer is gone must not be written from the backlog: its instances are
+                // unmounting.
+                for (const def of defs) {
+                    flipped.delete(def);
+                    queued.delete(def);
+                    deferred.delete(def);
+                    placement.forget(def);
+                }
+            };
+        },
+        applyScale(nextPixelSize) {
+            current = nextPixelSize;
+            view.pixelSize = nextPixelSize;
+            runHandlers(`pxToSvgScale ${+nextPixelSize.toFixed(3)}`, 'onScale');
+        },
+        applyRoll(nextRoll) {
+            currentRoll = nextRoll;
+            view.roll = nextRoll;
+            runHandlers(`roll ${+nextRoll.toFixed(3)}`, 'onRoll');
+        },
+        applyPlacement(context) {
+            placementDirty = false;
+            placementDrifted = false;
+            // Flips and clusters are reported in one synchronous call, flips first, so one drain writes
+            // a seed's hiding and the cluster standing for it together.
+            placement.run(groups, context, (def, placed) => {
+                const changed = def.placement?.onPlace(placed, view);
+                if (changed?.length)
+                    enqueue(changed);
+            }, (_layer, clusters, clustering) => {
+                // The options the pass hands over, not the layer's current ones: a layer that dropped
+                // `clustering` is still owed the empty set through the handler that drew its clusters.
+                const changed = clustering.onCluster(clusters, view);
+                if (changed?.length)
+                    enqueue(changed);
+            });
+        },
+        drain(frustum, budgetMs = -1) {
+            if (flipped.size === 0 && queued.size === 0 && deferred.size === 0)
+                return false;
+            const start = performance.now();
+            /**
+             * Defs this drain has taken off a queue, written or deferred.
+             *
+             * It gates the budget so that the **first** def of a drain is always taken. Without that, a
+             * budget already spent before the loop began — the worker descheduled between `start` and the
+             * check, which a loaded machine does routinely — dequeues nothing at all, and a drain that
+             * dequeues nothing is the stall this budget exists to prevent.
+             */
+            let processed = 0;
+            const overBudget = () => processed > 0 && budgetMs > 0 && performance.now() - start >= budgetMs;
+            // Sets iterate in insertion order and tolerate deletion mid-walk, which is what makes each pass
+            // a plain loop: a written def leaves its set before its write runs.
+            for (const queue of [flipped, queued]) {
+                for (const def of queue) {
+                    if (overBudget())
+                        break;
+                    processed++;
+                    queue.delete(def);
+                    // Deferral is priority, never a skip: a def the camera cannot see joins the last pass.
+                    if (frustum !== undefined && culledBy(def, frustum)) {
+                        deferred.add(def);
+                        continue;
+                    }
+                    write(def);
+                }
+            }
+            for (const def of deferred) {
+                if (overBudget())
+                    break;
+                processed++;
+                deferred.delete(def);
+                write(def);
+            }
+            const remaining = flipped.size + queued.size + deferred.size;
+            if (sweep) {
+                sweep.drains++;
+                sweep.writeMs += performance.now() - start;
+                if (remaining === 0) {
+                    logger.debug(`wrote ${sweep.defs} defs over ${sweep.drains} frames in ${sweep.writeMs.toFixed(2)}ms`);
+                    sweep = undefined;
+                }
+            }
+            return remaining > 0;
+        },
+    };
+}
+/**
+ * Whether a def declares a placement, participating in the pass or not.
+ * @param def - The def to test.
+ * @returns Whether it carries `placement`.
+ */
+function declaresPlacement(def) {
+    return def.placement !== undefined;
+}
+/**
+ * Reads what the pass measures of a participant: the box its bounds, origin and padding describe.
+ * @param def - The participant.
+ * @returns The reading.
+ */
+function measuredBy(def) {
+    const measured = { numbers: new Float64Array(9), padding: undefined };
+    remeasure(def, measured);
+    // The first reading is the baseline, not a change.
+    return measured;
+}
+/**
+ * Re-reads a participant into an earlier reading and says whether anything the pass measures moved.
+ * @param def - The participant.
+ * @param into - The reading to compare against and overwrite.
+ * @returns Whether the reading changed.
+ */
+function remeasure(def, into) {
+    const { bounds } = def;
+    const origin = isImageDef(def) ? def.origin : undefined;
+    const padding = def.placement?.padding;
+    const next = _measure;
+    next[0] = bounds.center.x;
+    next[1] = bounds.center.y;
+    next[2] = bounds.size.x;
+    next[3] = bounds.size.y;
+    next[4] = bounds.rotation;
+    next[5] = bounds.elevation;
+    next[6] = origin?.[0] ?? 0.5;
+    next[7] = origin?.[1] ?? 0.5;
+    let changed = padding !== into.padding;
+    for (let i = 0; i < 8; i++) {
+        if (next[i] !== into.numbers[i])
+            changed = true;
+        into.numbers[i] = next[i];
+    }
+    into.padding = padding;
+    return changed;
+}
+// Scratch for the reading, filled and compared within one call.
+const _measure = new Float64Array(9);

package/dist/events/placement/box.d.ts

@@ -0,0 +1,59 @@
+import { type Camera } from 'three';
+import { type Space } from '../../space/Space';
+import { type ImageDef, type TextDef } from '../../types/defs';
+import { type PlacementBox } from './grid';
+/**
+ * The screen rectangle one def occupies, in CSS pixels from the canvas's top-left corner.
+ *
+ * There is one path, because only a screen-space def is ever tested. Its anchor projects through
+ * the camera, and its extent comes from the pixel size rather than from the projection: constant
+ * pixel size means a sprite is the same number of pixels across at every depth, so the only
+ * camera-dependent term is where the anchor lands.
+ *
+ * `origin` shifts the rectangle relative to the anchor exactly as it shifts the quad, in the
+ * plan's y-down sense, which is also the canvas's. A bottom-center origin therefore puts the
+ * anchor on the rectangle's bottom edge and the rectangle above it.
+ *
+ * This is the def's own extent, without its `placement.padding`: that is what the grid stores, and
+ * {@link paddedBox} grows it into the box that is tested. Storing the grown box as well would make
+ * two padded defs keep twice the padding apart.
+ * @param def - The def to measure.
+ * @param space - The scene's space, for the projection.
+ * @param camera - The camera in use.
+ * @param pixelSize - Plan units per CSS pixel.
+ * @param out - The box to write into, reused across a pass.
+ * @returns The box, or nothing when the def has no extent or its anchor does not project.
+ */
+export declare function screenBoxOf(def: ImageDef | TextDef, space: Space, camera: Camera, pixelSize: number, out: PlacementBox): PlacementBox | undefined;
+/**
+ * The screen rectangle a constant-pixel-size sprite occupies when its anchor stands at a plan
+ * point, in CSS pixels from the canvas's top-left corner.
+ *
+ * What {@link screenBoxOf} measures a def with, taken apart so that a box can stand at an anchor
+ * that is not a def's own: a cluster's marker stands at the mean of its units' anchors.
+ * @param x - The anchor's plan x.
+ * @param y - The anchor's plan y.
+ * @param elevation - The anchor's elevation, in plan units.
+ * @param width - The sprite's width in CSS pixels.
+ * @param height - The sprite's height in CSS pixels.
+ * @param origin - Which point of the sprite stands on the anchor, centered when omitted.
+ * @param rotation - Its spin about the screen normal, in radians.
+ * @param space - The scene's space, for the projection.
+ * @param camera - The camera in use.
+ * @param out - The box to write into.
+ * @returns The box, or nothing when the sprite has no extent or its anchor does not project.
+ */
+export declare function spriteBoxAt(x: number, y: number, elevation: number, width: number, height: number, origin: readonly [number, number] | undefined, rotation: number, space: Space, camera: Camera, out: PlacementBox): PlacementBox | undefined;
+/**
+ * The box a def is tested with: its extent grown by `placement.padding`, by one number on all four
+ * sides or by a `[horizontal, vertical]` pair.
+ *
+ * The grid stores the extent and tests this, so each def's padding applies once, on the side that is
+ * testing. A def with no padding gets a copy of its extent.
+ * @param def - The def whose padding grows the box.
+ * @param box - The def's extent, from {@link screenBoxOf}.
+ * @param out - The box to write into, which may be `box` itself.
+ * @returns `out`.
+ */
+export declare function paddedBox(def: ImageDef | TextDef, box: PlacementBox, out: PlacementBox): PlacementBox;
+//# sourceMappingURL=box.d.ts.map