@expofp/renderer 0.0.0-experimental.cf063fc

package/dist/objects/images/atlas-packer.d.ts

@@ -0,0 +1,129 @@
+import { type ImageDef, type ImageSource } from '../../types/defs';
+import { type AtlasCanvas, type CreateAtlasCanvas, type SourceRect, type UvRect } from './pack-sources';
+export { type AtlasCanvas, type CreateAtlasCanvas, isResizableSource, type SourceRect, type UvRect, } from './pack-sources';
+/**
+ * The pixels an atlas can hold: a canvas, or a bitmap transferred out of one.
+ *
+ * `AtlasCanvas` stays narrow on purpose. `CreateAtlasCanvas` and `contextOf` both need a type they
+ * can open a 2D context on, and an `ImageBitmap` has no context to open.
+ */
+export type AtlasImage = AtlasCanvas | ImageBitmap;
+/** One image, or one tile of a split image, placed in an atlas. */
+export interface PackedImage {
+    /**
+     * The def that these pixels belong to. Defs whose sources dedupe appear as separate entries
+     * that share one region, so the list maps one-to-one onto the instances that an atlas must
+     * draw.
+     */
+    def: ImageDef;
+    /** Where the pixels sit in the atlas. */
+    uv: UvRect;
+    /**
+     * Which part of `def.source` this entry holds. This is undefined when the source packs whole,
+     * which is the common case. It is set only on the tiles of a split source, where a consumer
+     * needs it to work out the fraction of `def.bounds` that this tile covers.
+     */
+    source?: SourceRect;
+    /**
+     * The intrinsic pixel size of `def.source`. The packer measures this once and carries it on the
+     * placement, because a `Blob` source cannot be measured again later. A tile's consumer reads
+     * this field to find the fraction of the image the tile covers. The field spares that consumer
+     * from decoding the source a second time.
+     */
+    size: {
+        width: number;
+        height: number;
+    };
+}
+/** One packed atlas: its pixels, and a record of what landed where on it. */
+export interface Atlas {
+    /**
+     * The atlas's packed pixels: a canvas, or a bitmap a worker transferred out of one. Its
+     * `width`/`height` are the atlas's size.
+     */
+    image: AtlasImage;
+    /** Every def placement on this atlas. */
+    images: PackedImage[];
+    /**
+     * Whether this atlas's pixels can shrink to fit a memory budget. Image and bitmap sources pack
+     * into resizable atlases. Canvas sources pack into fixed ones. An atlas never mixes the two
+     * kinds, because the code packs them as separate groups. So this one flag applies to every
+     * placement on the atlas. It lets a memory budget scale a whole resizable canvas at once,
+     * without changing a canvas source's pixels. See {@link isResizableSource}.
+     */
+    resizable: boolean;
+}
+/** Options for {@link packAtlases}. */
+export interface AtlasPackerOptions {
+    /** Creates each atlas canvas. Defaults to {@link createAtlasCanvas}. */
+    createCanvas?: CreateAtlasCanvas;
+    /**
+     * Abandons the pack. A repack that supersedes a pack still in flight aborts that pack. The
+     * worker is told to drop it and goes on running, and a result that still arrives is thrown away
+     * instead of mounted.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Where a pack draws its atlases.
+ *
+ * There are two tiers and not three. Both tiers decode with `createImageBitmap`, because every
+ * build target has it (the plan's Global Constraints hold the compat data). What changes between
+ * the tiers is whether the drawing can leave the main thread. That turns on `OffscreenCanvas`,
+ * which Chrome 66 and Safari 15 do not have. The inline tier is a normal path for those targets
+ * and not an edge case. It is already around five times cheaper than the code it replaces, because
+ * it no longer decodes an `<img>`.
+ */
+export type PackTier = 
+/** `Worker` and `OffscreenCanvas` are present, and every source is a `Blob`: pack off-thread. */
+'worker'
+/** Anything else: decode and pack on the main thread. */
+ | 'inline';
+/**
+ * Packs image defs into atlas canvases and reports where each def's pixels landed.
+ *
+ * The code first dedupes the defs. Two defs that point at the same URL, or that hold the same
+ * object, draw once and share one region. The code then decodes every source that is not drawable
+ * yet, which is what makes this function asynchronous: a `Blob` holds bytes and not pixels. The
+ * code then hands the decoded sources to {@link packSources}, which does the pixel work. The
+ * placements come back addressed by source index, and this function expands them into one entry
+ * per def.
+ *
+ * Packing reads only the sources' pixel dimensions, never `bounds`. So a def that later moves or
+ * resizes keeps its region: the quad's matrix scales it, and nothing needs repacking. A change in
+ * membership is different. This is a batch call with no incremental path, so an added or removed
+ * def needs a fresh call.
+ *
+ * A worker that fails for any reason other than an abort falls back to the inline tier once. The
+ * worker is an optimization, and no host page may cost a layer its images by refusing one.
+ * @param defs - The images to pack.
+ * @param maxDimension - The largest atlas edge, in pixels. The function floors this to a positive
+ *   integer.
+ * @param options - Overrides for how atlas canvases are made, and the signal that abandons the
+ *   pack.
+ * @returns One entry for each atlas, in packing order: resizable atlases first, then fixed ones.
+ */
+export declare function packAtlases(defs: readonly ImageDef[], maxDimension: number, options?: AtlasPackerOptions): Promise<Atlas[]>;
+/**
+ * Picks the higher tier when this environment and this set of sources both allow it.
+ *
+ * A layer packs in the worker only when **every** source is a `Blob`. One source of any other kind
+ * keeps the whole layer on the main thread.
+ *
+ * The test names what may cross, never what must stay. A test that only excludes the known-bad
+ * kinds admits every kind nobody thought of, and this code shipped that mistake once: it asked
+ * whether a source was not a DOM canvas, which let an `<img>` through. An `<img>` neither clones
+ * nor moves, so `postMessage` threw on it and the layer drew nothing.
+ *
+ * A `Blob` is also the only source the worker can take without taking it from the def that owns it.
+ * Its handle clones, so the def keeps its bytes. Every other kind would have to move, and a moved
+ * source is dead on the main thread, so the next repack would find nothing to draw. Those sources
+ * lose nothing by packing inline. A canvas cannot cross at all — `transferControlToOffscreen` throws
+ * on a canvas that already holds a 2D context, and every floorplan canvas source holds one — and
+ * `createImageBitmap(canvas)` costs more than a pack of that canvas on the main thread (this is
+ * measured, see the design spec).
+ * @param sources - The unique sources that this pack will draw.
+ * @returns The tier to run.
+ */
+export declare function selectTier(sources: readonly ImageSource[]): PackTier;
+//# sourceMappingURL=atlas-packer.d.ts.map

package/dist/objects/images/atlas-packer.js

@@ -0,0 +1,287 @@
+import { createLogger } from '../../utils/logging';
+import { createAtlasCanvas, isBlob, packSources, } from './pack-sources';
+import { packInWorker } from './worker';
+const logger = createLogger('atlas-packer');
+/**
+ * How many source pixels per square unit of `bounds` a def can carry before code calls it
+ * over-sampled. Past this limit, the extra resolution cannot reach the screen at any reasonable
+ * zoom. The atlas space and texture memory are then wasted, usually on a full-size logo that
+ * stands in for a marker icon.
+ */
+const MAX_AREA_RATIO = 1000;
+export { isResizableSource, } from './pack-sources';
+/**
+ * Packs image defs into atlas canvases and reports where each def's pixels landed.
+ *
+ * The code first dedupes the defs. Two defs that point at the same URL, or that hold the same
+ * object, draw once and share one region. The code then decodes every source that is not drawable
+ * yet, which is what makes this function asynchronous: a `Blob` holds bytes and not pixels. The
+ * code then hands the decoded sources to {@link packSources}, which does the pixel work. The
+ * placements come back addressed by source index, and this function expands them into one entry
+ * per def.
+ *
+ * Packing reads only the sources' pixel dimensions, never `bounds`. So a def that later moves or
+ * resizes keeps its region: the quad's matrix scales it, and nothing needs repacking. A change in
+ * membership is different. This is a batch call with no incremental path, so an added or removed
+ * def needs a fresh call.
+ *
+ * A worker that fails for any reason other than an abort falls back to the inline tier once. The
+ * worker is an optimization, and no host page may cost a layer its images by refusing one.
+ * @param defs - The images to pack.
+ * @param maxDimension - The largest atlas edge, in pixels. The function floors this to a positive
+ *   integer.
+ * @param options - Overrides for how atlas canvases are made, and the signal that abandons the
+ *   pack.
+ * @returns One entry for each atlas, in packing order: resizable atlases first, then fixed ones.
+ */
+export async function packAtlases(defs, maxDimension, options = {}) {
+    const startedAt = performance.now();
+    const { createCanvas = createAtlasCanvas, signal } = options;
+    const entries = collectSources(defs);
+    const sources = entries.map((entry) => entry.source);
+    let tier = selectTier(sources);
+    let packed = null;
+    if (tier === 'worker') {
+        try {
+            packed = await packWorkerTier(entries, sources, maxDimension, signal);
+        }
+        catch (error) {
+            // An abort is the caller's own decision, and nothing may run after it.
+            if (signal?.aborted)
+                throw error;
+            // Any other failure is the worker alone failing, and the main thread can still do the work.
+            // The case that matters is a host page whose `script-src` forbids `blob:` and `data:`:
+            // `new Worker()` throws there, this SDK runs on origins it does not control, and without
+            // this the layer would stay blank on that site.
+            logger.warn('the worker could not pack, packing inline instead %O', error);
+            tier = 'inline';
+        }
+    }
+    // Only if the worker tier did not run, or ran and failed. `??=` does not evaluate its right side
+    // when the left side already holds the atlases.
+    packed ??= await packInlineTier(entries, sources, maxDimension, createCanvas, signal);
+    const elapsed = (performance.now() - startedAt).toFixed(1);
+    logger.debug('packed defs: %d, sources: %d, atlases: %d, tier: %s (%sms)', packed.reduce((count, atlas) => count + atlas.images.length, 0), entries.length, packed.length, tier, elapsed);
+    return packed;
+}
+/**
+ * Picks the higher tier when this environment and this set of sources both allow it.
+ *
+ * A layer packs in the worker only when **every** source is a `Blob`. One source of any other kind
+ * keeps the whole layer on the main thread.
+ *
+ * The test names what may cross, never what must stay. A test that only excludes the known-bad
+ * kinds admits every kind nobody thought of, and this code shipped that mistake once: it asked
+ * whether a source was not a DOM canvas, which let an `<img>` through. An `<img>` neither clones
+ * nor moves, so `postMessage` threw on it and the layer drew nothing.
+ *
+ * A `Blob` is also the only source the worker can take without taking it from the def that owns it.
+ * Its handle clones, so the def keeps its bytes. Every other kind would have to move, and a moved
+ * source is dead on the main thread, so the next repack would find nothing to draw. Those sources
+ * lose nothing by packing inline. A canvas cannot cross at all — `transferControlToOffscreen` throws
+ * on a canvas that already holds a 2D context, and every floorplan canvas source holds one — and
+ * `createImageBitmap(canvas)` costs more than a pack of that canvas on the main thread (this is
+ * measured, see the design spec).
+ * @param sources - The unique sources that this pack will draw.
+ * @returns The tier to run.
+ */
+export function selectTier(sources) {
+    const offthread = typeof Worker === 'function' && typeof OffscreenCanvas !== 'undefined' && sources.every(isBlob);
+    return offthread ? 'worker' : 'inline';
+}
+/**
+ * Packs in a worker, off the main thread.
+ *
+ * The worker decodes every source itself and builds its own offscreen canvases, so this tier
+ * ignores {@link AtlasPackerOptions.createCanvas}. A test that passes one is testing the inline
+ * tier: {@link selectTier} never picks this tier in jsdom, which has neither `Worker` nor
+ * `OffscreenCanvas`.
+ * @param entries - The unique sources, and the defs that draw each one.
+ * @param sources - The unique sources, aligned by index with `entries`.
+ * @param maxDimension - The largest atlas edge, in pixels.
+ * @param signal - Abandons the pack. The worker is told to drop it and goes on running.
+ * @returns One entry for each atlas, in packing order.
+ */
+async function packWorkerTier(entries, sources, maxDimension, signal) {
+    // `selectTier` picked this tier only because every source is a `Blob`, which is what a
+    // `WorkerSource` is. The compiler cannot follow that, so the cast states it.
+    const { atlases, reports } = await packInWorker(sources, maxDimension, {
+        signal,
+    });
+    // `packInWorker` already rejects on abort, so the pack still stands here. The code checks again
+    // because an abort raised in the same turn as the reply is a real ordering.
+    if (signal?.aborted) {
+        // Nothing will mount these atlases, and an `ImageBitmap` holds its pixels outside the
+        // JavaScript heap, so close them here.
+        for (const atlas of atlases)
+            atlas.bitmap.close();
+        throw new Error('atlas-packer: the pack was aborted');
+    }
+    reportSources(entries, reports);
+    return atlases.map((atlas) => ({
+        image: atlas.bitmap,
+        resizable: atlas.resizable,
+        images: expandPlacements(atlas.placements, entries, reports),
+    }));
+}
+/**
+ * Packs on the main thread. This tier decodes the sources here and draws the atlases here.
+ * @param entries - The unique sources, and the defs that draw each one.
+ * @param sources - The unique sources, aligned by index with `entries`.
+ * @param maxDimension - The largest atlas edge, in pixels.
+ * @param createCanvas - Makes each atlas canvas.
+ * @param signal - Abandons the pack.
+ * @returns One entry for each atlas, in packing order.
+ */
+async function packInlineTier(entries, sources, maxDimension, createCanvas, signal) {
+    const decoded = await decodeSources(sources);
+    // The caller abandoned the pack while the decodes were in flight, so nothing here is wanted any
+    // more. The code reads `signal.aborted` and not `throwIfAborted()`, which Chrome 66 and Safari
+    // 15 do not have.
+    if (signal?.aborted) {
+        closeDecoded(sources, decoded);
+        throw new Error('atlas-packer: the pack was aborted');
+    }
+    const { atlases, reports } = packSources(decoded, maxDimension, createCanvas);
+    // The atlases hold the pixels now, so the decoded bitmaps are dead.
+    closeDecoded(sources, decoded);
+    reportSources(entries, reports);
+    return atlases.map((atlas) => ({
+        image: atlas.canvas,
+        resizable: atlas.resizable,
+        images: expandPlacements(atlas.placements, entries, reports),
+    }));
+}
+/**
+ * Groups defs by the source they draw, so the pack draws identical images once.
+ *
+ * Identity is the source object itself. Two defs share a region only when they hold the exact same
+ * object. That is why floorplan hands two booths with one logo a single `Blob`, instead of two
+ * Blobs that hold the same bytes.
+ * @param defs - The defs to group.
+ * @returns One entry per unique source, in first-seen order.
+ */
+function collectSources(defs) {
+    const sources = new Map();
+    for (const def of defs) {
+        let entry = sources.get(def.source);
+        if (!entry) {
+            entry = { source: def.source, defs: [], bounds: { width: 0, height: 0 } };
+            sources.set(def.source, entry);
+        }
+        entry.defs.push(def);
+        // The code copies this size instead of keeping a reference to it. `Rect` exposes an in-place
+        // `set` method. A kept reference lets a later bounds change rewrite what this function
+        // already measured.
+        const { width, height } = def.bounds.size;
+        if (width * height > entry.bounds.width * entry.bounds.height) {
+            entry.bounds = { width, height };
+        }
+    }
+    return [...sources.values()];
+}
+/**
+ * Turns the packer's index-addressed placements into one entry per def. Deduped defs all share
+ * the one region, which is the whole point of deduping them.
+ * @param placements - One atlas's placements.
+ * @param entries - The unique sources, aligned by index with what the code gave the packer.
+ * @param reports - Per-source measurements, aligned by index with `entries`. Supplies each
+ *   placement's `size`.
+ * @returns One packed image for each def at each placement.
+ */
+function expandPlacements(placements, entries, reports) {
+    const images = [];
+    for (const { index, uv, source } of placements) {
+        const { width, height } = reports[index];
+        const size = { width, height };
+        for (const def of entries[index].defs) {
+            images.push(source ? { def, uv, source, size } : { def, uv, size });
+        }
+    }
+    return images;
+}
+/**
+ * Reports what the pack was unable to use. This covers sources with no pixels, and sources that
+ * carry far more resolution than their bounds can ever show. The function warns once for each
+ * source, not once for each def, because deduped defs all share the one texture region.
+ * @param entries - The unique sources, aligned by index with `reports`.
+ * @param reports - What the packer measured and placed.
+ */
+function reportSources(entries, reports) {
+    for (let index = 0; index < entries.length; index++) {
+        const entry = entries[index];
+        const { width, height, tiles } = reports[index];
+        if (tiles === 0) {
+            logger.warn('skipping source with no pixels (%dx%d) %O', width, height, entry.source);
+            continue;
+        }
+        if (tiles > 1) {
+            logger.warn('source %dx%d exceeds the atlas limit, split into %d tiles', width, height, tiles);
+        }
+        const boundsArea = entry.bounds.width * entry.bounds.height;
+        // Degenerate bounds divide out to Infinity. That triggers a warning for every such def, but
+        // the warning says nothing about resolution. It only points to a bug in the bounds, and this
+        // function does not report that kind of bug.
+        if (boundsArea <= 0)
+            continue;
+        const ratio = (width * height) / boundsArea;
+        if (ratio <= MAX_AREA_RATIO)
+            continue;
+        logger.warn('over-sampled source: %dx%d px drawn into %sx%s units — %d px per unit², limit %d', width, height, 
+        // At most two decimals, trailing zeros dropped: 4 → 4, 4.1 → 4.1, 4.2999 → 4.3.
+        Number(entry.bounds.width.toFixed(2)), Number(entry.bounds.height.toFixed(2)), Math.round(ratio), MAX_AREA_RATIO);
+    }
+}
+/**
+ * Decodes every source that is not drawable yet, and leaves the drawable ones as they are.
+ *
+ * The code starts every decode before it waits for any one of them, so the browser decoder
+ * overlaps them. Each decode gives back a bitmap. The packer draws that bitmap, and the caller
+ * closes it.
+ *
+ * One source that does not decode must not take the layer with it. A drawing can carry an
+ * `<image>` whose bytes are not an image at all. A `Promise.all` over the decodes rejects the whole
+ * pack, so a plan with one bad graphic draws none of its graphics. A failed decode becomes `null`
+ * instead. {@link packSources} already treats `null` as a source with no pixels: it skips that
+ * source, and `reportSources` warns about it by name.
+ * @param sources - The unique sources to decode.
+ * @returns The decoded sources, aligned by index with the input. An entry is `null` where the bytes
+ *   did not decode.
+ */
+async function decodeSources(sources) {
+    return Promise.all(sources.map((source) => decodeSource(source).catch(() => null)));
+}
+/**
+ * Frees the bitmaps that this pack decoded.
+ *
+ * An `ImageBitmap` holds its pixels outside the JavaScript heap, and garbage collection does not
+ * reclaim that memory promptly. A pack of a thousand logos would otherwise sit on a thousand
+ * decoded images until it did.
+ *
+ * The pack closes only what it decoded itself, which is every source that arrived as a `Blob`. A
+ * def is free to hold an `ImageBitmap` of its own, and {@link decodeSource} hands such a source
+ * straight back. Those pixels belong to the def: the next repack draws them again, and a pack that
+ * closed them would empty the layer instead.
+ * @param sources - The unique sources, aligned by index with `decoded`.
+ * @param decoded - What each source decoded into.
+ */
+function closeDecoded(sources, decoded) {
+    for (let index = 0; index < decoded.length; index++) {
+        const source = decoded[index];
+        if (source && isBlob(sources[index]) && 'close' in source)
+            source.close();
+    }
+}
+/**
+ * Decodes one source. Anything that is not a `Blob` is drawable already and comes back as it went
+ * in. A `Blob` goes through `createImageBitmap`, which every build target has.
+ * @param source - The source to decode.
+ * @returns A source that the packer can draw.
+ */
+async function decodeSource(source) {
+    // A `Blob` is the only member of the union with no size and no draw. Everything else is drawable
+    // already.
+    if (!isBlob(source))
+        return source;
+    return createImageBitmap(source);
+}

package/dist/objects/images/image-container.d.ts

@@ -0,0 +1,74 @@
+import { type InstancedMeshImpl, type InstancedMeshImplParams } from '../../core/instanced/InstancedMesh';
+import { type ImageDef } from '../../types/defs';
+import { SlotContainer } from '../containers';
+import { type PackedImage } from './atlas-packer';
+/**
+ * The per-instance uniform each atlas mesh reads its texture region from. The container owns the
+ * name: it writes each slot's region here (`setUniformAt`) and hands it to the mesh's
+ * `TextureMaterial` as the `uvOffset` prop, so the material patches its shader to sample the region
+ * without knowing the name itself. `xy` is the region's origin in uv space and `zw` its size, so
+ * `uv * zw + xy` maps the quad's unit uv onto the region.
+ */
+export declare const UV_OFFSET_UNIFORM = "uvOffset";
+/**
+ * The per-instance uniform each atlas mesh reads its opacity from. The container owns the name and
+ * hands it to the mesh's `TextureMaterial` as the `opacityUniform` prop, so the material patches its shader
+ * without knowing the name itself.
+ */
+export declare const OPACITY_UNIFORM = "instanceOpacity";
+/**
+ * The constructor tuple R3F builds one atlas's mesh from, passed as `<instancedMesh args={…}>`.
+ * R3F diffs `args` element-wise and rebuilds the object when any element changes, so this is
+ * snapshotted once and never mutated.
+ *
+ * Only the options: `InstancedMeshImpl` takes no geometry or material, seeding throwaways that the
+ * element's `<planeGeometry>` and `<TextureMaterial>` children replace (R3F creates, attaches, and
+ * disposes those).
+ */
+export type ImageMeshArgs = [params: InstancedMeshImplParams];
+/**
+ * One atlas's mesh bookkeeping.
+ *
+ * Simpler than a shape container, and deliberately so: an atlas draws one shared quad, so there is
+ * no geometry cache and no geometry-id juggling, and `InstancedMeshImpl` grows its own buffers, so
+ * there is no capacity pre-scan — the mesh is merely sized to the atlas's packed-image count and
+ * left to resize itself if a claim ever overflows it. What remains is a slot per packed image and
+ * the uv region each one samples, written once at claim since a def's source never changes.
+ *
+ * Paint order is incremental, like the shape container's, because packing is order-independent: a
+ * reorder of the same images keeps this container and only re-labels its slots, never repacking. A
+ * change to the *set* of images is the harder case and still repacks into a fresh container —
+ * packing has no incremental path for that — but a pure reorder does not.
+ */
+export declare class ImageContainer extends SlotContainer<PackedImage, InstancedMeshImpl, ImageDef> {
+    /** The constructor args R3F builds the mesh from; a frozen snapshot, never mutated. */
+    readonly args: ImageMeshArgs;
+    /**
+     * Builds one atlas's bookkeeping. The mesh, its quad, and its material are all R3F's — the atlas
+     * component renders `<instancedMesh args={container.args}>` with the geometry and material as
+     * children, and hands the mesh back through {@link SlotContainer.bind} — so R3F owns their
+     * lifetimes, including disposal on unmount and survival across StrictMode's simulated remount.
+     * @param capacity - How many instances to size the mesh for. This is the atlas's whole placement
+     *   count, not one kind's share of it, so moving a def between the two meshes never resizes a
+     *   buffer. The mesh grows past it on demand in any case.
+     */
+    constructor(capacity: number);
+    /**
+     * Whether the bound mesh draws its members facing the camera.
+     *
+     * Read off the mesh rather than stored, so one field cannot disagree with another. `screenSpace` is
+     * an ordinary def field, so flipping it re-renders nothing and only an instance can notice that it
+     * is drawing from the wrong mesh.
+     * @returns Whether this container holds a sprite batch.
+     */
+    get facesCamera(): boolean;
+    /**
+     * Writes a def's opacity into its slot, clamped, treating an absent value as fully opaque.
+     * @param slot - The instance's slot.
+     * @param opacity - The def's opacity, or `undefined` for the default.
+     */
+    setOpacityAt(slot: number, opacity: number | undefined): void;
+    protected addInstance(packed: PackedImage): number;
+    protected removeInstance(slot: number): void;
+}
+//# sourceMappingURL=image-container.d.ts.map

package/dist/objects/images/image-container.js

@@ -0,0 +1,100 @@
+import { Vector4 } from 'three';
+import { isBatchedSprites } from '../../core/sprites/BatchedSprites';
+import { SlotContainer } from '../containers';
+import { DIM_SCHEMA } from '../materials/effects/color-dim';
+/**
+ * The per-instance uniform each atlas mesh reads its texture region from. The container owns the
+ * name: it writes each slot's region here (`setUniformAt`) and hands it to the mesh's
+ * `TextureMaterial` as the `uvOffset` prop, so the material patches its shader to sample the region
+ * without knowing the name itself. `xy` is the region's origin in uv space and `zw` its size, so
+ * `uv * zw + xy` maps the quad's unit uv onto the region.
+ */
+export const UV_OFFSET_UNIFORM = 'uvOffset';
+/**
+ * The per-instance uniform each atlas mesh reads its opacity from. The container owns the name and
+ * hands it to the mesh's `TextureMaterial` as the `opacityUniform` prop, so the material patches its shader
+ * without knowing the name itself.
+ */
+export const OPACITY_UNIFORM = 'instanceOpacity';
+/**
+ * One atlas's mesh bookkeeping.
+ *
+ * Simpler than a shape container, and deliberately so: an atlas draws one shared quad, so there is
+ * no geometry cache and no geometry-id juggling, and `InstancedMeshImpl` grows its own buffers, so
+ * there is no capacity pre-scan — the mesh is merely sized to the atlas's packed-image count and
+ * left to resize itself if a claim ever overflows it. What remains is a slot per packed image and
+ * the uv region each one samples, written once at claim since a def's source never changes.
+ *
+ * Paint order is incremental, like the shape container's, because packing is order-independent: a
+ * reorder of the same images keeps this container and only re-labels its slots, never repacking. A
+ * change to the *set* of images is the harder case and still repacks into a fresh container —
+ * packing has no incremental path for that — but a pure reorder does not.
+ */
+export class ImageContainer extends SlotContainer {
+    /** The constructor args R3F builds the mesh from; a frozen snapshot, never mutated. */
+    args;
+    /**
+     * Builds one atlas's bookkeeping. The mesh, its quad, and its material are all R3F's — the atlas
+     * component renders `<instancedMesh args={container.args}>` with the geometry and material as
+     * children, and hands the mesh back through {@link SlotContainer.bind} — so R3F owns their
+     * lifetimes, including disposal on unmount and survival across StrictMode's simulated remount.
+     * @param capacity - How many instances to size the mesh for. This is the atlas's whole placement
+     *   count, not one kind's share of it, so moving a def between the two meshes never resizes a
+     *   buffer. The mesh grows past it on demand in any case.
+     */
+    constructor(capacity) {
+        super({ schema: IMAGE_SCHEMA });
+        this.args = [{ capacity: Math.max(1, capacity) }];
+    }
+    /**
+     * Whether the bound mesh draws its members facing the camera.
+     *
+     * Read off the mesh rather than stored, so one field cannot disagree with another. `screenSpace` is
+     * an ordinary def field, so flipping it re-renders nothing and only an instance can notice that it
+     * is drawing from the wrong mesh.
+     * @returns Whether this container holds a sprite batch.
+     */
+    get facesCamera() {
+        return isBatchedSprites(this.mesh);
+    }
+    /**
+     * Writes a def's opacity into its slot, clamped, treating an absent value as fully opaque.
+     * @param slot - The instance's slot.
+     * @param opacity - The def's opacity, or `undefined` for the default.
+     */
+    setOpacityAt(slot, opacity) {
+        const value = opacity === undefined ? 1 : Math.min(Math.max(opacity, 0), 1);
+        this.mesh.setUniformAt(slot, OPACITY_UNIFORM, value);
+    }
+    addInstance(packed) {
+        // `addInstances` grows the buffers itself if the atlas ever overflows its sized capacity, so
+        // there is nothing to pre-scan; the id is captured from the creation callback.
+        let slot = -1;
+        this.mesh.addInstances(1, (id) => {
+            slot = id;
+        });
+        // The uv region is fixed for the instance's life — a def's source never changes, and a set
+        // change repacks into a fresh container — so it is written once, here, rather than on every
+        // sync.
+        const { u0, v0, u1, v1 } = packed.uv;
+        this.mesh.setUniformAt(slot, UV_OFFSET_UNIFORM, _uvOffset.set(u0, v0, u1 - u0, v1 - v0));
+        return slot;
+    }
+    removeInstance(slot) {
+        this.mesh.removeInstances(slot);
+    }
+}
+/**
+ * The schema the mesh declares (via `addUniforms`) so it can hold a {@link UV_OFFSET_UNIFORM}, a
+ * {@link OPACITY_UNIFORM} and a dim per slot. The opacity float keeps the schema at two texels: a flat
+ * mesh is `vec4` + `float` + `float` = 6 floats, and a sprite mesh's own `anchor` brings it to 8.
+ *
+ * All in one call although they come from different places: `InstanceUniforms.add` merges and
+ * rebuilds the backing texture, so declaring them separately would build it twice per bind.
+ */
+const IMAGE_SCHEMA = {
+    vertex: { [UV_OFFSET_UNIFORM]: 'vec4', [OPACITY_UNIFORM]: 'float', ...DIM_SCHEMA.vertex },
+};
+// Scratch for the one uv-region upload a claim performs, filled and read within a single synchronous
+// statement.
+const _uvOffset = new Vector4();

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

@@ -0,0 +1,2 @@
+export { Images, type ImagesProps } from './Images';
+//# sourceMappingURL=index.d.ts.map

package/dist/objects/images/index.js

@@ -0,0 +1 @@
+export { Images } from './Images';