@expofp/renderer 3.38.0 → 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,5 +1,7 @@
 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';
 /**
  * Keeps one image placement current: claims a slot on mount (where the container writes the fixed
@@ -19,65 +21,131 @@ import { shapeToMatrix, useDefSync, writeMatrixIfChanged } from '../containers';
 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.
+    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);
+}
+/**
+ * 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 writeImageAnchor(container, slot, def, tile) {
+    const mesh = container.mesh;
+    if (!isBatchedSprites(mesh))
+        return;
     const [originX, originY] = def.origin ?? DEFAULT_ORIGIN;
-    matrix.multiply(_origin.makeTranslation(0.5 - originX, 0.5 - originY, 0));
-    if (packed.source)
-        applyTile(matrix, packed);
-    writeMatrixIfChanged(mesh, slot, matrix);
+    // 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);
 }
 /**
- * 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
- * also its fraction of the image. So the sub-quad is that same fraction of the unit plane. The
- * code scales the sub-quad to the tile's size, then moves it so its center lands on that
- * fraction's center point, in unit-plane coordinates.
- * @param matrix - The image transform, multiplied in place.
+ * 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 applyTile(matrix, packed) {
+function tileRect(packed) {
     const { source, size } = packed;
     if (!source || size.width <= 0 || size.height <= 0)
-        return;
+        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;
-    _tile
-        .makeScale(fx1 - fx0, fy1 - fy0, 1)
-        .setPosition((fx0 + fx1) / 2 - 0.5, (fy0 + fy1) / 2 - 0.5, 0);
-    matrix.multiply(_tile);
+    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

@@ -17,15 +17,16 @@ export interface ImagesProps extends DefsProps<ImageDef> {
     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

package/dist/objects/images/Images.js

@@ -3,25 +3,27 @@ import { useThree } from '@react-three/fiber';
 import { use, useEffect, useRef, useState } from 'react';
 import { CanvasTexture, SRGBColorSpace } from 'three';
 import { InstancedMesh } from '../../core/instanced/InstancedMesh';
+import { BatchedSprites } from '../../core/sprites/BatchedSprites';
 import { createLogger } from '../../utils/logging';
 import { defKey, useContainer } from '../containers';
 import { TextureMaterial } from '../materials/TextureMaterial';
-import { packAtlases } from './atlas-packer';
+import { packAtlases, } from './atlas-packer';
 import { ImageContainer, UV_OFFSET_UNIFORM } from './image-container';
 import { ImageInstance } from './ImageInstance';
 import { contextOf, createAtlasCanvas } from './pack-sources';
 import { TextureBudgetContext, useResizeFactor } from './texture-budget';
 const logger = createLogger('images');
 /**
- * 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
@@ -107,26 +109,26 @@ export function Images(props) {
     return (_jsx(_Fragment, { children: packed.atlases.map((atlas) => (_jsx(ImageAtlas, { atlas: atlas, defs: defs, mounted: mounted }, atlasKey(atlas, packed.generation)))) }));
 }
 /**
- * Draws one atlas as an `InstancedMesh`: the R3F-owned mesh with the atlas texture as its
- * `TextureMaterial`, plus one {@link ImageInstance} per placement on the atlas. Its set of images is
- * fixed for its lifetime — a repack remounts the whole component — so the batch and texture are
- * built once from state and released together on unmount. Paint order is not fixed: a reorder keeps
- * this atlas and re-labels its instances through the effect below.
+ * Owns one atlas's texture and its flat/sprite split, and draws each non-empty side as its own
+ * `AtlasMesh`. The atlas's set of images is fixed for its lifetime. A repack remounts the whole
+ * component, so the texture is built once from state and released on unmount.
  *
- * The uploaded texture is not fixed either: a resizable atlas registers with the scene's texture
- * budget and re-derives a downscaled copy of its canvas whenever the shared resize factor moves (see
- * {@link resizeTexture}). That is a texture re-upload, not a repack — the mesh, container,
- * instances, and their normalized uv regions all stand, since uv is invariant to the canvas's pixel
- * size.
+ * The uploaded texture is not fixed. A resizable atlas registers with the scene's texture budget and
+ * re-derives a downscaled copy of its canvas whenever the shared resize factor moves (see
+ * {@link resizeTexture}). That is a texture re-upload, not a repack. The meshes, their containers,
+ * their instances, and their normalized uv regions all stand, because uv does not depend on the
+ * canvas's pixel size.
+ *
+ * The flat/sprite split is a second kind of state, held here rather than derived every render. A
+ * def's `screenSpace` is an ordinary slot write that never re-renders this component, so an
+ * `AtlasMesh` calls `repartition` when it finds a member that no longer matches its kind.
  * @param props - The atlas and the layer's images in paint order.
- * @returns The mesh and one instance component per placement.
+ * @returns One `AtlasMesh` per non-empty kind, sharing this atlas's texture.
  */
 function ImageAtlas(props) {
     const { atlas, defs } = props;
-    // Only the placements are staged; the container and the texture are built from the whole atlas.
     const mounted = props.mounted ?? atlas.images.length;
     const [texture] = useState(() => makeAtlasTexture(atlas.image));
-    const container = useContainer(() => new ImageContainer(atlas), defs);
     const invalidate = useThree((state) => state.invalidate);
     const budget = use(TextureBudgetContext);
     const factor = useResizeFactor(budget, atlas);
@@ -157,15 +159,79 @@ function ImageAtlas(props) {
         const scaled = scaledRef.current;
         return () => closeScaled(scaled);
     }, []);
