@expofp/renderer 0.0.0-experimental.cf063fc

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,234 @@
+import { type Box, type LineLike, type Rect, type Shape } from '@expofp/geometry';
+import { type LayoutHandlers, type LayoutView, type PointerHandlers } from './events';
+/** A color as a CSS string or a packed number. */
+export type ColorInput = string | number;
+/**
+ * An image the renderer can upload as a texture. Pass fetched images as a `Blob`: the renderer
+ * decodes it off the main thread. `HTMLImageElement` and URL strings are not accepted.
+ */
+export type ImageSource = HTMLCanvasElement | ImageBitmap | OffscreenCanvas | Blob;
+/** Scene definition. */
+export interface SceneDef {
+    /** The root layer of the scene tree. */
+    rootLayer: LayerDef;
+    /** The background color. */
+    background?: ColorInput;
+    /** The SVG viewbox. */
+    viewbox: Box;
+    /**
+     * A plan-to-world matrix that replaces the viewbox fit, in the host's coordinates. It must keep
+     * plan space's handedness.
+     */
+    staticTransform?: number[];
+}
+/** Fields every renderable def shares. */
+export interface SharedDef extends LayoutHandlers {
+    /** Whether the def is hidden. */
+    hidden?: boolean;
+    /**
+     * How much the def is dimmed, from `0` (none) to `1` (full). `undefined` inherits from the
+     * nearest ancestor, so a def can set `0` to stay undimmed inside a dimmed layer. Animate it
+     * freely: a change costs one uniform write per layer.
+     */
+    dim?: number;
+}
+/** Any def that can be rendered into a scene. */
+export type RenderableDef = LayerDef | ShapeDef | ImageDef | TextDef | LineDef | ModelDef;
+/** An array of one {@link RenderableDef} kind. Mixed arrays do not type-check. */
+export type RenderableDefCollection<T = RenderableDef> = T extends RenderableDef ? T[] : never;
+/**
+ * Layer definition. Its {@link PointerHandlers} make its subtree pickable, and its
+ * {@link LayoutHandlers} run like any other def's.
+ */
+export interface LayerDef<T extends RenderableDef = RenderableDef> extends SharedDef, PointerHandlers<T> {
+    /** The layer's name. */
+    readonly name: string;
+    /** The layer's children, all of one kind. */
+    children: RenderableDefCollection<T>;
+    /**
+     * Draws the subtree above 3D content, with depth testing off. For flat content only: solid
+     * shapes and models ignore it. Descendants cannot opt out.
+     */
+    overlay?: boolean;
+    /**
+     * Placement defs compete only with defs in layers that share this key. Without it, the layer
+     * competes only with itself. Prefix the key with its owner.
+     */
+    collisionGroup?: string;
+    /**
+     * Turns collisions in this layer's collision scope into clusters. Both colliding defs are hidden
+     * through their own `onPlace`, and the cluster is reported to {@link ClusterOptions.onCluster}.
+     */
+    clustering?: ClusterOptions;
+}
+/** Clustering options of a layer. */
+export interface ClusterOptions {
+    /**
+     * The size of the marker you draw for a cluster. Any def or cluster that this marker would
+     * cover joins the cluster. Without it, the marker takes the size of the cluster's first member.
+     * When several clustering layers share a scope, the first layer's marker is used.
+     */
+    marker?: ClusterMarker;
+    /**
+     * Receives the full current set of clusters whenever it changes. A layer that loses all its
+     * clusters receives an empty array once.
+     *
+     * Changes are held while the plan moves on screen and are reported once it has stood still for a
+     * moment. A registration, an unregistration or a def whose bounds you update is reported at once.
+     * `onPlace` calls arrive first, in the same synchronous call.
+     *
+     * Return the defs that changed. Never call `update()` here. Keep the options object stable: a
+     * new object is not noticed while the set stays the same.
+     * @param clusters - A new array on each call, in placement order.
+     * @param view - The current camera view.
+     * @returns The defs that changed, or nothing.
+     */
+    onCluster(this: void, clusters: readonly Cluster[], view: LayoutView): readonly RenderableDef[] | void;
+}
+/** The screen box of a cluster's marker. */
+export interface ClusterMarker {
+    /** The width in CSS pixels. */
+    width: number;
+    /** The height in CSS pixels. */
+    height: number;
+    /** The point that stands on the cluster's anchor, as in {@link ImageDef.origin}. */
+    origin?: [number, number];
+}
+/** One cluster of colliding defs. */
+export interface Cluster {
+    /** How many units it holds, at least two. A `placement.group` counts as one unit. */
+    readonly unitCount: number;
+    /** The mean x of the units' anchors, in plan units. */
+    readonly x: number;
+    /** The mean y of the units' anchors, in plan units. */
+    readonly y: number;
+    /** The greatest elevation of its members, in plan units. */
+    readonly elevation: number;
+}
+/**
+ * How a def competes for room on screen.
+ *
+ * - `never` (default): it is placed only where nothing placed before covers it, and then it
+ *   blocks the defs after it.
+ * - `always`: it is always placed, blocks nothing and never clusters. In a group, it takes the
+ *   group's verdict.
+ */
+export type OverlapMode = 'never' | 'always';
+/** Placement options of a screen-space def. */
+export interface PlacementOptions {
+    /**
+     * Receives the placement verdict: on the first pass after the def registers, then each time the
+     * verdict changes. Changes are reported when the camera stops, as for
+     * {@link ClusterOptions.onCluster}.
+     *
+     * Return the defs that changed. Never call `update()` here.
+     * @param placed - Whether the def got room on screen.
+     * @param view - The current camera view.
+     * @returns The defs that changed, or nothing.
+     */
+    onPlace(this: void, placed: boolean, view: LayoutView): readonly RenderableDef[] | void;
+    /**
+     * Defs that share this key compete and cluster as one unit, with the union of their boxes. All
+     * members get the same verdict. The first member in order sets the unit's priority. Keys apply
+     * per collision scope. Prefix the key with its owner, and unregister old defs before you reuse
+     * their key.
+     */
+    group?: string;
+    /** CSS pixels added around the tested box: one value, or `[horizontal, vertical]`. */
+    padding?: number | [number, number];
+    /** How the def competes. Defaults to `never`. */
+    overlap?: OverlapMode;
+}
+/** Fields of the def kinds that can face the camera: {@link ImageDef} and {@link TextDef}. */
+export interface ScreenSpaceDef extends SharedDef {
+    /**
+     * Faces the def toward the camera. It pivots about `bounds.center` at `bounds.elevation`, sized
+     * by `bounds.size` in plan units. `bounds.rotation` spins it in the screen plane. Use an
+     * `onScale` rule to keep a constant pixel size.
+     */
+    screenSpace?: boolean;
+    /**
+     * Enters the def into the placement pass, which hides it where a def earlier in order already
+     * covers the screen. Works only when {@link screenSpace} is true.
+     */
+    placement?: PlacementOptions;
+}
+/** Shape definition. */
+export interface ShapeDef extends SharedDef {
+    /**
+     * The shape to render. To change it, assign a new `Shape` and call `update(def)`. A polygon
+     * changed in place does not rebuild.
+     */
+    shape: Shape;
+    /** The shape's color. */
+    color: ColorInput;
+}
+/** Image definition. */
+export interface ImageDef extends ScreenSpaceDef {
+    /** The image source. Fixed for the def's life: use a new def for a new image. */
+    readonly source: ImageSource;
+    /** The image's bounds. */
+    bounds: Rect;
+    /**
+     * The point of the image that `bounds.center` names. `[0, 0]` is the top-left corner,
+     * `[0.5, 0.5]` the center (default), `[1, 1]` the bottom-right corner.
+     */
+    origin?: [number, number];
+    /** How opaque the image is, from `0` to `1`. Defaults to `1`. It blends as alpha does. */
+    opacity?: number;
+}
+/** Text definition. */
+export interface TextDef extends ScreenSpaceDef {
+    /** The text lines, stacked inside {@link bounds}. A line with `fontSize` `0` is not drawn. */
+    lines: TextLineDef[];
+    /** The text's bounds. */
+    bounds: Rect;
+    /** The text's padding, `[horizontal, vertical]`. */
+    padding: [number, number];
+    /** How the text is aligned. */
+    alignment: TextAlignment;
+}
+/** One line of a text def. */
+export interface TextLineDef {
+    /** The line's text. */
+    text: string;
+    /** The line's color. */
+    color: ColorInput;
+    /** The font URL. Not updatable. Supports .ttf, .otf and .woff, not .woff2. */
+    fontUrl: string;
+    /** The em height in plan units. `0` hides the line. */
+    fontSize: number;
+    /** The stroke color, and its width in the same units as {@link fontSize}. */
+    stroke?: {
+        color: ColorInput;
+        width: number;
+    };
+}
+/** Text alignment. */
+export interface TextAlignment {
+    /** The horizontal alignment. */
+    horizontal: 'left' | 'center' | 'right';
+    /** The vertical alignment. */
+    vertical: 'top' | 'center' | 'bottom';
+    /** The alignment of text inside a line. */
+    text?: 'left' | 'center' | 'right';
+}
+/** Line definition. */
+export interface LineDef extends SharedDef {
+    /** The endpoints, with an optional elevation. Assign a new value and call `update(def)`. */
+    points: LineLike;
+    /** The line's color. */
+    color: ColorInput;
+    /** The width in screen pixels, constant at every zoom. `0` draws nothing. */
+    width: number;
+}
+/** External 3D model definition. */
+export interface ModelDef extends SharedDef {
+    /** The model URL. Not updatable. */
+    url: string;
+    /** The model's bounds. */
+    bounds: Rect;
+    /** The model's opacity, from `0` to `1`. */
+    opacity?: number;
+}
+//# sourceMappingURL=defs.d.ts.map

