@expofp/renderer 3.37.1 → 3.39.0

package/dist/core/text/MemberTexture.js

@@ -1,4 +1,5 @@
-import { Color, DataTexture, FloatType, Frustum, Matrix4, RGBAFormat, Sphere, } from 'three';
+import { Color, DataTexture, FloatType, Frustum, Matrix4, RGBAFormat, Sphere, Vector3, } from 'three';
+import { Y_DOWN_FLIP } from '../../space/Space';
 /**
  * The data texture a batch's shader reads each member's transform and style from: one 32-float row
  * per member, refilled once per draw with frustum culling folded in.
@@ -43,6 +44,16 @@ export class MemberTexture {
             .multiplyMatrices(camera.projectionMatrix, camera.matrixWorldInverse)
             .multiply(host.matrixWorld);
         _frustum.setFromProjectionMatrix(_matrix, camera.coordinateSystem);
+        // The camera's rotation, brought into the batch's own space, because that is where member
+        // matrices live. Computed once per draw, not once per member. `Y_DOWN_FLIP` plays the camera's
+        // own rest pose here, so `faceCamera` does not bake that pose in twice: once here and once more
+        // in the ordinary view transform at draw time. See `Y_DOWN_FLIP` in `space/Space.ts` for why
+        // this role holds regardless of a member's own scale or rotation.
+        _basis
+            .extractRotation(host.matrixWorld)
+            .transpose()
+            .multiply(_cameraBasis.extractRotation(camera.matrixWorld))
+            .multiply(Y_DOWN_FLIP);
         // Hoisted out of the loop: `Text`'s `material` getter calls `hasOutline()`, which walks every
         // member, so reading it per member made this loop quadratic — and it returns an *array* once
         // outlines are on, whose `.color` is undefined. The material being drawn is already in hand.
@@ -52,6 +63,7 @@ export class MemberTexture {
             // An unsynced member has no layout to write and draws nothing either.
             if (!text?.textRenderInfo)
                 continue;
+            faceCamera(text, _basis);
             const start = memberId * FLOATS_PER_MEMBER;
             if (isDrawn(text)) {
                 this.writeMember(texData, start, text, material, batchColor);
@@ -160,6 +172,43 @@ export class MemberTexture {
         }
     }
 }
+/**
+ * Turns a screen-space member to face the camera, and leaves a flat one alone.
+ *
+ * Composed on the CPU, on a loop that already runs once per member per draw, rather than in the
+ * shader. The shader path costs twelve bytes per member of GPU memory and needs a seam on both
+ * `BatchedTextImpl.raycast` and `isDrawn`. This path costs neither, because both of those read the
+ * member's matrix already. Write the sprite matrix there and both follow.
+ *
+ * The composition is `T(anchor) . basis . T(position - anchor) . Rz(rotation.z) . S(scale)`. The
+ * basis is the camera's rotation brought into the batch's own space, corrected by `Y_DOWN_FLIP`
+ * for the camera's own rest pose (see {@link Y_DOWN_FLIP} in `space/Space.ts`). Everything else is
+ * read off the member exactly as
+ * `updateMatrix` reads it. Straight overhead the basis is the identity and this reduces to the flat
+ * matrix, which is the equality the top-down baseline asserts on screen.
+ *
+ * Written through `setMatrix` only when it changed, so a still camera costs sixteen comparisons and
+ * no bounds invalidation. A pan or a zoom costs the same, because neither moves the camera's
+ * rotation. Only a roll or a pitch dirties a row.
+ * @param text - The member to turn.
+ * @param basis - The camera basis for this draw, in the batch's own space.
+ */
+function faceCamera(text, basis) {
+    const anchor = text.spriteAnchor;
+    if (!anchor)
+        return;
+    // `spriteAnchor` carries no z. The offset's z is zero by construction, and the pivot's z is read
+    // off the member's own position instead.
+    _offset.set(text.position.x - anchor.x, text.position.y - anchor.y, 0);
+    _spriteMatrix
+        .copy(basis)
+        .multiply(_step.makeTranslation(_offset.x, _offset.y, _offset.z))
+        .multiply(_step.makeRotationZ(text.rotation.z))
+        .scale(text.scale)
+        .premultiply(_step.makeTranslation(anchor.x, anchor.y, text.position.z));
+    if (!text.matrix.equals(_spriteMatrix))
+        text.setMatrix(_spriteMatrix);
+}
 /**
  * Whether a member draws this frame: shown, and inside the frustum this pass was set up with.
  * @param text - The member to test.
@@ -192,3 +241,8 @@ const _color = new Color();
 const _matrix = new Matrix4();
 const _frustum = new Frustum();
 const _sphere = new Sphere();
+const _basis = new Matrix4();
+const _cameraBasis = new Matrix4();
+const _spriteMatrix = new Matrix4();
+const _step = new Matrix4();
+const _offset = new Vector3();

package/dist/core/text/Text.d.ts

@@ -1,4 +1,4 @@
-import { Matrix4 } from 'three';
+import { Matrix4, type Vector2 } from 'three';
 import { Text as TroikaText, type TextMaterial } from 'troika-three-text';
 import { type BatchedTextImpl } from './BatchedText';
 /**
@@ -45,6 +45,21 @@ export declare class TextImpl extends TroikaText {
      * this initializer runs, so seeding `false` here would quietly undo them.
      */
     _syncFlag: boolean;
