@expofp/renderer 0.0.0-experimental.2d6c681

package/dist/objects/containers/hooks.d.ts

@@ -0,0 +1,61 @@
+import { type RefObject } from 'react';
+import { type RenderableDef } from '../../types/defs';
+import { type SlotContainer, type SlotMesh } from './SlotContainer';
+/**
+ * Creates one layer's container and keeps it wired to its layer for as long as the component is
+ * mounted: the membership's paint order, how hits on its mesh resolve back to defs, and what runs
+ * when a member no longer belongs in this container's kind.
+ *
+ * The container is built once, from the first render's defs, and outlives every render after —
+ * membership changes grow it in place rather than rebuilding it, which is what lets the mesh R3F
+ * built from its args stand too. `create` is therefore called once and its later identities ignored.
+ * @param create - Builds the container. Called on the first render only.
+ * @param defs - The layer's defs, in authored paint order.
+ * @param onKindMismatch - Re-splits the layer, for a container that finds a member of the wrong
+ *   kind. Registered as {@link SlotContainer.setKindMismatchHandler} and cleared on unmount or
+ *   before a new identity replaces it. A container with no kind of its own to leave omits it, and
+ *   nothing is registered.
+ * @returns The container.
+ */
+export declare function useContainer<T extends RenderableDef, C extends SlotContainer<unknown, SlotMesh, T>>(create: () => C, defs: readonly T[], onKindMismatch?: () => void): C;
+/**
+ * Claims a slot for one instance, releasing on unmount. Paint order is not this hook's concern —
+ * the container writes it for the whole sibling list in one pass (see {@link useContainer}).
+ * @param container - The container holding the slot.
+ * @param def - The def this instance renders.
+ * @param resource - The per-instance resource backing the slot; a new identity re-claims.
+ * @returns A ref holding the current slot, or `-1` while unclaimed. Read it at call time — a
+ *   re-claim changes the slot without re-rendering.
+ */
+export declare function useSlot<R>(container: SlotContainer<R>, def: RenderableDef, resource: R): RefObject<number>;
+/**
+ * Claims a slot for one instance and keeps it in sync with its def: the slot is released on
+ * unmount, and on mount and after every `update(def)` the def's visibility and dim are written and —
+ * only while it is visible — `write` fills in the rest of the instance's state.
+ *
+ * The sync is registered as the def's slot writer, so it is also what the camera re-layout frame
+ * loop pulls out of `slotWriters` and calls directly — the React path and the per-frame path are
+ * one implementation, and both therefore agree about visibility.
+ *
+ * `hidden` and `dim` live on every def type, so their writes — and the short-circuit `hidden` gates
+ * — belong here rather than repeated in each instance component's callback. A hidden instance is
+ * never drawn, so computing its transform, color, or glyphs would be wasted; the update that shows
+ * it re-runs this sync, which writes the then-current state. Everything type-specific stays in
+ * `write`, which is what keeps this hook generic across every def type.
+ *
+ * **An `update(def)` renders nothing unless the slot's resource moved.** The only thing a render of
+ * an instance can do that a sync cannot is re-claim its slot, and that is needed only when the
+ * resource backing it changed — a text's line count, a shape's geometry. So the store's snapshot is
+ * the resource itself, not a version counter: an update that leaves it alone (a dim, a color, a
+ * move) is written by the subscription's own listener, straight into the slot, and React bails out
+ * of the render because the snapshot is unchanged. An update that moves it renders, and the render's
+ * re-claim writes the def into the new slot.
+ * @param container - The container holding the slot.
+ * @param def - The def this instance renders.
+ * @param resourceOf - Reads the per-instance resource backing the slot off the def; a new identity
+ *   re-claims. Called on every update, so it must be cheap and return the same identity for an
+ *   unchanged def. `null` for a container whose slots need no resource, which never re-claims.
+ * @param write - Writes the def's type-specific state into its slot. Called only while visible.
+ */
+export declare function useDefSync<R>(container: SlotContainer<R>, def: RenderableDef, resourceOf: (() => R) | null, write: (slot: number) => void): void;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/objects/containers/hooks.js

