@expofp/renderer 3.2.4 → 3.27.0

package/dist/objects/text/text-container.d.ts

@@ -0,0 +1,105 @@
+import { type Intersection } from 'three';
+import { type BatchedTextExt } from '../../core/text/BatchedText';
+import { TextExt } from '../../core/text/Text';
+import { type RenderableDef, type TextDef } from '../../types/defs';
+import { SlotContainer } from '../containers';
+/** One def's members: a `TextExt` per line, and the batch slot each of them occupies. */
+export interface LineGroup {
+    /** The members, in the def's line order. */
+    readonly texts: readonly TextExt[];
+    /** Each member's batch slot, index-parallel to {@link texts}. */
+    readonly slots: readonly number[];
+}
+/**
+ * One text layer's bookkeeping: a group of members per def, and the paint order across them.
+ *
+ * The slot a def claims here is a **group**, not a batch member — a `TextDef` holds an array of
+ * lines and each line is its own `TextExt`. That is the one place this differs from the shape and
+ * image containers, and it falls out of the def type rather than being a choice: the lines of one
+ * def are laid out together (a centered block needs every line's height before it can place the
+ * first), so they cannot be independent instances.
+ *
+ * Group size is the slot's resource, so a def that gains or loses a line re-claims automatically —
+ * which is what makes `TextDef.lines` updatable here, where the imperative renderer required it to
+ * be fixed.
+ *
+ * Ordering differs too: a text batch draws through packed glyph attributes rather than a sortable
+ * draw list, so {@link applyOrder} hands the batch a rebuilt member list instead of labeling slots,
+ * and the inherited `customSort` goes unused.
+ */
+export declare class TextContainer extends SlotContainer<number, BatchedTextExt, TextDef> {
+    /** Groups by slot, with holes for released ones. */
+    private readonly groups;
+    private readonly freeGroups;
+    /**
+     * Batch member to the group holding it, so a hit — which names a member — resolves to a def. The
+     * batch reuses a released member's slot, so entries are dropped with the group that owned them.
+     */
+    private readonly groupByMember;
+    private groupCount;
+    /** The last order applied to the batch, kept so an unchanged one can skip the repack. */
+    private appliedOrder;
+    private syncScheduled;
+    private readonly invalidate;
+    /**
+     * Builds a text layer's bookkeeping. The batch itself is R3F's — the component renders
+     * `<BatchedText>` and hands it over through {@link SlotContainer.bind} — so R3F disposes it on
+     * unmount.
+     * @param invalidate - R3F's frame request, called when an asynchronous sync completes. Stable for
+     *   the lifetime of a canvas, so capturing it here is safe.
+     */
+    constructor(invalidate: () => void);
+    /**
+     * The members backing one def.
+     * @param slot - The def's group.
+     * @returns Its members and their batch slots.
+     */
+    linesAt(slot: number): LineGroup;
+    /**
+     * Requests one batch sync, coalescing every request made in the same tick.
+     *
+     * Eager rather than waiting for `onBeforeRender`, because syncing is asynchronous — troika loads
+     * and parses the font — and under on-demand rendering a sync started during a frame has nothing to
+     * request the *next* frame when it completes. The callback carries R3F's `invalidate`, which is
+     * what closes that loop; without it new text appears only when something else happens to
+     * invalidate.
+     */
+    scheduleSync(): void;
+    claim(def: RenderableDef, lineCount: number): number;
+    setVisibleAt(slot: number, visible: boolean): void;
+    /**
+     * Sets the draw order for the whole layer, then syncs.
+     *
+     * The sync rides along so one structural change costs exactly one sync — a mount writes content
+     * through its instances in the same effect flush, and every request in the tick coalesces.
+     * @param defs - The layer's texts, in paint order.
+     * @param layerDimmed - Whether the layer is dimmed, inherited by defs without a `dim` of their own.
+     */
+    setPaintOrder(defs: readonly TextDef[], layerDimmed: boolean): void;
+    /**
+     * A hit names the batch member it struck, and a def owns one member per line.
+     * @param hit - The intersection to trace.
+     * @returns The def, or `undefined` when no claimed group holds that member.
+     */
+    defFromHit(hit: Intersection): RenderableDef | undefined;
+    /**
+     * Rebuilds the flat member order from the current defs and hands it to the batch, unless nothing
+     * moved.
+     *
+     * Skipping an unchanged order matters more here than for the other containers: a text batch has no
+     * `customSort`, so reordering means repacking the glyph attributes, and `useStagedChildren` hands out
+     * a fresh snapshot on *every* layer update — including ones that moved nothing.
+     */
+    protected applyOrder(): void;
+    /**
+     * Per member, not per def: a def's lines are separate batch members, and the uniform row is
+     * addressed by member. One `dim` on the def therefore writes each of its lines, exactly as
+     * visibility does.
+     * @param slot - The def's group.
+     * @param amount - The encoded amount.
+     */
+    protected writeDim(slot: number, amount: number): void;
+    protected addInstance(lineCount: number): number;
+    protected removeInstance(slot: number): void;
+}
+//# sourceMappingURL=text-container.d.ts.map

