@expofp/renderer 0.0.0-experimental.2d6c681

package/dist/update/slot-writers.js

@@ -0,0 +1,76 @@
+import { isLayerDef } from '../types/guards';
+import { hotState } from '../utils/hot-state';
+import { update } from './store';
+/**
+ * Registers a def's sync closure, paired with the frame request that shows what it writes.
+ *
+ * The two are registered together rather than left to each caller because a slot write nobody asked
+ * a frame for is invisible: the renderer runs a demand frameloop, so the write lands in GPU memory
+ * and waits for a frame that never comes. Pairing them here is what makes every write path — React's
+ * and the frame loop's — correct without remembering anything. The frame loop's writes ask for a
+ * frame they are already inside, which costs one more after the camera stops.
+ * @param def - The def the instance component renders.
+ * @param sync - Writes the def's current state into its slot.
+ * @param invalidate - Requests the frame that draws it.
+ * @returns An unregister function, which removes this writer and leaves the def's others alone.
+ */
+export function registerSlotWriter(def, sync, invalidate) {
+    /** Writes the def's slot and asks for the frame that shows it. */
+    function write() {
+        sync();
+        invalidate();
+    }
+    const writers = slotWriters.get(def) ?? new Set();
+    writers.add(write);
+    slotWriters.set(def, writers);
+    return () => {
+        writers.delete(write);
+    };
+}
+/**
+ * Runs every write registered for a def — each of its slots, and the frame that draws them. A no-op
+ * for defs that are not mounted.
+ * @param def - The def to re-sync.
+ */
+export function syncNow(def) {
+    const writers = slotWriters.get(def);
+    if (!writers)
+        return;
+    // Over a copy: a write can re-claim a slot, and a re-claim mounts and unmounts writers.
+    for (const write of [...writers])
+        write();
+}
+/**
+ * Writes the defs a layout handler reported changed, by the cheapest route that is correct for
+ * each: a layer means its membership moved, which only React can reconcile, while anything else is
+ * a field write that goes straight into the slot, with no render at all behind the frame that draws
+ * it. This is what a layout handler returning defs buys — see `LayoutHandlers.onScale`.
+ * @param defs - The defs the handler reported changed, or nothing when it changed nothing.
+ */
+export function writeChanged(defs) {
+    if (!defs)
+        return;
+    for (const def of defs) {
+        if (isLayerDef(def))
+            update(def);
+        else
+            syncNow(def);
+    }
+}
+/**
+ * The write closures mounted instance components register for their defs — the single write path
+ * from a def's fields into its GPU slots, and the frame that draws what they wrote.
+ *
+ * Two callers run them: the instance's own effect (after `update(def)`), and the camera re-layout
+ * frame loop — the latter mutating defs and re-syncing them without going through React at all.
+ * Sharing one closure is what keeps the two paths from disagreeing.
+ *
+ * A **set** per def, because one def can be drawn by more than one mesh: a model merged into a part
+ * per source material has an instance in each, and an image whose source is split into tiles has one
+ * per placement. Holding a single writer let the last instance to mount overwrite its siblings, so
+ * every later write reached exactly one of a def's slots — a two-part model faded half of itself.
+ *
+ * Kept across hot updates, because an instance registers from a mount effect that a re-render does
+ * not re-run: a fresh map would make every later `update(def)` a silent no-op (see {@link hotState}).
+ */
+const slotWriters = hotState(import.meta.hot, 'slotWriters', () => new WeakMap());

package/dist/update/store.d.ts

