@expofp/renderer 0.0.0-experimental.2d6c681

package/dist/debug/components/Stats.js

@@ -0,0 +1,24 @@
+import { addAfterEffect, useThree } from '@react-three/fiber';
+import { useEffect } from 'react';
+import StatsGl from 'stats-gl';
+/**
+ * Performance-stats overlay (frame rate, GPU timing, refresh rate) attached to
+ * the document body and refreshed after every rendered frame.
+ *
+ * The overlay is mounted imperatively, so the component renders nothing.
+ * @returns `null`.
+ */
+export function Stats() {
+    const gl = useThree((state) => state.gl);
+    useEffect(() => {
+        const stats = new StatsGl({ trackGPU: true, trackHz: true });
+        void stats.init(gl);
+        document.body.appendChild(stats.domElement);
+        const removeAfterEffect = addAfterEffect(() => stats.update());
+        return () => {
+            stats.dispose();
+            removeAfterEffect();
+        };
+    }, [gl]);
+    return null;
+}

package/dist/debug/debug-chunk.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The one debug chunk, and the two ways into it.
+ *
+ * Beside `index.tsx` rather than in it, because Fast Refresh swaps a module in place only when every
+ * value it exports is a component. `prepareDebug` is this package's public API and cannot stop being
+ * exported, so it moves instead.
+ */
+/**
+ * Imports the debug chunk, memoized so `use()` sees a stable promise and it is fetched once.
+ *
+ * Shared by every consumer: the internal mount's context-patch gate, the overlay in both mounts'
+ * trees, and {@link prepareDebug}.
+ * @returns The import promise, the same one each call.
+ */
+export declare function loadDebugChunk(): Promise<unknown>;
+/**
+ * Loads the debug chunk ahead of time — for a host that creates its own WebGL context.
+ *
+ * The chunk's evaluation is what instruments context creation for the GPU-memory panel
+ * (webgl-memory patches `getContext` as it loads), so a context created before it exists can never
+ * report memory figures. The renderer's own mount orders this itself; a MapLibre host does it by
+ * awaiting this before constructing the map, when debug is on. Idempotent, and the only eager cost
+ * is the call: the debug code still lives in its own lazy chunk.
+ */
+export declare function prepareDebug(): Promise<void>;
+//# sourceMappingURL=debug-chunk.d.ts.map

package/dist/debug/debug-chunk.js

@@ -0,0 +1,32 @@
+/**
+ * The one debug chunk, and the two ways into it.
+ *
+ * Beside `index.tsx` rather than in it, because Fast Refresh swaps a module in place only when every
+ * value it exports is a component. `prepareDebug` is this package's public API and cannot stop being
+ * exported, so it moves instead.
+ */
+/**
+ * Imports the debug chunk, memoized so `use()` sees a stable promise and it is fetched once.
+ *
+ * Shared by every consumer: the internal mount's context-patch gate, the overlay in both mounts'
+ * trees, and {@link prepareDebug}.
+ * @returns The import promise, the same one each call.
+ */
+export function loadDebugChunk() {
+    debugChunk ??= import('./components/DebugTools');
+    return debugChunk;
+}
+/**
+ * Loads the debug chunk ahead of time — for a host that creates its own WebGL context.
+ *
+ * The chunk's evaluation is what instruments context creation for the GPU-memory panel
+ * (webgl-memory patches `getContext` as it loads), so a context created before it exists can never
+ * report memory figures. The renderer's own mount orders this itself; a MapLibre host does it by
+ * awaiting this before constructing the map, when debug is on. Idempotent, and the only eager cost
+ * is the call: the debug code still lives in its own lazy chunk.
+ */
+export async function prepareDebug() {
+    await loadDebugChunk();
+}
+/** The memoized import, set by the first {@link loadDebugChunk} call. */
+let debugChunk;

package/dist/debug/debug-context.d.ts

