@expofp/renderer 0.0.0-experimental.2d6c681

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

@@ -0,0 +1,26 @@
+import { type Camera, type OrthographicCamera, type PerspectiveCamera } from 'three';
+/**
+ * Whether a camera projects perspectively.
+ *
+ * Three's own `isPerspectiveCamera` brand rather than `instanceof`, so a camera from a second copy
+ * of three — a host's, under external mode — answers the same as one of ours.
+ * @param camera - The camera to test.
+ * @returns Whether it is a perspective camera.
+ */
+export declare function isPerspective(camera: Camera): camera is PerspectiveCamera;
+/**
+ * Whether a camera projects orthographically.
+ * @param camera - The camera to test.
+ * @returns Whether it is an orthographic camera.
+ */
+export declare function isOrthographic(camera: Camera): camera is OrthographicCamera;
+/**
+ * Whether a camera derives its own projection from a frustum, rather than carrying one handed to it.
+ *
+ * The question three's `Raycaster.setFromCamera` asks before it refuses a camera, and the one
+ * `Camera.tsx` and `VisibleRect.tsx` ask before writing frustum fields nothing else has.
+ * @param camera - The camera to test.
+ * @returns Whether it projects either standard way.
+ */
+export declare function projectsFromFrustum(camera: Camera): boolean;
+//# sourceMappingURL=camera-kind.d.ts.map

package/dist/space/camera-kind.js

@@ -0,0 +1,30 @@
+/**
+ * Whether a camera projects perspectively.
+ *
+ * Three's own `isPerspectiveCamera` brand rather than `instanceof`, so a camera from a second copy
+ * of three — a host's, under external mode — answers the same as one of ours.
+ * @param camera - The camera to test.
+ * @returns Whether it is a perspective camera.
+ */
+export function isPerspective(camera) {
+    return camera.isPerspectiveCamera === true;
+}
+/**
+ * Whether a camera projects orthographically.
+ * @param camera - The camera to test.
+ * @returns Whether it is an orthographic camera.
+ */
+export function isOrthographic(camera) {
+    return camera.isOrthographicCamera === true;
+}
+/**
+ * Whether a camera derives its own projection from a frustum, rather than carrying one handed to it.
+ *
+ * The question three's `Raycaster.setFromCamera` asks before it refuses a camera, and the one
+ * `Camera.tsx` and `VisibleRect.tsx` ask before writing frustum fields nothing else has.
+ * @param camera - The camera to test.
+ * @returns Whether it projects either standard way.
+ */
+export function projectsFromFrustum(camera) {
+    return isPerspective(camera) || isOrthographic(camera);
+}

package/dist/space/canvas-size.d.ts

@@ -0,0 +1,24 @@
+/** How large the canvas is, and how densely it draws. */
+export interface CanvasSize {
+    /** Width in css pixels. */
+    readonly width: number;
+    /** Height in css pixels. */
+    readonly height: number;
+    /** Device pixels per css pixel. Multiply by it for drawing-buffer sizes. */
+    readonly dpr: number;
+}
+/**
+ * The canvas's size, subscribed to one number at a time.
+ *
+ * Never read `state.size` as an object. R3F re-runs its canvas configuration on every render of the
+ * `<Canvas>` element and replaces that object as it goes, dimensions unchanged or not — so a
+ * component selecting it re-renders on renders that changed nothing, and anything memoized against
+ * it is rebuilt. Selecting the numbers is immune, because the numbers only move when the canvas
+ * really does.
+ *
+ * The returned object is a fresh literal, which costs nothing: it is not what the subscription
+ * compares, and the React Compiler keeps its identity stable across renders where the numbers hold.
+ * @returns The canvas's css size and device pixel ratio.
+ */
+export declare function useCanvasSize(): CanvasSize;
+//# sourceMappingURL=canvas-size.d.ts.map

package/dist/space/canvas-size.js

@@ -0,0 +1,20 @@
+import { useThree } from '@react-three/fiber';
+/**
+ * The canvas's size, subscribed to one number at a time.
+ *
+ * Never read `state.size` as an object. R3F re-runs its canvas configuration on every render of the
+ * `<Canvas>` element and replaces that object as it goes, dimensions unchanged or not — so a
+ * component selecting it re-renders on renders that changed nothing, and anything memoized against
+ * it is rebuilt. Selecting the numbers is immune, because the numbers only move when the canvas
+ * really does.
+ *
+ * The returned object is a fresh literal, which costs nothing: it is not what the subscription
+ * compares, and the React Compiler keeps its identity stable across renders where the numbers hold.
+ * @returns The canvas's css size and device pixel ratio.
+ */
+export function useCanvasSize() {
+    const width = useThree((state) => state.size.width);
+    const height = useThree((state) => state.size.height);
+    const dpr = useThree((state) => state.viewport.dpr);
+    return { width, height, dpr };
+}