-    // `args` is a frozen snapshot so R3F never rebuilds the mesh; the `ref` arrow (not
-    // `ref={container.bind}`) keeps the React Compiler from inferring `container` itself as a ref and
+    // Held in state rather than derived each render, which is the shape `Shapes` uses for its own
+    // split. screenSpace is an ordinary slot write that never re-renders this component, so a def
+    // crossing the orientation boundary would otherwise stay in a mesh that no longer suits it.
+    // repartition is what an instance's reportKindMismatch runs. The atlas's placements never change
+    // identity, because a repack remounts this whole component, so nothing else triggers a re-split.
+    const [partition, setPartition] = useState(() => partitionImages(atlas.images));
+    /** Re-splits the atlas's placements, for a mesh that found a member of the wrong kind. */
+    function repartition() {
+        setPartition(() => partitionImages(atlas.images));
+    }
+    // One mesh per kind, keyed so React never reconciles a flat mesh element against a sprite one
+    // when the first kind empties out. An empty subset renders nothing, so an unmixed layer costs
+    // exactly what it costs today and a mixed layer costs one extra draw call per atlas.
+    //
+    // renderOrder is the kind's place in IMAGE_KINDS, which makes "flats, then sprites" an explicit
+    // rule within a layer. Today the atlas meshes carry no order at all and it falls out of
+    // material.id, which is mount order. What that costs is that a flat def and a sprite def in one
+    // layer can no longer interleave in array order. `overlay` is there for a caller who needs strict
+    // separation, and a camera-facing pin is generally meant to be on top anyway.
+    return (_jsx(_Fragment, { children: IMAGE_KINDS.map((kind, renderOrder) => {
+            const placements = partition[kind];
+            if (placements.length === 0)
+                return null;
+            return (_jsx(AtlasMesh, { kind: kind, placements: placements, defs: defs, mounted: mounted, capacity: atlas.images.length, texture: texture, renderOrder: renderOrder, onKindMismatch: repartition }, kind));
+        }) }));
+}
+/**
+ * One atlas mesh and its instances: the atlas's flat images or its camera-facing ones, never both.
+ *
+ * The material is a child and is genuinely per mesh. `InstancedMeshImpl` wraps whatever it draws with
+ * in a closure over its own textures, and two instanced meshes on one material would both render
+ * against the first one's. The texture is shared, and that is the whole of the two-mesh split: an
+ * atlas is a texture packing and a mesh is a draw call, and nothing forces them to be one thing.
+ *
+ * The sprite mesh mounts no plane geometry child. `BatchedSpritesImpl` seeds the shared quad
+ * itself, and not rendering a replacement is what makes the seeded one stand.
+ * @param props - The kind, its placements, and the shared texture.
+ * @returns The mesh and one instance component per placement.
+ */
+function AtlasMesh(props) {
+    const { kind, placements, defs, capacity, texture, renderOrder, onKindMismatch } = props;
+    // Handed to this mesh as a prefix of its own placements rather than apportioned between the two,
+    // as Shapes does for its batches. A slice can overshoot the scheduler's budget by a factor of two
+    // at worst, and the scheduler measures what a slice actually cost and sizes the next one from it.
+    const mounted = props.mounted ?? placements.length;
+    // Sized from the atlas's whole placement count, not this subset's, so a re-split never resizes a
+    // buffer. The container is bookkeeping only, so the copy StrictMode's double-invoked initializer
+    // discards is plain garbage.
+    const container = useContainer(() => new ImageContainer(capacity), defs, onKindMismatch);
+    // args is a frozen snapshot, so R3F never rebuilds the mesh. The ref arrow, rather than
+    // ref={container.bind}, keeps the React Compiler from inferring container itself as a ref and
     // rejecting its render reads.
-    // The quad and the material are children so R3F creates, attaches, and disposes both — the args
-    // pair are placeholders the constructor demands (see `ImageMeshArgs`). The material has to be per
-    // mesh: `InstancedMeshImpl` wraps whatever it draws with in a closure over its own textures, and two
-    // instanced meshes on one material would both render against the first one's.
-    return (_jsxs(_Fragment, { children: [_jsxs(InstancedMesh, { args: container.args, ref: (mesh) => container.bind(mesh), sortObjects: true, customSort: container.customSort, perObjectFrustumCulled: true, children: [_jsx("planeGeometry", {}), _jsx(TextureMaterial, { map: texture, uvOffset: UV_OFFSET_UNIFORM })] }), atlas.images.slice(0, mounted).map((packed) => (_jsx(ImageInstance, { def: packed.def, packed: packed, container: container }, `${defKey(packed.def)}:${packed.uv.u0}:${packed.uv.v0}`)))] }));
+    const mesh = kind === 'sprite' ? (_jsx(BatchedSprites, { args: container.args, ref: (instance) => container.bind(instance), sortObjects: true, customSort: container.customSort, perObjectFrustumCulled: true, renderOrder: renderOrder, children: _jsx(TextureMaterial, { map: texture, uvOffset: UV_OFFSET_UNIFORM }) })) : (_jsxs(InstancedMesh, { args: container.args, ref: (instance) => container.bind(instance), sortObjects: true, customSort: container.customSort, perObjectFrustumCulled: true, renderOrder: renderOrder, children: [_jsx("planeGeometry", {}), _jsx(TextureMaterial, { map: texture, uvOffset: UV_OFFSET_UNIFORM })] }));
+    return (_jsxs(_Fragment, { children: [mesh, placements.slice(0, mounted).map((packed) => (_jsx(ImageInstance, { def: packed.def, packed: packed, container: container }, `${defKey(packed.def)}:${packed.uv.u0}:${packed.uv.v0}`)))] }));
+}
+/**
+ * Splits an atlas's placements by orientation.
+ *
+ * A filter over an array the component already holds. The packing, the canvas, the uv regions and the
+ * texture budget are all untouched, so nothing repacks. That is what makes flipping a def's
+ * screenSpace cheaper here than a shape's kind change, where a re-split rebuilds partitions.
+ * @param images - The atlas's placements, in packing order.
+ * @returns The two subsets, each still in packing order.
+ */
+function partitionImages(images) {
+    const flat = [];
+    const sprite = [];
+    for (const packed of images)
+        (packed.def.screenSpace === true ? sprite : flat).push(packed);
+    return { flat, sprite };
 }
+/** The atlas's two meshes, in draw order: flats first, then the camera-facing ones. */
+const IMAGE_KINDS = ['flat', 'sprite'];
 /**
  * Whether two snapshots hold the same *set* of images, order aside — the question "does this need a
  * repack". Order is excluded on purpose: packing reads only pixels, so a reorder produces the same