@expofp/renderer 0.0.0-experimental.2d6c681

package/dist/space/Space.js

@@ -0,0 +1,359 @@
+import { Point } from '@expofp/geometry';
+import { createContext, use } from 'react';
+import { Matrix4, Plane, Ray, Raycaster, Vector2, Vector3, Vector4, } from 'three';
+import { createLogger } from '../utils/logging';
+import { axisLength, clamp } from '../utils/math';
+import { projectsFromFrustum } from './camera-kind';
+const logger = createLogger('space');
+/**
+ * The scene's space.
+ * @returns The space {@link Scene} published, or the identity one when rendered outside a scene.
+ */
+export function useSpace() {
+    return use(SpaceContext);
+}
+/**
+ * The mapping between the plan's own coordinates and the world the camera is placed in, and the
+ * conversions that ride on it.
+ *
+ * The mapping is one matrix. Without a `staticTransform` it is the **viewbox fit**: centre the
+ * viewbox on the world origin and scale it uniformly to best fill the drawing buffer. That fit is
+ * what makes one world unit one device pixel when the plan exactly fills the canvas, which in turn
+ * is what lets the camera's zoom math be written without reference to the scene at all — see
+ * {@link Camera}.
+ *
+ * With a `staticTransform` the matrix is whatever the caller supplied, and the fit is not computed:
+ * a host like maplibre places the plan itself, in its own space.
+ *
+ * Either way the matrix ends with {@link HANDEDNESS_FLIP}, which is what makes the space three's
+ * rather than the plan's or a host's — a positive elevation then lands nearer the camera.
+ *
+ * **Stable for the scene's lifetime.** A resize does not build a new space — {@link Scene} refits
+ * this one in place — so every holder reads the current fit through the same object and none of
+ * them re-render for it. What makes that safe is a reading discipline: render output must never be
+ * derived from these fields, because no render follows a refit. Read them at the moment of use —
+ * in event handlers, effects and the frame loop, which always run against the current fit. `Scene`
+ * itself is the one exception, and it re-applies the world matrix from the same effect that refits.
+ */
+export class Space {
+    /** Plan → world. */
+    matrix = new Matrix4();
+    /** World → plan. */
+    matrixInverse = new Matrix4();
+    _scale = 1;
+    _isExternal = false;
+    /** The canvas width in css pixels, which the canvas conversions measure against. */
+    width = 0;
+    /** The canvas height in css pixels. */
+    height = 0;
+    /**
+     * @param options - How to map the plan onto the canvas. Omit them entirely for the identity
+     *   space, in which world coordinates already read as plan coordinates; the individual fields are
+     *   not separately optional, because a fit needs all of them.
+     */
+    constructor(options) {
+        if (options)
+            this.refit(options);
+    }
+    /**
+     * World units per plan unit: the geometric mean of the two transformed axes, rather than the
+     * length of one of them.
+     *
+     * Both paths that build a matrix produce a similarity — the fit scales x and y alike, and the
+     * maplibre solver forces uniform scale and no shear — so the two axes agree and the mean is
+     * simply their common length. It differs only for a transform this renderer does not produce, and
+     * there no single number is right anyway: an anisotropic plan covers different amounts of plan per
+     * pixel along each axis, and the mean is the one that preserves area.
+     */
+    get scale() {
+        return this._scale;
+    }
+    /**
+     * Whether an external host placed the plan itself, by supplying a valid `staticTransform`,
+     * rather than this renderer fitting the viewbox to the canvas — external mode, where the host
+     * owns the canvas, the camera and the frames.
+     */
+    get isExternal() {
+        return this._isExternal;
+    }
+    /**
+     * Refits the plan onto the canvas in place, leaving every held reference reading the new fit.
+     * @param options - How to map the plan onto the canvas.
+     */
+    refit(options) {
+        this.width = options.width;
+        this.height = options.height;
+        this._isExternal = this.validateStaticTransform(options.staticTransform);
+        if (this._isExternal) {
+            this.matrix.fromArray(options.staticTransform);
+        }
+        else {
+            const fit = fitScale(options.viewbox, this.width * options.dpr, this.height * options.dpr);
+            const { x: centerX, y: centerY } = options.viewbox.center;
+            // three composes a matrix as T·R·S, so the plan-space translation has to be pre-scaled for the
+            // product to come out as scale∘translate — the order the imperative renderer built it in.
+            this.matrix
+                .makeTranslation(-centerX * fit, -centerY * fit, 0)
+                .scale(new Vector3(fit, fit, fit));
+        }
+        // Both paths land in a host's space or ours; this is what makes either one three's.
+        this.matrix.premultiply(HANDEDNESS_FLIP);
+        this.matrixInverse.copy(this.matrix).invert();
+        this._scale = Math.sqrt(axisLength(this.matrix, 0) * axisLength(this.matrix, 1));
+    }
+    /**
+     * Converts a point from plan to world coordinates.
+     * @param point - The plan-space point; a missing `z` is read as `0`.
+     * @param out - Where to write the result.
+     * @returns The world-space point.
+     */
+    planToWorld(point, out = new Vector3()) {
+        return out.set(point.x, point.y, point.z ?? 0).applyMatrix4(this.matrix);
+    }
+    /**
+     * Converts a point from world to plan coordinates.
+     * @param point - The world-space point.
+     * @param out - Where to write the result.
+     * @returns The plan-space point.
+     */
+    worldToPlan(point, out = new Point()) {
+        _world.set(point.x, point.y, point.z).applyMatrix4(this.matrixInverse);
+        out.set(_world.x, _world.y, _world.z);
+        return out;
+    }
+    /**
+     * Converts a point on the canvas — css pixels from its top-left corner — to normalized device
+     * coordinates, clamped to the canvas.
+     * @param point - The canvas-space point.
+     * @param out - Where to write the result.
+     * @returns The point in normalized device coordinates.
+     */
+    canvasToNdc(point, out = new Vector2()) {
+        if (this.width <= 0 || this.height <= 0) {
+            logger.warn('canvasToNdc: the canvas has no size');
+            return out.set(0, 0);
+        }
+        const x = (point.x / this.width) * 2 - 1;
+        // NDC y grows upward where canvas y grows downward.
+        const y = -(point.y / this.height) * 2 + 1;
+        return out.set(clamp(x, -1, 1), clamp(y, -1, 1));
+    }
+    /**
+     * Where a point in normalized device coordinates lands on the canvas, in css pixels from its
+     * top-left corner.
+     *
+     * **Unclamped, where {@link canvasToNdc} clamps**, and the asymmetry is the point: clamping on the
+     * way in keeps a pointer event on the canvas it was dispatched from, while clamping on the way out
+     * would erase the one thing a caller asking about an off-screen point wants to know.
+     *
+     * No guard on a canvas with no size either, where `canvasToNdc` needs one — this multiplies by the
+     * size where that divides by it, so an unsized canvas gives an honest zero rather than a `NaN`.
+     * @param ndc - The point in normalized device coordinates.
+     * @param out - Where to write the result.
+     * @returns The canvas-space point.
+     */
+    ndcToCanvas(ndc, out = new Point()) {
+        // Canvas y grows downward where NDC y grows upward. Zero elevation, always: a point on the
+        // canvas has none, and an `out` that carried one from an earlier use must not keep it.
+        return out.set(((ndc.x + 1) / 2) * this.width, ((1 - ndc.y) / 2) * this.height, 0);
+    }
+    /**
+     * Where a ray crosses the plan, in plan units.
+     *
+     * The ray is taken into plan space and crossed with plan `z = 0` there, rather than crossed with
+     * the plan's image in world space and converted back. Both agree for the viewbox fit; only this
+     * one stays correct for a `staticTransform` that rotates or lifts the plan off world `z = 0`.
+     * @param ray - The ray, in world space.
+     * @param out - Where to write the result.
+     * @returns The crossing, or `undefined` when the ray runs parallel to the plan.
+     */
+    rayToPlan(ray, out = new Point()) {
+        _ray.copy(ray).applyMatrix4(this.matrixInverse);
+        if (!_ray.intersectPlane(PLAN_PLANE, _world))
+            return undefined;
+        return out.set(_world.x, _world.y, 0);
+    }
+    /**
+     * Where a point in normalized device coordinates lands on the plan.
+     * @param ndc - The point in normalized device coordinates.
+     * @param camera - The camera the canvas is drawn through.
+     * @param out - Where to write the result.
+     * @returns The plan position, or `undefined` when the camera never meets the plan.
+     */
+    ndcToPlan(ndc, camera, out) {
+        castRay(_raycaster, ndc, camera);
+        return this.rayToPlan(_raycaster.ray, out);
+    }
+    /**
+     * Where a point on the plan lands in normalized device coordinates — the inverse of
+     * {@link ndcToPlan}, and the projection every question about "where is this on screen" is built
+     * from.
+     *
+     * Carried through **clip space** rather than through three's `Vector3.project`, which divides by
+     * `w` without looking at its sign: a point behind the camera comes back mirrored through the
+     * origin, and so lands inside the canvas as convincingly as a point in front of it. Reading `w`
+     * first is what separates the two.
+     *
+     * The camera's view offset rides in `projectionMatrix`, so a scene framed inside a `visibleRect`
+     * projects through this with no seam — the same way picking and culling follow it.
+     * @param point - The plan-space point; a missing `z` is read as `0`.
+     * @param camera - The camera the canvas is drawn through.
+     * @param out - Where to write the result.
+     * @returns The point in normalized device coordinates, unclamped, or `undefined` when it sits
+     *   behind the camera and has no image on the canvas at all.
+     */
+    planToNdc(point, camera, out = new Vector2()) {
+        this.planToWorld(point, _projected);
+        _clip
+            .set(_projected.x, _projected.y, _projected.z, 1)
+            .applyMatrix4(camera.matrixWorldInverse)
+            .applyMatrix4(camera.projectionMatrix);
+        if (_clip.w <= 0)
+            return undefined;
+        return out.set(_clip.x / _clip.w, _clip.y / _clip.w);
+    }
+    /**
+     * Where a point on the canvas — css pixels from its top-left corner — lands on the plan.
+     * @param point - The canvas-space point.
+     * @param camera - The camera the canvas is drawn through.
+     * @param out - Where to write the result.
+     * @returns The plan position, or `undefined` when the camera never meets the plan.
+     */
+    canvasToPlan(point, camera, out) {
+        return this.ndcToPlan(this.canvasToNdc(point, _ndc), camera, out);
+    }
+    /**
+     * Where a point on the plan lands on the canvas, in css pixels from its top-left corner — the
+     * inverse of {@link canvasToPlan}, composed from the same two halves the other way round.
+     * @param point - The plan-space point; a missing `z` is read as `0`.
+     * @param camera - The camera the canvas is drawn through.
+     * @param out - Where to write the result.
+     * @returns The canvas position, unclamped, or `undefined` when the point sits behind the camera.
+     */
+    planToCanvas(point, camera, out) {
+        const ndc = this.planToNdc(point, camera, _screen);
+        if (!ndc)
+            return undefined;
+        return this.ndcToCanvas(ndc, out);
+    }
+    /**
+     * Whether a caller supplied a usable plan → world matrix, warning when they supplied an unusable
+     * one rather than silently falling back.
+     * @param staticTransform - What the caller supplied, if anything.
+     * @returns Whether it should be used as the matrix.
+     */
+    validateStaticTransform(staticTransform) {
+        if (staticTransform === undefined)
+            return false;
+        if (staticTransform.length !== 16) {
+            logger.warn(`staticTransform must be 16 elements long, got ${staticTransform.length}`);
+            return false;
+        }
+        return true;
+    }
+}
+/**
+ * The scale that fits a viewbox inside a drawing buffer, contain-style: the constraining axis fills
+ * and the other one keeps slack.
+ *
+ * Exported because it is also what tells a caller how large the plan is drawn: `VisibleRect` needs
+ * the plan's footprint in device pixels, and deriving it from this rather than from `Space.scale`
+ * keeps it free of the commit-ordering hazard the class documents — the fit is a function of the
+ * props it already holds.
+ * @param viewbox - The region to frame, in plan units.
+ * @param bufferWidth - The drawing buffer's width in device pixels.
+ * @param bufferHeight - The drawing buffer's height in device pixels.
+ * @returns World units per plan unit, or `1` while either is degenerate.
+ */
+export function fitScale(viewbox, bufferWidth, bufferHeight) {
+    const { width, height } = viewbox.size;
+    if (width <= 0 || height <= 0 || bufferWidth <= 0 || bufferHeight <= 0)
+        return 1;
+    return Math.min(bufferWidth / width, bufferHeight / height);
+}
+/**
+ * The scene's space, published by {@link Scene}. The default is the identity space, so a component
+ * rendered without one still converts — it just converts nothing.
+ */
+export const SpaceContext = createContext(new Space());
+/**
+ * Points a raycaster from a camera through a point in normalized device coordinates.
+ *
+ * The fallback is for a camera whose projection was handed to it rather than derived from a frustum
+ * — an external host like maplibre supplies one — which three's own `setFromCamera` refuses. It unprojects the
+ * same screen point on the near and far planes; both lie on the true ray whatever the matrix folds,
+ * where anchoring the origin at the eye would need a camera transform such a camera does not carry.
+ *
+ * Exported for the external event system, which must aim R3F's raycaster the same way; the space's own
+ * conversions go through the module's private raycaster.
+ * @param raycaster - The raycaster to aim.
+ * @param ndc - The point in normalized device coordinates.
+ * @param camera - The camera to cast from.
+ */
+export function castRay(raycaster, ndc, camera) {
+    if (projectsFromFrustum(camera)) {
+        raycaster.setFromCamera(_cast.set(ndc.x, ndc.y), camera);
+        return;
+    }
+    raycaster.ray.origin.set(ndc.x, ndc.y, -1).unproject(camera);
+    raycaster.ray.direction
+        .set(ndc.x, ndc.y, 1)
+        .unproject(camera)
+        .sub(raycaster.ray.origin)
+        .normalize();
+}
+/**
+ * The last step of both paths into world space: mirror z.
+ *
+ * Plan space is left-handed — x right, y **down**, z up — where three's world is right-handed, so
+ * one axis has to flip and z is it: the plan's up is world `-z`, the side the camera is on.
+ *
+ * The flip belongs in the plan → world matrix and nowhere else. three reads a face's winding from
+ * that matrix's determinant alone (`matrixWorld.determinantAffine() < 0`) and never from the
+ * projection, so a reflection anywhere else is invisible to it: every `DoubleSide` lit surface
+ * negates its normal and shades from behind.
+ *
+ * **Assumes a host's world shares the plan's handedness**, which mercator does — x east, y south,
+ * z up — resolving the clash inside its own projection instead (`MercatorTransform._calcMatrices`
+ * scales by `[1, -1, 1]`). So the same flip serves both paths, and external mode undoes it on the
+ * host's own matrix (`setExternalCameraProjection`). A host with a right-handed world would
+ * need it skipped on both — a `leftHandedWorld` flag on the external contract is where that choice
+ * would go.
+ */
+export const HANDEDNESS_FLIP = new Matrix4().makeScale(1, 1, -1);
+/**
+ * The plan's y-down convention, mirrored for a consumer that reads y as up.
+ *
+ * One value, two unrelated roles. In `ImageInstance.tsx` it is the plan-to-view y mirror composed
+ * into a screen-space quad's own 2D linear map, so the quad's offset reads correctly once the
+ * shader plants it in the view basis. In `MemberTexture.ts` it is the camera's own rest pose
+ * relative to the plan. Its job there is to stop that pose being applied twice, once baked into a
+ * member's own matrix and once more by the ordinary view transform at draw time. That role does
+ * not depend on the sign of a member's own `scale.y`. The requirement is that the billboard matrix
+ * equal the flat matrix at the rest pose, and the scale cancels from both sides of that equality.
+ *
+ * The two roles share a value by coincidence of geometry, not by a shared derivation. Check both
+ * call sites before changing this constant for either reason.
+ */
+export const Y_DOWN_FLIP = new Matrix4().makeScale(1, -1, 1);
+/** The plan's own plane in plan space, which every pointer position is reported on. */
+const PLAN_PLANE = new Plane(new Vector3(0, 0, 1), 0);
+/**
+ * One raycaster for the module, not one per space and deliberately not R3F's.
+ *
+ * `Space` is React-free, so it cannot reach `state.raycaster`; and it should not, because R3F sets
+ * that one up for the pointer event it is dispatching — a coordinate query that overwrote its ray
+ * mid-dispatch would corrupt the hit test in flight.
+ */
+const _raycaster = new Raycaster();
+const _ray = new Ray();
+const _ndc = new Vector2();
+/** The screen point {@link castRay} hands three's `setFromCamera`. */
+const _cast = new Vector2();
+const _world = new Vector3();
+/** The world point {@link Space.planToNdc} projects, kept apart from `_world` so the two never alias. */
+const _projected = new Vector3();
+/** Where that projection lands before the perspective divide, which is where `w` can still be read. */
+const _clip = new Vector4();
+/** The projected point {@link Space.planToCanvas} hands on to {@link Space.ndcToCanvas}. */
+const _screen = new Vector2();