+    /**
+     * Where this member pivots when it faces the camera, in the plan's x and y. `null` draws it flat
+     * on the plan.
+     *
+     * One object, set and cleared together, so the two halves cannot disagree. Deliberately not named
+     * `anchorX` or `anchorY`, which troika owns and lists in its syncable properties. Assigning those
+     * would re-run layout and repack the batch on every write. `position`, `quaternion`, `scale` and
+     * `matrix` are all absent from that list, which is what makes the per-draw compose free of layout.
+     *
+     * Two dimensional on purpose. Every line of a def sits at the def's own elevation, so the anchor's
+     * z always equals the member's own `position.z`. There is no separate z to store.
+     *
+     * Derived, never authored. `applyPlacement` sets it from the def's bounds.
+     */
+    spriteAnchor: Vector2 | null;
     /**
      * Writes the local transform directly and tells the batch its bounds moved.
      *

package/dist/core/text/Text.js

@@ -45,6 +45,21 @@ export class TextImpl extends TroikaText {
      * this initializer runs, so seeding `false` here would quietly undo them.
      */
     _syncFlag = true;
+    /**
+     * Where this member pivots when it faces the camera, in the plan's x and y. `null` draws it flat
+     * on the plan.
+     *
+     * One object, set and cleared together, so the two halves cannot disagree. Deliberately not named
+     * `anchorX` or `anchorY`, which troika owns and lists in its syncable properties. Assigning those
+     * would re-run layout and repack the batch on every write. `position`, `quaternion`, `scale` and
+     * `matrix` are all absent from that list, which is what makes the per-draw compose free of layout.
+     *
+     * Two dimensional on purpose. Every line of a def sits at the def's own elevation, so the anchor's
+     * z always equals the member's own `position.z`. There is no separate z to store.
+     *
+     * Derived, never authored. `applyPlacement` sets it from the def's bounds.
+     */
+    spriteAnchor = null;
     /**
      * Writes the local transform directly and tells the batch its bounds moved.
      *

package/dist/core/text/batched-text-material.js

@@ -56,9 +56,11 @@ export function configureDerivedMaterial(derived, base, uniforms) {
     // term.) Building it here, with a lower id, restores the intended order; troika's getter finds it
     // already cached and uses it.
     derived._outlineMtl = makeOutlineMaterial(derived);
-    // Recompile when the uniform schema changes, since that changes the generated GLSL.
+    // Recompile when the uniform schema changes, since that changes the generated GLSL. The whole
+    // schema, not just whether a texture exists: two batches declaring different uniforms compile
+    // different source, and three compares nothing but this key.
     const cacheKeyBase = derived.customProgramCacheKey.bind(derived);
-    derived.customProgramCacheKey = () => `efpText_${!!uniforms.texture}|${cacheKeyBase()}`;
+    derived.customProgramCacheKey = () => `efpText_${uniforms.shaderKey}|${cacheKeyBase()}`;
     // Assignment, *not* the read-bind-wrap pattern the sibling meshes use: troika defines
     // `onBeforeCompile` as an accessor pair whose getter returns troika's own handler and whose setter
     // stashes ours (troika-three-utils DerivedMaterial), so calling through the getter from inside our

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

@@ -3,16 +3,21 @@ 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.
+ * 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[]): C;
+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}).

package/dist/objects/containers/hooks.js

@@ -1,24 +1,29 @@
 import { useThree } from '@react-three/fiber';
-import { use, useEffect, useRef, useState, useSyncExternalStore } from 'react';
+import { useEffect, useRef, useState, useSyncExternalStore } from 'react';
 import { registerHitResolver } from '../../events/pointer';
 import { registerSlotWriter, subscribeDef, syncNow, versionOf } from '../../update';
-import { LayerDimContext } from '../materials/effects/color-dim';
+import { useLayerDim } 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, and how hits on its mesh resolve back to defs.
+ * 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) {
+export function useContainer(create, defs, onKindMismatch) {
     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 layerDimmed = useLayerDim() > 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
@@ -33,6 +38,16 @@ export function useContainer(create, defs) {
     // 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]);
+    // 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;
 }
 /**

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

@@ -82,9 +82,9 @@ export function writeColorIfChanged(mesh, slot, def, logger) {
     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
+// 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();

package/dist/objects/images/ImageInstance.js

@@ -1,7 +1,8 @@
 import { memo } from 'react';
-import { Matrix4 } from 'three';
+import { Matrix4, Vector2, Vector3 } from 'three';
+import { isBatchedSprites } from '../../core/sprites/BatchedSprites';
+import { Y_DOWN_FLIP } from '../../space/Space';
 import { shapeToMatrix, useDefSync, writeMatrixIfChanged } from '../containers';
-import { imageSourceSize } from './atlas-packer';
 /**
  * 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
@@ -20,64 +21,131 @@ import { imageSourceSize } from './atlas-packer';
 export const ImageInstance = memo(function ImageInstance(props) {
     const { def, packed, container } = props;
     useDefSync(container, def, packed, (slot) => {
-        writeImageMatrix(container.mesh, slot, def, packed);
+        const tile = tileRect(packed);
+        writeImageMatrix(container, slot, def, tile);
+        writeImageAnchor(container, slot, def, tile);
+        // Checked on every sync rather than behind the write, because screenSpace is an ordinary def
+        // field. Flipping it reaches this instance and stops there, so this is where a mesh learns that
+        // it holds something it should not. The atlas re-filters, which never touches the packing.
+        if (!!def.screenSpace !== container.facesCamera)
+            container.reportKindMismatch();
     });
     return null;
 });
 /**
- * Writes an image placement's transform into its instance, skipping the write when nothing moved.
+ * Composes an image placement's instance matrix, and skips the write when nothing moved.
  *
- * `bounds` is a rect, so the quad's placement composes exactly as a rect shape's does; the image's
- * own offsets are then post-multiplied onto it, innermost last. The origin shifts the quad within
- * its own unit square so the anchor — not the quad's center — lands on `bounds.center`, which also
- * makes the anchor the point rotation pivots about. A split source draws as several instances, so
- * this instance's quad is finally shrunk onto the fraction of the image its tile covers.
- * @param mesh - The mesh holding the instance.
+ * `bounds` is a rect, so the quad's placement composes exactly as a rect shape's does. The two
+ * kinds part over the anchor and the tile.
+ *
+ * A flat quad folds the anchor into the matrix. That shifts the quad within its own unit square so
+ * the anchor, not the quad's center, lands on the bounds center, which also makes the anchor the
+ * point rotation pivots about. A tile then shrinks the quad onto the fraction of the image it covers.
+ *
+ * A sprite cannot fold the anchor in. It pivots about its anchor, so the matrix translation has to
+ * be the bounds center and stay there for every tile of a split source. Only the tile's scale and
+ * the plan-to-view y mirror stay in the matrix here. The anchor itself is
+ * {@link writeImageAnchor}'s write, not this one's.
+ * @param container - The container holding the instance, which says which kind it draws.
  * @param slot - The instance's slot.
  * @param def - The image def supplying the transform.
- * @param packed - This instance's placement, whose `source` region marks it as a tile.
+ * @param tile - This instance's tile within the source, or `undefined` for an unsplit image.
  */