package/dist/types/defs.js

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

package/dist/types/events.d.ts

@@ -0,0 +1,198 @@
+import { type PlanPoint } from '../space/Space';
+import { type LayerDef, type RenderableDef } from './defs';
+/**
+ * The def one of a layer's {@link PointerHandlers} is handed: a content layer's own child type, and —
+ * because a layer whose children are layers stands above every kind — any renderable at all for one
+ * of those. Never a {@link LayerDef} in practice: a hit resolves to the primitive under the pointer.
+ */
+export type SubtreeDef<T extends RenderableDef> = T extends LayerDef ? RenderableDef : T;
+/** A pointer event delivered to one of a layer's {@link PointerHandlers}. */
+export interface PointerEventData<T extends RenderableDef = RenderableDef> {
+    /**
+     * The def under the pointer — the nearest hit inside the subtree of the layer whose handler is
+     * running. A hit the renderer cannot trace back to a def is dropped rather than reported, so this
+     * is never absent.
+     */
+    def: SubtreeDef<T>;
+    /**
+     * Where the pointer struck {@link def}, in plan units — the ray's own intersection with the
+     * geometry, taken back into plan space, so `z` is the elevation it was drawn at and a click on the
+     * roof of a raised model reports the roof.
+     *
+     * The same kind of answer {@link PointerMissedEventData} carries, which searches the scene for
+     * itself. A caller that wants the floor coordinate under an elevated hit instead — "which square
+     * metre of the hall is this" rather than "what did I touch" — converts the canvas position through
+     * `ViewportAPI.canvasToPlan`, which crosses the plan plane on purpose.
+     *
+     * A fresh instance per event, so keeping a reference to it is safe.
+     */
+    point: PlanPoint;
+    /**
+     * Ends the event's delivery: neither the ancestors of the layer whose handler is running nor any
+     * def farther along the ray receives it. A handler that wants only the nearest of several
+     * overlapping defs calls this.
+     */
+    stopPropagation(): void;
+    /** The DOM event this was dispatched from. */
+    nativeEvent: MouseEvent;
+}
+/**
+ * A click that reached no layer handler — empty background, or a def whose layer declares no
+ * handlers and so is not picked at all. Delivered to the renderer's `onPointerMissed`.
+ */
+export interface PointerMissedEventData {
+    /**
+     * Where the click landed, in plan units — the nearest geometry under the pointer, with the
+     * elevation it was struck at, exactly as {@link PointerEventData.point} reports for a hit.
+     *
+     * **Reaching no handler is not the same as striking nothing.** A layer declaring no pointer
+     * handlers is never raycast, so a click arrives here as readily from the middle of a wall as from
+     * open background. The scene is searched along the same ray to tell those apart, and only the case
+     * that really is empty — past the edge of every piece of geometry — falls back to where the ray
+     * crosses the plan plane (`z = 0`).
+     */
+    point: PlanPoint;
+    /** The DOM event this was dispatched from. */
+    nativeEvent: MouseEvent;
+}
+/**
+ * The pointer handlers a {@link LayerDef} may carry. Kept apart from {@link LayoutHandlers} so that
+ * `keyof PointerHandlers` is exactly the dispatchable names.
+ *
+ * **Declaring one is what makes a layer interactive.** A layer with none is never raycast; a layer
+ * with any is raycast together with its whole subtree; a layer that is off screen — hidden, or under
+ * something hidden — is not picked at all.
+ *
+ * **Events travel upward and away.** The nearest def's layer handler runs first, then each ancestor
+ * that declares the same handler, then the next def along the ray, until one calls
+ * {@link PointerEventData.stopPropagation}; `event.def` stays the def that was hit. Overlapping defs
+ * deliver one event apiece, even within one layer. Defs at the same distance, such as coplanar flat
+ * defs, arrive in the order their slots were claimed (mount order), not paint order;
+ * `Pointer/Overlap` pins that.
+ *
+ * **Everything else occludes.** Geometry in a layer with no handlers is never hit itself, but it
+ * hides the defs behind it, opaque or translucent: a booth behind a wall or a model receives no
+ * event, and a click there is a miss. Geometry coplanar with a def, such as its label, does not
+ * hide it.
+ *
+ * **Handlers return nothing.** One that mutates defs calls `update()` afterward, like any other code.
+ *
+ * **Handlers take no receiver.** They are read off the layer and called as plain functions —
+ * `this: void` makes reading `this` a compile error rather than an `undefined` at runtime — so a
+ * handler shared across layers keys off `event.def`. Declared as methods rather than function-typed
+ * fields on purpose: a method's parameters are checked bivariantly, which is what keeps a
+ * `LayerDef<ShapeDef>` assignable to a plain `RenderableDef`.
+ */
+export interface PointerHandlers<T extends RenderableDef = RenderableDef> {
+    /**
+     * Called for a click on a def in this layer — a press and release that stayed within a few pixels,
+     * so a pan gesture ending over a def does not click it.
+     * @param event - The def that was clicked, and where.
+     */
+    onClick?(this: void, event: PointerEventData<T>): void;
+    /**
+     * Called while the pointer is over a def in this layer, on every move it stays over one, including
+     * the move that first entered it.
+     * @param event - The def under the pointer, and where.
+     */
+    onPointerMove?(this: void, event: PointerEventData<T>): void;
+    /**
+     * Called when the pointer leaves the def it was over, naming that def — so a handler mirroring
+     * hover state clears it here.
+     * @param event - The def the pointer left, and where the pointer was.
+     */
+    onPointerOut?(this: void, event: PointerEventData<T>): void;
+}
+/** The pointer handlers by name, so dispatch can name one without repeating the list. */
+export type PointerHandlerName = keyof PointerHandlers;
+/** A def's re-layout handler, named so a caller can annotate one apart from the def it serves. */
+export type ScaleHandler = NonNullable<LayoutHandlers['onScale']>;
+/** A def's counter-rotation handler, named like {@link ScaleHandler}. */
+export type RollHandler = NonNullable<LayoutHandlers['onRoll']>;
+/**
+ * What the camera currently shows, as a layout rule sees it — every {@link LayoutHandlers} handler
+ * receives the same view, whichever axis's move invoked it, so a rule that turns a label can re-fit
+ * it at the size it is drawn at without asking anyone.
+ *
+ * **Valid during the call.** The registry reuses one instance across a sweep, so destructure or
+ * copy what you need rather than retaining the object.
+ */
+export interface LayoutView {
+    /**
+     * How much of the plan one CSS pixel spans, in plan units — the factor anything sized in
+     * pixels is laid out against, and the quantity the imperative renderer published as `ptScale`.
+     *
+     * CSS pixels, so a size authored in them comes out the same at every screen density. The device
+     * ratio never reaches a rule because a rule never needs it: the ratio sets how crisp a def is
+     * drawn, not how big.
+     */
+    readonly pixelSize: number;
+    /**
+     * Which way the plan is turned, in **radians** clockwise from north — the same quantity, in the
+     * same unit, the imperative renderer's `navigation:roll` event carried, so ported rules keep the
+     * quarter-turn thresholds they were written against. (`CameraState.roll` reports the same angle
+     * in degrees, for people; rules get the unit their arithmetic wants.)
+     */
+    readonly roll: number;
+}
+/**
+ * The layout handlers a def may carry — camera-driven rules that re-derive a def's geometry, one
+ * per axis the camera moves on: `onScale` for the pixel size, `onRoll` for the turn. Both receive
+ * the same {@link LayoutView}.
+ *
+ * Where {@link PointerHandlers} hang off the layer that gets picked — picking is a query over a
+ * subtree — a layout handler hangs off the one def it lays out, a layer included (which is how a
+ * layer whose *membership* depends on the camera re-derives it), and never propagates: a def's
+ * geometry has exactly one owner.
+ *
+ * A handler takes no def parameter: it is typically a closure built where its def is built, closing
+ * over the def or the plan-lived object that owns it. **What such a closure captures is the one
+ * thing to watch.** Defs live for the plan's lifetime, so a handler must capture nothing
+ * shorter-lived than the def — an owner alive as long as the plan is safe, since the closure then
+ * retains nothing the def was not already keeping alive, while a build-time temporary (a parse
+ * buffer, a raw config) captured even incidentally would stay pinned in memory for as long as the
+ * def exists. Should defs ever stop being built by plan-lived owners, keep that property by moving
+ * per-def data onto the defs themselves and capturing only the def.
+ */
+export interface LayoutHandlers {
+    /**
+     * Lays the def this handler is declared on out for a new pixel size — the hook everything sized
+     * in pixels rather than plan units hangs off: label font steps, badge and marker rescaling, a
+     * bookmark's clamp.
+     *
+     * Called once when the def is first registered, and again whenever the pixel size moves — hidden
+     * defs included, since whether a def draws at all can be exactly what its rule decides (a booth's
+     * dot appears only once the plan is far enough out for its label to stop fitting).
+     *
+     * **Returns what changed, and the renderer writes it** by the cheapest route that is correct for
+     * each def: a layer is reconciled, anything else goes straight into its slot with no render — what
+     * makes it affordable for every label on a plan to re-lay out while the camera moves. Return
+     * nothing when nothing changed and the write — the expensive half — is skipped; the def still
+     * counts as laid out either way. Do not call `update()` here: returning *is* this handler's
+     * update.
+     *
+     * Called as a plain function with no receiver, like the pointer handlers.
+     * @param view - What the camera shows; multiply pixel-authored sizes by `view.pixelSize`.
+     * @returns The defs that changed and need writing, or nothing.
+     */
+    onScale?(this: void, view: LayoutView): readonly RenderableDef[] | void;
+    /**
+     * Lays the def out for a new camera roll — the hook everything that stays upright, or snaps to the
+     * nearest cardinal direction, hangs off: label and bookmark counter-rotation, a badge walking its
+     * anchor corner, a marker turning with the plan.
+     *
+     * Called once when the def is first registered — so a def added while the plan is turned is
+     * correct before its first paint — and again whenever the roll moves at all. There is no epsilon:
+     * the rules themselves step in quarter turns, so nearly every call returns nothing, exactly as the
+     * imperative renderer's `navigation:roll` handlers did.
+     *
+     * The same write contract as {@link onScale}: return what changed, return nothing when nothing
+     * did, and never call `update()` here. Called as a plain function with no receiver.
+     * @param view - What the camera shows — `view.roll` is the angle to lay out against, and
+     *   `view.pixelSize` rides along because a rule that turns a label re-fits it at the size it is
+     *   currently drawn at.
+     * @returns The defs that changed and need writing, or nothing.
+     */
+    onRoll?(this: void, view: LayoutView): readonly RenderableDef[] | void;
+}
+//# sourceMappingURL=events.d.ts.map