package/dist/space/VisibleRect.d.ts

@@ -0,0 +1,45 @@
+import { type Box } from '@expofp/geometry';
+/** Props for {@link VisibleRect}. */
+export interface VisibleRectProps {
+    /**
+     * The part of the canvas the plan should be framed inside, in css pixels from the canvas's
+     * top-left corner.
+     *
+     * Required, because there is no such thing as this component with nothing to do: a caller who
+     * named no rect does not render it at all, which is what keeps the default path free of a
+     * component whose every effect would return early.
+     */
+    rect: Box;
+    /** The scene's viewbox, in plan units: what "the plan fits" is measured against. */
+    viewbox: Box;
+}
+/**
+ * Frames the plan inside a sub-region of the canvas, for a host whose own UI covers the rest.
+ *
+ * **The plan is still drawn across the whole canvas.** Nothing is clipped and nothing is cropped:
+ * the frustum is *expanded*, so the strips behind a header or a bottom sheet show more of the plan
+ * than they would otherwise, while the viewbox itself is guaranteed to land inside the clear
+ * region. That is the point of doing this in the projection rather than with `gl.viewport`.
+ *
+ * **Two calls, and nothing else in the renderer knows.** The transform is a uniform scale and a
+ * translate in clip space, which is exactly what {@link PerspectiveCamera.setViewOffset} expresses
+ * when its virtual screen is *smaller* than the rendered window — the reverse of the tiled-render
+ * case it is usually reached for. Because it lands in `projectionMatrix`, picking, R3F's pointer
+ * events, frustum culling, `Space`'s coordinate conversions and the pixel-size measurement all follow it with
+ * no seam: three re-derives `view` inside every `updateProjectionMatrix()`, so it also survives
+ * R3F's per-resize `aspect` write and `Camera`'s near and far updates.
+ *
+ * The second call is for `camera-controls`, which is the one thing that does *not* read the
+ * projection: it converts a pixel drag to a world offset through `fov` and the element's height,
+ * and finds the cursor's world position for `dollyToCursor` the same way. `setViewport` exists for
+ * exactly that — it tells the controls which part of the element the image occupies — and handed
+ * the landing box it makes every one of those conversions correct, with no fork patch and no
+ * speed fudge. The box keeps the canvas's aspect by construction, which is what leaves
+ * `camera.aspect` right inside the `dollyToCursor` arithmetic.
+ *
+ * **The scale is measured against the plan, not the canvas** — see {@link framingScale}.
+ * @param props - Where to frame the plan, and what to measure the framing against.
+ * @returns Nothing; this renders no scene node.
+ */
+export declare function VisibleRect(props: VisibleRectProps): null;
+//# sourceMappingURL=VisibleRect.d.ts.map