package/dist/objects/text/text-container.js

@@ -0,0 +1,206 @@
+import { TextExt } from '../../core/text/Text';
+import { sameSequence } from '../../utils/arrays';
+import { SlotContainer } from '../containers';
+import { dimOrdered, isDimmed } from '../materials/dim';
+import { LAYOUT_FONT_SIZE, LINE_HEIGHT } from './text-layout';
+/**
+ * One text layer's bookkeeping: a group of members per def, and the paint order across them.
+ *
+ * The slot a def claims here is a **group**, not a batch member — a `TextDef` holds an array of
+ * lines and each line is its own `TextExt`. That is the one place this differs from the shape and
+ * image containers, and it falls out of the def type rather than being a choice: the lines of one
+ * def are laid out together (a centered block needs every line's height before it can place the
+ * first), so they cannot be independent instances.
+ *
+ * Group size is the slot's resource, so a def that gains or loses a line re-claims automatically —
+ * which is what makes `TextDef.lines` updatable here, where the imperative renderer required it to
+ * be fixed.
+ *
+ * Ordering differs too: a text batch draws through packed glyph attributes rather than a sortable
+ * draw list, so {@link applyOrder} hands the batch a rebuilt member list instead of labeling slots,
+ * and the inherited `customSort` goes unused.
+ */
+export class TextContainer extends SlotContainer {
+    /** Groups by slot, with holes for released ones. */
+    groups = [];
+    freeGroups = [];
+    /**
+     * Batch member to the group holding it, so a hit — which names a member — resolves to a def. The
+     * batch reuses a released member's slot, so entries are dropped with the group that owned them.
+     */
+    groupByMember = new Map();
+    groupCount = 0;
+    /** The last order applied to the batch, kept so an unchanged one can skip the repack. */
+    appliedOrder = [];
+    syncScheduled = false;
+    invalidate;
+    /**
+     * Builds a text layer's bookkeeping. The batch itself is R3F's — the component renders
+     * `<BatchedText>` and hands it over through {@link SlotContainer.bind} — so R3F disposes it on
+     * unmount.
+     * @param invalidate - R3F's frame request, called when an asynchronous sync completes. Stable for
+     *   the lifetime of a canvas, so capturing it here is safe.
+     */
+    constructor(invalidate) {
+        super();
+        this.invalidate = invalidate;
+    }
+    /**
+     * The members backing one def.
+     * @param slot - The def's group.
+     * @returns Its members and their batch slots.
+     */
+    linesAt(slot) {
+        return this.groups[slot] ?? EMPTY_GROUP;
+    }
+    /**
+     * Requests one batch sync, coalescing every request made in the same tick.
+     *
+     * Eager rather than waiting for `onBeforeRender`, because syncing is asynchronous — troika loads
+     * and parses the font — and under on-demand rendering a sync started during a frame has nothing to
+     * request the *next* frame when it completes. The callback carries R3F's `invalidate`, which is
+     * what closes that loop; without it new text appears only when something else happens to
+     * invalidate.
+     */
+    scheduleSync() {
+        if (this.syncScheduled)
+            return;
+        this.syncScheduled = true;
+        // `Promise.resolve().then`, not `queueMicrotask`: the SDK targets Android WebViews as old as
+        // Chrome 66, which predates it. Same microtask timing.
+        void Promise.resolve().then(() => {
+            this.syncScheduled = false;
+            // Unmounted between the request and the microtask; the batch is R3F's and already disposed.
+            if (!this.mesh)
+                return;
+            this.mesh.sync(this.invalidate);
+        });
+    }
+    claim(def, lineCount) {
+        const slot = super.claim(def, lineCount);
+        // `addText` appends to the batch's order, so a first mount draws in claim order and the layer's
+        // own pass relabels it in the same effect flush. A *re*-claim after that pass has to re-run it,
+        // or the new members would stay stuck at the end of the paint order.
+        if (this.layerDefs.length)
+            this.applyOrder();
+        return slot;
+    }
+    setVisibleAt(slot, visible) {
+        const group = this.groups[slot];
+        if (!group)
+            return;
+        for (const member of group.slots) {
+            this.mesh.setVisibleAt(member, visible);
+        }
+    }
+    /**
+     * Sets the draw order for the whole layer, then syncs.
+     *
+     * The sync rides along so one structural change costs exactly one sync — a mount writes content
+     * through its instances in the same effect flush, and every request in the tick coalesces.
+     * @param defs - The layer's texts, in paint order.
+     * @param layerDimmed - Whether the layer is dimmed, inherited by defs without a `dim` of their own.
+     */
+    setPaintOrder(defs, layerDimmed) {
+        super.setPaintOrder(defs, layerDimmed);
+        this.scheduleSync();
+    }
+    /**
+     * A hit names the batch member it struck, and a def owns one member per line.
+     * @param hit - The intersection to trace.
+     * @returns The def, or `undefined` when no claimed group holds that member.
+     */
+    defFromHit(hit) {
+        const member = hit.instanceId;
+        return member === undefined ? undefined : this.defAt(this.groupByMember.get(member));
+    }
+    /**
+     * Rebuilds the flat member order from the current defs and hands it to the batch, unless nothing
+     * moved.
+     *
+     * Skipping an unchanged order matters more here than for the other containers: a text batch has no
+     * `customSort`, so reordering means repacking the glyph attributes, and `useStagedChildren` hands out
+     * a fresh snapshot on *every* layer update — including ones that moved nothing.
+     */
+    applyOrder() {
+        const order = [];
+        for (const def of dimOrdered(this.layerDefs, this.layerDimmed)) {
+            const slot = this.slotOf(def);
+            if (slot === undefined)
+                continue;
+            const group = this.groups[slot];
+            if (!group)
+                continue;
+            order.push(...group.texts);
+            this.dimmedBySlot[slot] = isDimmed(def.dim, this.layerDimmed);
+        }
+        if (sameSequence(order, this.appliedOrder))
+            return;
+        this.appliedOrder = order;
+        this.mesh.setOrder(order);
+    }
+    /**
+     * Per member, not per def: a def's lines are separate batch members, and the uniform row is
+     * addressed by member. One `dim` on the def therefore writes each of its lines, exactly as
+     * visibility does.
+     * @param slot - The def's group.
+     * @param amount - The encoded amount.
+     */
+    writeDim(slot, amount) {
+        const group = this.groups[slot];
+        if (!group)
+            return;
+        for (const member of group.slots) {
+            super.writeDim(member, amount);
+        }
+    }
+    addInstance(lineCount) {
+        const slot = this.freeGroups.pop() ?? this.groupCount++;
+        const texts = [];
+        const slots = [];
+        for (let line = 0; line < lineCount; line++) {
+            const text = makeMember();
+            texts.push(text);
+            slots.push(this.mesh.addText(text));
+        }
+        this.groups[slot] = { texts, slots };
+        for (const member of slots)
+            this.groupByMember.set(member, slot);
+        return slot;
+    }
+    removeInstance(slot) {
+        const group = this.groups[slot];
+        if (!group)
+            return;
+        for (const member of group.slots)
+            this.groupByMember.delete(member);
+        for (const text of group.texts) {
+            this.mesh.removeText(text);
+            // The member's own `GlyphsGeometry`, which only ever held its bounds — the batch draws from
+            // its own. Nothing was uploaded, so this is bookkeeping, not a GPU free.
+            text.dispose();
+        }
+        this.groups[slot] = undefined;
+        this.freeGroups.push(slot);
+        // Members left the batch's order with them; drop the stale copy so the next pass reapplies.
+        this.appliedOrder = [];
+    }
+}
+/**
+ * Builds a batch member with the properties that never change for its lifetime.
+ *
+ * All three are syncable, so writing them once here — rather than per update — is what keeps a
+ * layout change from re-running troika's async layout and repacking the batch.
+ * @returns The member.
+ */
+function makeMember() {
+    const text = new TextExt();
+    text.fontSize = LAYOUT_FONT_SIZE;
+    text.lineHeight = LINE_HEIGHT;
+    // Wrapping is the floorplan's job: it measures and breaks lines itself, then hands over the
+    // result with explicit newlines. Letting troika re-wrap on top would fight that.
+    text.whiteSpace = 'nowrap';
+    return text;
+}
+/** Returned for an unclaimed slot, so a caller reading one iterates nothing rather than throwing. */
+const EMPTY_GROUP = { texts: [], slots: [] };