@@ -0,0 +1,41 @@
+import type { GUI } from 'lil-gui';
+/**
+ * Context carrying the active debug GUI, or `null` when the debug UI is
+ * disabled or has not finished loading. Isolated in its own module (with a
+ * type-only GUI import) so components can read the GUI without pulling the
+ * debug UI bundle into the main chunk.
+ */
+export declare const GuiContext: import("react").Context<GUI | null>;
+/**
+ * Reads the active debug GUI from context.
+ *
+ * Returns `null` while the debug UI is off or still loading, so guard on a
+ * non-null value before adding folders or controllers.
+ * @returns The current GUI instance, or `null`.
+ */
+export declare const useGui: () => GUI | null;
+/** Write API for the debug panel: components publish key/value entries that the panel combines into one object and renders. */
+export interface DebugPanel {
+    /** Adds or updates the entry under `key`. */
+    set(key: string, value: unknown): void;
+    /** Removes the entry under `key`. */
+    remove(key: string): void;
+}
+/**
+ * Context carrying the debug panel's write API, or `null` when the debug UI is
+ * disabled. Kept separate from {@link GuiContext} so panel updates never
+ * re-render GUI consumers and vice versa.
+ */
+export declare const DebugPanelContext: import("react").Context<DebugPanel | null>;
+/**
+ * Returns a setter that publishes a key/value entry to the debug panel.
+ *
+ * The returned `set(key, value)` is stable and safe to call from anywhere,
+ * including a per-frame loop — it never re-renders the calling tree, and the
+ * panel itself re-renders only when its combined, serialized value changes.
+ * Every key a component writes is removed automatically when it unmounts.
+ * Outside the debug provider the setter is a no-op.
+ * @returns A `set(key, value)` function for the debug panel.
+ */
+export declare function useDebugPanel(): (key: string, value: unknown) => void;
+//# sourceMappingURL=debug-context.d.ts.map

package/dist/debug/debug-context.js

@@ -0,0 +1,59 @@
+import { createContext, use, useEffect, useRef } from 'react';
+/**
+ * Context carrying the active debug GUI, or `null` when the debug UI is
+ * disabled or has not finished loading. Isolated in its own module (with a
+ * type-only GUI import) so components can read the GUI without pulling the
+ * debug UI bundle into the main chunk.
+ */
+export const GuiContext = createContext(null);
+/**
+ * Reads the active debug GUI from context.
+ *
+ * Returns `null` while the debug UI is off or still loading, so guard on a
+ * non-null value before adding folders or controllers.
+ * @returns The current GUI instance, or `null`.
+ */
+export const useGui = () => use(GuiContext);
+/**
+ * Context carrying the debug panel's write API, or `null` when the debug UI is
+ * disabled. Kept separate from {@link GuiContext} so panel updates never
+ * re-render GUI consumers and vice versa.
+ */
+export const DebugPanelContext = createContext(null);
+// eslint-disable-next-line @typescript-eslint/no-empty-function
+const noop = () => { };
+/**
+ * Returns a setter that publishes a key/value entry to the debug panel.
+ *
+ * The returned `set(key, value)` is stable and safe to call from anywhere,
+ * including a per-frame loop — it never re-renders the calling tree, and the
+ * panel itself re-renders only when its combined, serialized value changes.
+ * Every key a component writes is removed automatically when it unmounts.
+ * Outside the debug provider the setter is a no-op.
+ * @returns A `set(key, value)` function for the debug panel.
+ */
+export function useDebugPanel() {
+    const panel = use(DebugPanelContext);
+    // One stable Set per consumer, tracking every key it has published. The
+    // compiler memoizes the allocation, so subsequent renders don't churn it; even
+    // without the compiler, useRef discards the extra `new Set()` after mount.
+    const keysRef = useRef(new Set());
+    useEffect(() => {
+        // Outside the debug provider there is nothing to clean up.
+        if (!panel)
+            return;
+        // Capture the (stable) Set locally so the cleanup closure doesn't read a ref
+        // in teardown. Every key this component published is removed on unmount.
+        const tracked = keysRef.current;
+        return () => tracked.forEach((key) => panel.remove(key));
+    }, [panel]);
+    // Non-debug consumers share one stable no-op — no per-consumer closure.
+    if (!panel)
+        return noop;
+    // Stable identity comes from the React Compiler — no hand-written useCallback —
+    // so callers can put `set` in effect deps without churn.
+    return (key, value) => {
+        keysRef.current.add(key);
+        panel.set(key, value);
+    };
+}

package/dist/debug/index.d.ts

