@expofp/renderer 3.2.5 → 3.27.1

package/dist/space/Space.d.ts

@@ -0,0 +1,288 @@
+import { type Box, Point, type Point2Like, type PointLike } from '@expofp/geometry';
+import { type Camera, Matrix4, Ray, Raycaster, Vector2, type Vector2Like, Vector3, type Vector3Like } from 'three';
+/**
+ * A point in **plan space**: the plan's own coordinates, the ones every def is authored in. Reads x
+ * right, y down and z **up**, so an elevation is a positive number.
+ *
+ * Plan points are `@expofp/geometry` points because plan space crosses the public API — a pointer
+ * event reports where it landed as one, and floorplan authors its defs in the same type. So does
+ * {@link CanvasPoint}, for the same reason: those two are what a caller converts between.
+ */
+export type PlanPoint = Point & {
+    __space: 'plan';
+};
+/**
+ * A plain object in plan space — what a caller may pass in.
+ *
+ * The brand is required rather than optional, so a bare `{ x, y }` is assignable to no space at all
+ * and crossing into one is an explicit `as`. An optional brand would make every plain object
+ * assignable to *every* space, which is the mistake these types exist to catch.
+ */
+export type PlanPointLike = PointLike & {
+    __space: 'plan';
+};
+/**
+ * A point in **world space**: three's own space, the one the camera is placed in. World z grows *away*
+ * from the viewer under the viewbox fit, which is why {@link Space} mirrors it.
+ *
+ * World and NDC points are three's vectors instead of `@expofp/geometry`: neither is part of the
+ * public API, and both exist only to be multiplied by matrices and unprojected through cameras.
+ */
+export type WorldPoint = Vector3 & {
+    __space: 'world';
+};
+/** A plain object point in world space. */
+export type WorldPointLike = Vector3Like & {
+    __space: 'world';
+};
+/**
+ * A point in **canvas space**: css pixels from the canvas's top-left corner, x right and y **down**,
+ * the coordinates a DOM pointer event reports.
+ *
+ * Two dimensions and no more, unlike a plan point: what is drawn at a canvas position has a height,
+ * but the position itself does not — which is why {@link Space.ndcToCanvas} writes a zero `z` rather
+ * than carrying one through.
+ *
+ * Canvas and plan points are the pair most easily confused — both are 2D `{ x, y }` over comparable
+ * ranges, and both read as "where on screen" — so this is the brand that earns its keep most.
+ */
+export type CanvasPoint = Point & {
+    __space: 'canvas';
+};
+/** A plain object point in canvas space — what a caller reading a DOM event may pass in. */
+export type CanvasPointLike = Point2Like & {
+    __space: 'canvas';
+};
+/**
+ * A point in **normalized device coordinates**: where something sits on the canvas irrespective of
+ * its size, `[-1, 1]` on both axes with the origin at the centre and y growing upward.
+ */
+export type NDCPoint = Vector2 & {
+    __space: 'ndc';
+};
+/** A plain object point in normalized device coordinates. */
+export type NDCPointLike = Vector2Like & {
+    __space: 'ndc';
+};
+/** How a {@link Space} maps the plan onto the canvas. */
+export interface SpaceOptions {
+    /** The scene's viewbox, in plan units — the region the fit frames. */
+    viewbox: Box;
+    /** The canvas width in css pixels. */
+    width: number;
+    /** The canvas height in css pixels. */
+    height: number;
+    /**
+     * The device pixel ratio the canvas draws at.
+     *
+     * Separate rather than pre-multiplied into css pixels because both are needed: the fit measures the buffer pixels,
+     * while canvas coordinates arrive from DOM events in css pixels. Passing the buffer size instead would just move the
+     * division to the other side.
+     */
+    dpr: number;
+    /**
+     * A caller-supplied plan → world matrix, 16 elements column-major. When present it *replaces* the
+     * viewbox fit rather than composing with it, and carries its own z convention — the maplibre
+     * transform scales z upward where the fit mirrors it.
+     */
+    staticTransform?: number[];
+}
+/**
+ * The scene's space.
+ * @returns The space {@link Scene} published, or the identity one when rendered outside a scene.
+ */
+export declare function useSpace(): Space;
+/**
+ * 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, mirroring z so a positive
+ * elevation lands nearer the camera. 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 and with its own z convention.
+ *
+ * **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 declare class Space {
+    /** Plan → world. */
+    readonly matrix: Matrix4;
+    /** World → plan. */
+    readonly matrixInverse: Matrix4;
+    private _scale;
+    private _isExternal;
+    /** The canvas width in css pixels, which the canvas conversions measure against. */
+    private width;
+    /** The canvas height in css pixels. */
+    private height;
+    /**
+     * @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?: SpaceOptions);
+    /**
+     * 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(): number;
+    /**
+     * 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(): boolean;
+    /**
+     * 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: SpaceOptions): void;
+    /**
+     * 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: PlanPointLike, out?: WorldPoint): WorldPoint;
+    /**
+     * 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: WorldPointLike, out?: PlanPoint): PlanPoint;
+    /**
+     * 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: CanvasPointLike, out?: NDCPoint): NDCPoint;
+    /**
+     * 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: NDCPointLike, out?: CanvasPoint): CanvasPoint;
+    /**
+     * 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: Ray, out?: PlanPoint): PlanPoint | undefined;
+    /**
+     * 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: NDCPointLike, camera: Camera, out?: PlanPoint): PlanPoint | undefined;
+    /**
+     * 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: PlanPointLike, camera: Camera, out?: NDCPoint): NDCPoint | undefined;
+    /**
+     * 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: CanvasPointLike, camera: Camera, out?: PlanPoint): PlanPoint | undefined;
+    /**
+     * 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: PlanPointLike, camera: Camera, out?: CanvasPoint): CanvasPoint | undefined;
+    /**
+     * 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.
+     */
+    private validateStaticTransform;
+}
+/**
+ * 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 declare function fitScale(viewbox: Box, bufferWidth: number, bufferHeight: number): number;
+/**
+ * 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 declare const SpaceContext: import("react").Context<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 declare function castRay(raycaster: Raycaster, ndc: NDCPointLike, camera: Camera): void;
+//# sourceMappingURL=Space.d.ts.map

package/dist/space/Space.js

@@ -0,0 +1,329 @@
+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 { 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, mirroring z so a positive
+ * elevation lands nearer the camera. 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 and with its own z convention.
+ *
+ * **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));
+        }
+        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 length one unit along an axis is drawn at.
+ * @param matrix - The matrix to measure.
+ * @param axis - Which axis: `0` for x, `1` for y.
+ * @returns The transformed axis's length.
+ */
+function axisLength(matrix, axis) {
+    return new Vector3().setFromMatrixColumn(matrix, axis).length();
+}
+/** 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();