@expofp/renderer 3.2.5 → 3.27.0

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

@@ -0,0 +1,65 @@
+import { type Camera } from 'three';
+import { type CameraControlsImpl } from '../controls/CameraControls';
+import { type Space } from './Space';
+/**
+ * How much of the plan one device 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.
+ *
+ * **Device pixels, not css pixels** — a plan at dpr 2 reports half the pixel size of the same plan
+ * at dpr 1, as the imperative renderer did measuring `canvas.height`.
+ * @param camera - The camera in use.
+ * @param space - The scene's space.
+ * @param bufferWidth - The drawing buffer's width in device pixels.
+ * @param controls - The camera controls, when mounted; they own the distance to the target.
+ * @returns Plan units per device pixel, or `undefined` while the camera misses the plan or the
+ *   buffer has no width.
+ */
+export declare function measurePixelSize(camera: Camera, space: Space, bufferWidth: 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 bufferWidth - The drawing buffer's width in device pixels.
+ * @param bufferHeight - Its height, 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, bufferWidth: number, bufferHeight: 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,173 @@
+import { Point } from '@expofp/geometry';
+import { Matrix4, Ray, Vector2, Vector4 } from 'three';
+import { bearing } from '../controls/CameraControls';
+import { euclideanModulo } from '../utils/math';
+import { isOrthographic, isPerspective } from './camera-kind';
+/**
+ * How much of the plan one device 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.
+ *
+ * **Device pixels, not css pixels** — a plan at dpr 2 reports half the pixel size of the same plan
+ * at dpr 1, as the imperative renderer did measuring `canvas.height`.
+ * @param camera - The camera in use.
+ * @param space - The scene's space.
+ * @param bufferWidth - The drawing buffer's width in device pixels.
+ * @param controls - The camera controls, when mounted; they own the distance to the target.
+ * @returns Plan units per device pixel, or `undefined` while the camera misses the plan or the
+ *   buffer has no width.
+ */
+export function measurePixelSize(camera, space, bufferWidth, controls) {
+    if (!(bufferWidth > 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 / bufferWidth / 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 / bufferWidth;
+}
+/**
+ * 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 bufferWidth - The drawing buffer's width in device pixels.
+ * @param bufferHeight - Its height, 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, bufferWidth, bufferHeight, 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]) * bufferWidth;
+    const dy = -(column[1] * clip.w - clip.y * column[3]) * bufferHeight;
+    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 buffer 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

package/dist/space/viewport.js

@@ -0,0 +1,67 @@
+import { useThree } from '@react-three/fiber';
+import { Vector2 } from 'three';
+import { useSpace, } from './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 function useViewport() {
+    const get = useThree((state) => state.get);
+    const space = useSpace();
+    return new Viewport({ get, space });
+}
+/**
+ * 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 class Viewport {
+    context;
+    /**
+     * @param context - What the scene holds; the instance is rebuilt whenever it moves.
+     */
+    constructor(context) {
+        this.context = context;
+    }
+    /** @inheritdoc */
+    canvasToPlan(point, out) {
+        const { space, get } = this.context;
+        return space.canvasToPlan(point, get().camera, out);
+    }
+    /** @inheritdoc */
+    planToCanvas(point, out) {
+        const { space, get } = this.context;
+        // Never a shared scratch when the caller named none: this is public, and a caller that kept the
+        // point it was handed must never find it moved under them. An `out` they passed is theirs, and
+        // the aliasing is then a choice they made rather than one made for them.
+        return space.planToCanvas(point, get().camera, out);
+    }
+    /** @inheritdoc */
+    isVisible(point) {
+        const { space, get } = this.context;
+        // Tested in normalized device coordinates rather than in canvas pixels, which is the same test
+        // — `ndcToCanvas` maps `[-1, 1]` onto the canvas and nothing else — arrived at without the
+        // canvas size, and so with nothing to disagree with when a resize is halfway through.
+        const ndc = space.planToNdc(point, get().camera, _ndc);
+        return !!ndc && Math.abs(ndc.x) <= 1 && Math.abs(ndc.y) <= 1;
+    }
+}
+/** Where {@link Viewport.isVisible} projects to; it never escapes the method. */
+const _ndc = new Vector2();

package/dist/types/defs.d.ts

@@ -0,0 +1,169 @@
+import { type Box, type LineLike, type Rect, type Shape } from '@expofp/geometry';
+import { type LayoutHandlers, type PointerHandlers } from './events';
+/** A color as a css string or a packed numeric value. */
+export type ColorInput = string | number;
+/** Any image-like source that can be uploaded as a texture. */
+export type ImageSource = HTMLImageElement | HTMLCanvasElement | ImageBitmap | OffscreenCanvas;
+/** Scene definition */
+export interface SceneDef {
+    /** Root layer of the scene tree */
+    rootLayer: LayerDef;
+    /** Background color in css format */
+    background?: ColorInput;
+    /** SVG viewbox */
+    viewbox: Box;
+    /** Static transform matrix */
+    staticTransform?: number[];
+}
+/** Shared properties for all renderable defs */
+export interface SharedDef extends LayoutHandlers {
+    /** Whether the def is hidden */
+    hidden?: boolean;
+    /**
+     * How strongly the def is dimmed — desaturated toward gray and darkened — from `0` (undimmed) to
+     * `1` (fully dimmed), interpolating in between.
+     *
+     * `undefined` inherits from the nearest ancestor that sets one, and only `undefined` inherits: a
+     * def's own `0` un-dims it inside a dimmed layer, and its own `1` dims it inside an undimmed one.
+     * A layer and a single def carry the same field with the same meaning, so dimming a whole floor
+     * and un-dimming one booth on it are the same operation at two levels. The root defaults to `0`.
+     *
+     * Values outside `[0, 1]` are clamped. Being a number rather than a flag is what lets a dim be
+     * animated — easing a layer's value from `0` to `1` costs one uniform per layer per frame,
+     * whatever the layer holds.
+     */
+    dim?: number;
+}
+/** Any def that can be rendered into a scene. */
+export type RenderableDef = LayerDef | ShapeDef | ImageDef | TextDef | LineDef | ModelDef;
+/**
+ * An array of a single {@link RenderableDef} kind (never a mixed union). The conditional
+ * distributes over {@link RenderableDef}, so even the default is a union of single-kind arrays —
+ * a mixed array is unrepresentable, which is what lets a first-element guard speak for the whole
+ * collection. `Readonly<RenderableDefCollection<T>>` distributes the same way, into readonly
+ * single-kind arrays.
+ */
+export type RenderableDefCollection<T = RenderableDef> = T extends RenderableDef ? T[] : never;
+/**
+ * Layer definition.
+ *
+ * A layer is also where interaction lives: the handlers it inherits from {@link PointerHandlers} are
+ * what make its subtree pickable, and each event names the def it hit. Layout is the other way round
+ * — a layer carries its own {@link LayoutHandlers} through {@link SharedDef}, like any other def, and
+ * that is how a layer whose contents depend on the camera re-derives them.
+ */
+export interface LayerDef<T extends RenderableDef = RenderableDef> extends SharedDef, PointerHandlers<T> {
+    /** Layer's name */
+    readonly name: string;
+    /** Collection of layer's children. Mixing different types of children is not supported. */
+    children: RenderableDefCollection<T>;
+}
+/** Shape definition. */
+export interface ShapeDef extends SharedDef {
+    /**
+     * Shape to render. To change it, **replace** this with a new `Shape` and call `update(def)`: the
+     * new object re-claims the instance against fresh geometry, so even the shape *type* may change
+     * (rect ↔ polygon). Mutating the existing shape in place is more limited — a rect's or box's
+     * transform (center, size, rotation) is re-read every update, but a polygon's vertices and indices
+     * are cached by shape identity and will not rebuild in place.
+     */
+    shape: Shape;
+    /** Shape's color in css format */
+    color: ColorInput;
+}
+/** Image definition */
+export interface ImageDef extends SharedDef {
+    /**
+     * Image source. Write-once — a def's pixels are fixed for its lifetime: the atlas packs and
+     * uploads them at claim time and never re-reads the source, so a new image is a new def, not a
+     * reassignment. `readonly` makes that the type's guarantee (see {@link SceneDef.memoryLimit},
+     * which relies on a pack's byte totals staying stable until a repack).
+     */
+    readonly source: ImageSource;
+    /** Image's bounds */
+    bounds: Rect;
+    /**
+     * Image's anchor point. Defines the point on the image that is used as an origin point for transformations.
+     * [0, 0] is the top-left corner, [0.5, 0.5] is the center (default), [1, 1] is the bottom-right corner.
+     */
+    origin?: [number, number];
+}
+/** Text definition */
+export interface TextDef extends SharedDef {
+    /**
+     * Array of text lines, drawn as a block stacked inside {@link bounds}.
+     *
+     * Updatable in both directions: a line's own fields are re-read on every `update(def)`, and
+     * changing the array's *length* re-claims the def's batch members against the new count. (The
+     * imperative renderer allocated members once and so required this to be fixed; React reconciles
+     * it instead.) A line whose `fontSize` is `0` is not drawn.
+     */
+    lines: TextLineDef[];
+    /** Text's bounds */
+    bounds: Rect;
+    /** Text's padding [horizontal, vertical] */
+    padding: [number, number];
+    /** {@link TextAlignment} object describing text's alignment */
+    alignment: TextAlignment;
+}
+/** Single text line definition */
+export interface TextLineDef {
+    /** Line's text */
+    text: string;
+    /** Line's color in css format */
+    color: ColorInput;
+    /** Line's font URL. Not updatable. Supported formats: .ttf, .otf, .woff (.woff2 is not supported). */
+    fontUrl: string;
+    /**
+     * Line's font size: its em height in plan units, the same units as the def's `bounds` and
+     * `padding`.
+     *
+     * Nothing here converts from pixels. A plan sizing a line to hold an on-screen size does that
+     * itself, against the pixel size the renderer publishes — as it does for every other
+     * pixel-authored thing it draws. `0` means the line is not drawn.
+     */
+    fontSize: number;
+    /** Line's stroke color & width, the width in the same units as {@link fontSize}. Optional. */
+    stroke?: {
+        color: ColorInput;
+        width: number;
+    };
+}
+/** Text alignment */
+export interface TextAlignment {
+    /** Horizontal alignment */
+    horizontal: 'left' | 'center' | 'right';
+    /** Vertical alignment */
+    vertical: 'top' | 'center' | 'bottom';
+    /** Text alignment within the line. Optional. */
+    text?: 'left' | 'center' | 'right';
+}
+/** Line definition */
+export interface LineDef extends SharedDef {
+    /**
+     * The segment's endpoints, with an optional `elevation` placing it on its layer's plane.
+     *
+     * Updatable: both ends are re-read on every `update(def)` and written only when they moved,
+     * so a line can be animated in place rather than replaced. A `LineLike` exposes readonly coordinates,
+     * so an update means replacing this with a new one — or moving the `Line` behind it,
+     * whose own setters do the same job.
+     */
+    points: LineLike;
+    /** Line's color in css format */
+    color: ColorInput;
+    /**
+     * Line's width in screen-space units (pixels), so it holds its thickness as the plan zooms.
+     * `0` draws nothing.
+     */
+    width: number;
+}
+/** External 3D model definition */
+export interface ModelDef extends SharedDef {
+    /** Model's URL. Not updatable. */
+    url: string;
+    /** Model's bounds */
+    bounds: Rect;
+    /** Model's opacity. Optional. */
+    opacity?: number;
+}
+//# sourceMappingURL=defs.d.ts.map

package/dist/types/defs.js

@@ -0,0 +1 @@
+export {};