@expofp/renderer 0.0.0-experimental.cf063fc

package/dist/objects/images/ImageInstance.js

@@ -0,0 +1,152 @@
+import { memo } from 'react';
+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
+ * uv region), writes the def's transform and visibility on mount and after every `update(def)`, and
+ * releases the slot on unmount.
+ *
+ * Renders no scene node — the mesh belongs to the container. Only the transform lives here:
+ * visibility is `useDefSync`'s, the uv region is written once at claim (a def's source cannot
+ * change), and color has no analogue for a textured quad. Memoized for the same reason as
+ * `ShapeInstance`: a structural change hands the atlas a fresh placement list, rebuilding every
+ * instance element, so only prop-equality keeps the unchanged siblings from re-rendering. Both props
+ * are identity-stable across a membership's lifetime — a change repacks into a fresh container and
+ * fresh placements — so the bailout holds.
+ * @param props - The def, its placement, and its container.
+ * @returns `null`; the instance lives in the mesh, not the scene graph.
+ */
+export const ImageInstance = memo(function ImageInstance(props) {
+    const { def, packed, container } = props;
+    useDefSync(container, def, () => packed, (slot) => {
+        const tile = tileRect(packed);
+        writeImageMatrix(container, slot, def, tile);
+        writeImageAnchor(container, slot, def, tile);
+        container.setOpacityAt(slot, def.opacity);
+        // 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;
+});
+/**
+ * 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 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 tile - This instance's tile within the source, or `undefined` for an unsplit image.
+ */
+function writeImageMatrix(container, slot, def, tile) {
+    const matrix = shapeToMatrix(def.bounds);
+    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;
+    // 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. 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

@@ -0,0 +1,49 @@
+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> {
+    /**
+     * Largest atlas edge in pixels, capping how big a source can be before it is split into tiles.
+     * Defaults to the GPU's `maxTextureSize`, which is the true hardware ceiling; pass a smaller
+     * 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.
+ * 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 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
+ * set does not — packing is order-independent, so the atlases stand and each simply re-labels its
+ * instances' paint order in place. A per-def `update()` flows straight to the instance's slot, never
+ * through here.
+ *
+ * Paint order holds **within** an atlas (each mesh sorts its instances by the def's membership
+ * 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.
+ */
+export declare function Images(props: ImagesProps): import("react").JSX.Element;
+//# sourceMappingURL=Images.d.ts.map

package/dist/objects/images/Images.js

@@ -0,0 +1,394 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+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 { ImageContainer, OPACITY_UNIFORM, 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.
+ * 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 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
+ * set does not — packing is order-independent, so the atlases stand and each simply re-labels its
+ * instances' paint order in place. A per-def `update()` flows straight to the instance's slot, never
+ * through here.
+ *
+ * Paint order holds **within** an atlas (each mesh sorts its instances by the def's membership
+ * 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.
+ */
+export function Images(props) {
+    const { defs, maxAtlasSize, createCanvas } = props;
+    // Handed to each atlas as a prefix of *its* placements rather than apportioned between them, and
+    // a split source has several placements per def — so a slice mounts somewhere between one and a
+    // few instances per granted child. The scheduler measures what a slice cost and sizes the next
+    // one from that, which is what keeps the budget whatever the ratio turns out to be here.
+    const mounted = props.mounted ?? defs.length;
+    const gl = useThree((state) => state.gl);
+    const invalidate = useThree((state) => state.invalidate);
+    const maxTextureSize = maxAtlasSize ?? gl.capabilities.maxTextureSize;
+    // Repack when the *set* of images changes, through the "adjust state on prop change" pattern. The
+    // comparison reads content and not identity. `useStagedChildren` rebuilds its snapshot on *every*
+    // `update(layer)`, even one that only flipped the layer's own `hidden`, so identity alone would
+    // repack for changes that touched no image. Order is excluded on purpose. Packing reads only
+    // pixels, so a reorder produces the same atlases and needs no repack, only the paint-order
+    // relabel that each atlas does below. Set equality costs O(n) over a list already in cache, and a
+    // repack redraws every canvas.
+    const [target, setTarget] = useState(defs);
+    if (!sameSet(target, defs))
+        setTarget(defs);
+    const [packed, setPacked] = useState(NO_ATLASES);
+    // Pack the current target, and abandon the pack when the target moves before that pack settles. A
+    // pack that already produced atlases when it is abandoned closes them here. Nothing mounted them,
+    // so nothing else will.
+    //
+    // No abort reaches that branch today, on either tier. Everything from the pack's own result down
+    // to the handler below is one uninterrupted drain of microtasks, and the only call to `abort` is
+    // this effect's cleanup, which runs in a task. So an abort lands before the result, and
+    // `packAtlases` rejects instead; or it lands after `adopted` is set, and the cleanup does not
+    // abort at all. The branch stays as insurance. One task boundary added anywhere in that chain
+    // opens the window, and the cost of finding out late is a leaked set of atlases.
+    useEffect(() => {
+        const controller = new AbortController();
+        let adopted = false;
+        packAtlases(target, maxTextureSize, { createCanvas, signal: controller.signal }).then((atlases) => {
+            if (controller.signal.aborted) {
+                closeAtlases(atlases);
+                return;
+            }
+            adopted = true;
+            setPacked((current) => ({
+                defs: target,
+                atlases,
+                generation: current.generation + 1,
+            }));
+            invalidate();
+        }, (error) => {
+            // An abort is the normal end of a superseded pack, and not a fault worth reporting.
+            if (!controller.signal.aborted)
+                logger.error('atlas pack failed %O', error);
+        });
+        return () => {
+            if (!adopted)
+                controller.abort();
+        };
+    }, [target, maxTextureSize, createCanvas, invalidate]);
+    // Free the pixels of a pack that a later pack superseded, and of the pack that is mounted when
+    // this layer goes away. The effect is keyed on the pack object, so its cleanup holds the pack it
+    // closes and never the pack that is mounted now. The initial state holds no atlases, so
+    // StrictMode's simulated remount cycles this effect once with that initial value and closes
+    // nothing.
+    useEffect(() => {
+        return () => closeAtlases(packed.atlases);
+    }, [packed]);
+    return (_jsx(_Fragment, { children: packed.atlases.map((atlas) => (_jsx(ImageAtlas, { atlas: atlas, defs: defs, mounted: mounted }, atlasKey(atlas, packed.generation)))) }));
+}
+/**
+ * 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. 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 One `AtlasMesh` per non-empty kind, sharing this atlas's texture.
+ */
+function ImageAtlas(props) {
+    const { atlas, defs } = props;
+    const mounted = props.mounted ?? atlas.images.length;
+    const [texture] = useState(() => makeAtlasTexture(atlas.image));
+    const invalidate = useThree((state) => state.invalidate);
+    const budget = use(TextureBudgetContext);
+    const factor = useResizeFactor(budget, atlas);
+    const scaledRef = useRef({});
+    // Only the texture is ours to free — the mesh, its quad, and its material are all R3F's.
+    // StrictMode's simulated unmount disposes then remounts, but three's `dispose` only frees GPU
+    // resources — the state-retained texture re-uploads from its canvas on the next render — so the
+    // double is a harmless dev-only reupload, not a use-after-free.
+    useEffect(() => {
+        invalidate();
+        return () => texture.dispose();
+    }, [texture, invalidate]);
+    // Re-derive the uploaded pixels for the current resize factor. This runs on mount and on every
+    // factor change. A fixed atlas always reads a factor of `1`, so this settles once for it and
+    // never fires again.
+    useEffect(() => {
+        resizeTexture(texture, atlas.image, scaledRef, factor);
+        invalidate();
+    }, [texture, atlas, factor, invalidate]);
+    // The smaller copy belongs to this component, not to the atlas, so this effect frees it. This is
+    // safe under StrictMode's simulated unmount. The next `resizeTexture` call rebuilds the copy from
+    // the full atlas, which stays untouched.
+    //
+    // `scaledRef.current` is read once, here, instead of inside the returned function. The ref holds
+    // one stable object for the component's whole life and is never pointed at a new one, so the read
+    // is safe either way, but reading it here is what lets the cleanup skip a ref read of its own.
+    useEffect(() => {
+        const scaled = scaledRef.current;
+        return () => closeScaled(scaled);
+    }, []);
+    // 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.
+    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, opacityUniform: OPACITY_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, opacityUniform: OPACITY_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
+ * atlases and needs only a paint-order relabel, not a repack. Array identity answers neither
+ * question, because the store hands out a fresh snapshot on every layer update.
+ * @param a - The packed set.
+ * @param b - The incoming set.
+ * @returns Whether they hold the same defs.
+ */
+function sameSet(a, b) {
+    if (a.length !== b.length)
+        return false;
+    const set = new Set(a);
+    return b.every((def) => set.has(def));
+}
+/**
+ * A stable React key for an atlas: the repack generation, so a repack remounts every atlas, plus
+ * its first placement's def, uv origin, and — for a split source — tile region, which together no
+ * other atlas in the same generation can repeat (a placement lands on exactly one atlas). Packing
+ * never returns an empty atlas, so the first placement always exists.
+ * @param atlas - The atlas to key.
+ * @param generation - The repack counter this atlas belongs to.
+ * @returns The key.
+ */
+function atlasKey(atlas, generation) {
+    const first = atlas.images[0];
+    // A def keys by identity and uv origin, but a source split into one-tile-per-atlas puts the same
+    // def at uv origin (0, 0) on every one of its atlases; the tile's source region is what tells
+    // those atlases apart. Absent for an unsplit image, whose uv origin already differs per atlas.
+    const region = first.source ? `:${first.source.x},${first.source.y}` : '';
+    return `${generation}:${defKey(first.def)}:${first.uv.u0}:${first.uv.v0}${region}`;
+}
+/**
+ * Releases an atlas's pixel memory.
+ *
+ * A worker returns each atlas as an `ImageBitmap`, which holds its pixels outside the JavaScript
+ * heap, where garbage collection does not reclaim them promptly. Every path that drops an atlas must
+ * therefore close it: a repack that supersedes one, a canceled pack, and unmount. A canvas has no
+ * `close`, so the inline path passes through here and nothing happens.
+ * @param atlases - The atlases to release.
+ */
+function closeAtlases(atlases) {
+    for (const atlas of atlases) {
+        if ('close' in atlas.image)
+            atlas.image.close();
+    }
+}
+/**
+ * Points an atlas texture at the pixels for the current resize factor.
+ *
+ * At `factor >= 1`, the texture points at the full atlas. Below that, it points at a downscaled
+ * copy.
+ *
+ * The copy lives in `scaledRef`. The function creates the copy the first time it needs one. After
+ * that, it resizes the same copy in place. If the factor later climbs back up because the budget
+ * freed up, the next downscale starts from the untouched full atlas. It never upscales pixels
+ * already thrown away. The atlas keeps the full atlas regardless, so a downscale costs one extra
+ * surface only while it is active. UVs stay the same throughout. They are normalized, so the same
+ * regions still address the smaller surface without change.
+ *
+ * Where `OffscreenCanvas` exists, the downscale draws into one and uploads the bitmap from its
+ * `transferToImageBitmap()`. The whole design avoids uploading a DOM canvas. Without
+ * `OffscreenCanvas` here, a downscale below a factor of 1 brings that cost back on every atlas.
+ * @param texture - The atlas texture to re-point.
+ * @param full - The full-resolution atlas pixels. The function never changes them.
+ * @param scaledRef - Holds the smaller copy across factor changes. Its object is stable for the
+ *   caller's whole life; only the fields inside it change.
+ * @param factor - The linear scale factor, in `(0, 1]`.
+ */
+function resizeTexture(texture, full, scaledRef, factor) {
+    const scaled = scaledRef.current;
+    if (factor >= 1) {
+        // Point back at the full atlas. Close and drop a copy from an earlier, smaller factor.
+        if (texture.image !== full) {
+            closeScaled(scaled);
+            texture.image = full;
+            texture.needsUpdate = true;
+        }
+        return;
+    }
+    const width = Math.max(1, Math.round(full.width * factor));
+    const height = Math.max(1, Math.round(full.height * factor));
+    const atlasCanvas = (scaled.canvas ??= createAtlasCanvas(width, height));
+    // Setting the size also clears the canvas, so the downscale draws onto a blank surface.
+    atlasCanvas.width = width;
+    atlasCanvas.height = height;
+    const context = contextOf(atlasCanvas);
+    // A missing 2D context is a dead end, the same as a blank atlas. Fall back to the full atlas, so
+    // the images still draw over budget rather than not at all. Close the last transfer on the way
+    // out: the texture points at the full atlas from here on, so the `texture.image !== full` guard
+    // above never fires again and nothing else would ever free those pixels.
+    if (!context) {
+        closeScaled(scaled);
+        texture.image = full;
+        texture.needsUpdate = true;
+        return;
+    }
+    context.drawImage(full, 0, 0, width, height);
+    // The old transfer's pixels are dead the moment a new one replaces them. Garbage collection does
+    // not reclaim an `ImageBitmap` right away.
+    scaled.bitmap?.close();
+    scaled.bitmap =
+        'transferToImageBitmap' in atlasCanvas ? atlasCanvas.transferToImageBitmap() : undefined;
+    texture.image = scaled.bitmap ?? atlasCanvas;
+    texture.needsUpdate = true;
+}
+/**
+ * Releases a smaller copy's transferred pixels, if the copy ever took one.
+ * @param scaled - The copy.
+ */
+function closeScaled(scaled) {
+    scaled.bitmap?.close();
+    scaled.bitmap = undefined;
+}
+/**
+ * Wraps an atlas image as a texture for `MeshBasicMaterial.map`.
+ *
+ * Mipmaps stay on. A floor plan is zoomed far out as often as it is zoomed far in, and without
+ * mipmaps every image shimmers under minification. The cost is that neighbors can bleed through
+ * the deeper mip levels, where the packer's one-pixel gutter no longer separates them.
+ * @param image - The packed atlas image: a canvas, or a bitmap a worker transferred out of one.
+ * @returns The texture.
+ */
+function makeAtlasTexture(image) {
+    const texture = new CanvasTexture(image);
+    // The atlas holds sRGB pixels; tagging the color space is what makes `MeshBasicMaterial` sample
+    // and display them without a gamma shift.
+    texture.colorSpace = SRGBColorSpace;
+    // Upload the canvas rows in their own order, instead of the vertical flip three applies by
+    // default. This way, v runs down the atlas, in the same direction as the packer's uv regions and
+    // the scene's y axis. Every axis in the chain then points the same way. If only one end flips,
+    // images come out upside down.
+    //
+    // This governs the inline path, where the texture uploads a canvas. For an `ImageBitmap`, this
+    // line does nothing: three skips it, along with two other pixel-store calls, whenever the
+    // texture image is an `ImageBitmap` (see `premultiplyAlpha`, below, for the one skip that is not
+    // harmless). Orientation then comes from how the bitmap was made. The worker draws into an
+    // `OffscreenCanvas` with row 0 at the top and transfers it unflipped, which matches the
+    // orientation `UvRect` documents. Do not delete this line: the worker path does not read it, but
+    // the inline path still does.
+    texture.flipY = false;
+    // The same skip covers `UNPACK_PREMULTIPLY_ALPHA_WEBGL` and `UNPACK_COLORSPACE_CONVERSION_WEBGL`.
+    // Skipping the second changes nothing: it is a legacy flag for an embedded color profile, and an
+    // atlas canvas is drawn, never decoded from a file that could carry one. Skipping the first is
+    // not harmless. `transferToImageBitmap()` hands over the canvas's own backing store, which a 2D
+    // canvas always keeps premultiplied, and it takes no option to ask for straight alpha instead.
+    // With the GL call skipped, that premultiplied data reaches the texture unchanged. Setting
+    // `premultiplyAlpha = true` here makes the canvas path premultiply on upload too, so both paths
+    // agree by construction rather than by luck. `TextureMaterial` blends on that agreement: it
+    // expects a premultiplied source, not a straight one.
+    texture.premultiplyAlpha = true;
+    texture.generateMipmaps = true;
+    return texture;
+}
+/**
+ * The pack that a layer starts on: none. Packing is asynchronous, so a layer draws nothing for the
+ * first microtask of its life. One value serves every layer, because every layer starts from the
+ * same nothing, and nothing writes to it.
+ */
+const NO_ATLASES = { defs: [], atlases: [], generation: 0 };