@@ -0,0 +1,41 @@
+import { type CanvasProps } from '@react-three/fiber';
+import { type ReactNode } from 'react';
+/** Props for {@link CanvasWithDebug}: the Canvas props plus the debug toggle. */
+export interface CanvasWithDebugProps extends CanvasProps {
+    /** When falsy, the Canvas mounts untouched and no debug code is loaded. */
+    debugEnabled?: boolean;
+}
+/**
+ * The renderer's own Canvas with the debug ordering folded in: when `debugEnabled`, it suspends —
+ * into the boundary its parent provides — until the debug chunk has loaded, so the chunk's
+ * webgl-memory patch lands *before* the Canvas creates its context and the context is born
+ * instrumented. That ordering is this component's whole job, and it has to sit above `<Canvas>`:
+ * children mount only after the root is configured, which is after the context exists, so nothing
+ * inside the tree could order it. The overlay itself is {@link DebugOverlay}'s, inside the tree,
+ * the same in both mounts.
+ *
+ * Turning `debugEnabled` on at runtime is not supported: React keeps a suspending, already-mounted
+ * Canvas alive through the fallback, so the context is never recreated and the patch arrives too
+ * late for it. `debug` is derived from a module constant fixed for the session, so this never
+ * happens in practice.
+ * @param props - `debugEnabled` plus the Canvas props; `children` is the scene.
+ * @returns The Canvas, its context creation deferred behind the debug chunk when enabled.
+ */
+export declare function CanvasWithDebug(props: CanvasWithDebugProps): ReactNode;
+/** Props for {@link DebugOverlay}: the toggle and the tree it may instrument. */
+export interface DebugOverlayProps {
+    /** When falsy, the children render untouched and no debug code is loaded. */
+    enabled?: boolean;
+    /** The scene tree. */
+    children?: ReactNode;
+}
+/**
+ * Mounts the debug overlay around the scene tree when enabled — the same element in both mounts,
+ * which is what makes `debug` a shared prop: the GUI, the panels and the stats attach to the
+ * document, not to whichever canvas is drawing. Lazy behind the shared debug chunk; disabled, it
+ * is the children and nothing else.
+ * @param props - The toggle and the tree.
+ * @returns The tree, instrumented when enabled.
+ */
+export declare function DebugOverlay(props: DebugOverlayProps): ReactNode;
+//# sourceMappingURL=index.d.ts.map

package/dist/debug/index.js

@@ -0,0 +1,43 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Canvas } from '@react-three/fiber';
+import { lazy, Suspense, use } from 'react';
+import { loadDebugChunk } from './debug-chunk';
+const DebugTools = lazy(() => import('./components/DebugTools').then((module) => ({ default: module.DebugTools })));
+/**
+ * The renderer's own Canvas with the debug ordering folded in: when `debugEnabled`, it suspends —
+ * into the boundary its parent provides — until the debug chunk has loaded, so the chunk's
+ * webgl-memory patch lands *before* the Canvas creates its context and the context is born
+ * instrumented. That ordering is this component's whole job, and it has to sit above `<Canvas>`:
+ * children mount only after the root is configured, which is after the context exists, so nothing
+ * inside the tree could order it. The overlay itself is {@link DebugOverlay}'s, inside the tree,
+ * the same in both mounts.
+ *
+ * Turning `debugEnabled` on at runtime is not supported: React keeps a suspending, already-mounted
+ * Canvas alive through the fallback, so the context is never recreated and the patch arrives too
+ * late for it. `debug` is derived from a module constant fixed for the session, so this never
+ * happens in practice.
+ * @param props - `debugEnabled` plus the Canvas props; `children` is the scene.
+ * @returns The Canvas, its context creation deferred behind the debug chunk when enabled.
+ */
+export function CanvasWithDebug(props) {
+    const { debugEnabled, children, ...canvasProps } = props;
+    // `use` is built for conditional calls, and the condition is the point: an undebugged mount
+    // never touches the chunk.
+    if (debugEnabled)
+        use(loadDebugChunk());
+    return _jsx(Canvas, { ...canvasProps, children: children });
+}
+/**
+ * Mounts the debug overlay around the scene tree when enabled — the same element in both mounts,
+ * which is what makes `debug` a shared prop: the GUI, the panels and the stats attach to the
+ * document, not to whichever canvas is drawing. Lazy behind the shared debug chunk; disabled, it
+ * is the children and nothing else.
+ * @param props - The toggle and the tree.
+ * @returns The tree, instrumented when enabled.
+ */
+export function DebugOverlay(props) {
+    const { enabled, children } = props;
+    if (!enabled)
+        return children;
+    return (_jsx(Suspense, { fallback: null, children: _jsx(DebugTools, { children: children }) }));
+}

