@expofp/renderer 3.2.5 → 3.27.0

package/dist/debug/index.d.ts

@@ -0,0 +1,51 @@
+import { type CanvasProps } from '@react-three/fiber';
+import { type ReactNode } from 'react';
+/**
+ * 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>;
+/** 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,64 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Canvas } from '@react-three/fiber';
+import { lazy, Suspense, use } from 'react';
+/**
+ * The one debug chunk, shared by every consumer: the internal mount's context-patch gate, the
+ * overlay in both mounts' trees, and {@link prepareDebug}. Memoized so `use()` sees a stable
+ * promise and the chunk is fetched once.
+ */
+let debugChunk;
+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();
+}
+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,31 @@
+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 starts a **sweep**, never a synchronous pass: each frame drains the registry's backlog for
+ * at most {@link LAYOUT_BUDGET_MS}, defs inside the camera's frustum first, and asks for another
+ * frame while any backlog remains — so a plan of ten thousand labels re-lays out over a handful of
+ * frames instead of stalling one, and what the user is looking at is what lands first. The layouts
+ * stay inside the frame callback, before three's own render, so their attribute writes upload in
+ * the very frame that draws them.
+ *
+ * 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,88 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useFrame, useThree } from '@react-three/fiber';
+import { useState } from 'react';
+import { Frustum } from 'three';
+import { useCameraControls } from '../controls';
+import { measurePixelSize, measureRoll, pixelSizeMoved } from '../space/layout-measure';
+import { useSpace } from '../space/Space';
+import { createLogger } from '../utils/logging';
+import { planFrustum } from './def-culling';
+import { createLayoutTargets, LayoutTargetsContext } from './layout-targets';
+const logger = createLogger('layout');
+/**
+ * How much of a frame one drain may spend running layout rules, 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, visible defs first.
+ */
+const LAYOUT_BUDGET_MS = 3;
+/**
+ * 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 starts a **sweep**, never a synchronous pass: each frame drains the registry's backlog for
+ * at most {@link LAYOUT_BUDGET_MS}, defs inside the camera's frustum first, and asks for another
+ * frame while any backlog remains — so a plan of ten thousand labels re-lays out over a handful of
+ * frames instead of stalling one, and what the user is looking at is what lands first. The layouts
+ * stay inside the frame callback, before three's own render, so their attribute writes upload in
+ * the very frame that draws them.
+ *
+ * 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) ?? 1, measureRoll(camera, space, gl.domElement.width, gl.domElement.height) ?? 0));
+    useFrame((state) => {
+        const camera = state.camera;
+        const { width, height } = state.gl.domElement;
+        // One call for every camera — the renderer's own and external mode's folded matrix alike. The
+        // controls are handed over rather than branched on here: with them the reading is the cheap
+        // arithmetic the imperative renderer used, and without them it is measured off the matrices,
+        // which both cameras carry.
+        const pixelSize = measurePixelSize(camera, space, width, controls);
+        // The epsilon compares against the sweep's target size, so a camera that stopped mid-sweep does
+        // not re-mark the same sweep on every one of the frames that finish it.
+        if (pixelSize !== undefined && pixelSizeMoved(pixelSize, targets.pixelSize)) {
+            logger.debug(`pxToSvgScale ${+pixelSize.toFixed(3)}`);
+            targets.applyScale(pixelSize);
+        }
+        // Roll has no epsilon — the imperative renderer swept its roll handlers on any bearing change
+        // at all, and the rules themselves step in quarter turns, so almost every layout is a cheap
+        // no-write. Which of the two ways it is reached — the controls' own angle, or a measurement off
+        // the camera for external mode and bare scenes — is `measureRoll`'s to choose.
+        const roll = measureRoll(camera, space, width, height, controls);
+        if (roll !== undefined && roll !== targets.roll)
+            targets.applyRoll(roll);
+        if (!targets.hasWork)
+            return;
+        // Priority, never correctness: the frustum only decides who waits, and it is rebuilt each drain
+        // so a camera that pans mid-sweep re-prioritizes what is left.
+        const frustum = planFrustum(state.camera, space.matrix, _frustum);
+        // The writes self-invalidate through the defs' slot writers; this asks for the *extra* frame a
+        // leftover backlog needs, which is what keeps the demand loop ticking until the sweep is done.
+        if (targets.drain(frustum, LAYOUT_BUDGET_MS))
+            invalidate();
+    });
+    return _jsx(LayoutTargetsContext, { value: targets, children: children });
+}
+// Scratch for the drain's frustum, filled and consumed within one frame callback.
+const _frustum = new Frustum();

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

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,104 @@
+import { type Frustum } from 'three';
+import { type LayerDef, type RenderableDef } from '../types/defs';
+/**
+ * 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 pixel-size move is a **sweep**, not a synchronous pass: {@link applyScale} marks every registered def
+ * stale and {@link drain} works the backlog off a frame's budget at a time, defs the camera can see
+ * first. The shape is the legacy renderer's `UpdatesSystem` (fp-engine `core/updates.ts`), whose
+ * pending/deferred queues and per-frame time budget this registry inherits — with the queue's unit
+ * changed from "def whose fields moved" to "def whose layout rule must re-run".
+ */
+export interface LayoutTargets {
+    /**
+     * The pixel size the registered defs are laid out at — from the moment {@link applyScale} marks a
+     * sweep, the size defs are being *brought* to, which is what the driver's epsilon must compare
+     * against so a camera that stopped moving does not re-mark the same sweep every frame.
+     */
+    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: against the sweep's target, not the last
+     * drained value.
+     */
+    readonly roll: number;
+    /** Whether a sweep still has defs to lay out — what makes a caller keep frames coming. */
+    readonly hasWork: boolean;
+    /**
+     * Registers defs for re-layout, and lays out 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 defs - The defs to lay out; every one of them declares an `onScale` or an `onRoll`.
+     * @returns An unregister function; it also drops whatever of these defs a sweep still queued.
+     */
+    register(defs: readonly RenderableDef[]): () => void;
+    /**
+     * Starts a sweep: records the new pixel size and marks every registered def stale. Nothing is
+     * laid out here — that is {@link drain}'s job — so the frame that noticed the move pays only the
+     * marking. Applying again mid-sweep re-marks at the newer size, and a def the earlier sweep had
+     * not reached is simply laid out once, at that newer size: the backlog coalesces by construction.
+     * @param pixelSize - The new pixel size.
+     */
+    applyScale(pixelSize: number): void;
+    /**
+     * Starts a roll sweep — {@link applyScale}'s counterpart on the other axis, marking only the defs that
+     * declare an `onRoll`. The two axes coalesce independently, and one {@link drain} works both off.
+     * @param roll - The new roll, in radians clockwise from north.
+     */
+    applyRoll(roll: number): void;
+    /**
+     * Works off the sweep within a frame's budget, and says whether any backlog remains — the
+     * caller's cue to ask for another frame.
+     *
+     * Two passes, in the legacy `UpdatesSystem`'s shape: the stale defs first, except that a hidden
+     * def or one the frustum rejects is *deferred* rather than laid out; then the deferred ones, with
+     * whatever budget is left. Priority is all deferral buys — every def is still laid out before the
+     * sweep ends, because whether a def draws can be exactly what its rule decides. The budget is
+     * checked before each def, so even a blown budget lays at least one out and a sweep can never
+     * stall.
+     * @param frustum - The camera's frustum in plan space, when the caller has one; without it only
+     *   hidden defs are 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`, and the layer itself when it declares one.
+ *
+ * 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