package/dist/space/clipping.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The steepest the plan may **ever** be pitched away from face-on, in degrees.
+ *
+ * A hard cap, not a setting. The near plane below is sized against this angle: pitching the camera
+ * foreshortens an elevation along the view axis, and this is the steepest view the depth guarantee
+ * must survive, so a steeper view is one it never allowed for. `Camera` clamps `maxPitch` to it,
+ * and defaults to it.
+ *
+ * Deliberately **not** what the polygon offsets in `objects/materials` are sized against, though the
+ * imperative renderer's were (`⌈tan(maxPolarAngle)⌉`): a slope-scaled `polygonOffsetFactor` reads
+ * the actual slope per draw, so no worst-case angle enters that calculation — see `sharedParams`.
+ *
+ * In degrees, like every pitch the renderer's API talks about; the cosine the arithmetic actually
+ * wants is {@link MIN_PITCH_COSINE}, so the conversion happens once, here, and nowhere else.
+ *
+ * The imperative renderer's own limit, and the angle its depth guarantee was stated against.
+ */
+export declare const MAX_PITCH = 85;
+/**
+ * The near clipping plane that keeps depth precision at the plan constant as the camera dollies.
+ *
+ * Two constraints set it, and the larger wins so precision is never traded away for headroom:
+ *
+ * - **Headroom.** `distance × (1 − HEADROOM_RATIO)`. Dominates at close and default zoom, where it
+ *   keeps the near plane a fixed fraction of the way to the plan and precision is already better
+ *   than asked for.
+ * - **Precision.** `distance² / (levels × precision)`, the distance a depth buffer of that many
+ *   levels can still resolve at the plan. Dominates far out, where it buys the guarantee back at
+ *   the cost of some headroom.
+ *
+ * The guarantee is stated in **plan** units — see {@link ELEVATION_PRECISION} — so it is scaled
+ * into world units before the depth buffer is asked about it. The imperative renderer did not do
+ * that: it applied the plan-unit constant to world distances, which quietly loosened the guarantee
+ * on any plan drawn smaller than world scale. On a 60 000-unit plan in a 1600-pixel buffer that is a
+ * factor of 2.7 at default zoom, enough for two surfaces separated by exactly the documented minimum
+ * to z-fight.
+ *
+ * Sized against {@link MAX_PITCH} rather than against whatever pitch a scene currently allows, which
+ * is the conservative choice on purpose: the worst case is the only one that is always true, and a
+ * near plane computed from the pitch *in force* would have to be recomputed whenever that moved and
+ * would silently weaken the guarantee wherever nothing was enforcing a limit at all. What it costs
+ * is headroom, and only in the regime where {@link MIN_HEADROOM_RATIO} has already capped it.
+ * @param distance - Camera distance to the plan, in world units.
+ * @param scale - World units per plan unit, from the scene's {@link Space}.
+ * @returns The near plane in world units, or `undefined` while the camera sits on the plan.
+ */
+export declare function nearPlane(distance: number, scale: number): number | undefined;
+/**
+ * The far plane for a camera that may pull back that far, with a factor of two spare so content
+ * behind the plan — anything at a negative elevation — is not clipped at full zoom-out.
+ * @param maxDistance - The furthest the camera may get from the plan, in world units.
+ * @returns The far plane in world units.
+ */
+export declare function farPlane(maxDistance: number): number;
+/**
+ * {@link ELEVATION_PRECISION} in the world units everything downstream of the scene's space works
+ * in: the least separation at which two surfaces still draw in a defined order.
+ *
+ * Every reader of the constant needs it this way round, which is why the conversion lives here
+ * rather than at each of them. The near plane sizes the depth buffer against it, `occludeHits` keeps
+ * a hit that near behind an occluder because the occluder is drawn *on* it rather than in front of
+ * it, and `orderCoplanarHits` treats two hits that near as one depth the buffer never separated — so
+ * a tuning of the constant moves picking and drawing together, which is the only way the two can
+ * agree.
+ * @param scale - World units per plan unit, from the scene's {@link Space}.
+ * @returns The separation in world units.
+ */
+export declare function depthSeparation(scale: number): number;
+//# sourceMappingURL=clipping.d.ts.map