package/dist/events/LayoutDriver.d.ts

@@ -0,0 +1,36 @@
+import { type ReactNode } from 'react';
+/** Props for {@link LayoutDriver}. */
+export interface LayoutDriverProps {
+    /** The scene whose defs register as re-layout targets. */
+    children: ReactNode;
+}
+/**
+ * Drives camera-driven re-layout: it owns the renderer's {@link LayoutTargets} and watches both
+ * layout axes every frame — the pixel size, swept past an epsilon, and the roll, swept on any
+ * change — running each registered def's stale rules and writing back whatever they report changed.
+ *
+ * It runs at the default frame priority, after the controls have updated the camera at `-1`, so a
+ * frame lays out against the camera it is about to draw. And it runs only on frames something asked
+ * for: under the on-demand loop the camera's own movement is what requests them, so a still plan
+ * costs nothing at all.
+ *
+ * A move runs every stale rule at once — the cheap half — and starts a **sweep** of the writes: each
+ * frame drains the registry's write queue for at most {@link LAYOUT_BUDGET_MS}, visibility flips
+ * first and then defs inside the camera's frustum, and asks for another frame while any remain — so
+ * a plan of ten thousand labels re-writes over a handful of frames instead of stalling one, and what
+ * the user sees change lands first. The writes stay inside the frame callback, before three's own
+ * render, so they upload in the very frame that draws them.
+ *
+ * It also drives the registry's placement pass, which depends on the whole camera: a pan, a pitch
+ * or a resize moves every screen box while the pixel size and roll sit still. The pass runs before
+ * the drain and before three's render, so a verdict is written in the frame that draws it.
+ * {@link runPlacement} decides when it runs.
+ *
+ * No React is involved in a re-layout. The handlers mutate def fields and the defs' own sync closures
+ * write them, so a zoom does not re-render a single component — which is what makes it affordable for
+ * every label in a plan to re-lay out while the camera moves.
+ * @param props - The scene to provide the registry to.
+ * @returns The scene, under the registry.
+ */
+export declare function LayoutDriver(props: LayoutDriverProps): import("react").JSX.Element;
+//# sourceMappingURL=LayoutDriver.d.ts.map

package/dist/events/LayoutDriver.js