package/dist/types/events.js

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

package/dist/types/guards.d.ts

@@ -0,0 +1,21 @@
+import { type ImageDef, type LayerDef, type LineDef, type ModelDef, type RenderableDef, type RenderableDefCollection, type ShapeDef, type TextDef } from './defs';
+export declare function isShapeDef(def: RenderableDef): def is ShapeDef;
+export declare function isImageDef(def: RenderableDef): def is ImageDef;
+export declare function isTextDef(def: RenderableDef): def is TextDef;
+export declare function isLineDef(def: RenderableDef): def is LineDef;
+export declare function isModelDef(def: RenderableDef): def is ModelDef;
+export declare function isLayerDef(def: RenderableDef): def is LayerDef;
+/**
+ * Whether a def takes part in the placement pass: it declares placement options, and it faces the
+ * camera. A flat def carrying options is not a target, which is what the pass warns about.
+ * @param def - The def to test.
+ * @returns Whether the pass tests it.
+ */
+export declare function isPlacementTarget(def: RenderableDef): def is ImageDef | TextDef;
+export declare function isLayerDefs(defs: Readonly<RenderableDefCollection>): defs is readonly LayerDef[];
+export declare function isShapeDefs(defs: Readonly<RenderableDefCollection>): defs is readonly ShapeDef[];
+export declare function isImageDefs(defs: Readonly<RenderableDefCollection>): defs is readonly ImageDef[];
+export declare function isTextDefs(defs: Readonly<RenderableDefCollection>): defs is readonly TextDef[];
+export declare function isLineDefs(defs: Readonly<RenderableDefCollection>): defs is readonly LineDef[];
+export declare function isModelDefs(defs: Readonly<RenderableDefCollection>): defs is readonly ModelDef[];
+//# sourceMappingURL=guards.d.ts.map