package/dist/space/clipping.js

@@ -0,0 +1,130 @@
+/**
+ * Where the camera's frustum begins and ends.
+ *
+ * Both planes answer the same question from opposite sides — what the camera can still draw — and
+ * they are set on different clocks: the near plane follows the camera's distance, every frame it
+ * moves, because that is what depth precision at the plan depends on; the far plane is fixed by how
+ * far the zoom bounds let the camera retreat, so it changes only when those do.
+ */
+import { degToRad } from '@expofp/geometry';
+/**
+ * The steepest the plan may **ever** be pitched away from face-on, in degrees.
+ *
+ * A hard cap, not a setting. The near plane below is sized against this angle: pitching the camera
+ * foreshortens an elevation along the view axis, and this is the steepest view the depth guarantee
+ * must survive, so a steeper view is one it never allowed for. `Camera` clamps `maxPitch` to it,
+ * and defaults to it.
+ *
+ * Deliberately **not** what the polygon offsets in `objects/materials` are sized against, though the
+ * imperative renderer's were (`⌈tan(maxPolarAngle)⌉`): a slope-scaled `polygonOffsetFactor` reads
+ * the actual slope per draw, so no worst-case angle enters that calculation — see `sharedParams`.
+ *
+ * In degrees, like every pitch the renderer's API talks about; the cosine the arithmetic actually
+ * wants is {@link MIN_PITCH_COSINE}, so the conversion happens once, here, and nowhere else.
+ *
+ * The imperative renderer's own limit, and the angle its depth guarantee was stated against.
+ */
+export const MAX_PITCH = 85;
+/**
+ * The near clipping plane that keeps depth precision at the plan constant as the camera dollies.
+ *
+ * Two constraints set it, and the larger wins so precision is never traded away for headroom:
+ *
+ * - **Headroom.** `distance × (1 − HEADROOM_RATIO)`. Dominates at close and default zoom, where it
+ *   keeps the near plane a fixed fraction of the way to the plan and precision is already better
+ *   than asked for.
+ * - **Precision.** `distance² / (levels × precision)`, the distance a depth buffer of that many
+ *   levels can still resolve at the plan. Dominates far out, where it buys the guarantee back at
+ *   the cost of some headroom.
+ *
+ * The guarantee is stated in **plan** units — see {@link ELEVATION_PRECISION} — so it is scaled
+ * into world units before the depth buffer is asked about it. The imperative renderer did not do
+ * that: it applied the plan-unit constant to world distances, which quietly loosened the guarantee
+ * on any plan drawn smaller than world scale. On a 60 000-unit plan in a 1600-pixel buffer that is a
+ * factor of 2.7 at default zoom, enough for two surfaces separated by exactly the documented minimum
+ * to z-fight.
+ *
+ * Sized against {@link MAX_PITCH} rather than against whatever pitch a scene currently allows, which
+ * is the conservative choice on purpose: the worst case is the only one that is always true, and a
+ * near plane computed from the pitch *in force* would have to be recomputed whenever that moved and
+ * would silently weaken the guarantee wherever nothing was enforcing a limit at all. What it costs
+ * is headroom, and only in the regime where {@link MIN_HEADROOM_RATIO} has already capped it.
+ * @param distance - Camera distance to the plan, in world units.
+ * @param scale - World units per plan unit, from the scene's {@link Space}.
+ * @returns The near plane in world units, or `undefined` while the camera sits on the plan.
+ */
+export function nearPlane(distance, scale) {
+    if (distance <= 0)
+        return undefined;
+    // Pitching the camera foreshortens an elevation along the view axis, so the separation the depth
+    // buffer actually sees is the plan one times the cosine.
+    const precision = depthSeparation(scale) * MIN_PITCH_COSINE;
+    const near = (distance * distance) / (DEPTH_BUFFER_LEVELS * precision);
+    return Math.min(Math.max(near, distance * (1 - HEADROOM_RATIO)), distance * (1 - MIN_HEADROOM_RATIO));
+}
+/**
+ * The far plane for a camera that may pull back that far, with a factor of two spare so content
+ * behind the plan — anything at a negative elevation — is not clipped at full zoom-out.
+ * @param maxDistance - The furthest the camera may get from the plan, in world units.
+ * @returns The far plane in world units.
+ */
+export function farPlane(maxDistance) {
+    return Math.max(maxDistance, 0.1) * 2;
+}
+/**
+ * {@link ELEVATION_PRECISION} in the world units everything downstream of the scene's space works
+ * in: the least separation at which two surfaces still draw in a defined order.
+ *
+ * Every reader of the constant needs it this way round, which is why the conversion lives here
+ * rather than at each of them. The near plane sizes the depth buffer against it, `occludeHits` keeps
+ * a hit that near behind an occluder because the occluder is drawn *on* it rather than in front of
+ * it, and `orderCoplanarHits` treats two hits that near as one depth the buffer never separated — so
+ * a tuning of the constant moves picking and drawing together, which is the only way the two can
+ * agree.
+ * @param scale - World units per plan unit, from the scene's {@link Space}.
+ * @returns The separation in world units.
+ */
+export function depthSeparation(scale) {
+    return ELEVATION_PRECISION * scale;
+}
+/**
+ * Minimum z-axis separation between overlapping surfaces, in **plan** units. Picking reads it too,
+ * through {@link depthSeparation}: geometry closer than this to a hit is drawn on it rather than in
+ * front of it, so it does not occlude it, and two hits this close are one depth the buffer never
+ * ordered, so the pointer takes whichever of them draws last.
+ *
+ * **For plan data providers:** shapes sharing an x/y footprint — an elevated platform over a floor
+ * area, layered decorations at one position — must be separated by at least this much on z to be
+ * ordered correctly. No minimum horizontal separation is required: screen-pixel density and depth
+ * precision both scale with camera distance and with the scene's scale, so any separation visible on
+ * screen already has depth margin, at any viewport size, zoom, scale or camera rotation.
+ *
+ * Deliberately the renderer's own constant rather than `@expofp/geometry`'s `ELEVATION_TOLERANCE`,
+ * which happens to hold the same number. They answer different questions — geometry's is "are these
+ * two elevations the same point?", this one is "must these two elevations still draw in the right
+ * order?" — and importing it would let a tuning of the geometry predicate silently re-tune the depth
+ * buffer.
+ *
+ * Unexported: every reader wants it scaled, so {@link depthSeparation} is the way out of this module
+ * and this stays the one place the plan-unit figure is written down.
+ */
+const ELEVATION_PRECISION = 0.1;
+/**
+ * Fraction of the camera's distance kept clear of the near plane at close and default zoom, so
+ * depth-buffer levels are not spent on the empty space between the camera and the plan.
+ */
+const HEADROOM_RATIO = 0.98;
+/**
+ * Least headroom the precision constraint may leave. Without it a plan drawn very small — a viewbox
+ * hundreds of times the buffer — asks for a near plane beyond the camera's own target and blanks the
+ * canvas. Past this point precision degrades instead, which is visible only where two surfaces are
+ * within the documented minimum of each other.
+ */
+const MIN_HEADROOM_RATIO = 0.5;
+/** 24-bit depth buffer: 2²⁴ discrete levels, which covers 99%+ of devices. */
+const DEPTH_BUFFER_LEVELS = 2 ** 24;
+/**
+ * How much of an elevation survives being viewed at {@link MAX_PITCH} — the least of it the depth
+ * buffer ever has to resolve, and so the figure the near plane is sized against.
+ */
+const MIN_PITCH_COSINE = Math.cos(degToRad(MAX_PITCH));

