@expofp/renderer 3.2.5 → 3.27.1

package/dist/objects/containers/SlotContainer.js

@@ -0,0 +1,251 @@
+import { DIM_SCHEMA, DIM_UNIFORM, dimOrdered, instanceDim, isDimmed } from '../materials/dim';
+/**
+ * One layer's mesh bookkeeping: the bound mesh, which slot each def holds, and the paint order
+ * across them.
+ *
+ * A container is what stands between a layer's defs and one mesh. It is created during render,
+ * sized to the membership it first sees, and held in `useState` for as long as its component is
+ * mounted; the mesh itself is R3F's, constructed from the subclass's args and handed back through
+ * {@link bind}, so R3F owns its lifetime and disposal. Instances claim and release slots from their
+ * own effects, and write their type-specific state through the subclass's own methods.
+ *
+ * What lives here is everything that does not depend on which def type is drawn:
+ *
+ * - **Slot allocation**, in both directions. `slotOf` is what a paint-order pass over the layer's
+ *   defs looks each def up with, and {@link defAt} is what turns a pointer hit — which names a slot
+ *   — back into the def that drew it. Slots come from a mesh's free list, so a released slot may be
+ *   handed to a different def later; freeing by slot keeps both directions from outliving the claim
+ *   they describe.
+ * - **Paint order**, explicitly. Instance ids come from a mesh's free list, so they do not track
+ *   sibling order — a container that let slot order stand in for paint order would reorder itself
+ *   after any claim/release churn, and again under StrictMode's remount, which re-claims in reverse.
+ *   Explicit order is also what the 2D painter's algorithm needs: 2D content never writes depth, so
+ *   nothing it draws is in the buffer for the next 2D fragment to test against, and the draw list's
+ *   order is the only thing that decides overlap.
+ * - **The two fields every def type carries**, `hidden` and `dim`, through {@link setVisibleAt} and
+ *   {@link setDimAt} — which is what lets one hook drive them for every def type.
+ *
+ * A subclass supplies {@link addInstance} and {@link removeInstance}, names its mesh and def types,
+ * and adds whatever its own defs need.
+ * @template R - The per-instance resource a claim allocates against (a geometry, a texture region,
+ *   a line count); compared by identity, so a stable reference means a stable slot. `null` for a
+ *   container whose members share everything.
+ * @template M - The mesh this container writes into.
+ * @template T - The def kind the layer holds.
+ */
+export class SlotContainer {
+    /**
+     * Sorts a mesh's render list into paint order. Assigned straight to the mesh's `customSort` JSX
+     * prop, whose R3F-generated type leaves the value effectively unchecked — so the entry type here
+     * needs no cast against three's published one, which omits `index`.
+     *
+     * An arrow property rather than a method, because it is handed over as a bare value and a
+     * prototype method would arrive unbound.
+     * @param list - The render list, sorted in place.
+     */
+    customSort = (list) => {
+        const order = this.orderBySlot;
+        list.sort((a, b) => this.sortDirection * ((order[a.index] ?? 0) - (order[b.index] ?? 0)));
+    };
+    /**
+     * The layer's membership, in authored paint order. Kept so a def whose own dim changes can re-run
+     * the order pass without this container having re-rendered — `update(def)` reaches the instance,
+     * not here.
+     */
+    layerDefs = [];
+    /**
+     * Whether the layer is dimmed, which is what a def without a `dim` of its own inherits.
+     *
+     * A flag rather than the layer's amount, because the amount is the shader's business and this is
+     * only ever asked a yes-or-no question. It is also what makes an eased layer dim cheap: the order
+     * pass re-runs when the value crosses zero, not on every frame of the ease.
+     */
+    layerDimmed = false;
+    /**
+     * Whether each slot currently draws dimmed, so a dim write that does not cross the split costs
+     * nothing.
+     */
+    dimmedBySlot = [];
+    /**
+     * Each def's order, durable and weak — collected with the def. It outlives a slot, so a re-claim
+     * can seed the new slot's order without waiting for the next order pass.
+     */
+    orderByDef = new WeakMap();
+    /** Each slot's place in the paint order, read by {@link customSort}. */
+    orderBySlot = [];
+    slotByDef = new Map();
+    defBySlot = new Map();
+    schema;
+    sortDirection;
+    /** Set by {@link bind}, which runs before any effect can claim a slot. */
+    boundMesh;
+    /**
+     * @param options - How this container differs from the default.
+     */
+    constructor(options = {}) {
+        this.schema = options.schema ?? DIM_SCHEMA;
+        this.sortDirection = options.reverse ? -1 : 1;
+    }
+    /**
+     * The mesh every instance writes into. Undefined until {@link bind}; refs attach before passive
+     * effects run, so every claim and slot write sees it bound.
+     */
+    get mesh() {
+        // Asserted rather than guarded: reading before the ref attached is a programming error, and the
+        // ordering that rules it out is React's, not something a check here could repair.
+        return this.boundMesh;
+    }
+    /**
+     * Binds the mesh R3F constructed from this container's args, declaring its per-instance uniforms.
+     *
+     * Bind-once: the ref-cleanup `null` and any re-bind are ignored, because React StrictMode cycles
+     * refs (attach → cleanup → attach) around a passive effect cycle — a container that forgot its
+     * mesh there would turn {@link release} into a no-op and leak the slot when the remounted instance
+     * re-claims, and one that re-declared its uniforms would strand the values already written into
+     * them.
+     * @param mesh - The mounted mesh, or the ref-cleanup `null`.
+     */
+    bind(mesh) {
+        if (!mesh || this.boundMesh)
+            return;
+        this.boundMesh = mesh;
+        // The material owns each uniform's name and shape; the mesh only has to declare the rows before
+        // any slot writes into them — which the ref this runs from guarantees, since refs attach before
+        // the effects that claim slots and long before the first draw.
+        mesh.addUniforms(this.schema);
+    }
+    /**
+     * Reserves a slot for one instance, backed by `resource`.
+     *
+     * Paint order is deliberately not a parameter: it is a property of the whole sibling list, so the
+     * component writes it for every def in one pass after each membership change (see
+     * {@link setPaintOrder}) — an instance never learns its index, which is what lets a memoized
+     * instance ignore structural re-renders entirely.
+     * @param def - The def the slot will draw; def-to-slot bookkeeping is keyed by its identity.
+     * @param resource - The per-instance resource to allocate against.
+     * @returns The slot index.
+     */
+    claim(def, resource) {
+        const slot = this.addInstance(resource);
+        this.slotByDef.set(def, slot);
+        this.defBySlot.set(slot, def);
+        // Seeded from the durable assignment so a re-claim keeps its order; a first claim before any
+        // `setPaintOrder` defaults to 0 and the component's order pass relabels it in the same effect
+        // flush, before anything draws.
+        this.orderBySlot[slot] = this.orderByDef.get(def) ?? 0;
+        return slot;
+    }
+    /**
+     * Frees a slot, and everything recorded about the claim it held.
+     * @param slot - The slot to free.
+     */
+    release(slot) {
+        this.removeInstance(slot);
+        this.orderBySlot[slot] = 0;
+        this.dimmedBySlot[slot] = undefined;
+        const def = this.defBySlot.get(slot);
+        if (!def)
+            return;
+        this.slotByDef.delete(def);
+        this.defBySlot.delete(slot);
+    }
+    /**
+     * The def holding a slot — the reverse of {@link claim}.
+     * @param slot - The slot to look up, or `undefined` for a hit that named none.
+     * @returns The def, or `undefined` when the slot is free.
+     */
+    defAt(slot) {
+        return slot === undefined ? undefined : this.defBySlot.get(slot);
+    }
+    /**
+     * The def an intersection with this container's mesh hit.
+     *
+     * Which field of an intersection names a slot is the container's own knowledge — `instanceId` for
+     * an instanced mesh, `batchId` for a batched one, the member id for a text batch, whose defs own
+     * several — so it is answered here rather than at each registration site.
+     * @param hit - The intersection to trace.
+     * @returns The def, or `undefined` when the hit cannot be traced to one.
+     */
+    defFromHit(hit) {
+        return this.defAt(hit.instanceId);
+    }
+    /**
+     * Shows or hides one instance. Every def type carries `hidden`, so `useDefSync` drives this for
+     * all of them.
+     * @param slot - The slot to show or hide.
+     * @param visible - Whether the instance should draw.
+     */
+    setVisibleAt(slot, visible) {
+        this.mesh.setVisibleAt(slot, visible);
+    }
+    /**
+     * Sets one instance's own dim, or clears it back to its layer's.
+     *
+     * The counterpart to {@link setVisibleAt}, and here for the same reason: `dim` is a `SharedDef`
+     * field, so `useDefSync` drives it for every def type. The raw field is passed through rather than
+     * an encoded amount, which keeps the sentinel — and the rest of the shader's contract — inside the
+     * material module that reads it.
+     * @param slot - The slot to dim.
+     * @param dim - The def's `dim`; `undefined` defers to the layer's.
+     */
+    setDimAt(slot, dim) {
+        this.writeDim(slot, instanceDim(dim));
+        // Crossing the dimmed/lit split changes where this def draws, and nothing else will notice: a
+        // def's own `update()` reaches its instance, never the component that renders this container.
+        const dimmed = isDimmed(dim, this.layerDimmed);
+        if (this.layerDefs.length === 0 || this.dimmedBySlot[slot] === dimmed)
+            return;
+        this.applyOrder();
+    }
+    /**
+     * Writes an encoded dim into a slot's uniform — the part of {@link setDimAt} that knows how a slot
+     * maps onto the mesh, split out so a container whose slot spans several mesh instances overrides
+     * only that and keeps the split-crossing check above.
+     * @param slot - The slot to write.
+     * @param amount - The encoded amount, from `instanceDim`.
+     */
+    writeDim(slot, amount) {
+        this.mesh.setUniformAt(slot, DIM_UNIFORM, amount);
+    }
+    /**
+     * Declares the layer's membership and dim, and re-runs the order pass over them.
+     *
+     * The component calls this from an effect after each structural change — child effects run first,
+     * so every mounted instance has claimed by then. Defs that have not claimed yet are recorded
+     * anyway: a later claim seeds its slot's order from this assignment, which is what keeps a
+     * re-claim correctly ordered without React involvement.
+     * @param defs - The current membership, in paint order.
+     * @param layerDimmed - Whether the layer is dimmed, inherited by defs without a `dim` of their own.
+     */
+    setPaintOrder(defs, layerDimmed) {
+        this.layerDefs = defs;
+        this.layerDimmed = layerDimmed;
+        this.applyOrder();
+    }
+    /**
+     * Labels every claimed slot with its place in the layer's draw order, undimmed defs last.
+     *
+     * Overridden by a container whose mesh has no sortable draw list, where ordering means handing the
+     * mesh a rebuilt member list instead.
+     */
+    applyOrder() {
+        const ordered = dimOrdered(this.layerDefs, this.layerDimmed);
+        for (let order = 0; order < ordered.length; order++) {
+            const def = ordered[order];
+            this.orderByDef.set(def, order);
+            const slot = this.slotOf(def);
+            if (slot === undefined)
+                continue;
+            this.orderBySlot[slot] = order;
+            this.dimmedBySlot[slot] = isDimmed(def.dim, this.layerDimmed);
+        }
+    }
+    /**
+     * The slot a def holds, for an order pass walking the layer's defs.
+     * @param def - The def to look up.
+     * @returns The slot, or `undefined` when the def has not claimed one.
+     */
+    slotOf(def) {
+        return this.slotByDef.get(def);
+    }
+}

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