package/dist/types/guards.js

@@ -0,0 +1,52 @@
+export function isShapeDef(def) {
+    return def.shape !== undefined;
+}
+export function isImageDef(def) {
+    return def.source !== undefined;
+}
+export function isTextDef(def) {
+    return def.lines !== undefined;
+}
+export function isLineDef(def) {
+    return def.points !== undefined;
+}
+export function isModelDef(def) {
+    return def.url !== undefined;
+}
+export function isLayerDef(def) {
+    return def.children !== undefined;
+}
+/**
+ * Whether a def takes part in the placement pass: it declares placement options, and it faces the
+ * camera. A flat def carrying options is not a target, which is what the pass warns about.
+ * @param def - The def to test.
+ * @returns Whether the pass tests it.
+ */
+export function isPlacementTarget(def) {
+    const target = def;
+    return target.placement !== undefined && target.screenSpace === true;
+}
+// The array guards below take the collection type, not `readonly RenderableDef[]`: the collection
+// is a union of single-kind arrays, so a first-element check is sound for the whole array. A plain
+// `RenderableDef[]` parameter would admit mixed arrays the check cannot speak for. The `Readonly`
+// wrapper widens, not narrows: mutable collections are assignable to readonly parameters (and
+// narrowing a mutable union member keeps it mutable), while the reverse would reject the readonly
+// snapshots from `useStagedChildren`.
+export function isLayerDefs(defs) {
+    return defs[0] !== undefined && isLayerDef(defs[0]);
+}
+export function isShapeDefs(defs) {
+    return defs[0] !== undefined && isShapeDef(defs[0]);
+}
+export function isImageDefs(defs) {
+    return defs[0] !== undefined && isImageDef(defs[0]);
+}
+export function isTextDefs(defs) {
+    return defs[0] !== undefined && isTextDef(defs[0]);
+}
+export function isLineDefs(defs) {
+    return defs[0] !== undefined && isLineDef(defs[0]);
+}
+export function isModelDefs(defs) {
+    return defs[0] !== undefined && isModelDef(defs[0]);
+}