package/dist/objects/text/text-layout.d.ts

@@ -0,0 +1,83 @@
+import { type Rect } from '@expofp/geometry';
+import { type TextExt } from '../../core/text/Text';
+import { type TextDef, type TextLineDef } from '../../types/defs';
+/**
+ * The em size every member lays out at, fixed for its lifetime.
+ *
+ * `fontSize` is a syncable property: changing it re-runs troika's async layout and repacks the whole
+ * batch. A label's size changes on every zoom step, so paying that would make zooming a sequence of
+ * repacks. Laying out at a constant 1 em and carrying the real size in the member's `scale` costs a
+ * matrix write instead — the scale is not syncable, so nothing re-lays-out.
+ *
+ * One, not zero: troika reads `this.fontSize || 0.1`, so a member left at zero lays out at a tenth of
+ * an em and every scale below would have to carry a compensating factor of ten.
+ */
+export declare const LAYOUT_FONT_SIZE = 1;
+/** Line box height as a multiple of the font size, matching the `lineHeight` members are given. */
+export declare const LINE_HEIGHT = 1.1;
+/**
+ * A line's placement **in its def's own unrotated frame**, as an offset from the bounds' center.
+ *
+ * Layout stops here on purpose: where the bounds sit in the plan, and how they are turned, is a
+ * separate step ({@link applyPlacement}). Keeping the two apart is what lets the stacking be
+ * asserted as plain numbers, with no trigonometry in the test.
+ */
+export interface LaidOutLine {
+    /** Which horizontal point of the line's box sits at its origin. */
+    anchorX: 'left' | 'center' | 'right';
+    /** Which vertical point of the line's box sits at its origin; only the outer edges are used. */
+    anchorY: 'top' | 'bottom';
+    /** How wrapped rows align against each other within this line. */
+    textAlign: 'left' | 'center' | 'right';
+    /** Offset from the bounds' center along the bounds' own x axis. */
+    offsetX: number;
+    /** Offset from the bounds' center along the bounds' own y axis. */
+    offsetY: number;
+    /** Horizontal scale: the line's font size, which is its em height in plan units. */
+    scaleX: number;
+    /** Vertical scale: negative, because plan space runs y-down and text lays out y-up. */
+    scaleY: number;
+    /** `[minX, minY, maxX, maxY]` in the line's own em space, clipping it to the def's bounds. */
+    clipRect: [number, number, number, number];
+}
+/**
+ * Stacks a text def's lines inside its bounds, aligned as the def asks.
+ *
+ * Works entirely in the bounds' unrotated frame, so a rotated def lays out identically to an
+ * unrotated one — the rotation is applied afterwards, to the whole stack at once. That is also what
+ * lets the clip rect be a plain offset from the center: the member carries the same rotation, so the
+ * rect turns with it.
+ *
+ * **The y flip lives in `scaleY`.** Plan space runs y-down; troika lays text out y-up. Rather than
+ * troika's `orientation` — a `lookAt` rotation, which would leave the clip rect to be flipped
+ * separately — the flip rides on the scale the lines need anyway for their font size, so the clip
+ * rect, which divides by that scale, inherits it for free.
+ *
+ * **Plan units throughout**, font sizes included. A plan that wants a label to hold an on-screen size
+ * converts for itself, against the pixel size the renderer publishes — the same way it sizes every
+ * other pixel-authored thing it draws.
+ * @param def - The text to lay out.
+ * @returns One placement per line, in the def's line order.
+ */
+export declare function layoutText(def: TextDef): LaidOutLine[];
+/**
+ * Writes a laid-out line onto its member: the bounds' rotation and position applied to the local
+ * offset, the line's scale, and its clip rect.
+ *
+ * The post-transform half of {@link layoutText}. `updateMatrix` is what reports the move to the
+ * batch — members are not in the scene graph, so nothing else would.
+ * @param text - The member to place.
+ * @param line - The line's local placement.
+ * @param bounds - The def's bounds, supplying the rotation, center and elevation.
+ */
+export declare function applyPlacement(text: TextExt, line: LaidOutLine, bounds: Rect): void;
+/**
+ * The height one line's box occupies.
+ *
+ * A single `TextLineDef` can hold embedded newlines — the floorplan joins an exhibitor's name rows
+ * into one def — so its box is as many line boxes tall as it has rows.
+ * @param line - The line to measure.
+ * @returns The height, in plan units.
+ */
+export declare function lineHeight(line: TextLineDef): number;
+//# sourceMappingURL=text-layout.d.ts.map