-function writeImageMatrix(mesh, slot, def, packed) {
-    // The shared scratch `shapeToMatrix` returns, adjusted in place below and uploaded before any
-    // other write can claim it.
+function writeImageMatrix(container, slot, def, tile) {
     const matrix = shapeToMatrix(def.bounds);
-    // Unit-plane axes run the same way as image axes — x right, y down, matching the atlas uv and the
-    // scene's y-down coordinates — so an origin of `[0, 0]` (top-left) shifts the quad by a positive
-    // half in both, putting its top-left corner on the bounds' center.
-    const [originX, originY] = def.origin ?? DEFAULT_ORIGIN;
-    matrix.multiply(_origin.makeTranslation(0.5 - originX, 0.5 - originY, 0));
-    if (packed.source)
-        applyTile(matrix, packed.source, def);
-    writeMatrixIfChanged(mesh, slot, matrix);
+    if (container.facesCamera) {
+        if (tile)
+            matrix.scale(_tileScale.set(tile.width, tile.height, 1));
+        // Y_DOWN_FLIP is the plan-to-view y mirror for this quad's own 2D linear map. Order does not
+        // matter against the tile scale above: the flip lands on the left of the whole linear map
+        // either way. Premultiplying also flips the translation, so save it and put it back. The
+        // translation is the bounds center the sprite pivots about and must not move.
+        const centerY = matrix.elements[13];
+        matrix.premultiply(Y_DOWN_FLIP);
+        matrix.elements[13] = centerY;
+    }
+    else {
+        const [originX, originY] = def.origin ?? DEFAULT_ORIGIN;
+        // The anchor as an offset from the quad's middle, which is the convention both paths use.
+        const anchorX = originX - 0.5;
+        const anchorY = originY - 0.5;
+        // Unit-plane axes run the same way as image axes, x right and y down, matching the atlas uv and
+        // the scene's y-down coordinates. So an origin of [0, 0], the top-left corner, shifts the quad
+        // by a positive half in both and puts its top-left corner on the bounds center.
+        matrix.multiply(_anchor.makeTranslation(-anchorX, -anchorY, 0));
+        if (tile) {
+            matrix.multiply(_tile.makeScale(tile.width, tile.height, 1).setPosition(tile.x, tile.y, 0));
+        }
+    }
+    writeMatrixIfChanged(container.mesh, slot, matrix);
 }
 /**
- * Post-multiplies the image transform by the local sub-quad a tile occupies, so a split source's
- * tiles reassemble into the whole image. The tile's fraction of the source (in source pixels) is
- * its fraction of the image, so the sub-quad is that fraction of the unit plane — scaled to the
- * tile's size and translated to its center, both in unit-plane coordinates.
- * @param matrix - The image transform, multiplied in place.
- * @param source - The tile's region of the source, in source pixels.
- * @param def - The def whose source supplies the total pixel dimensions.
+ * Writes an image placement's anchor uniform, for the one kind that has one, skipping the write when
+ * it did not move.
+ *
+ * Only a sprite pivots about its anchor. The flat path folds the anchor into the matrix instead (see
+ * {@link writeImageMatrix}) and has no anchor uniform to write. The mesh is narrowed here rather
+ * than asked through `facesCamera`, which answers the same question but cannot narrow the mesh's
+ * type for the two anchor calls. A tile shifts the anchor by the tile's own offset from the image's
+ * middle and rescales it into the tile's unit square, so the result still reads as an offset from
+ * the tile's own middle.
+ *
+ * `setAnchorAt` invalidates the mesh's bounds on every call, so the compare-and-skip is what keeps
+ * a def whose anchor did not move from paying for that invalidation on every sync, the same way
+ * `writeMatrixIfChanged` does for the matrix.
+ * @param container - The container holding the instance.
+ * @param slot - The instance's slot.
+ * @param def - The image def supplying the origin.
+ * @param tile - This instance's tile within the source, or `undefined` for an unsplit image.
  */
-function applyTile(matrix, source, def) {
-    const { width, height } = imageSourceSize(def.source);
-    if (width <= 0 || height <= 0)
+function writeImageAnchor(container, slot, def, tile) {
+    const mesh = container.mesh;
+    if (!isBatchedSprites(mesh))
         return;
-    const fx0 = source.x / width;
-    const fy0 = source.y / height;
-    const fx1 = (source.x + source.width) / width;
-    const fy1 = (source.y + source.height) / height;
-    _tile
-        .makeScale(fx1 - fx0, fy1 - fy0, 1)
-        .setPosition((fx0 + fx1) / 2 - 0.5, (fy0 + fy1) / 2 - 0.5, 0);
-    matrix.multiply(_tile);
+    const [originX, originY] = def.origin ?? DEFAULT_ORIGIN;
+    // The anchor as an offset from the quad's middle, which is the convention both paths use.
+    let x = originX - 0.5;
+    let y = originY - 0.5;
+    if (tile) {
+        x = (x - tile.x) / tile.width;
+        y = (y - tile.y) / tile.height;
+    }
+    mesh.getAnchorAt(slot, _previousAnchor);
+    if (_previousAnchor.x === x && _previousAnchor.y === y)
+        return;
+    mesh.setAnchorAt(slot, x, y);
+}
+/**
+ * Where one tile sits inside the whole image, in unit-quad lengths.
+ * @param packed - This instance's placement, with the tile's region and the source size to divide
+ *   by.
+ * @returns The tile's size and the offset of its center from the image's middle, or `undefined` for
+ *   an unsplit placement or a source that has no size to measure against.
+ */
+function tileRect(packed) {
+    const { source, size } = packed;
+    if (!source || size.width <= 0 || size.height <= 0)
+        return undefined;
+    const fx0 = source.x / size.width;
+    const fy0 = source.y / size.height;
+    const fx1 = (source.x + source.width) / size.width;
+    const fy1 = (source.y + source.height) / size.height;
+    return {
+        width: fx1 - fx0,
+        height: fy1 - fy0,
+        x: (fx0 + fx1) / 2 - 0.5,
+        y: (fy0 + fy1) / 2 - 0.5,
+    };
 }
 /**
  * The anchor a def leaves unset: the image's center, so `bounds.center` is where the middle of the
  * image sits. Matches {@link ImageDef.origin}'s documented default.
  */
 const DEFAULT_ORIGIN = [0.5, 0.5];
-// Scratch shared by every instance and every write: filled and uploaded within a single
-// synchronous statement, so an instance costs a texture write and no allocation.
-const _origin = new Matrix4();
+// Scratch shared by every instance and every write. Each is filled and uploaded within a single
+// synchronous statement, so an instance costs a texture write and no allocation. `_previousAnchor`
+// is only ever read back and compared, so a caller still holding the matrix never collides with it.
+const _anchor = new Matrix4();
 const _tile = new Matrix4();
+const _tileScale = new Vector3();
+const _previousAnchor = new Vector2();

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

@@ -1,5 +1,6 @@
 import { type ImageDef } from '../../types/defs';
 import { type DefsProps } from '../containers';
+import { type CreateAtlasCanvas } from './atlas-packer';
 /** Props for {@link Images}. */
 export interface ImagesProps extends DefsProps<ImageDef> {
     /**
@@ -8,17 +9,24 @@ export interface ImagesProps extends DefsProps<ImageDef> {
      * value to cap atlas memory below it, or to force splitting deterministically in a test.
      */
     maxAtlasSize?: number;
+    /**
+     * Makes each atlas canvas. Defaults to {@link createAtlasCanvas}, which builds an
+     * `OffscreenCanvas` wherever that global exists and a DOM canvas otherwise. The prop exists so
+     * that a test can pack without a real 2D context. It is not part of the public scene API.
+     */
+    createCanvas?: CreateAtlasCanvas;
 }
 /**
- * Draws a collection of images as textured quads, packing their pixels into one or more atlases and
- * drawing each atlas as a single `InstancedMesh` — so a layer of many images costs a handful of
- * draw calls, not one per image.
+ * Draws a collection of images as textured quads, packing their pixels into one or more atlases.
+ * Each atlas draws through up to two meshes that share its texture, so a layer of many images still
+ * costs a handful of draw calls, not one per image.
  *
  * Unlike a shape layer, an image layer can span **several meshes**: bin-packing splits the images
- * across as many atlases as their pixels need, and each atlas gets its own mesh, batch, and
- * texture (an {@link ImageAtlas}). A def whose source is too big for one atlas is cut into tiles
- * that may land on different atlases, so one def can drive several instances — the atlas iterates
- * its packed placements, not the defs.
+ * across as many atlases as their pixels need, and each atlas gets its own texture drawn through up
+ * to two meshes, a flat `InstancedMesh` and a camera-facing `BatchedSprites` (an
+ * {@link ImageAtlas}). An unmixed layer still mounts only one mesh. A def whose source is too big
+ * for one atlas is cut into tiles that may land on different atlases, so one def can drive several
+ * instances. The atlas iterates its packed placements, not the defs.
  *
  * Packing has no incremental path, so a change to the **set** of images **repacks from scratch**: a
  * fresh atlas set under fresh keys, remounting every mesh and instance. A **reorder** of the same
@@ -30,6 +38,10 @@ export interface ImagesProps extends DefsProps<ImageDef> {
  * index) but is best-effort **across** atlases: separate meshes draw in atlas order, which packing
  * decides, not paint order. Overlapping images in one layer that pack onto different atlases is the
  * one case this does not order — rare for the markers, dots, and logos an image layer holds.
+ *
+ * Packing is asynchronous, so a layer draws nothing until its first pack settles, which is one
+ * microtask after the defs arrive. A repack that supersedes a pack still in flight aborts that
+ * pack, and closes whatever it produced.
  * @param props - The images to draw.
  * @returns One {@link ImageAtlas} per packed atlas.
  */