@@ -0,0 +1,41 @@
+import { type LayerDef, type RenderableDef, type RenderableDefCollection } from '../types/defs';
+/**
+ * Marks defs as changed after their fields, geometry, or `children` were mutated, so the renderer
+ * mirrors the mutation into GPU state.
+ *
+ * This is the renderer's only update signal. Mutate whatever you like — scalar fields, geometry in
+ * place, a layer's `children` array — then pass the defs you touched; for a membership change pass
+ * the parent layer, and for a reparent pass both parents. Calling it before the renderer mounts, or
+ * after it unmounts, is a safe no-op: defs are the source of truth and mounting performs a full
+ * sync. Calling it on an unchanged def is harmless.
+ * @param defs - Defs that changed.
+ */
+export declare function update(...defs: RenderableDef[]): void;
+/**
+ * Subscribes to a def's change notifications. Internal — components reach this through
+ * `useDefSync` and `useStagedChildren`.
+ * @param def - The def to watch.
+ * @param listener - Called after every {@link update} touching the def.
+ * @returns An unsubscribe function.
+ */
+export declare function subscribeDef(def: RenderableDef, listener: () => void): () => void;
+/**
+ * Reads a def's current version — the value `useSyncExternalStore` snapshots.
+ * @param def - The def to read.
+ * @returns The version, or `0` when nothing is subscribed.
+ */
+export declare function versionOf(def: RenderableDef): number;
+/**
+ * Reads a layer's children as a version-keyed snapshot. Internal — components reach this through
+ * `useStagedChildren`.
+ *
+ * The layer's `children` array is mutated in place, so its identity can never signal a membership
+ * change to memoization. The snapshot restores that signal at the store level: it is rebuilt as a
+ * fresh copy exactly when the layer's version has moved, and the cached copy is returned otherwise —
+ * the identity stability `useSyncExternalStore` requires between updates, and the identity change
+ * downstream memoization invalidates on.
+ * @param def - The layer whose children to snapshot.
+ * @returns The current snapshot; a new array iff the layer was updated since the last call.
+ */
+export declare function childrenOf<T extends RenderableDef>(def: LayerDef<T>): Readonly<RenderableDefCollection<T>>;
+//# sourceMappingURL=store.d.ts.map

package/dist/update/store.js