@@ -0,0 +1,192 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Point } from '@expofp/geometry';
+import { useFrame, useThree } from '@react-three/fiber';
+import { useRef, useState } from 'react';
+import { Frustum, Matrix4, Vector2, Vector4 } from 'three';
+import { useCameraControls } from '../controls/hooks';
+import { measurePixelSize, measureRoll, pixelSizeMoved } from '../space/layout-measure';
+import { useSpace } from '../space/Space';
+import { planFrustum } from './def-culling';
+import { createLayoutTargets, LayoutTargetsContext } from './layout-targets';
+/**
+ * Drives camera-driven re-layout: it owns the renderer's {@link LayoutTargets} and watches both
+ * layout axes every frame — the pixel size, swept past an epsilon, and the roll, swept on any
+ * change — running each registered def's stale rules and writing back whatever they report changed.
+ *
+ * It runs at the default frame priority, after the controls have updated the camera at `-1`, so a
+ * frame lays out against the camera it is about to draw. And it runs only on frames something asked
+ * for: under the on-demand loop the camera's own movement is what requests them, so a still plan
+ * costs nothing at all.
+ *
+ * A move runs every stale rule at once — the cheap half — and starts a **sweep** of the writes: each
+ * frame drains the registry's write queue for at most {@link LAYOUT_BUDGET_MS}, visibility flips
+ * first and then defs inside the camera's frustum, and asks for another frame while any remain — so
+ * a plan of ten thousand labels re-writes over a handful of frames instead of stalling one, and what
+ * the user sees change lands first. The writes stay inside the frame callback, before three's own
+ * render, so they upload in the very frame that draws them.
+ *
+ * It also drives the registry's placement pass, which depends on the whole camera: a pan, a pitch
+ * or a resize moves every screen box while the pixel size and roll sit still. The pass runs before
+ * the drain and before three's render, so a verdict is written in the frame that draws it.
+ * {@link runPlacement} decides when it runs.
+ *
+ * No React is involved in a re-layout. The handlers mutate def fields and the defs' own sync closures
+ * write them, so a zoom does not re-render a single component — which is what makes it affordable for
+ * every label in a plan to re-lay out while the camera moves.
+ * @param props - The scene to provide the registry to.
+ * @returns The scene, under the registry.
+ */
+export function LayoutDriver(props) {
+    const { children } = props;
+    const camera = useThree((state) => state.camera);
+    const gl = useThree((state) => state.gl);
+    const invalidate = useThree((state) => state.invalidate);
+    const controls = useCameraControls();
+    const space = useSpace();
+    // Seeded from the camera as it stands, so defs registering before the first frame are laid out at
+    // the size they will be drawn at rather than at a placeholder. The measurement asks nothing of
+    // the controls — absent at this point whatever the mount order, since they publish themselves in
+    // an effect and this runs during render — which is also what lets this component be rendered,
+    // and tested, without any controls at all.
+    const [targets] = useState(() => createLayoutTargets(invalidate, measurePixelSize(camera, space, gl.domElement.width / gl.getPixelRatio()) ?? 1, measureRoll(camera, space, gl.domElement.width / gl.getPixelRatio(), gl.domElement.height / gl.getPixelRatio()) ?? 0));
+    // Frame state for the placement debounce. Nothing renders on it.
+    const placementRef = useRef({
+        seen: new Matrix4(),
+        size: new Vector2(),
+        frameAt: -Infinity,
+        changedAt: -Infinity,
+        placedAt: -Infinity,
+    });
+    useFrame((state) => {
+        const { camera, gl, viewport } = state;
+        const { width, height } = gl.domElement;
+        // Everything the renderer publishes is in CSS pixels, so the device ratio stops here.
+        const cssWidth = width / viewport.dpr;
+        const cssHeight = height / viewport.dpr;
+        // 1. The pixel size, swept past an epsilon against the sweep's own target.
+        const pixelSize = measurePixelSize(camera, space, cssWidth, controls);
+        if (pixelSize !== undefined && pixelSizeMoved(pixelSize, targets.pixelSize)) {
+            targets.applyScale(pixelSize);
+        }
+        // 2. The roll, swept on any change: the rules step in quarter turns, so most are no-writes.
+        const roll = measureRoll(camera, space, cssWidth, cssHeight, controls);
+        if (roll !== undefined && roll !== targets.roll)
+            targets.applyRoll(roll);
+        // 3. The placement pass, ahead of the drain so its verdicts are written this frame.
+        const view = {
+            space,
+            camera,
+            pixelSize: targets.pixelSize,
+            width: cssWidth,
+            height: cssHeight,
+        };
+        if (runPlacement(targets, placementRef.current, view, performance.now()))
+            invalidate();
+        // 4. The writes, inside the frustum first, on a budget. A leftover backlog asks for a frame.
+        if (!targets.hasWork)
+            return;
+        const frustum = planFrustum(camera, space.matrix, _frustum);
+        if (targets.drain(frustum, LAYOUT_BUDGET_MS))
+            invalidate();
+    });
+    return _jsx(LayoutTargetsContext, { value: targets, children: children });
+}
+/**
+ * Runs the placement pass once the plan has not visibly moved on screen for
+ * {@link PLACEMENT_DEBOUNCE_MS}, and at once when a participant registers, leaves or moves. Every
+ * pass reports.
+ *
+ * Visibly means faster than {@link SETTLE_SPEED_PX_PER_S}. The controls' easing tail, which
+ * creeps for hundreds of milliseconds after the plan looks still, therefore does not hold the pass.
+ * @param targets - The registry.
+ * @param state - The debounce state, updated here.
+ * @param context - The pass's context.
+ * @param now - The clock, in milliseconds.
+ * @returns Whether the driver must ask for a frame: a pass is waiting out the debounce.
+ */
+function runPlacement(targets, state, context, now) {
+    const { space, camera, width, height } = context;
+    const step = Math.min(now - state.frameAt, MAX_STEP_MS);
+    const motion = screenMotion(space, camera, state.seen, width, height);
+    const resized = state.size.x !== width || state.size.y !== height;
+    if (resized || motion > (SETTLE_SPEED_PX_PER_S * step) / 1000)
+        state.changedAt = now;
+    state.seen.multiplyMatrices(camera.projectionMatrix, camera.matrixWorldInverse);
+    state.size.set(width, height);
+    state.frameAt = now;
+    const pending = state.changedAt > state.placedAt;
+    const owed = targets.needsPlacement || targets.placementDrifted;
+    if (!owed && !(pending && now - state.changedAt >= PLACEMENT_DEBOUNCE_MS))
+        return pending;
+    state.placedAt = now;
+    targets.applyPlacement(context);
+    return false;
+}
+/**
+ * How far the plan moved on screen between the last frame's camera and this one, in CSS pixels:
+ * the most that any of a grid of points across the canvas moved. Each point is cast onto the plan
+ * through this frame's camera and projected back through the last frame's, so a pan, a zoom, a
+ * turn and a tilt all count, by however far they move what is on screen. A point that misses the
+ * plan, above the horizon, is skipped, as is one the last frame had behind the camera.
+ * @param space - The scene's space.
+ * @param camera - This frame's camera, its matrices up to date.
+ * @param previous - `projection * viewInverse` as of the last frame.
+ * @param cssWidth - The canvas width in CSS pixels.
+ * @param cssHeight - The canvas height in CSS pixels.
+ * @returns The motion in CSS pixels: 0 for a camera that did not move, and `Infinity` when no
+ *   point lands on the plan, so a camera that sees none of it settles only by standing still.
+ */
+function screenMotion(space, camera, previous, cssWidth, cssHeight) {
+    _motionNow.multiplyMatrices(camera.projectionMatrix, camera.matrixWorldInverse);
+    if (_motionNow.equals(previous))
+        return 0;
+    let motion = -1;
+    for (const x of MOTION_SAMPLES) {
+        for (const y of MOTION_SAMPLES) {
+            const plan = space.ndcToPlan(_motionNdc.set(x, y), camera, _motionPlan);
+            if (!plan)
+                continue;
+            _motionClip.set(plan.x, plan.y, 0, 1).applyMatrix4(space.matrix).applyMatrix4(previous);
+            if (_motionClip.w <= 0)
+                continue;
+            const dx = (_motionClip.x / _motionClip.w - x) * (cssWidth / 2);
+            const dy = (_motionClip.y / _motionClip.w - y) * (cssHeight / 2);
+            motion = Math.max(motion, Math.hypot(dx, dy));
+        }
+    }
+    return motion < 0 ? Infinity : motion;
+}
+/**
+ * How much of a frame one drain may spend writing laid-out defs into their slots, in milliseconds —
+ * the same budget the legacy renderer's `UpdatesSystem` drained its update queue with. Small enough
+ * to leave a 60fps frame its render; the backlog it leaves is carried into the next frame.
+ */
+const LAYOUT_BUDGET_MS = 3;
+/**
+ * How long the view must stay unchanged before the placement pass runs, in milliseconds. Long
+ * enough that a drag or a run of wheel events reports once, not on every event.
+ */
+const PLACEMENT_DEBOUNCE_MS = 60;
+/**
+ * How fast the plan may move on screen, in CSS pixels a second, and still count as still: one CSS
+ * pixel a frame at 60 Hz. Each frame is held against its own time step, so the rule is the same at
+ * any frame rate.
+ */
+const SETTLE_SPEED_PX_PER_S = 60;
+/**
+ * The longest time step a frame's motion is measured over, in milliseconds. The first frame after an
+ * idle loop would otherwise read any jump as slow.
+ */
+const MAX_STEP_MS = 1000 / 30;
+/**
+ * Where {@link screenMotion} samples the canvas, in normalized device coordinates along each axis:
+ * a 3 by 3 grid reaching nearly to the edges, where a zoom or a turn moves the plan most.
+ */
+const MOTION_SAMPLES = [-0.96, 0, 0.96];
+// Scratch for the drain's frustum, filled and consumed within one frame callback.
+const _frustum = new Frustum();
+// Scratch for screenMotion, filled and consumed within one call.
+const _motionNow = new Matrix4();
+const _motionNdc = new Vector2();
+const _motionPlan = new Point();
+const _motionClip = new Vector4();