@@ -0,0 +1,196 @@
+import { useStore } from '@react-three/fiber';
+import { useEffect, useRef, useState, useSyncExternalStore } from 'react';
+import { registerHitSource } from '../../events/pointer';
+import { registerSlotWriter, subscribeDef, syncNow } from '../../update';
+import { resolveDim, subscribeDim, useDimChain } from '../layer/layer-context';
+/**
+ * Creates one layer's container and keeps it wired to its layer for as long as the component is
+ * mounted: the membership's paint order, how hits on its mesh resolve back to defs, and what runs
+ * when a member no longer belongs in this container's kind.
+ *
+ * The container is built once, from the first render's defs, and outlives every render after —
+ * membership changes grow it in place rather than rebuilding it, which is what lets the mesh R3F
+ * built from its args stand too. `create` is therefore called once and its later identities ignored.
+ * @param create - Builds the container. Called on the first render only.
+ * @param defs - The layer's defs, in authored paint order.
+ * @param onKindMismatch - Re-splits the layer, for a container that finds a member of the wrong
+ *   kind. Registered as {@link SlotContainer.setKindMismatchHandler} and cleared on unmount or
+ *   before a new identity replaces it. A container with no kind of its own to leave omits it, and
+ *   nothing is registered.
+ * @returns The container.
+ */
+export function useContainer(create, defs, onKindMismatch) {
+    const [container] = useState(create);
+    const chain = useDimChain();
+    const invalidate = useInvalidate();
+    // The membership the dim subscription below re-orders, current as of the last commit.
+    const defsRef = useRef(defs);
+    useEffect(() => {
+        defsRef.current = defs;
+    });
+    // Paint order for the whole membership, one pass per structural change. Child effects run before
+    // this one, so every instance the change mounted has already claimed its slot; defs whose
+    // instances bailed out (memo) never re-ran, which is fine — order lives in the container, not in
+    // their props. Running inside the same effect flush as the claims is what keeps a frame from
+    // drawing between a claim's default order and this pass.
+    useEffect(() => {
+        container.setPaintOrder(defs, resolveDim(chain) > 0);
+        invalidate();
+    }, [container, defs, chain, invalidate]);
+    // And again as the layer's dim crosses zero — only whether it is dimmed, not by how much, since the
+    // order pass splits two ways. Followed by subscription, not render: an eased dim crosses zero once
+    // for every container in the plan in the same frame, and rendering each of them to get here cost
+    // that frame more than the passes themselves.
+    useEffect(() => {
+        let dimmed = resolveDim(chain) > 0;
+        return subscribeDim(chain, () => {
+            const next = resolveDim(chain) > 0;
+            if (next === dimmed)
+                return;
+            dimmed = next;
+            container.setPaintOrder(defsRef.current, next);
+            invalidate();
+        });
+    }, [container, chain, invalidate]);
+    // What a hit on this container's mesh means: which def drew it, and where that def sits in the
+    // draw order. From an effect, so the mesh is bound by now; the container answers both, so nothing
+    // here has to know one mesh kind from another.
+    useEffect(() => registerHitSource(container.mesh, container), [container]);
+    // Assigned after mount rather than passed to `create`, because the container is built once and
+    // outlives every render, so it cannot close over a fresh callback. A caller with nothing to run on
+    // a mismatch passes no handler, and this then does nothing: no call into the container and no
+    // cleanup closure either.
+    useEffect(() => {
+        if (!onKindMismatch)
+            return;
+        container.setKindMismatchHandler(onKindMismatch);
+        return () => container.setKindMismatchHandler(undefined);
+    }, [container, onKindMismatch]);
+    return container;
+}
+/**
+ * Claims a slot for one instance, releasing on unmount. Paint order is not this hook's concern —
+ * the container writes it for the whole sibling list in one pass (see {@link useContainer}).
+ * @param container - The container holding the slot.
+ * @param def - The def this instance renders.
+ * @param resource - The per-instance resource backing the slot; a new identity re-claims.
+ * @returns A ref holding the current slot, or `-1` while unclaimed. Read it at call time — a
+ *   re-claim changes the slot without re-rendering.
+ */
+export function useSlot(container, def, resource) {
+    const slotRef = useRef(-1);
+    const invalidate = useInvalidate();
+    useEffect(() => {
+        const slot = container.claim(def, resource);
+        slotRef.current = slot;
+        // On a re-claim the instance is already registered, so its state must be rewritten into the new
+        // slot. On first mount nothing is registered yet and `useDefSync` performs the initial write.
+        syncNow(def);
+        invalidate();
+        return () => {
+            container.release(slot);
+            slotRef.current = -1;
+            invalidate();
+        };
+    }, [container, def, resource, invalidate]);
+    return slotRef;
+}
+/**
+ * Claims a slot for one instance and keeps it in sync with its def: the slot is released on
+ * unmount, and on mount and after every `update(def)` the def's visibility and dim are written and —
+ * only while it is visible — `write` fills in the rest of the instance's state.
+ *
+ * The sync is registered as the def's slot writer, so it is also what the camera re-layout frame
+ * loop pulls out of `slotWriters` and calls directly — the React path and the per-frame path are
+ * one implementation, and both therefore agree about visibility.
+ *
+ * `hidden` and `dim` live on every def type, so their writes — and the short-circuit `hidden` gates
+ * — belong here rather than repeated in each instance component's callback. A hidden instance is
+ * never drawn, so computing its transform, color, or glyphs would be wasted; the update that shows
+ * it re-runs this sync, which writes the then-current state. Everything type-specific stays in
+ * `write`, which is what keeps this hook generic across every def type.
+ *
+ * **An `update(def)` renders nothing unless the slot's resource moved.** The only thing a render of
+ * an instance can do that a sync cannot is re-claim its slot, and that is needed only when the
+ * resource backing it changed — a text's line count, a shape's geometry. So the store's snapshot is
+ * the resource itself, not a version counter: an update that leaves it alone (a dim, a color, a
+ * move) is written by the subscription's own listener, straight into the slot, and React bails out
+ * of the render because the snapshot is unchanged. An update that moves it renders, and the render's
+ * re-claim writes the def into the new slot.
+ * @param container - The container holding the slot.
+ * @param def - The def this instance renders.
+ * @param resourceOf - Reads the per-instance resource backing the slot off the def; a new identity
+ *   re-claims. Called on every update, so it must be cheap and return the same identity for an
+ *   unchanged def. `null` for a container whose slots need no resource, which never re-claims.
+ * @param write - Writes the def's type-specific state into its slot. Called only while visible.
+ */
+export function useDefSync(container, def, resourceOf, write) {
+    // A container without resources is a `SlotContainer<null>`, so `null` is the resource it claims.
+    const readResource = (resourceOf ?? readNull);
+    const invalidate = useInvalidate();
+    // Refreshed after every render below; declared first because the subscription reaches for it.
+    const syncRef = useRef(noop);
+    const resource = useSyncExternalStore((listener) => subscribeDef(def, () => {
+        // This instance's own write rather than `syncNow`, which runs every instance drawing the
+        // def: each of them holds a subscription of its own, so `syncNow` here would write a def
+        // with N instances N² times.
+        syncRef.current();
+        invalidate();
+        listener();
+    }), readResource);
+    const slotRef = useSlot(container, def, resource);
+    /**
+     * Writes the def's current state into its slot: visibility always, the rest only when shown.
+     */
+    function sync() {
+        const slot = slotRef.current;
+        if (slot < 0)
+            return;
+        // The slot was claimed for the resource this render saw. When the def has since moved on to
+        // another — more lines than the claimed group holds — the write would overrun it; the render
+        // the change triggers re-claims and writes then.
+        if (!Object.is(readResource(), resource))
+            return;
+        const visible = !def.hidden;
+        container.setVisibleAt(slot, visible);
+        // Written even while hidden, unlike everything in `write`: it is one number, and writing it
+        // unconditionally is what makes the slot's dim true of the def at all times rather than only
+        // while it draws — including across the re-claim that `useSlot` syncs through.
+        container.setDimAt(slot, def.dim);
+        if (!visible)
+            return;
+        write(slot);
+    }
+    // Held in a ref and refreshed after every render: `sync` closes over a fresh `write` each time,
+    // and the effect below must not re-run just because that identity changed — only a new def or a
+    // new resource means the slot needs writing from here.
+    useEffect(() => {
+        syncRef.current = sync;
+    });
+    useEffect(() => registerSlotWriter(def, () => syncRef.current(), invalidate), [def, invalidate]);
+    // The first write, and the one after a re-claim. Declared after the ref refresh above, so it runs
+    // the closure that knows the new resource — `useSlot`'s own sync ran the previous render's, which
+    // the resource check turned into a no-op. Through the registry, so the frame request that shows it
+    // comes with it.
+    useEffect(() => {
+        syncNow(def);
+    }, [def, resource]);
+}
+/**
+ * The renderer's frame request, without subscribing to R3F's store for it.
+ *
+ * `useThree(selector)` subscribes, and every instance holds this hook's result — so with a selector
+ * each R3F state change (a canvas re-render re-configures the root) ran one selector per instance,
+ * tens of thousands on a large plan, for a value that never changes. The store handle is context
+ * alone, and reading `invalidate` at call time also follows a host that replaces it (external mode).
+ * @returns A stable function requesting a frame.
+ */
+function useInvalidate() {
+    const store = useStore();
+    const [invalidate] = useState(() => () => store.getState().invalidate());
+    return invalidate;
+}
+// The resource of an instance whose container needs none.
+const readNull = () => null;
+// What an instance's sync ref holds before its first render has committed.
+const noop = () => undefined;