@@ -0,0 +1,104 @@
+import { hotState } from '../utils/hot-state';
+/**
+ * Marks defs as changed after their fields, geometry, or `children` were mutated, so the renderer
+ * mirrors the mutation into GPU state.
+ *
+ * This is the renderer's only update signal. Mutate whatever you like — scalar fields, geometry in
+ * place, a layer's `children` array — then pass the defs you touched; for a membership change pass
+ * the parent layer, and for a reparent pass both parents. Calling it before the renderer mounts, or
+ * after it unmounts, is a safe no-op: defs are the source of truth and mounting performs a full
+ * sync. Calling it on an unchanged def is harmless.
+ * @param defs - Defs that changed.
+ */
+export function update(...defs) {
+    for (const def of defs)
+        notify(def);
+}
+/**
+ * Subscribes to a def's change notifications. Internal — components reach this through
+ * `useDefSync` and `useStagedChildren`.
+ * @param def - The def to watch.
+ * @param listener - Called after every {@link update} touching the def.
+ * @returns An unsubscribe function.
+ */
+export function subscribeDef(def, listener) {
+    const entry = entryFor(def);
+    entry.listeners.add(listener);
+    return () => {
+        const current = subscriptions.get(def);
+        if (!current)
+            return;
+        current.listeners.delete(listener);
+        // The entry outlives its listeners deliberately. `useSyncExternalStore` re-subscribes whenever
+        // its subscribe closure changes identity, which happens on every render unless the closure is
+        // memoized; dropping the entry on the last unsubscribe would reset the version to 0 mid-render,
+        // costing a spurious re-render and re-sync and breaking the monotonicity the `childrenOf` cache
+        // relies on to signal in-place mutation. Retaining it costs nothing: the map is weak, so
+        // an entry is collected with its def.
+    };
+}
+/**
+ * Reads a def's current version — the value `useSyncExternalStore` snapshots.
+ * @param def - The def to read.
+ * @returns The version, or `0` when nothing is subscribed.
+ */
+export function versionOf(def) {
+    return subscriptions.get(def)?.version ?? 0;
+}
+/**
+ * Reads a layer's children as a version-keyed snapshot. Internal — components reach this through
+ * `useStagedChildren`.
+ *
+ * The layer's `children` array is mutated in place, so its identity can never signal a membership
+ * change to memoization. The snapshot restores that signal at the store level: it is rebuilt as a
+ * fresh copy exactly when the layer's version has moved, and the cached copy is returned otherwise —
+ * the identity stability `useSyncExternalStore` requires between updates, and the identity change
+ * downstream memoization invalidates on.
+ * @param def - The layer whose children to snapshot.
+ * @returns The current snapshot; a new array iff the layer was updated since the last call.
+ */
+export function childrenOf(def) {
+    const entry = entryFor(def);
+    if (entry.childrenSnapshot?.version !== entry.version) {
+        entry.childrenSnapshot = { version: entry.version, snapshot: [...def.children] };
+    }
+    // A layer's children are homogeneous (`RenderableDefCollection<T>`), so the erased cache entry is
+    // safely re-narrowed to the layer's own child type.
+    return entry.childrenSnapshot.snapshot;
+}
+/**
+ * Returns a def's subscription entry, creating it on first contact.
+ * @param def - The def to look up.
+ * @returns The entry.
+ */
+function entryFor(def) {
+    let entry = subscriptions.get(def);
+    if (!entry) {
+        entry = { version: 0, listeners: new Set() };
+        subscriptions.set(def, entry);
+    }
+    return entry;
+}
+/**
+ * Bumps one def's version and notifies its listeners.
+ * @param def - The def that changed.
+ */
+function notify(def) {
+    const entry = subscriptions.get(def);
+    if (!entry)
+        return;
+    entry.version++;
+    for (const listener of entry.listeners)
+        listener();
+}
+/**
+ * Per-def subscription state, created on first subscribe and dropped when the last subscriber
+ * leaves. Keyed weakly by def identity: a def the renderer never mounted has no entry, which is
+ * exactly why {@link update} on it is a no-op rather than an error.
+ *
+ * Kept across hot updates, because a component subscribes once and `useSyncExternalStore` re-runs
+ * that only when the subscribe function changes identity: a fresh map would leave every mounted
+ * subscriber listening to entries no `update` can reach, and that "never mounted" no-op would start
+ * swallowing real changes (see {@link hotState}).
+ */
+const subscriptions = hotState(import.meta.hot, 'subscriptions', () => new WeakMap());

package/dist/utils/arrays.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Whether two arrays hold the same values in the same positions, compared by identity.
+ *
+ * The batched classes keep an applied order and are handed a desired one on every membership
+ * change; this is what lets an unchanged order skip the work of applying it — which matters most
+ * where applying it is expensive (repacking glyphs or endpoints) and the caller cannot know whether
+ * anything moved.
+ * @param a - The first sequence.
+ * @param b - The second sequence.
+ * @returns Whether they match.
+ */
+export declare function sameSequence<T>(a: readonly T[], b: readonly T[]): boolean;
+//# sourceMappingURL=arrays.d.ts.map

package/dist/utils/arrays.js

@@ -0,0 +1,20 @@
+/**
+ * Whether two arrays hold the same values in the same positions, compared by identity.
+ *
+ * The batched classes keep an applied order and are handed a desired one on every membership
+ * change; this is what lets an unchanged order skip the work of applying it — which matters most
+ * where applying it is expensive (repacking glyphs or endpoints) and the caller cannot know whether
+ * anything moved.
+ * @param a - The first sequence.
+ * @param b - The second sequence.
+ * @returns Whether they match.
+ */
+export function sameSequence(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i])
+            return false;
+    }
+    return true;
+}

package/dist/utils/colors.d.ts