package/dist/space/VisibleRect.js

@@ -0,0 +1,129 @@
+import { useThree } from '@react-three/fiber';
+import { useLayoutEffect } from 'react';
+import { useCameraControls } from '../controls';
+import { isPerspective } from './camera-kind';
+import { useCanvasSize } from './canvas-size';
+import { fitScale } from './Space';
+/**
+ * Frames the plan inside a sub-region of the canvas, for a host whose own UI covers the rest.
+ *
+ * **The plan is still drawn across the whole canvas.** Nothing is clipped and nothing is cropped:
+ * the frustum is *expanded*, so the strips behind a header or a bottom sheet show more of the plan
+ * than they would otherwise, while the viewbox itself is guaranteed to land inside the clear
+ * region. That is the point of doing this in the projection rather than with `gl.viewport`.
+ *
+ * **Two calls, and nothing else in the renderer knows.** The transform is a uniform scale and a
+ * translate in clip space, which is exactly what {@link PerspectiveCamera.setViewOffset} expresses
+ * when its virtual screen is *smaller* than the rendered window — the reverse of the tiled-render
+ * case it is usually reached for. Because it lands in `projectionMatrix`, picking, R3F's pointer
+ * events, frustum culling, `Space`'s coordinate conversions and the pixel-size measurement all follow it with
+ * no seam: three re-derives `view` inside every `updateProjectionMatrix()`, so it also survives
+ * R3F's per-resize `aspect` write and `Camera`'s near and far updates.
+ *
+ * The second call is for `camera-controls`, which is the one thing that does *not* read the
+ * projection: it converts a pixel drag to a world offset through `fov` and the element's height,
+ * and finds the cursor's world position for `dollyToCursor` the same way. `setViewport` exists for
+ * exactly that — it tells the controls which part of the element the image occupies — and handed
+ * the landing box it makes every one of those conversions correct, with no fork patch and no
+ * speed fudge. The box keeps the canvas's aspect by construction, which is what leaves
+ * `camera.aspect` right inside the `dollyToCursor` arithmetic.
+ *
+ * **The scale is measured against the plan, not the canvas** — see {@link framingScale}.
+ * @param props - Where to frame the plan, and what to measure the framing against.
+ * @returns Nothing; this renders no scene node.
+ */
+export function VisibleRect(props) {
+    const { rect, viewbox } = props;
+    const invalidate = useThree((state) => state.invalidate);
+    // Held rather than identified. `Camera` keeps only its camera's uuid because it *assigns* to
+    // fields of it and the React Compiler refuses to lower that; everything here is a method call,
+    // which the compiler is content with — so the dependency can be the camera itself and the effect
+    // needs no second read to find it.
+    const camera = useThree((state) => state.camera);
+    const controls = useCameraControls();
+    const { width, height, dpr } = useCanvasSize();
+    // Derived during render and depended on as three numbers, so a caller handing over a fresh `Box`
+    // each render — a MobX computed, say — does not re-place the framing for an unchanged rect.
+    const scale = framingScale(rect, viewbox, width, height, dpr);
+    const centerX = rect.center.x;
+    const centerY = rect.center.y;
+    useLayoutEffect(() => {
+        if (!isPerspective(camera))
+            return undefined;
+        if (width <= 0 || height <= 0)
+            return undefined;
+        // Nothing to place: a rect the plan already fills, sat in the middle of the canvas, works out to
+        // the identity, and leaving the camera untouched says so.
+        if (scale === 1 && centerX === width / 2 && centerY === height / 2)
+            return undefined;
+        placeFraming(camera, controls, scale, centerX, centerY, width, height);
+        invalidate();
+        return () => {
+            camera.clearViewOffset();
+            controls?.setViewport(null, 0, 0, 0);
+            invalidate();
+        };
+    }, [scale, centerX, centerY, width, height, camera, controls, invalidate]);
+    return null;
+}
+/**
+ * How far the plan has to shrink to fit inside the rect: `1` when it already does.
+ *
+ * **Measured against the plan's own footprint, not the canvas's.** Fitting the canvas into the rect
+ * would compose two contain-fits — plan into canvas, then canvas into rect — and a product of two
+ * independent minima is not the minimum the imperative renderer took over the same pair. The two
+ * agree only when the same axis binds both, and disagree in the commonest configuration there is: a
+ * wide hall on a portrait phone, where the plan already fits the clear band and fitting the canvas
+ * into it would shrink the plan by two thirds for nothing.
+ *
+ * Measured against the plan, the factorization telescopes back to what the imperative renderer
+ * computed in one step:
+ *
+ * ```
+ * fitScale · framingScale = min(W/a, H/b) · min(w/(a·fit), h/(b·fit)) = min(w/a, h/b)
+ * ```
+ *
+ * The clamp only guards a rect larger than the canvas; for a rect inside it the result is already
+ * at most `1`, because the fit leaves the plan touching at least one edge.
+ * @param rect - The region to frame the plan inside, in css pixels.
+ * @param viewbox - The scene's viewbox, in plan units.
+ * @param width - The canvas width in css pixels.
+ * @param height - The canvas height in css pixels.
+ * @param dpr - Device pixels per css pixel.
+ * @returns The scale, in `(0, 1]`.
+ */
+function framingScale(rect, viewbox, width, height, dpr) {
+    const fit = fitScale(viewbox, width * dpr, height * dpr);
+    // The plan's footprint on the canvas at zoom 1, in device pixels — the viewbox fit sizes one
+    // world unit to one device pixel, so this is the viewbox scaled and nothing more.
+    const planWidth = viewbox.size.width * fit;
+    const planHeight = viewbox.size.height * fit;
+    if (!(planWidth > 0) || !(planHeight > 0))
+        return 1;
+    return Math.min((rect.size.width * dpr) / planWidth, (rect.size.height * dpr) / planHeight, 1);
+}
+/**
+ * Writes the framing onto the camera and the controls.
+ *
+ * A function taking both rather than two statements in the effect, which is what lets the caller
+ * hold the controls from a hook: the React Compiler rejects a write to a *field of* a hook's return
+ * value and is content once that value is an argument someone else was passed.
+ *
+ * The camera call reads: the natural frustum maps to a virtual screen of `scale · canvas` css
+ * pixels, positioned so its centre lands on the rect's centre, and the canvas is the window onto
+ * it. The controls call names the same box in the element's own coordinates, `y` measured from the
+ * bottom as `setViewport` takes it.
+ * @param camera - The camera to place the framing on.
+ * @param controls - The scene's controls, when they have mounted.
+ * @param scale - How far the plan shrinks; see {@link framingScale}.
+ * @param centerX - The rect's centre, in css pixels from the canvas's left edge.
+ * @param centerY - The rect's centre, in css pixels from the canvas's top edge.
+ * @param width - The canvas width in css pixels.
+ * @param height - The canvas height in css pixels.
+ */
+function placeFraming(camera, controls, scale, centerX, centerY, width, height) {
+    const boxWidth = scale * width;
+    const boxHeight = scale * height;
+    camera.setViewOffset(boxWidth, boxHeight, boxWidth / 2 - centerX, boxHeight / 2 - centerY, width, height);
+    controls?.setViewport(centerX - boxWidth / 2, height - boxHeight / 2 - centerY, boxWidth, boxHeight);
+}