package/dist/objects/containers/index.d.ts

@@ -0,0 +1,6 @@
+export { useContainer, useDefSync } from './hooks';
+export { defKey } from './keys';
+export { type ColorWritable, type MatrixWritable, shapeToMatrix, writeColorIfChanged, writeMatrixIfChanged, } from './mesh-writes';
+export { type DefsProps, type InstanceProps } from './props';
+export { type BatchedMeshRenderItem, type RenderListItem, SlotContainer, type SlotContainerOptions, type SlotMesh, } from './SlotContainer';
+//# sourceMappingURL=index.d.ts.map

package/dist/objects/containers/index.js

@@ -0,0 +1,4 @@
+export { useContainer, useDefSync } from './hooks';
+export { defKey } from './keys';
+export { shapeToMatrix, writeColorIfChanged, writeMatrixIfChanged, } from './mesh-writes';
+export { SlotContainer, } from './SlotContainer';

package/dist/objects/containers/keys.d.ts

@@ -0,0 +1,10 @@
+import { type RenderableDef } from '../../types/defs';
+/**
+ * A stable React key for a def. Defs carry no id, and their array position shifts as siblings are
+ * added or removed, so identity is the only durable key — which is also what lets React mount and
+ * unmount exactly the defs that entered or left a layer.
+ * @param def - The def to key.
+ * @returns The def's key, allocated on first use.
+ */
+export declare function defKey(def: RenderableDef): string;
+//# sourceMappingURL=keys.d.ts.map