@@ -0,0 +1,19 @@
+import { type RgbaColor } from 'colord';
+import { type ColorInput } from '../types/defs';
+/**
+ * Normalizes a {@link ColorInput} into an rgba color object.
+ * @param colorInput color as a css color string or a numeric 0xRRGGBB value
+ * @returns rgba color (r/g/b 0-255, a 0-1), or undefined if the input is not a valid color
+ */
+export declare function normalizeColor(colorInput: ColorInput): RgbaColor | undefined;
+/**
+ * Whether a color carries an alpha below 1, and so belongs in a translucent batch.
+ *
+ * A color that does not parse counts as **opaque**: `ShapeInstance` reports it and leaves the slot's
+ * tint alone, so moving a shape into a later render pass on the strength of a value the renderer
+ * could not read would compound one fault with another.
+ * @param colorInput color as a css color string or a numeric 0xRRGGBB value
+ * @returns true when the color is translucent
+ */
+export declare function isTranslucentColor(colorInput: ColorInput): boolean;
+//# sourceMappingURL=colors.d.ts.map

package/dist/utils/colors.js

@@ -0,0 +1,27 @@
+import { colord, extend } from 'colord';
+import namesPlugin from 'colord/plugins/names';
+extend([namesPlugin]);
+/**
+ * Normalizes a {@link ColorInput} into an rgba color object.
+ * @param colorInput color as a css color string or a numeric 0xRRGGBB value
+ * @returns rgba color (r/g/b 0-255, a 0-1), or undefined if the input is not a valid color
+ */
+export function normalizeColor(colorInput) {
+    const colorString = typeof colorInput === 'string' ? colorInput : `#${colorInput.toString(16).padStart(6, '0')}`;
+    const color = colord(colorString);
+    if (!color.isValid())
+        return undefined;
+    return color.toRgb();
+}
+/**
+ * Whether a color carries an alpha below 1, and so belongs in a translucent batch.
+ *
+ * A color that does not parse counts as **opaque**: `ShapeInstance` reports it and leaves the slot's
+ * tint alone, so moving a shape into a later render pass on the strength of a value the renderer
+ * could not read would compound one fault with another.
+ * @param colorInput color as a css color string or a numeric 0xRRGGBB value
+ * @returns true when the color is translucent
+ */
+export function isTranslucentColor(colorInput) {
+    return (normalizeColor(colorInput)?.a ?? 1) < 1;
+}

package/dist/utils/hot-state.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Module-level state that survives a hot update.
+ *
+ * A registry held in a module-level `const` is lost the moment Vite re-evaluates that module, and the
+ * renderer has several that hold live wiring rather than a cache: which def a mesh's hits resolve to,
+ * which closures `update(def)` reaches, which recognizer a canvas's gestures share. Each is filled
+ * once, from a mount effect, so React Refresh — which re-renders without re-running an effect whose
+ * dependencies did not change — never refills it. The module comes back empty, every lookup through
+ * it misses, and the feature goes quiet with no error anywhere: picking stops resolving defs, updates
+ * stop reaching slots.
+ */
+/** The part of Vite's `import.meta.hot` this needs, taken structurally so nothing imports its type. */
+interface HotModule {
+    /**
+     * Carried over to the next instance of the same module by every hot update.
+     *
+     * Optional because a host may offer a hot context without one: vitest defines `import.meta.hot` for
+     * its own watch-mode reload and leaves `data` unset, so reading through it throws at import time
+     * and takes the importing module down with it.
+     */
+    data?: Record<string, unknown>;
+}
+/**
+ * The value a module keeps across its own hot updates, built on first use.
+ *
+ * Each module passes its own `import.meta.hot`, which is `undefined` in a production build — Vite
+ * replaces the expression statically, so the branch and this whole module fall away and the call is
+ * nothing but the builder. That is also what makes this safe to reach for: it changes development
+ * only, and the value a module gets is the same value either way.
+ * @param hot - The calling module's `import.meta.hot`.
+ * @param key - Names the value within the module, so one module may keep several.
+ * @param build - Builds the value the first time the module is evaluated.
+ * @returns The value, built now or carried over from the instance before.
+ * @example
+ * ```ts
+ * const sources = hotState(import.meta.hot, 'sources', () => new WeakMap<Object3D, HitSource>());
+ * ```
+ */
+export declare function hotState<T>(hot: HotModule | undefined, key: string, build: () => T): T;
+export {};
+//# sourceMappingURL=hot-state.d.ts.map