package/dist/space/camera-handle.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The camera's zoom, as the rest of the renderer asks about it.
+ *
+ * Zoom is a factor, not a distance: `1` frames the scene's viewbox exactly, `2` shows half of it.
+ * The camera stores a distance, and the two convert through the buffer height — which is why this
+ * is a handle published by {@link Camera} rather than arithmetic a caller could do itself.
+ */
+export interface CameraHandle {
+    /** The zoom factor the camera is currently at. */
+    readonly zoomFactor: number;
+    /**
+     * The camera distance that shows the plan at a zoom factor.
+     * @param zoomFactor - The factor to convert.
+     * @returns The distance in world units.
+     */
+    zoomFactorToDistance(zoomFactor: number): number;
+    /**
+     * The zoom factor a camera distance shows the plan at.
+     * @param distance - The distance in world units.
+     * @returns The factor.
+     */
+    distanceToZoomFactor(distance: number): number;
+}
+/** The scene's camera handle, published by {@link Camera}. */
+export declare const CameraContext: import("react").Context<CameraHandle | undefined>;
+/**
+ * The scene's camera handle, once {@link Camera} has published it.
+ * @returns The handle, or `undefined` when rendered outside a scene.
+ */
+export declare function useCamera(): CameraHandle | undefined;
+/**
+ * The zoom handle {@link Camera} publishes.
+ *
+ * A plain object rather than anything reactive: every member is derived from the buffer height it
+ * was built against and whatever the camera holds when it is asked, so there is no state here to go
+ * stale — only a factor and the two conversions that turn it into a distance and back.
+ *
+ * Takes a reading rather than the canvas state: the one live number it needs is how far the camera
+ * is from the plan, and asking for that instead of for the store keeps this file pure arithmetic —
+ * with no view on where a distance comes from, and nothing to import from `controls`.
+ * @param bufferHeight - The drawing buffer's height in device pixels.
+ * @param getDistance - How far the camera currently is from the plan, in world units, read at the
+ *   moment of asking.
+ * @returns The handle.
+ */
+export declare function createCameraHandle(bufferHeight: number, getDistance: () => number): CameraHandle;
+/**
+ * The camera distance at which the drawing buffer's height covers exactly that many world units —
+ * zoom factor `1`.
+ *
+ * Paired with the viewbox fit, which sizes a world unit to a device pixel, this is what "the plan
+ * fills the canvas" means as a number.
+ * @param bufferHeight - The drawing buffer's height in device pixels.
+ * @param fov - The camera's vertical field of view in degrees.
+ * @returns The distance in world units, or `0` while the buffer has no height.
+ */
+export declare function zoomIdentityDistance(bufferHeight: number, fov: number): number;
+/**
+ * The camera's vertical field of view, in degrees — `2·atan(1/3)`, the value the imperative renderer
+ * took from Mapbox.
+ *
+ * Narrow on purpose. The plan is laid out against a single pixel-to-plan factor per frame (see
+ * `readPixelSize`), which under perspective is only ever an approximation across a tilted view; the
+ * narrower the field, the closer that approximation holds.
+ */
+export declare const CAMERA_FOV = 36.87;
+//# sourceMappingURL=camera-handle.d.ts.map