package/dist/objects/containers/keys.js

@@ -0,0 +1,18 @@
+/** Keys already handed out, so a def keeps the same key for its whole life. */
+const keys = new WeakMap();
+let nextKey = 0;
+/**
+ * A stable React key for a def. Defs carry no id, and their array position shifts as siblings are
+ * added or removed, so identity is the only durable key — which is also what lets React mount and
+ * unmount exactly the defs that entered or left a layer.
+ * @param def - The def to key.
+ * @returns The def's key, allocated on first use.
+ */
+export function defKey(def) {
+    let key = keys.get(def);
+    if (key === undefined) {
+        key = `def-${nextKey++}`;
+        keys.set(def, key);
+    }
+    return key;
+}

package/dist/objects/containers/mesh-writes.d.ts

@@ -0,0 +1,106 @@
+import { type Shape } from '@expofp/geometry';
+import { Matrix4, Vector4 } from 'three';
+import { type ColorInput } from '../../types/defs';
+import { type Logger } from '../../utils/logging';
+/**
+ * A mesh whose instances carry a transform.
+ *
+ * Named as a capability rather than listed as a union of our mesh classes, because not every batch
+ * has one: `BatchedLinesImpl` places its members by their endpoints and has no per-instance matrix
+ * at all, yet still writes colors through the helper below. A class that satisfies only one of
+ * these two interfaces is the point — the alternative was no-op matrix methods on a class that has
+ * no transforms, which would read as a capability it does not have.
+ *
+ * Implementations flag their own buffer uploads and invalidate their own bounds inside
+ * `setMatrixAt`, so no caller has to.
+ */
+export interface MatrixWritable {
+    /**
+     * Reads an instance's transform.
+     * @param slot - The instance to read.
+     * @param target - Receives the result.
+     */
+    getMatrixAt(slot: number, target: Matrix4): unknown;
+    /**
+     * Writes an instance's transform.
+     * @param slot - The instance to write.
+     * @param matrix - The transform.
+     */
+    setMatrixAt(slot: number, matrix: Matrix4): unknown;
+}
+/**
+ * A mesh whose instances carry an RGBA color, alpha in the fourth channel.
+ *
+ * `BatchedMesh` types this pair for `Color | Vector4` and our vendored classes widen it the same
+ * way, so a `Vector4` is what every implementation routes to its own opacity storage.
+ */
+export interface ColorWritable {
+    /**
+     * Reads an instance's color.
+     * @param slot - The instance to read.
+     * @param target - Receives the result, alpha in `.w`.
+     */
+    getColorAt(slot: number, target: Vector4): unknown;
+    /**
+     * Writes an instance's color.
+     * @param slot - The instance to write.
+     * @param color - The color, alpha in `.w`.
+     */
+    setColorAt(slot: number, color: Vector4): unknown;
+}
+/** A def carrying a color of its own. */
+interface ColoredDef {
+    /** The def's color, as a css string or packed number. */
+    color: ColorInput;
+}
+/**
+ * Composes the instance transform a shape draws with, into the shared scratch matrix.
+ *
+ * A box or rect is drawn as the shared unit plane, so its transform carries the whole shape: the
+ * plane is scaled to the shape's size, spun about z by its rotation, and moved to its center. A
+ * mesh already carries absolute coordinates in its own geometry, including a z per vertex, so it
+ * draws at identity. A polygon is the one in between: its vertices are 2D and its `elevation` is a
+ * single scalar beside them, so that scalar is the only part of its placement the geometry cannot
+ * hold and the transform lifts it. An image's `bounds` is a rect, so it composes here too and then
+ * post-multiplies its own origin and tile offsets onto the result.
+ *
+ * The result **is the shared scratch** — valid until the next call, which is all any caller needs:
+ * a write composes, optionally adjusts, and uploads within one synchronous statement. Handing it
+ * back rather than taking a target keeps every instance type off its own private matrix.
+ * @param shape - The shape supplying the transform.
+ * @returns The scratch matrix, composed.
+ */
+export declare function shapeToMatrix(shape: Shape): Matrix4;
+/**
+ * Writes a transform into an instance, skipping the upload when nothing moved.
+ *
+ * The compare-and-skip is what keeps a def that only changed color from paying for a matrix
+ * upload and a bounds invalidation: a color-only `update(def)` re-runs the whole sync, and an
+ * unchanged transform costs sixteen comparisons instead.
+ * @param mesh - The mesh holding the instance.
+ * @param slot - The instance's slot.
+ * @param matrix - The transform to write.
+ * @returns Whether the matrix was written.
+ */
+export declare function writeMatrixIfChanged(mesh: MatrixWritable, slot: number, matrix: Matrix4): boolean;
+/**
+ * Parses a def's color and writes it into an instance, skipping the upload when it did not change
+ * — the color counterpart to {@link writeMatrixIfChanged}, so a def that only moved does not pay
+ * for a color upload either.
+ *
+ * Alpha rides in the fourth channel, which every mesh routes to its own opacity storage.
+ *
+ * A color that does not parse warns and leaves the instance untouched rather than throwing: a bad
+ * color is a bad def, not a broken renderer, and the sync that found it has other writes to finish.
+ * Naming the def in the warning is why this takes the whole def rather than the color alone — it is
+ * the only thing that makes the report actionable.
+ * @param mesh - The mesh holding the instance.
+ * @param slot - The instance's slot.
+ * @param def - The def supplying the color, and named in the warning.
+ * @param logger - Reports an unparsable color, so the warning names the instance component.
+ * @returns Whether the color was written; `false` both for one that did not change and for one that
+ *   did not parse.
+ */
+export declare function writeColorIfChanged(mesh: ColorWritable, slot: number, def: ColoredDef, logger: Logger): boolean;
+export {};
+//# sourceMappingURL=mesh-writes.d.ts.map