package/dist/update/index.d.ts

@@ -0,0 +1,3 @@
+export { registerSlotWriter, syncNow, writeChanged } from './slot-writers';
+export { childrenOf, subscribeDef, update, versionOf } from './store';
+//# sourceMappingURL=index.d.ts.map

package/dist/update/index.js

@@ -0,0 +1,2 @@
+export { registerSlotWriter, syncNow, writeChanged } from './slot-writers';
+export { childrenOf, subscribeDef, update, versionOf } from './store';

package/dist/update/slot-writers.d.ts

@@ -0,0 +1,30 @@
+import { type RenderableDef } from '../types/defs';
+/**
+ * Registers a def's sync closure, paired with the frame request that shows what it writes.
+ *
+ * The two are registered together rather than left to each caller because a slot write nobody asked
+ * a frame for is invisible: the renderer runs a demand frameloop, so the write lands in GPU memory
+ * and waits for a frame that never comes. Pairing them here is what makes every write path — React's
+ * and the frame loop's — correct without remembering anything. The frame loop's writes ask for a
+ * frame they are already inside, which costs one more after the camera stops.
+ * @param def - The def the instance component renders.
+ * @param sync - Writes the def's current state into its slot.
+ * @param invalidate - Requests the frame that draws it.
+ * @returns An unregister function, which removes this writer and leaves the def's others alone.
+ */
+export declare function registerSlotWriter(def: RenderableDef, sync: () => void, invalidate: () => void): () => void;
+/**
+ * Runs every write registered for a def — each of its slots, and the frame that draws them. A no-op
+ * for defs that are not mounted.
+ * @param def - The def to re-sync.
+ */
+export declare function syncNow(def: RenderableDef): void;
+/**
+ * Writes the defs a layout handler reported changed, by the cheapest route that is correct for
+ * each: a layer means its membership moved, which only React can reconcile, while anything else is
+ * a field write that goes straight into the slot, with no render at all behind the frame that draws
+ * it. This is what a layout handler returning defs buys — see `LayoutHandlers.onScale`.
+ * @param defs - The defs the handler reported changed, or nothing when it changed nothing.
+ */
+export declare function writeChanged(defs: readonly RenderableDef[] | undefined): void;
+//# sourceMappingURL=slot-writers.d.ts.map