package/dist/space/layout-measure.d.ts

@@ -0,0 +1,67 @@
+import { type Camera } from 'three';
+import { type CameraControlsImpl } from '../controls';
+import { type Space } from './Space';
+/**
+ * How much of the plan one CSS pixel spans, in plan units — what everything sized in pixels is
+ * authored against, and what the imperative renderer published as `ptScale`.
+ *
+ * **One number for a view that has many.** Perspective foreshortens a pitched plan, so no single
+ * factor is true across the whole screen. The one the plan is laid out against is the value where
+ * the camera is aimed ({@link aimedAt}), which is why the reading does not move with pitch — only
+ * with dolly.
+ *
+ * **Derived where the controls can say, measured where they cannot.** They hold the distance to
+ * that point, and the projection says how much world a screen spans at it: the imperative
+ * renderer's own arithmetic, for free. Without them — external mode, a bare scene — the screen row
+ * through the aim is taken onto the plan and divided by the buffer's width, which asks nothing of
+ * the camera but its matrices. That row is an iso-depth line wherever the screen's x axis lies
+ * parallel to the plan, true for this renderer's camera and a map host's alike, so the average
+ * along it is exact rather than approximate.
+ *
+ * Neither path knows a `visibleRect` exists: its framing rides in `projectionMatrix`, which one
+ * reads `m00` out of and the other projects through.
+ *
+ * **CSS pixels, not device pixels** — a plan reports the same pixel size at every device ratio. The
+ * renderer's public surface is CSS pixels, because a caller authors in CSS pixels and the ratio of
+ * the drawing buffer is the renderer's own business; the caller hands over the canvas's width in
+ * CSS pixels and the ratio never enters here.
+ * @param camera - The camera in use.
+ * @param space - The scene's space.
+ * @param cssWidth - The canvas's width in CSS pixels.
+ * @param controls - The camera controls, when mounted; they own the distance to the target.
+ * @returns Plan units per CSS pixel, or `undefined` while the camera misses the plan or the canvas
+ *   has no width.
+ */
+export declare function measurePixelSize(camera: Camera, space: Space, cssWidth: number, controls?: CameraControlsImpl): number | undefined;
+/**
+ * Which way the plan is turned, in radians clockwise from north — {@link measurePixelSize}'s
+ * counterpart on the roll axis, split the same way.
+ *
+ * The controls hold an azimuth, so where they exist that is the whole answer. Without them it is
+ * the screen direction of the plan's own x axis at {@link aimedAt}, read off the matrix that takes
+ * the plan to clip space: the plan's x axis is that matrix's first column, and a screen direction is
+ * what its clip image becomes once the perspective divide is differentiated through. Under an
+ * external host this composes the host's bearing with the static transform's own rotation, which is
+ * the venue-relative angle the imperative path fed its roll handlers by hand.
+ *
+ * A direction rather than the angle between two projected points is what removes the probe the
+ * imperative renderer used, and with it the question of how far apart to place it.
+ * @param camera - The camera in use.
+ * @param space - The scene's space.
+ * @param cssWidth - The canvas's width in CSS pixels.
+ * @param cssHeight - Its height in CSS pixels, which weights the two NDC axes back into pixels.
+ * @param controls - The camera controls, when mounted; they hold the angle outright.
+ * @returns The roll in `[0, 2π)`, or `undefined` while the camera misses the plan.
+ */
+export declare function measureRoll(camera: Camera, space: Space, cssWidth: number, cssHeight: number, controls?: CameraControlsImpl): number | undefined;
+/**
+ * Whether a new pixel size differs enough from the last one to re-lay out on.
+ *
+ * Absolute rather than relative, and the same `1e-4` the imperative renderer compared with, so the
+ * handlers ported onto this API keep firing at the zoom steps they were tuned against.
+ * @param pixelSize - The new value.
+ * @param previous - The value last laid out at.
+ * @returns Whether the change is worth acting on.
+ */
+export declare function pixelSizeMoved(pixelSize: number, previous: number): boolean;
+//# sourceMappingURL=layout-measure.d.ts.map