package/dist/objects/containers/mesh-writes.js

@@ -0,0 +1,97 @@
+import { isBox, isRect } from '@expofp/geometry';
+import { Color, Matrix4, Quaternion, SRGBColorSpace, Vector3, Vector4 } from 'three';
+import { normalizeColor } from '../../utils/colors';
+/**
+ * Composes the instance transform a shape draws with, into the shared scratch matrix.
+ *
+ * A box or rect is drawn as the shared unit plane, so its transform carries the whole shape: the
+ * plane is scaled to the shape's size, spun about z by its rotation, and moved to its center. A
+ * mesh already carries absolute coordinates in its own geometry, including a z per vertex, so it
+ * draws at identity. A polygon is the one in between: its vertices are 2D and its `elevation` is a
+ * single scalar beside them, so that scalar is the only part of its placement the geometry cannot
+ * hold and the transform lifts it. An image's `bounds` is a rect, so it composes here too and then
+ * post-multiplies its own origin and tile offsets onto the result.
+ *
+ * The result **is the shared scratch** — valid until the next call, which is all any caller needs:
+ * a write composes, optionally adjusts, and uploads within one synchronous statement. Handing it
+ * back rather than taking a target keeps every instance type off its own private matrix.
+ * @param shape - The shape supplying the transform.
+ * @returns The scratch matrix, composed.
+ */
+export function shapeToMatrix(shape) {
+    if (!isBox(shape) && !isRect(shape)) {
+        // A `Mesh` has no `elevation` at all, so this is identity for one; a `Polygon` is lifted onto
+        // its plane. Zero composes to identity either way, so the common case costs nothing.
+        return _matrix.makeTranslation(0, 0, 'elevation' in shape ? shape.elevation : 0);
+    }
+    // A Box is a pure 2D AABB — it carries neither field — so both default to zero.
+    const elevation = 'elevation' in shape ? shape.elevation : 0;
+    const rotation = 'rotation' in shape ? shape.rotation : 0;
+    _position.set(shape.center.x, shape.center.y, elevation);
+    _quaternion.setFromAxisAngle(Z_AXIS, rotation);
+    _scale.set(shape.size.x, shape.size.y, 1);
+    return _matrix.compose(_position, _quaternion, _scale);
+}
+/**
+ * Writes a transform into an instance, skipping the upload when nothing moved.
+ *
+ * The compare-and-skip is what keeps a def that only changed color from paying for a matrix
+ * upload and a bounds invalidation: a color-only `update(def)` re-runs the whole sync, and an
+ * unchanged transform costs sixteen comparisons instead.
+ * @param mesh - The mesh holding the instance.
+ * @param slot - The instance's slot.
+ * @param matrix - The transform to write.
+ * @returns Whether the matrix was written.
+ */
+export function writeMatrixIfChanged(mesh, slot, matrix) {
+    mesh.getMatrixAt(slot, _previousMatrix);
+    if (_previousMatrix.equals(matrix))
+        return false;
+    mesh.setMatrixAt(slot, matrix);
+    return true;
+}
+/**
+ * Parses a def's color and writes it into an instance, skipping the upload when it did not change
+ * — the color counterpart to {@link writeMatrixIfChanged}, so a def that only moved does not pay
+ * for a color upload either.
+ *
+ * Alpha rides in the fourth channel, which every mesh routes to its own opacity storage.
+ *
+ * A color that does not parse warns and leaves the instance untouched rather than throwing: a bad
+ * color is a bad def, not a broken renderer, and the sync that found it has other writes to finish.
+ * Naming the def in the warning is why this takes the whole def rather than the color alone — it is
+ * the only thing that makes the report actionable.
+ * @param mesh - The mesh holding the instance.
+ * @param slot - The instance's slot.
+ * @param def - The def supplying the color, and named in the warning.
+ * @param logger - Reports an unparsable color, so the warning names the instance component.
+ * @returns Whether the color was written; `false` both for one that did not change and for one that
+ *   did not parse.
+ */
+export function writeColorIfChanged(mesh, slot, def, logger) {
+    const rgb = normalizeColor(def.color);
+    if (!rgb) {
+        logger.warn(`Invalid color: ${String(def.color)} %O`, def);
+        return false;
+    }
+    _color.setRGB(rgb.r / 255, rgb.g / 255, rgb.b / 255, SRGBColorSpace);
+    _colorWithAlpha.set(_color.r, _color.g, _color.b, rgb.a);
+    mesh.getColorAt(slot, _previousColor);
+    if (_previousColor.equals(_colorWithAlpha))
+        return false;
+    mesh.setColorAt(slot, _colorWithAlpha);
+    return true;
+}
+// Scratch shared by every write. Each is filled and consumed within a single synchronous
+// statement, so a write costs buffer uploads and no allocation. `_matrix` is the one callers see,
+// through `shapeToMatrix`. The `_previous*` values are only ever read back and compared inside the
+// write helpers, so a caller still holding `_matrix` never collides with them.
+const _position = new Vector3();
+const _quaternion = new Quaternion();
+const _scale = new Vector3();
+const _matrix = new Matrix4();
+const _previousMatrix = new Matrix4();
+const _color = new Color();
+const _colorWithAlpha = new Vector4();
+const _previousColor = new Vector4();
+const Z_AXIS = new Vector3(0, 0, 1);