package/dist/space/camera-handle.js

@@ -0,0 +1,63 @@
+import { degToRad } from '@expofp/geometry';
+import { createContext, use } from 'react';
+/** The scene's camera handle, published by {@link Camera}. */
+export const CameraContext = createContext(undefined);
+/**
+ * The scene's camera handle, once {@link Camera} has published it.
+ * @returns The handle, or `undefined` when rendered outside a scene.
+ */
+export function useCamera() {
+    return use(CameraContext);
+}
+/**
+ * The zoom handle {@link Camera} publishes.
+ *
+ * A plain object rather than anything reactive: every member is derived from the buffer height it
+ * was built against and whatever the camera holds when it is asked, so there is no state here to go
+ * stale — only a factor and the two conversions that turn it into a distance and back.
+ *
+ * Takes a reading rather than the canvas state: the one live number it needs is how far the camera
+ * is from the plan, and asking for that instead of for the store keeps this file pure arithmetic —
+ * with no view on where a distance comes from, and nothing to import from `controls`.
+ * @param bufferHeight - The drawing buffer's height in device pixels.
+ * @param getDistance - How far the camera currently is from the plan, in world units, read at the
+ *   moment of asking.
+ * @returns The handle.
+ */
+export function createCameraHandle(bufferHeight, getDistance) {
+    const identity = zoomIdentityDistance(bufferHeight, CAMERA_FOV);
+    const toZoomFactor = (distance) => identity > 0 && distance > 0 ? identity / distance : 1;
+    return {
+        get zoomFactor() {
+            return toZoomFactor(getDistance());
+        },
+        zoomFactorToDistance(zoomFactor) {
+            return zoomFactor > 0 ? identity / zoomFactor : identity;
+        },
+        distanceToZoomFactor: toZoomFactor,
+    };
+}
+/**
+ * The camera distance at which the drawing buffer's height covers exactly that many world units —
+ * zoom factor `1`.
+ *
+ * Paired with the viewbox fit, which sizes a world unit to a device pixel, this is what "the plan
+ * fills the canvas" means as a number.
+ * @param bufferHeight - The drawing buffer's height in device pixels.
+ * @param fov - The camera's vertical field of view in degrees.
+ * @returns The distance in world units, or `0` while the buffer has no height.
+ */
+export function zoomIdentityDistance(bufferHeight, fov) {
+    if (bufferHeight <= 0)
+        return 0;
+    return bufferHeight / 2 / Math.tan(degToRad(fov) / 2);
+}
+/**
+ * The camera's vertical field of view, in degrees — `2·atan(1/3)`, the value the imperative renderer
+ * took from Mapbox.
+ *
+ * Narrow on purpose. The plan is laid out against a single pixel-to-plan factor per frame (see
+ * `readPixelSize`), which under perspective is only ever an approximation across a tilted view; the
+ * narrower the field, the closer that approximation holds.
+ */
+export const CAMERA_FOV = 36.87;