package/dist/utils/hot-state.js

@@ -0,0 +1,37 @@
+/**
+ * Module-level state that survives a hot update.
+ *
+ * A registry held in a module-level `const` is lost the moment Vite re-evaluates that module, and the
+ * renderer has several that hold live wiring rather than a cache: which def a mesh's hits resolve to,
+ * which closures `update(def)` reaches, which recognizer a canvas's gestures share. Each is filled
+ * once, from a mount effect, so React Refresh — which re-renders without re-running an effect whose
+ * dependencies did not change — never refills it. The module comes back empty, every lookup through
+ * it misses, and the feature goes quiet with no error anywhere: picking stops resolving defs, updates
+ * stop reaching slots.
+ */
+/**
+ * The value a module keeps across its own hot updates, built on first use.
+ *
+ * Each module passes its own `import.meta.hot`, which is `undefined` in a production build — Vite
+ * replaces the expression statically, so the branch and this whole module fall away and the call is
+ * nothing but the builder. That is also what makes this safe to reach for: it changes development
+ * only, and the value a module gets is the same value either way.
+ * @param hot - The calling module's `import.meta.hot`.
+ * @param key - Names the value within the module, so one module may keep several.
+ * @param build - Builds the value the first time the module is evaluated.
+ * @returns The value, built now or carried over from the instance before.
+ * @example
+ * ```ts
+ * const sources = hotState(import.meta.hot, 'sources', () => new WeakMap<Object3D, HitSource>());
+ * ```
+ */
+export function hotState(hot, key, build) {
+    const data = hot?.data;
+    if (!data)
+        return build();
+    // `in` rather than a comparison against undefined, so a value that is legitimately undefined is
+    // kept rather than rebuilt on every update.
+    if (!(key in data))
+        data[key] = build();
+    return data[key];
+}

package/dist/utils/logging.d.ts

@@ -0,0 +1,29 @@
+import { type Debugger } from 'debug';
+import { type SceneDef } from '../types/defs';
+/** Logger interface */
+export interface Logger {
+    /** Debug level logger */
+    debug: Debugger;
+    /** Info level logger */
+    info: Debugger;
+    /** Warn level logger */
+    warn: Debugger;
+    /** Error level logger */
+    error: Debugger;
+}
+/**
+ * Creates a logger for one namespace, nested under the root namespace.
+ *
+ * Each level prints only if you enable its namespace, for example with
+ * `debug.enable('efp:renderer:*')`.
+ * @param namespace - The namespace to nest under the root namespace.
+ * @returns A logger with four levels, all under that namespace.
+ */
+export declare function createLogger(namespace: string): Logger;
+/**
+ * Prints the layer tree of the given scene to the console.
+ * @param scene - Scene tree to print
+ * @param logger - The logger to use to print the tree.
+ */
+export declare function printScene(scene: SceneDef, logger: Debugger): void;
+//# sourceMappingURL=logging.d.ts.map

package/dist/utils/logging.js