package/dist/objects/containers/props.d.ts

@@ -0,0 +1,33 @@
+import { type RenderableDef } from '../../types/defs';
+/** Props for a component drawing one layer's defs. */
+export interface DefsProps<T extends RenderableDef> {
+    /**
+     * The defs to draw, in paint order. Layer-level concerns (`hidden`, `dim`, pointer handlers)
+     * belong to `<Layer>`, not here.
+     *
+     * A **new array identity means the collection may have changed** — that is the whole contract.
+     * Callers must not pass a layer's `children` directly: it is mutated in place, so its identity
+     * never changes and a memoizing compiler would keep serving a stale instance list. Pass the
+     * version-keyed snapshot from `useStagedChildren`, whose identity changes exactly when the layer is
+     * updated.
+     */
+    defs: readonly T[];
+    /**
+     * How many of `defs` may mount their instances now, counted from the start of the list — the
+     * staged-mount slice, from `useStagedChildren`. Defaults to all of them, which is what a caller
+     * mounting a layer outside the scheduler wants.
+     *
+     * Only the instances are sliced. The container is still built, sized and paint-ordered from the
+     * whole of `defs`, so a growing prefix claims into buffers that were allocated once, and the
+     * order pass that labels them runs per membership change rather than per slice.
+     */
+    mounted?: number;
+}
+/** Props for a component keeping one def's instance in sync. */
+export interface InstanceProps<T extends RenderableDef, C> {
+    /** The def this instance draws. */
+    def: T;
+    /** The container holding the instance. */
+    container: C;
+}
+//# sourceMappingURL=props.d.ts.map