package/dist/objects/text/text-layout.js

@@ -0,0 +1,154 @@
+import { Vector2 } from 'three';
+/**
+ * The em size every member lays out at, fixed for its lifetime.
+ *
+ * `fontSize` is a syncable property: changing it re-runs troika's async layout and repacks the whole
+ * batch. A label's size changes on every zoom step, so paying that would make zooming a sequence of
+ * repacks. Laying out at a constant 1 em and carrying the real size in the member's `scale` costs a
+ * matrix write instead — the scale is not syncable, so nothing re-lays-out.
+ *
+ * One, not zero: troika reads `this.fontSize || 0.1`, so a member left at zero lays out at a tenth of
+ * an em and every scale below would have to carry a compensating factor of ten.
+ */
+export const LAYOUT_FONT_SIZE = 1;
+/** Line box height as a multiple of the font size, matching the `lineHeight` members are given. */
+export const LINE_HEIGHT = 1.1;
+/**
+ * Stacks a text def's lines inside its bounds, aligned as the def asks.
+ *
+ * Works entirely in the bounds' unrotated frame, so a rotated def lays out identically to an
+ * unrotated one — the rotation is applied afterwards, to the whole stack at once. That is also what
+ * lets the clip rect be a plain offset from the center: the member carries the same rotation, so the
+ * rect turns with it.
+ *
+ * **The y flip lives in `scaleY`.** Plan space runs y-down; troika lays text out y-up. Rather than
+ * troika's `orientation` — a `lookAt` rotation, which would leave the clip rect to be flipped
+ * separately — the flip rides on the scale the lines need anyway for their font size, so the clip
+ * rect, which divides by that scale, inherits it for free.
+ *
+ * **Plan units throughout**, font sizes included. A plan that wants a label to hold an on-screen size
+ * converts for itself, against the pixel size the renderer publishes — the same way it sizes every
+ * other pixel-authored thing it draws.
+ * @param def - The text to lay out.
+ * @returns One placement per line, in the def's line order.
+ */
+export function layoutText(def) {
+    const { bounds, lines, alignment, padding } = def;
+    const half = _half.set(bounds.size.x, bounds.size.y).multiplyScalar(0.5);
+    // Where the first line's anchor sits. A centered block starts half the leftover space in from the
+    // top edge, so the stack ends up centered as a whole; every other alignment starts at the padded
+    // edge itself.
+    const offset = _offset.copy(half);
+    if (alignment.vertical === 'center') {
+        let stackHeight = 0;
+        for (const line of lines)
+            stackHeight += lineHeight(line);
+        offset.y -= (bounds.size.y - stackHeight) / 2;
+    }
+    else {
+        offset.sub(_padding.fromArray(padding));
+    }
+    offset.multiply(alignmentFactors(alignment));
+    const placed = [];
+    for (const line of lines) {
+        const scaleX = line.fontSize;
+        // Negative: the y flip. Also why the clip rect below comes out correctly ordered — dividing by a
+        // negative scale swaps its min and max back.
+        const scaleY = -scaleX;
+        placed.push({
+            anchorX: alignment.horizontal,
+            // Only the outer edges: a middle-anchored line would stack against its own center, so the
+            // block's vertical alignment is carried by the starting offset above instead.
+            anchorY: alignment.vertical === 'bottom' ? 'bottom' : 'top',
+            textAlign: alignment.text ?? alignment.horizontal,
+            offsetX: offset.x,
+            offsetY: offset.y,
+            scaleX,
+            scaleY,
+            // The bounds' corners relative to this line's origin, converted from plan units into the
+            // line's em space. A zero-size line would divide by zero, but those are hidden before they
+            // draw (see `TextInstance`), so the clip rect is never read.
+            clipRect: [
+                (-half.x - offset.x) / scaleX,
+                (half.y - offset.y) / scaleY,
+                (half.x - offset.x) / scaleX,
+                (-half.y - offset.y) / scaleY,
+            ],
+        });
+        offset.y += lineHeight(line);
+    }
+    return placed;
+}
+/**
+ * Writes a laid-out line onto its member: the bounds' rotation and position applied to the local
+ * offset, the line's scale, and its clip rect.
+ *
+ * The post-transform half of {@link layoutText}. `updateMatrix` is what reports the move to the
+ * batch — members are not in the scene graph, so nothing else would.
+ * @param text - The member to place.
+ * @param line - The line's local placement.
+ * @param bounds - The def's bounds, supplying the rotation, center and elevation.
+ */
+export function applyPlacement(text, line, bounds) {
+    const { rotation } = bounds;
+    const position = _position
+        .set(line.offsetX, line.offsetY)
+        .rotateAround(ORIGIN, rotation)
+        .add(bounds.center);
+    text.position.set(position.x, position.y, bounds.elevation);
+    text.rotation.set(0, 0, rotation);
+    text.scale.set(line.scaleX, line.scaleY, 1);
+    text.updateMatrix();
+    // Held as one array for the member's life: `clipRect` is not a syncable property, so this is a
+    // plain per-frame read and mutating it in place avoids a per-update allocation.
+    const clipRect = (text.clipRect ??= [0, 0, 0, 0]);
+    clipRect[0] = line.clipRect[0];
+    clipRect[1] = line.clipRect[1];
+    clipRect[2] = line.clipRect[2];
+    clipRect[3] = line.clipRect[3];
+}
+/**
+ * The height one line's box occupies.
+ *
+ * A single `TextLineDef` can hold embedded newlines — the floorplan joins an exhibitor's name rows
+ * into one def — so its box is as many line boxes tall as it has rows.
+ * @param line - The line to measure.
+ * @returns The height, in plan units.
+ */
+export function lineHeight(line) {
+    return line.fontSize * LINE_HEIGHT * line.text.split('\n').length;
+}
+/**
+ * Which way each axis is offset from the bounds' center for a given alignment.
+ *
+ * Vertical `center` shares `top`'s factor deliberately: a centered block still stacks downward from
+ * a start position, and it is that start position the caller moves.
+ * @param alignment - The def's alignment.
+ * @returns The scratch factors, valid until the next call.
+ */
+function alignmentFactors(alignment) {
+    return _factors.set(HORIZONTAL_FACTORS[alignment.horizontal], VERTICAL_FACTORS[alignment.vertical]);
+}
+/** Which edge a horizontal alignment offsets toward: `-1` left, `0` centered, `1` right. */
+const HORIZONTAL_FACTORS = {
+    left: -1,
+    center: 0,
+    right: 1,
+};
+/** Which edge a vertical alignment offsets toward; `center` shares `top`'s sign (see above). */
+const VERTICAL_FACTORS = {
+    top: -1,
+    center: -1,
+    bottom: 1,
+};
+/**
+ * Scratch reused across calls: layout runs once per def per update and never escapes a synchronous
+ * block, so it allocates nothing.
+ */
+const _half = new Vector2();
+const _offset = new Vector2();
+const _padding = new Vector2();
+const _factors = new Vector2();
+const _position = new Vector2();
+/** The point a rotated block turns about — its own bounds center, which the offsets are relative to. */
+const ORIGIN = new Vector2(0, 0);