package/dist/space/layout-measure.js

@@ -0,0 +1,175 @@
+import { Point } from '@expofp/geometry';
+import { Matrix4, Ray, Vector2, Vector4 } from 'three';
+import { bearing } from '../controls';
+import { euclideanModulo } from '../utils/math';
+import { isOrthographic, isPerspective } from './camera-kind';
+/**
+ * How much of the plan one CSS pixel spans, in plan units — what everything sized in pixels is
+ * authored against, and what the imperative renderer published as `ptScale`.
+ *
+ * **One number for a view that has many.** Perspective foreshortens a pitched plan, so no single
+ * factor is true across the whole screen. The one the plan is laid out against is the value where
+ * the camera is aimed ({@link aimedAt}), which is why the reading does not move with pitch — only
+ * with dolly.
+ *
+ * **Derived where the controls can say, measured where they cannot.** They hold the distance to
+ * that point, and the projection says how much world a screen spans at it: the imperative
+ * renderer's own arithmetic, for free. Without them — external mode, a bare scene — the screen row
+ * through the aim is taken onto the plan and divided by the buffer's width, which asks nothing of
+ * the camera but its matrices. That row is an iso-depth line wherever the screen's x axis lies
+ * parallel to the plan, true for this renderer's camera and a map host's alike, so the average
+ * along it is exact rather than approximate.
+ *
+ * Neither path knows a `visibleRect` exists: its framing rides in `projectionMatrix`, which one
+ * reads `m00` out of and the other projects through.
+ *
+ * **CSS pixels, not device pixels** — a plan reports the same pixel size at every device ratio. The
+ * renderer's public surface is CSS pixels, because a caller authors in CSS pixels and the ratio of
+ * the drawing buffer is the renderer's own business; the caller hands over the canvas's width in
+ * CSS pixels and the ratio never enters here.
+ * @param camera - The camera in use.
+ * @param space - The scene's space.
+ * @param cssWidth - The canvas's width in CSS pixels.
+ * @param controls - The camera controls, when mounted; they own the distance to the target.
+ * @returns Plan units per CSS pixel, or `undefined` while the camera misses the plan or the canvas
+ *   has no width.
+ */
+export function measurePixelSize(camera, space, cssWidth, controls) {
+    if (!(cssWidth > 0) || !(space.scale > 0))
+        return undefined;
+    if (controls) {
+        const worldWidth = visibleWorldWidth(camera, controls.distance);
+        if (!(worldWidth > 0))
+            return undefined;
+        // The camera measures the world, and only the fit says how much plan that world is.
+        return worldWidth / cssWidth / space.scale;
+    }
+    const aim = aimedAt(camera, space);
+    if (!aim)
+        return undefined;
+    // Only the row's height is wanted, so `_ndc` is free to be re-aimed along it below.
+    const rowY = space.planToNdc(aim, camera, _ndc)?.y;
+    if (rowY === undefined)
+        return undefined;
+    const left = space.ndcToPlan(_ndc.set(-1, rowY), camera, _left);
+    const right = space.ndcToPlan(_ndc.set(1, rowY), camera, _right);
+    if (!left || !right)
+        return undefined;
+    const planLength = Math.hypot(right.x - left.x, right.y - left.y);
+    if (!(planLength > 0))
+        return undefined;
+    return planLength / cssWidth;
+}
+/**
+ * Which way the plan is turned, in radians clockwise from north — {@link measurePixelSize}'s
+ * counterpart on the roll axis, split the same way.
+ *
+ * The controls hold an azimuth, so where they exist that is the whole answer. Without them it is
+ * the screen direction of the plan's own x axis at {@link aimedAt}, read off the matrix that takes
+ * the plan to clip space: the plan's x axis is that matrix's first column, and a screen direction is
+ * what its clip image becomes once the perspective divide is differentiated through. Under an
+ * external host this composes the host's bearing with the static transform's own rotation, which is
+ * the venue-relative angle the imperative path fed its roll handlers by hand.
+ *
+ * A direction rather than the angle between two projected points is what removes the probe the
+ * imperative renderer used, and with it the question of how far apart to place it.
+ * @param camera - The camera in use.
+ * @param space - The scene's space.
+ * @param cssWidth - The canvas's width in CSS pixels.
+ * @param cssHeight - Its height in CSS pixels, which weights the two NDC axes back into pixels.
+ * @param controls - The camera controls, when mounted; they hold the angle outright.
+ * @returns The roll in `[0, 2π)`, or `undefined` while the camera misses the plan.
+ */
+export function measureRoll(camera, space, cssWidth, cssHeight, controls) {
+    if (controls)
+        return bearing(controls);
+    const aim = aimedAt(camera, space);
+    if (!aim)
+        return undefined;
+    _planToClip
+        .multiplyMatrices(camera.projectionMatrix, camera.matrixWorldInverse)
+        .multiply(space.matrix);
+    // Column-major, so elements 0 to 3 are the first column: the plan's x axis as a clip direction.
+    const column = _planToClip.elements;
+    const clip = _clip.set(aim.x, aim.y, 0, 1).applyMatrix4(_planToClip);
+    // d(ndc)/dx by the quotient rule, less its `1/w²` — positive, so it moves no direction. NDC is
+    // aspect-distorted, so each axis is weighted back into pixels; canvas y grows downward where NDC
+    // y grows up.
+    const dx = (column[0] * clip.w - clip.x * column[3]) * cssWidth;
+    const dy = -(column[1] * clip.w - clip.y * column[3]) * cssHeight;
+    if (dx === 0 && dy === 0)
+        return undefined;
+    // The plan turned clockwise by θ shows its east axis at screen angle -θ.
+    return euclideanModulo(-Math.atan2(dy, dx), 2 * Math.PI);
+}
+/**
+ * Whether a new pixel size differs enough from the last one to re-lay out on.
+ *
+ * Absolute rather than relative, and the same `1e-4` the imperative renderer compared with, so the
+ * handlers ported onto this API keep firing at the zoom steps they were tuned against.
+ * @param pixelSize - The new value.
+ * @param previous - The value last laid out at.
+ * @returns Whether the change is worth acting on.
+ */
+export function pixelSizeMoved(pixelSize, previous) {
+    return Math.abs(pixelSize - previous) >= PIXEL_SIZE_EPSILON;
+}
+/**
+ * Where the camera is aimed on the plan: the point its own axis crosses, which is what the controls
+ * would call their target and what the derived path's distance is measured to.
+ *
+ * Read off the camera's world matrix rather than asked of anything that might not be there —
+ * external mode's camera carries a rigid one recovered from the host's folded matrix, so its eye
+ * and direction are as true as a camera three placed itself.
+ * @param camera - The camera in use.
+ * @param space - The scene's space.
+ * @returns The plan point, or `undefined` when the camera looks along the plan and never meets it.
+ */
+function aimedAt(camera, space) {
+    _axis.origin.setFromMatrixPosition(camera.matrixWorld);
+    camera.getWorldDirection(_axis.direction);
+    return space.rayToPlan(_axis, _aim);
+}
+/**
+ * The world-space width one screen covers at a distance.
+ *
+ * Read off the projection matrix rather than rebuilt from `fov` and `zoom`: `m00` is `2·near /
+ * (right − left)` under perspective and `2 / (right − left)` under orthographic, so it holds for a
+ * projection nobody derived from a symmetric frustum — the off-centre, expanded one a `visibleRect`
+ * installs, which leaves `fov` untouched.
+ *
+ * Width where the imperative renderer took height, so both of {@link measurePixelSize}'s paths
+ * divide by the one canvas dimension they are given; for a projection whose aspect is the buffer's
+ * the two agree exactly.
+ * @param camera - The camera in use.
+ * @param distance - Distance from the camera to the point it is aimed at, in world units.
+ * @returns The width in world units, or `NaN` for a camera that projects neither way.
+ */
+function visibleWorldWidth(camera, distance) {
+    // Column-major: element 0 is row 0 of column 0.
+    const m00 = camera.projectionMatrix.elements[0];
+    if (!(m00 > 0))
+        return NaN;
+    // A perspective frustum widens with distance; an orthographic one covers the same width wherever
+    // it sits, which is the whole difference between the two.
+    if (isPerspective(camera))
+        return (2 * distance) / m00;
+    if (isOrthographic(camera))
+        return 2 / m00;
+    return NaN;
+}
+/**
+ * The change in {@link measurePixelSize} below which nothing is re-laid out. Not configurable: it
+ * is the granularity every handler's thresholds are expressed against, so a scene tuning it would
+ * be tuning every handler at once.
+ */
+const PIXEL_SIZE_EPSILON = 1e-4;
+// Scratch, each filled and consumed within one call — and the two readings never overlap, so the
+// aim they share is one point rather than two.
+const _axis = new Ray();
+const _aim = new Point();
+const _left = new Point();
+const _right = new Point();
+const _ndc = new Vector2();
+const _planToClip = new Matrix4();
+const _clip = new Vector4();