package/dist/objects/containers/props.js

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

package/dist/objects/images/ImageInstance.d.ts

@@ -0,0 +1,29 @@
+import { type ImageDef } from '../../types/defs';
+import { type InstanceProps } from '../containers';
+import { type PackedImage } from './atlas-packer';
+import { type ImageContainer } from './image-container';
+/** Props for {@link ImageInstance}. */
+export interface ImageInstanceProps extends InstanceProps<ImageDef, ImageContainer> {
+    /**
+     * The atlas placement this instance draws — the whole image, or one tile of a split one. A def
+     * whose source was cut across atlases has several instances, one per {@link PackedImage}.
+     */
+    packed: PackedImage;
+}
+/**
+ * Keeps one image placement current: claims a slot on mount (where the container writes the fixed
+ * uv region), writes the def's transform and visibility on mount and after every `update(def)`, and
+ * releases the slot on unmount.
+ *
+ * Renders no scene node — the mesh belongs to the container. Only the transform lives here:
+ * visibility is `useDefSync`'s, the uv region is written once at claim (a def's source cannot
+ * change), and color has no analogue for a textured quad. Memoized for the same reason as
+ * `ShapeInstance`: a structural change hands the atlas a fresh placement list, rebuilding every
+ * instance element, so only prop-equality keeps the unchanged siblings from re-rendering. Both props
+ * are identity-stable across a membership's lifetime — a change repacks into a fresh container and
+ * fresh placements — so the bailout holds.
+ * @param props - The def, its placement, and its container.
+ * @returns `null`; the instance lives in the mesh, not the scene graph.
+ */
+export declare const ImageInstance: import("react").MemoExoticComponent<(props: ImageInstanceProps) => null>;
+//# sourceMappingURL=ImageInstance.d.ts.map