package/dist/events/PointerMissed.d.ts

@@ -0,0 +1,23 @@
+import { type PointerMissedEventData } from '../types/events';
+/** Props for {@link PointerMissed}. */
+export interface PointerMissedProps {
+    /** Called for a click that reached no layer handler. */
+    onPointerMissed?: (event: PointerMissedEventData) => void;
+}
+/**
+ * Publishes the renderer's missed-click handler, wrapped so it reports a plan position rather than
+ * the bare DOM event R3F hands out.
+ *
+ * Two reasons this is a component inside the canvas rather than the `onPointerMissed` prop `<Canvas>`
+ * already accepts. The position is only computable here: R3F sets up the pointer ray before deciding
+ * a click reached no handler, so the ray is still current when this runs and the scene can be
+ * searched along it — which is what a miss needs, since reaching no *handler* is not the same as
+ * striking nothing. And the canvas prop is effectively write-once —
+ * R3F copies it into its store under `if (!state.onPointerMissed)`, so a caller swapping the handler
+ * would keep firing the first one. Setting the store directly re-publishes on every change and clears
+ * the slot on unmount.
+ * @param props - The handler to publish.
+ * @returns Nothing; this renders no scene node.
+ */
+export declare function PointerMissed(props: PointerMissedProps): null;
+//# sourceMappingURL=PointerMissed.d.ts.map