@@ -0,0 +1,55 @@
+/* eslint-disable no-console */
+import createLog from 'debug';
+import { isLayerDefs } from '../types/guards';
+const rootNamespace = 'efp:renderer';
+/**
+ * Creates a logger for one namespace, nested under the root namespace.
+ *
+ * Each level prints only if you enable its namespace, for example with
+ * `debug.enable('efp:renderer:*')`.
+ * @param namespace - The namespace to nest under the root namespace.
+ * @returns A logger with four levels, all under that namespace.
+ */
+export function createLogger(namespace) {
+    const fullNamespace = namespace ? `${rootNamespace}:${namespace}` : rootNamespace;
+    const info = createLog(fullNamespace);
+    // Each wrapper reads the console method at call time, not at setup time. A plain
+    // `console.warn.bind(console)` freezes the method the console object held at that
+    // moment. A test can later replace `console.warn`, for example with
+    // `vi.spyOn(console, 'warn')`. The frozen copy still calls the old method, so the
+    // spy never sees the call.
+    info.log = (...args) => console.info(...args);
+    const debug = info.extend('debug');
+    debug.log = (...args) => console.debug(...args);
+    const warn = info.extend('warn');
+    warn.log = (...args) => console.warn(...args);
+    const error = info.extend('error');
+    error.log = (...args) => console.error(...args);
+    return {
+        debug,
+        info,
+        warn,
+        error,
+    };
+}
+/**
+ * Prints the layer tree of the given scene to the console.
+ * @param scene - Scene tree to print
+ * @param logger - The logger to use to print the tree.
+ */
+export function printScene(scene, logger) {
+    function printLayer(def) {
+        const fullName = def.name;
+        if (isLayerDefs(def.children)) {
+            console.groupCollapsed(fullName);
+            def.children.forEach((c) => printLayer(c));
+            console.groupEnd();
+        }
+        else {
+            logger(fullName);
+        }
+    }
+    if (!logger.enabled)
+        return;
+    printLayer(scene.rootLayer);
+}

package/dist/utils/math.d.ts

@@ -0,0 +1,52 @@
+import { type Camera, type Matrix4 } from 'three';
+/**
+ * Holds a value inside an inclusive range.
+ *
+ * Written out rather than reached for from a library: three's own `clamp` is only exported as part
+ * of the whole `MathUtils` namespace object, and one import of that object pins every function it
+ * holds against tree-shaking.
+ * @param value - The value to clamp.
+ * @param min - The lowest value to return.
+ * @param max - The highest value to return.
+ * @returns The value, held within `[min, max]`.
+ */
+export declare function clamp(value: number, min: number, max: number): number;
+/**
+ * Wraps a value into `[0, modulus)`, keeping the sign of the modulus rather than of the value —
+ * which is what `%` does not do, and why an angle run through it can come back negative.
+ *
+ * Written out for the same reason {@link clamp} is: three has this one too, and reaching for it
+ * would pin the whole `MathUtils` namespace against tree-shaking.
+ * @param value - The value to wrap, of any magnitude or sign.
+ * @param modulus - The size of the range to wrap into.
+ * @returns The value in `[0, modulus)`.
+ */
+export declare function euclideanModulo(value: number, modulus: number): number;
+/**
+ * The length one unit along an axis is drawn at, which is the scale the matrix applies there.
+ *
+ * Reads the elements directly rather than through a vector, because picking calls this per instance
+ * per test and a scratch vector would be one more shared object to reason about.
+ * @param matrix - The matrix to measure.
+ * @param axis - Which axis. `0` is x, `1` is y and `2` is z.
+ * @returns The transformed axis's length.
+ */
+export declare function axisLength(matrix: Matrix4, axis: number): number;
+/**
+ * How far the camera's own axis travels before it meets a batch's own plane, in world units.
+ *
+ * That is the depth a plan-unit size is exact at, so it is what the shader cancels the perspective
+ * divide against. It has to agree with the depth `measurePixelSize` in `space/layout-measure.ts`
+ * works at, because a caller's `onScale` rule sizes a def in plan units from the pixel size that
+ * function reports. Without controls mounted that function reads this same crossing point. With
+ * them it reads their distance to their target, and the two agree while the target sits on the
+ * plan, which is what orbiting a floor plan keeps true.
+ *
+ * The plane is the batch's own, taken from its world matrix, because a sprite batch draws at plan
+ * `z = 0` and whatever places the plan places the mesh with it.
+ * @param camera - The camera this draw uses.
+ * @param planToWorld - The batch's world matrix.
+ * @returns The distance in world units, or `0` for a camera that never meets the plane ahead of it.
+ */
+export declare function aimDepth(camera: Camera, planToWorld: Matrix4): number;
+//# sourceMappingURL=math.d.ts.map