package/dist/space/viewport.d.ts

@@ -0,0 +1,112 @@
+import { type Camera as ThreeCamera } from 'three';
+import { type CanvasPoint, type CanvasPointLike, type PlanPoint, type PlanPointLike, type Space } from './Space';
+/**
+ * Where things are: the two directions between the plan's own coordinates and the canvas the user
+ * points at, and the one question that rides on them.
+ *
+ * The counterpart to `CameraAPI`, and the division is the obvious one — that moves the camera, this
+ * reads where the camera has left things. Nothing here changes anything, so nothing here returns a
+ * promise: every method answers for the plan as it stands at the moment of asking.
+ *
+ * Both conversions can fail, and both failures are real rather than defensive: a tilted camera looks
+ * past the plan entirely above the horizon, and a plan point can sit behind the camera. `undefined`
+ * says so in each direction, rather than a number that would read as a position.
+ *
+ * This is the surface that replaces the imperative renderer's `viewport`, whose `canvasToSvg`
+ * covered only the first of these — and returned one point per loaded scene, leaving every caller
+ * to pick the default one out of an array.
+ */
+export interface ViewportAPI {
+    /**
+     * Where a point on the canvas lands on the plan.
+     *
+     * **The plan plane, not the geometry drawn on it.** A click on the roof of a raised model reports
+     * the ground point the ray carries on to, which is the floor coordinate this answers for; what the
+     * ray actually struck is a pointer event's business, and `PointerEventData.point` reports that.
+     * @param point - The canvas position, in css pixels from the canvas's top-left corner.
+     * @param out - A point to write into, for a caller converting enough of them to care. Omit it and
+     *   each call allocates, which is what makes the result safe to keep.
+     * @returns The plan position, or `undefined` when the camera never meets the plan there.
+     */
+    canvasToPlan(point: CanvasPointLike, out?: PlanPoint): PlanPoint | undefined;
+    /**
+     * Where a point on the plan lands on the canvas.
+     *
+     * **Unclamped:** a point off the side of the plan reports the position it really has, outside the
+     * canvas, which is what makes it usable for placing something that may scroll into view.
+     * @param point - The plan position; a missing `z` is read as `0`, so an elevated point projects
+     *   from the height it is drawn at.
+     * @param out - A point to write into, for a caller converting enough of them to care. Omit it and
+     *   each call allocates, which is what makes the result safe to keep.
+     * @returns The canvas position in css pixels, or `undefined` when the point is behind the camera.
+     */
+    planToCanvas(point: PlanPointLike, out?: CanvasPoint): CanvasPoint | undefined;
+    /**
+     * Whether a point on the plan is on screen.
+     *
+     * **The whole canvas counts**, including any part of it a host's own UI covers: a `visibleRect`
+     * expands the frustum rather than cropping it, so the plan really is drawn edge to edge and a
+     * point behind a bottom sheet is drawn as much as one beside it. A caller asking the narrower
+     * question — can the *user* see it — tests {@link planToCanvas} against its own region.
+     * @param point - The plan position; a missing `z` is read as `0`.
+     * @returns Whether it is drawn on the canvas.
+     */
+    isVisible(point: PlanPointLike): boolean;
+}
+/**
+ * What {@link Viewport} needs from the scene it reads.
+ *
+ * Handed over whole rather than reached for, as `CameraContext` is, and the store getter is here for
+ * the same reason: R3F may swap the camera out from under a held reference, and every conversion
+ * below has to run through the one the canvas is currently drawn with.
+ */
+interface ViewportContext {
+    /** Reads the canvas state, which is where the camera in use is found. */
+    get: () => {
+        camera: ThreeCamera;
+    };
+    /** The scene's space, which owns the mapping every conversion here composes. */
+    space: Space;
+}
+/**
+ * The scene's coordinate conversions.
+ *
+ * A hook for the same reason `useCameraAPI` is one: it resolves only inside a component mounted
+ * under `<Renderer>`, so "the plan cannot be measured before the scene exists" is enforced by where
+ * the code can live rather than by a null check every caller has to remember. A host that needs to
+ * convert coordinates from outside React publishes this object from an effect.
+ *
+ * **Nothing here subscribes to the canvas size**, and it does not need to: `Space` is refitted in
+ * place on every resize, so the object below reads the current fit through the same reference for as
+ * long as the scene lives, and the camera is read at the moment of asking. That is the reading
+ * discipline `Space` documents — and the reason it is safe here is that no render output is derived
+ * from these answers.
+ *
+ * **The returned object is new on every render, deliberately**, as `useCameraAPI`'s is: this module
+ * memoizes nothing, so a consumer that cannot re-subscribe cheaply holds it in a ref and pays that
+ * cost where the cost is understood.
+ * @returns The conversions.
+ */
+export declare function useViewport(): ViewportAPI;
+/**
+ * The coordinate conversions, over whatever the scene currently holds.
+ *
+ * A class rather than an object literal because it is the renderer's published surface, and built
+ * fresh rather than mutated so that nothing here is state — every answer is composed from the space
+ * and the camera as they stand when the method is called.
+ */
+export declare class Viewport implements ViewportAPI {
+    private readonly context;
+    /**
+     * @param context - What the scene holds; the instance is rebuilt whenever it moves.
+     */
+    constructor(context: ViewportContext);
+    /** @inheritdoc */
+    canvasToPlan(point: CanvasPointLike, out?: PlanPoint): PlanPoint | undefined;
+    /** @inheritdoc */
+    planToCanvas(point: PlanPointLike, out?: CanvasPoint): CanvasPoint | undefined;
+    /** @inheritdoc */
+    isVisible(point: PlanPointLike): boolean;
+}
+export {};
+//# sourceMappingURL=viewport.d.ts.map