package/dist/events/PointerMissed.js

@@ -0,0 +1,58 @@
+import { useThree } from '@react-three/fiber';
+import { useEffect, useEffectEvent } from 'react';
+import { useSpace } from '../space/Space';
+import { missedPoint } from './pointer';
+/**
+ * Publishes the renderer's missed-click handler, wrapped so it reports a plan position rather than
+ * the bare DOM event R3F hands out.
+ *
+ * Two reasons this is a component inside the canvas rather than the `onPointerMissed` prop `<Canvas>`
+ * already accepts. The position is only computable here: R3F sets up the pointer ray before deciding
+ * a click reached no handler, so the ray is still current when this runs and the scene can be
+ * searched along it — which is what a miss needs, since reaching no *handler* is not the same as
+ * striking nothing. And the canvas prop is effectively write-once —
+ * R3F copies it into its store under `if (!state.onPointerMissed)`, so a caller swapping the handler
+ * would keep firing the first one. Setting the store directly re-publishes on every change and clears
+ * the slot on unmount.
+ * @param props - The handler to publish.
+ * @returns Nothing; this renders no scene node.
+ */
+export function PointerMissed(props) {
+    const { onPointerMissed } = props;
+    const raycaster = useThree((state) => state.raycaster);
+    const scene = useThree((state) => state.scene);
+    const set = useThree((state) => state.set);
+    const space = useSpace();
+    /**
+     * Reports a missed click at the pointer's plan position.
+     *
+     * An effect event rather than a closure the publish effect rebuilds: the handler, the scene and
+     * the space are read fresh when a click arrives, so none of them is a dependency of the effect
+     * below. The space is the one that matters — a resize refits it on every step, and a publish that
+     * depended on it wrote the store twice per step, notifying every `useThree` subscriber in the
+     * renderer each time.
+     * **Clicks only, where R3F counts three events as one.** It dispatches this for `contextmenu` and
+     * `dblclick` as readily as for `click`, and a browser fires `contextmenu` on the *press* rather
+     * than the release — so a right-drag, which is how a pitch gesture begins, would report a miss
+     * before the gesture had moved at all, and a double-click would report a third on top of the two
+     * clicks that composed it. Only a real click has missed anything.
+     * @param nativeEvent - The DOM event; anything but a click is not one.
+     */
+    const handleMissed = useEffectEvent((nativeEvent) => {
+        if (nativeEvent.type !== 'click')
+            return;
+        onPointerMissed?.({
+            point: missedPoint(raycaster, scene, space),
+            nativeEvent,
+        });
+    });
+    // Republished only when the caller's handler appears or disappears; which function it currently
+    // is stays out of the dependencies, like the space, because the effect event reads it at click
+    // time.
+    const handles = onPointerMissed !== undefined;
+    useEffect(() => {
+        set({ onPointerMissed: handles ? handleMissed : undefined });
+        return () => set({ onPointerMissed: undefined });
+    }, [handles, set]);
+    return null;
+}

package/dist/events/def-culling.d.ts

@@ -0,0 +1,46 @@
+import { type Rect } from '@expofp/geometry';
+import { type Camera, Frustum, Matrix4, Sphere } from 'three';
+import { type RenderableDef } from '../types/defs';
+/**
+ * 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 declare function boundingSphereOf(bounds: Rect, origin: [number, number] | undefined, out: Sphere): Sphere;
+/**
+ * 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 declare function culledBy(def: RenderableDef, frustum: Frustum): boolean;
+/**
+ * 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 declare function planFrustum(camera: Camera, planMatrix: Matrix4, out?: Frustum): Frustum;
+//# sourceMappingURL=def-culling.d.ts.map