package/dist/utils/math.js

@@ -0,0 +1,76 @@
+import { Vector3 } from 'three';
+/**
+ * Holds a value inside an inclusive range.
+ *
+ * Written out rather than reached for from a library: three's own `clamp` is only exported as part
+ * of the whole `MathUtils` namespace object, and one import of that object pins every function it
+ * holds against tree-shaking.
+ * @param value - The value to clamp.
+ * @param min - The lowest value to return.
+ * @param max - The highest value to return.
+ * @returns The value, held within `[min, max]`.
+ */
+export function clamp(value, min, max) {
+    return Math.min(Math.max(value, min), max);
+}
+/**
+ * Wraps a value into `[0, modulus)`, keeping the sign of the modulus rather than of the value —
+ * which is what `%` does not do, and why an angle run through it can come back negative.
+ *
+ * Written out for the same reason {@link clamp} is: three has this one too, and reaching for it
+ * would pin the whole `MathUtils` namespace against tree-shaking.
+ * @param value - The value to wrap, of any magnitude or sign.
+ * @param modulus - The size of the range to wrap into.
+ * @returns The value in `[0, modulus)`.
+ */
+export function euclideanModulo(value, modulus) {
+    return ((value % modulus) + modulus) % modulus;
+}
+/**
+ * The length one unit along an axis is drawn at, which is the scale the matrix applies there.
+ *
+ * Reads the elements directly rather than through a vector, because picking calls this per instance
+ * per test and a scratch vector would be one more shared object to reason about.
+ * @param matrix - The matrix to measure.
+ * @param axis - Which axis. `0` is x, `1` is y and `2` is z.
+ * @returns The transformed axis's length.
+ */
+export function axisLength(matrix, axis) {
+    const elements = matrix.elements;
+    const at = axis * 4;
+    return Math.hypot(elements[at], elements[at + 1], elements[at + 2]);
+}
+/**
+ * How far the camera's own axis travels before it meets a batch's own plane, in world units.
+ *
+ * That is the depth a plan-unit size is exact at, so it is what the shader cancels the perspective
+ * divide against. It has to agree with the depth `measurePixelSize` in `space/layout-measure.ts`
+ * works at, because a caller's `onScale` rule sizes a def in plan units from the pixel size that
+ * function reports. Without controls mounted that function reads this same crossing point. With
+ * them it reads their distance to their target, and the two agree while the target sits on the
+ * plan, which is what orbiting a floor plan keeps true.
+ *
+ * The plane is the batch's own, taken from its world matrix, because a sprite batch draws at plan
+ * `z = 0` and whatever places the plan places the mesh with it.
+ * @param camera - The camera this draw uses.
+ * @param planToWorld - The batch's world matrix.
+ * @returns The distance in world units, or `0` for a camera that never meets the plane ahead of it.
+ */
+export function aimDepth(camera, planToWorld) {
+    // A camera looks down its own negative z.
+    const direction = _direction.setFromMatrixColumn(camera.matrixWorld, 2).normalize().negate();
+    const normal = _normal.setFromMatrixColumn(planToWorld, 2).normalize();
+    const facing = direction.dot(normal);
+    // The camera looks along the plane and never meets it.
+    if (facing === 0)
+        return 0;
+    const eye = _eye.setFromMatrixPosition(camera.matrixWorld);
+    const depth = _origin.setFromMatrixPosition(planToWorld).sub(eye).dot(normal) / facing;
+    // Behind the camera is no measurement, so the shader keeps its plan-unit sizing instead.
+    return depth > 0 ? depth : 0;
+}
+// Scratch for aimDepth, filled and consumed within one call.
+const _direction = new Vector3();
+const _normal = new Vector3();
+const _eye = new Vector3();
+const _origin = new Vector3();