package/dist/space/Camera.d.ts

@@ -0,0 +1,103 @@
+import { type Box } from '@expofp/geometry';
+import { type PropsWithChildren } from 'react';
+/**
+ * How far the camera may go: the limits every move is held to, dragged or programmatic.
+ *
+ * Distinct from what a *user* may do, which is `ControlsConfig` — a caller switches a gesture off
+ * without changing where the camera may go, and constrains the camera without taking a gesture
+ * away. `RendererProps` carries both, and these are the half that ends up here.
+ *
+ * Every one is optional and defaulted where it is used, a few lines below, so nothing else in the
+ * renderer has to know or import what an omitted limit means.
+ */
+export interface CameraProps {
+    /**
+     * How far the plan may be zoomed out, as a factor of the framing that fits the whole viewbox;
+     * defaults to `0.1`. Which viewbox zoom factor `1` frames is the {@link Space}'s business, not
+     * this component's — all it needs is the bounds.
+     */
+    minZoom?: number;
+    /**
+     * How far the plan may be zoomed in, as a factor of the framing that fits the whole viewbox;
+     * defaults to `35`.
+     */
+    maxZoom?: number;
+    /**
+     * The shallowest the plan may be pitched away from face-on, in degrees — `0` looks straight down
+     * at it; defaults to `0`.
+     */
+    minPitch?: number;
+    /**
+     * The steepest the plan may be pitched away from face-on, in degrees; defaults to
+     * {@link MAX_PITCH}, which is also the most that may be asked for — the depth guarantee is sized
+     * against that angle, so a steeper view is one it never allowed for.
+     */
+    maxPitch?: number;
+    /**
+     * Where the camera may look: the region its target is held inside, in plan units. Omitted — the
+     * default — lets it look anywhere.
+     *
+     * A limit like the four above rather than a command, which is what makes it a prop: a host whose
+     * bounds follow the floor on show changes them by rendering, with no reaction to write.
+     */
+    bounds?: Box;
+    /**
+     * How long a programmatic move takes to settle; see {@link SmoothTime}. Any duration left out
+     * takes {@link DEFAULT_SMOOTH_TIME}, so this prop always says the whole truth rather than adding
+     * to what was set before.
+     *
+     * Only programmatic moves: how a *dragged* one feels is the gesture's business and is set where
+     * the controls are mounted.
+     */
+    smoothTime?: SmoothTime;
+}
+/**
+ * How long each kind of programmatic camera move takes to settle, in seconds.
+ *
+ * Named for what a caller asked the plan to do rather than for how `camera-controls` does it, which
+ * is why this is the renderer's own type and not the library's: a host turning the plan asked for a
+ * roll*, and has no reason to know that it is driven by an azimuth. The same four durations the
+ * imperative renderer took, under the same four names.
+ */
+export interface SmoothTime {
+    /** How long {@link CameraAPI.zoomTo} and {@link CameraAPI.zoomBy} take. */
+    zoomTime?: number;
+    /** How long {@link CameraAPI.panTo} and {@link CameraAPI.panBy} take. */
+    panTime?: number;
+    /** How long {@link CameraAPI.rollTo} and {@link CameraAPI.rollBy} take. */
+    rollTime?: number;
+    /** How long {@link CameraAPI.pitchTo} and {@link CameraAPI.pitchBy} take. */
+    pitchTime?: number;
+}
+/**
+ * The camera the plan is drawn through, and the zoom that camera is read as.
+ *
+ * Everything the imperative renderer's camera system did, with one simplification the viewbox fit
+ * pays for: because {@link Space} sizes a world unit to a device pixel, the distance that frames the
+ * plan follows from the drawing buffer alone and none of the arithmetic here has to know what the
+ * scene holds. The near plane is the one exception, its guarantee being stated in plan units.
+ *
+ * **Zoom is the state and distance is derived.** The camera stores a distance, which the buffer
+ * height converts to a factor — so a resize would silently change the zoom if nothing held it. This
+ * remembers the factor and dollies back to it, which is what the imperative renderer kept a previous
+ * viewport height for; a user dolly writes the factor back on the controls' own update.
+ *
+ * **The one thing it needs from the scene is `space.scale`,** and only for the near plane. The
+ * imperative renderer kept its camera and scene independent because it applied its depth guarantee
+ * to world distances; that guarantee is stated in plan units, so converting it is what makes it hold
+ * on a plan drawn at any scale (see {@link nearPlane}). Nothing else here reads the scene.
+ *
+ * **All four limits are written here**, zoom and pitch alike, because they are the same kind of
+ * thing: a constraint on where the camera may go, holding for a programmatic move as much as for a
+ * dragged one. What the *user* may do is `Controls`'s business and nothing to do with these. Keeping
+ * them together also puts each limit beside the clipping plane derived from it — `maxPolarAngle`
+ * sizes the near plane, the maximum distance the far one.
+ *
+ * Configures R3F's camera rather than replacing it, which leaves `aspect` to R3F — it writes that on
+ * every resize, from the same size this reads. Mutations go through the store getter because the
+ * React Compiler refuses to lower a write to anything a hook returned.
+ * @param props - How far the plan may be zoomed and pitched, and what should reach the handle.
+ * @returns The children, under the camera handle.
+ */
+export declare function Camera(props: PropsWithChildren<CameraProps>): import("react").JSX.Element;
+//# sourceMappingURL=Camera.d.ts.map