@expofp/renderer 3.44.8 → 3.45.0

package/dist/Renderer.js

@@ -63,7 +63,13 @@ export function Renderer(props) {
         // and its own bootstrap effect must run once per context, not be double-invoked into churn.
         return (_jsx(ExternalCanvas, { gl: gl, requestFrame: requestFrame, onFrame: onFrame, children: tree }));
     }
-    return (_jsx(StrictMode, { children: _jsx(Suspense, { fallback: null, children: _jsx(CanvasWithDebug, { ...canvasProps, debugEnabled: debug, 
+    return (_jsx(StrictMode, { children: _jsx(Suspense, { fallback: null, children: _jsx(CanvasWithDebug, { ...canvasProps, 
+                // No `dpr`: R3F's default caps the buffer at 2x, and that is a performance choice rather
+                // than a size one. Every pixel-authored size is derived from CSS units and the pixel size
+                // the renderer publishes (also CSS), so a 3x canvas rasterized by a caller still draws at
+                // the size it asked for while the buffer stays at 2x. A 3x buffer is 2.25 times the area
+                // of a 2x one, on exactly the devices that can least afford it.
+                debugEnabled: debug, 
                 // R3F force-writes ACES filmic tone mapping onto a fresh renderer unless `flat` is set,
                 // which lands it on three's own default, `NoToneMapping`, instead. This renderer does not
                 // tone map: `Lighting` keeps the rig's light sum in range by construction, rather than

package/dist/controls/hooks.d.ts

@@ -85,8 +85,9 @@ export interface CameraState {
     /** How far the plan is tilted away from face-on, in degrees. */
     pitch: number;
     /**
-     * How much of the plan one device pixel spans, in plan units — the factor anything sized in
+     * How much of the plan one CSS pixel spans, in plan units — the factor anything sized in
      * pixels is laid out against, and the quantity the imperative renderer published as `ptScale`.
+     * The device ratio is not part of it.
      */
     pixelSize: number;
 }

package/dist/core/sprites/BatchedSprites.js

@@ -1,5 +1,6 @@
 import { extend } from '@react-three/fiber';
-import { Matrix4, PlaneGeometry, Vector2, Vector3, } from 'three';
+import { Matrix4, PlaneGeometry, Vector2, } from 'three';
+import { aimDepth } from '../../utils/math';
 import { InstancedMeshImpl } from '../instanced/InstancedMesh';
 import { RaycastingSprites } from './RaycastingSprites';
 import { ANCHOR_SCHEMA, ANCHOR_UNIFORM, patchSpriteMaterial, spriteReferenceDepth, } from './sprite-material';
@@ -165,41 +166,8 @@ export const BatchedSprites = extend(BatchedSpritesImpl);
 function furthestCorner(anchor) {
     return Math.hypot(0.5 + Math.abs(anchor.x), 0.5 + Math.abs(anchor.y));
 }
-/**
- * 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.
- */
-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;
-}
 /** The quad every sprite batch draws. One per process. See `BatchedSpritesImpl.geometry`. */
 const SPRITE_QUAD = new PlaneGeometry(1, 1);
 // Scratch, each filled and consumed within one synchronous call.
 const _anchor = new Vector2();
 const _matrix = new Matrix4();
-const _direction = new Vector3();
-const _normal = new Vector3();
-const _eye = new Vector3();
-const _origin = new Vector3();

package/dist/core/text/MemberTexture.js

@@ -1,5 +1,6 @@
 import { Color, DataTexture, FloatType, Frustum, Matrix4, RGBAFormat, Sphere, Vector3, } from 'three';
 import { Y_DOWN_FLIP } from '../../space/Space';
+import { aimDepth } from '../../utils/math';
 /**
  * The data texture a batch's shader reads each member's transform and style from: one 32-float row
  * per member, refilled once per draw with frustum culling folded in.
@@ -58,12 +59,20 @@ export class MemberTexture {
         // member, so reading it per member made this loop quadratic — and it returns an *array* once
         // outlines are on, whose `.color` is undefined. The material being drawn is already in hand.
         const batchColor = host.color ?? material.color ?? 0xffffff;
+        // What a screen-space member's size is exact at, and where the camera looks from. Zero turns the
+        // correction off, for an orthographic camera (no divide to cancel) and for one that never meets
+        // the plan. See `depthScaleOf`.
+        const reference = camera.isPerspectiveCamera
+            ? aimDepth(camera, host.matrixWorld)
+            : 0;
+        _eye.setFromMatrixPosition(camera.matrixWorld);
+        _forward.setFromMatrixColumn(camera.matrixWorld, 2).normalize().negate();
         for (let memberId = 0; memberId < rowCount; memberId++) {
             const text = host.getText(memberId);
             // An unsynced member has no layout to write and draws nothing either.
             if (!text?.textRenderInfo)
                 continue;
-            faceCamera(text, _basis);
+            faceCamera(text, _basis, reference > 0 ? depthScaleOf(text, host.matrixWorld, reference) : 1);
             const start = memberId * FLOATS_PER_MEMBER;
             if (isDrawn(text)) {
                 this.writeMember(texData, start, text, material, batchColor);
@@ -172,6 +181,32 @@ export class MemberTexture {
         }
     }
 }
+/**
+ * How much a screen-space member is scaled so that it keeps the on-screen size its plan-unit size
+ * asks for wherever it sits in a perspective frame.
+ *
+ * The same correction a sprite's shader applies to an image (`spriteDepthScale` in
+ * `sprites/sprite-material.ts`), and for the same reason: a member sized in plan units shrinks by
+ * the projection's divide, and a pitched camera spreads the plan across a range of depths, so one
+ * pixel size is right only where the camera's axis crosses the plan. Without it an image beside its
+ * text is constant in pixels while the text is not, and anything laid out inside the image's
+ * pixels (a count in a counter circle) slides off it as the pin moves up or down the screen.
+ * @param text - The member, with its sprite anchor set.
+ * @param matrixWorld - The batch's world matrix.
+ * @param reference - The depth the plan-unit size is exact at. Must be positive.
+ * @returns The scale, one at the reference depth. One as well for an anchor at or behind the eye.
+ */
+function depthScaleOf(text, matrixWorld, reference) {
+    const anchor = text.spriteAnchor;
+    if (!anchor)
+        return 1;
+    const depth = _offset
+        .set(anchor.x, anchor.y, text.position.z)
+        .applyMatrix4(matrixWorld)
+        .sub(_eye)
+        .dot(_forward);
+    return depth > 0 ? depth / reference : 1;
+}
 /**
  * Turns a screen-space member to face the camera, and leaves a flat one alone.
  *
@@ -180,20 +215,23 @@ export class MemberTexture {
  * `BatchedTextImpl.raycast` and `isDrawn`. This path costs neither, because both of those read the
  * member's matrix already. Write the sprite matrix there and both follow.
  *
- * The composition is `T(anchor) . basis . T(position - anchor) . Rz(rotation.z) . S(scale)`. The
- * basis is the camera's rotation brought into the batch's own space, corrected by `Y_DOWN_FLIP`
- * for the camera's own rest pose (see {@link Y_DOWN_FLIP} in `space/Space.ts`). Everything else is
- * read off the member exactly as
- * `updateMatrix` reads it. Straight overhead the basis is the identity and this reduces to the flat
- * matrix, which is the equality the top-down baseline asserts on screen.
+ * The composition is
+ * `T(anchor) . basis . S(depth) . T(position - anchor) . Rz(rotation.z) . S(scale)`. The basis is
+ * the camera's rotation brought into the batch's own space, corrected by `Y_DOWN_FLIP` for the
+ * camera's own rest pose (see {@link Y_DOWN_FLIP} in `space/Space.ts`). `S(depth)` is
+ * {@link depthScaleOf}, which scales the offset from the anchor along with the glyphs. Everything
+ * else is read off the member exactly as `updateMatrix` reads it. Straight overhead with the
+ * anchor at the reference depth the basis is the identity and the depth scale is one, so this
+ * reduces to the flat matrix, which is the equality the top-down baseline asserts on screen.
  *
  * Written through `setMatrix` only when it changed, so a still camera costs sixteen comparisons and
  * no bounds invalidation. A pan or a zoom costs the same, because neither moves the camera's
  * rotation. Only a roll or a pitch dirties a row.
  * @param text - The member to turn.
  * @param basis - The camera basis for this draw, in the batch's own space.
+ * @param depthScale - The member's perspective correction. One for none.
  */
-function faceCamera(text, basis) {
+function faceCamera(text, basis, depthScale) {
     const anchor = text.spriteAnchor;
     if (!anchor)
         return;
@@ -202,6 +240,7 @@ function faceCamera(text, basis) {
     _offset.set(text.position.x - anchor.x, text.position.y - anchor.y, 0);
     _spriteMatrix
         .copy(basis)
+        .multiply(_step.makeScale(depthScale, depthScale, depthScale))
         .multiply(_step.makeTranslation(_offset.x, _offset.y, _offset.z))
         .multiply(_step.makeRotationZ(text.rotation.z))
         .scale(text.scale)
@@ -246,3 +285,5 @@ const _cameraBasis = new Matrix4();
 const _spriteMatrix = new Matrix4();
 const _step = new Matrix4();
 const _offset = new Vector3();
+const _eye = new Vector3();
+const _forward = new Vector3();

package/dist/events/LayoutDriver.d.ts

@@ -21,6 +21,11 @@ export interface LayoutDriverProps {
  * 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.

package/dist/events/LayoutDriver.js

@@ -1,18 +1,13 @@
 import { jsx as _jsx } from "react/jsx-runtime";
+import { Point } from '@expofp/geometry';
 import { useFrame, useThree } from '@react-three/fiber';
-import { useState } from 'react';
-import { Frustum } from 'three';
-import { useCameraControls } from '../controls';
+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';
-/**
- * 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;
 /**
  * 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
@@ -30,6 +25,11 @@ const LAYOUT_BUDGET_MS = 3;
  * 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.
@@ -48,38 +48,145 @@ export function LayoutDriver(props) {
     // 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));
+    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 = 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.
+        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);
         }
-        // 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);
+        // 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;
-        // 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.
+        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/layout-targets.d.ts

@@ -1,5 +1,6 @@
 import { type Frustum } from 'three';
 import { type LayerDef, type RenderableDef } from '../types/defs';
+import { type PlacementContext } from './placement';
 /**
  * The defs a renderer re-lays out when the camera moves: the pixel size and the roll are the two
  * layout axes.
@@ -30,14 +31,32 @@ export interface LayoutTargets {
     readonly roll: number;
     /** Whether writes are still queued — what makes a caller keep frames coming. */
     readonly hasWork: boolean;
+    /**
+     * Whether a pass is owed because a participant registered, unregistered or was passed to
+     * `update()` since the last one ran.
+     *
+     * The driver also runs a pass when the camera moves, which this does not report: a camera move is
+     * the driver's own observation, not the registry's.
+     */
+    readonly needsPlacement: boolean;
+    /**
+     * Whether a participant's box moved since the last pass, through `update()`.
+     *
+     * The driver runs the pass at once for this, as for {@link needsPlacement}: the verdicts the def
+     * earned were earned at its old position.
+     */
+    readonly placementDrifted: boolean;
     /**
      * Registers defs for re-layout, and lays out and writes the ones that are not current — so a def
      * is current from the moment it is registered, and a membership change re-lays out only what it
      * added.
-     * @param defs - The defs to lay out; every one of them declares an `onScale` or an `onRoll`.
+     * @param layer - The layer registering them, which is what places its participants in a collision
+     *   scope: its own, or the one its {@link LayerDef.collisionGroup} names.
+     * @param defs - The defs to lay out; every one of them declares an `onScale`, an `onRoll` or a
+     *   `placement`.
      * @returns An unregister function; it also drops whatever of these defs a sweep still queued.
      */
-    register(defs: readonly RenderableDef[]): () => void;
+    register(layer: LayerDef, defs: readonly RenderableDef[]): () => void;
     /**
      * Records the new pixel size and runs every registered scale rule against it, queueing what they
      * report changed. Nothing is written here — that is {@link drain}'s job. Applying again before
@@ -52,6 +71,28 @@ export interface LayoutTargets {
      * @param roll - The new roll, in radians clockwise from north.
      */
     applyRoll(roll: number): void;
+    /**
+     * Runs the placement pass over every registered participant and queues what the reports change:
+     * what each `onPlace` returns, then what each clustering layer's `onCluster` returns, through the
+     * same queue — a layer among them is written at once, as from any rule.
+     *
+     * The third `apply*`, and the one that is not an axis: placement depends on the whole camera
+     * rather than on one quantity, so the driver decides when to call this rather than comparing a
+     * number. The pass itself is synchronous and complete; only the writes it produces are budgeted,
+     * through the same queue {@link drain} works off.
+     *
+     * A registered def that no longer participates, because its `placement` was removed or it stopped
+     * being screen-space, is forgotten by the pass: it has no handler left to tell, and forgetting
+     * means that participating again reports its verdict afresh. A caller that removes `placement`
+     * owns restoring the def's appearance: one left shrunk or faded by its last `onPlace(false)`
+     * stays that way, because the handler left with the options and nothing can report to it.
+     *
+     * A known gap follows from the same removal: the defs it was holding down stay stood down, until
+     * something else owes a pass, because removing an option is a plain mutation that notifies
+     * nobody. Their room is free, and nothing re-offers it.
+     * @param context - What the camera shows this pass.
+     */
+    applyPlacement(context: PlacementContext): void;
     /**
      * Writes queued defs within a frame's budget, and says whether any remain — the caller's cue to
      * ask for another frame.
@@ -79,7 +120,8 @@ export interface LayoutTargets {
 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.
+ * declare an `onScale`, an `onRoll` or a `placement`, and the layer itself when it declares a
+ * layout rule.
  *
  * A child *layer* is never registered here even when it declares a handler — it registers itself, and
  * it has to: a handler assigned to a layer after mount re-renders that layer alone, so a registration