@@ -0,0 +1,46 @@
+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, and how hits on its mesh resolve back to defs.
+ *
+ * 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.
+ * @returns The container.
+ */
+export declare function useContainer<T extends RenderableDef, C extends SlotContainer<unknown, SlotMesh, T>>(create: () => C, defs: readonly T[]): 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.
+ * @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.
+ * @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, resource: R, write: (slot: number) => void): void;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/objects/containers/hooks.js

@@ -0,0 +1,118 @@
+import { useThree } from '@react-three/fiber';
+import { use, useEffect, useRef, useState, useSyncExternalStore } from 'react';
+import { registerHitResolver } from '../../events/pointer';
+import { registerSlotWriter, subscribeDef, syncNow, versionOf } from '../../update';
+import { LayerDimContext } from '../materials/dim';
+/**
+ * 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, and how hits on its mesh resolve back to defs.
+ *
+ * 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.
+ * @returns The container.
+ */
+export function useContainer(create, defs) {
+    const [container] = useState(create);
+    // Only whether the layer is dimmed, not by how much: the order pass splits two ways, so an eased
+    // dim re-runs it as its value crosses zero rather than on every frame of the ease.
+    const layerDimmed = use(LayerDimContext) > 0;
+    const invalidate = useThree((state) => state.invalidate);
+    // 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, layerDimmed);
+        invalidate();
+    }, [container, defs, layerDimmed, invalidate]);
+    // How a hit on this container's mesh becomes a def. From an effect, so the mesh is bound by now;
+    // the container answers which field of an intersection names its slot, so nothing here has to know
+    // one mesh kind from another.
+    useEffect(() => registerHitResolver(container.mesh, (hit) => container.defFromHit(hit)), [container]);
+    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 = useThree((state) => state.invalidate);
+    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.
+ * @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.
+ * @param write - Writes the def's type-specific state into its slot. Called only while visible.
+ */
+export function useDefSync(container, def, resource, write) {
+    const slotRef = useSlot(container, def, resource);
+    const version = useSyncExternalStore((listener) => subscribeDef(def, listener), () => versionOf(def));
+    const invalidate = useThree((state) => state.invalidate);
+    /**
+     * 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;
+        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 version bump
+    // means the def actually moved.
+    const syncRef = useRef(sync);
+    useEffect(() => {
+        syncRef.current = sync;
+    });
+    useEffect(() => registerSlotWriter(def, () => syncRef.current(), invalidate), [def, invalidate]);
+    // Through the registry rather than the ref, so the React path runs the very same write every other
+    // path does — the frame request that shows it included.
+    useEffect(() => {
+        syncNow(def);
+    }, [def, version]);
+}

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: `BatchedLinesExt` 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*` pair is 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);