@expofp/renderer 3.37.1 → 3.39.0

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

@@ -1,315 +1,287 @@
-import { MaxRectsPacker } from 'maxrects-packer';
 import { createLogger } from '../../utils/logging';
+import { createAtlasCanvas, isBlob, packSources, } from './pack-sources';
+import { packInWorker } from './worker';
 const logger = createLogger('atlas-packer');
-// Need to reduce blocking time on the main thread
-// Naive approach of offloading to web worker is not feasible:
-// HTMLImageElement can't be easily transferred, and createImageBitmap() on sources takes more time
-// than actual atlas packing. Needs to be investigated further
 /**
- * Gap kept between neighboring images in an atlas, so linear filtering at one image's edge can
- * never reach into the next one's pixels. The packer applies it *between* rects only — atlas edges
- * stay flush against the pixels — which is also what lets a tile exactly `maxDimension` across
- * still fit a bin.
- */
-const PADDING = 1;
-/**
- * How many source pixels per square unit of `bounds` a def may carry before it is called
- * over-sampled. Past this the extra resolution cannot reach the screen at any sane zoom, so the
- * atlas space and texture memory are simply wasted — usually a full-size logo standing in for a
- * marker icon.
+ * 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';
 /**
- * Whether a source's pixels may be downscaled to fit a memory budget. `true` for decoded images and
- * bitmaps, `false` for canvases — a canvas's pixels are the caller's, counted at full size but never
- * compressed (see the scene's `memoryLimit`).
+ * Packs image defs into atlas canvases and reports where each def's pixels landed.
  *
- * Detected by the absence of `getContext`: `HTMLCanvasElement` and `OffscreenCanvas` both have it,
- * `HTMLImageElement` and `ImageBitmap` do not. A property test rather than `instanceof`, because the
- * SDK runs in WebViews where `OffscreenCanvas`/`ImageBitmap` may be missing as globals and an
- * `instanceof` against an absent one throws.
- * @param source - The source to classify.
- * @returns Whether the source can be downscaled.
- */
-export function isResizableSource(source) {
-    return !('getContext' in source);
-}
-/**
- * Packs image defs into atlas canvases and reports where every 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.
  *
- * Sources are split by kind first — resizable (image/bitmap) from fixed (canvas) — and each kind is
- * packed on its own, so no atlas ever mixes the two and a memory budget can scale a resizable atlas
- * whole without touching a canvas's pixels. Within a kind, sources are deduped — two defs pointing
- * at the same URL, or holding the same canvas object, are drawn once and share one region — and then
- * offered to the packer whole. Anything too big for an atlas comes back parked in a natural-size bin
- * of its own, which the packer flags; those are the only sources cut into tiles, and the tiles go
- * back through the same packer. Letting the packer decide is what keeps the guarantee that no atlas
- * exceeds `maxDimension` without measuring every image up front.
+ * 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.
  *
- * 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. Membership
- * changes do, though — this is a batch call with no incremental path.
+ * 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 - Largest atlas edge in pixels, floored to a positive integer.
- * @param options - Overrides for how atlas canvases are made.
- * @returns One entry per atlas, in packing order — resizable atlases first, then fixed.
+ * @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 function packAtlases(defs, maxDimension, options = {}) {
+export async function packAtlases(defs, maxDimension, options = {}) {
     const startedAt = performance.now();
-    const { createCanvas = createDomCanvas } = options;
-    const limit = Math.max(1, Math.floor(maxDimension));
-    const resizable = [];
-    const fixed = [];
-    for (const def of defs)
-        (isResizableSource(def.source) ? resizable : fixed).push(def);
-    // One packer for both groups, `reset()` between them — the config (size, padding, options) is the
-    // same for each, so reusing it spares an allocation per pack. It cannot be shared across pack calls
-    // though: `limit` is baked in at construction and varies call to call.
-    // `pot: false` because WebGL 2 samples non-power-of-two textures without restriction, so rounding
-    // each atlas up would only waste memory. `smart` stays on (the default), shrinking every bin to
-    // its content — hence reading the size back off the bin rather than assuming `limit`.
-    const packer = new MaxRectsPacker(limit, limit, PADDING, { pot: false });
-    const packedResizable = packGroup(packer, resizable, limit, createCanvas, true);
-    const packedFixed = packGroup(packer, fixed, limit, createCanvas, false);
-    const atlases = [...packedResizable.atlases, ...packedFixed.atlases];
+    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 (%d resizable), sources: %d, tiles: %d, atlases: %d (%sms)', packedResizable.defs + packedFixed.defs, packedResizable.defs, packedResizable.sources + packedFixed.sources, packedResizable.tiles + packedFixed.tiles, atlases.length, elapsed);
-    return atlases;
+    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;
 }
 /**
- * Packs one kind of source — all resizable, or all fixed — into atlases, tagging each with the
- * group's kind. Same pipeline for both: dedup, offer whole, cut whatever the packer parks oversized.
- * @param packer - The shared packer, reset to empty before this group is added.
- * @param defs - The defs of this kind; may be empty, which packs to nothing.
- * @param limit - Largest atlas edge in pixels.
- * @param createCanvas - Makes each atlas canvas.
- * @param resizable - The kind, stamped onto every atlas produced.
- * @returns The atlases and their counts.
+ * 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.
  */
-function packGroup(packer, defs, limit, createCanvas, resizable) {
-    const sources = collectSources(defs);
-    const { rects, skipped } = sourceRects(sources.values());
-    // Clear whatever the previous group left in the packer, keeping its configuration.
-    packer.reset();
-    // `addArray` sorts by longest edge before placing, which packs far tighter than insertion order.
-    packer.addArray(rects);
-    // The packer tags whatever it had to park in an oversized bin, so it — not a measurement of our
-    // own — decides what needs cutting. The tiles are ordinary rects, and pack into the bins the
-    // first pass already opened.
-    const oversized = rects.filter((rect) => rect.oversized);
-    if (oversized.length > 0)
-        packer.addArray(oversized.flatMap((rect) => cutTiles(rect, limit)));
-    // Every oversized bin is now represented by its tiles, so it is dropped rather than returned:
-    // handing back a canvas larger than the caller's limit is the thing this all exists to prevent.
-    const bins = packer.bins.filter((bin) => !bin.rects.some((rect) => rect.oversized));
-    const atlases = bins.map((bin) => ({ ...renderAtlas(bin, createCanvas), resizable }));
-    return {
-        atlases,
-        defs: defs.length - skipped.defs,
-        sources: sources.size - skipped.sources,
-        tiles: bins.reduce((count, bin) => count + bin.rects.length, 0),
-    };
+export function selectTier(sources) {
+    const offthread = typeof Worker === 'function' && typeof OffscreenCanvas !== 'undefined' && sources.every(isBlob);
+    return offthread ? 'worker' : 'inline';
 }
 /**
- * The pixel size of an image source.
+ * Packs in a worker, off the main thread.
  *
- * Duck-typed rather than `instanceof`: the SDK runs in WebViews where `OffscreenCanvas` and
- * `ImageBitmap` may be missing as globals, and an `instanceof` against an absent global throws.
- * @param source - The source to measure.
- * @returns Its intrinsic size, `0 × 0` for an image element that has not decoded yet.
+ * 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.
  */
-export function imageSourceSize(source) {
-    // `naturalWidth` is the decoded size; an `<img>`'s `width` is its layout size, which is 0 for an
-    // element that was never in the document — the usual case for images loaded purely as textures.
-    const image = source;
-    return typeof image.naturalWidth === 'number'
-        ? { width: image.naturalWidth, height: image.naturalHeight }
-        : { width: source.width, height: source.height };
+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 identical images are packed once.
+ * Groups defs by the source they draw, so the pack draws identical images once.
  *
- * Identity is the URL for an image element and the object itself for a canvas or bitmap — a `Map`
- * never confuses the two, since a string key cannot collide with an object one. An `<img>` with no
- * `src` keys on itself instead, so a set of blank images is not collapsed into a single region.
+ * 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) {
-        const src = def.source.src;
-        const key = typeof src === 'string' && src !== '' ? src : def.source;
-        let entry = sources.get(key);
+        let entry = sources.get(def.source);
         if (!entry) {
-            entry = {
-                source: def.source,
-                ...imageSourceSize(def.source),
-                defs: [],
-                bounds: { width: 0, height: 0 },
-            };
-            sources.set(key, entry);
+            entry = { source: def.source, defs: [], bounds: { width: 0, height: 0 } };
+            sources.set(def.source, entry);
         }
         entry.defs.push(def);
-        // Copied rather than referenced: `Rect` exposes an in-place `set`, so holding onto its size
-        // vector would let a later bounds change rewrite what was measured here.
+        // 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;
+    return [...sources.values()];
 }
 /**
- * Turns each unique source into the one rect that offers it to the packer whole, dropping the ones
- * with no pixels to draw and flagging the ones carrying more resolution than they can show.
- * @param sources - The unique sources to offer.
- * @returns The rects to pack, and what was dropped for having no pixels.
+ * 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 sourceRects(sources) {
-    const rects = [];
-    const skipped = { defs: 0, sources: 0 };
-    for (const entry of sources) {
-        // A `drawImage` with a zero-width or zero-height source region throws in some browsers, so an
-        // image that has not decoded (or a canvas sized to nothing) is dropped rather than drawn.
-        if (entry.width <= 0 || entry.height <= 0) {
-            skipped.sources++;
-            skipped.defs += entry.defs.length;
-            logger.warn('skipping source with no pixels (%dx%d) %O', entry.width, entry.height, entry.source);
-            continue;
+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 });
         }
-        warnIfOverSampled(entry);
-        rects.push({
-            width: entry.width,
-            height: entry.height,
-            x: 0,
-            y: 0,
-            hash: `${rects.length}`,
-            data: { entry },
-        });
     }
-    return { rects, skipped };
-}
-/**
- * Reports a source carrying far more pixels than the bounds it is drawn into can ever show. Once
- * per source rather than once per def, since deduped defs all share the one texture region.
- * @param entry - The source to check.
- */
-function warnIfOverSampled(entry) {
-    const boundsArea = entry.bounds.width * entry.bounds.height;
-    // Degenerate bounds would divide out to Infinity and warn about every such def, which says
-    // nothing about resolution — that is a bounds bug, and not this function's to report.
-    if (boundsArea <= 0)
-        return;
-    const ratio = (entry.width * entry.height) / boundsArea;
-    if (ratio <= MAX_AREA_RATIO)
-        return;
-    logger.warn('over-sampled source: %dx%d px drawn into %sx%s units — %d px per unit², limit %d', entry.width, entry.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);
+    return images;
 }
 /**
- * Cuts a source the packer could not fit into a grid of tiles no larger than one atlas. Tiles are
- * exact and non-overlapping — each ends up alone (or beside its own siblings) in an atlas, so
- * nothing can bleed across the cut and no overlap column is needed to hide it.
- * @param rect - The oversized rect, holding the source to cut.
- * @param limit - Largest tile edge in pixels.
- * @returns The tiles to pack in its place.
+ * 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 cutTiles(rect, limit) {
-    const { entry } = rect.data;
-    const columns = Math.ceil(entry.width / limit);
-    const rows = Math.ceil(entry.height / limit);
-    logger.warn('source %dx%d exceeds the %dpx atlas limit, splitting into %d tiles', entry.width, entry.height, limit, columns * rows);
-    const tiles = [];
-    for (let row = 0; row < rows; row++) {
-        const y = row * limit;
-        const height = Math.min(limit, entry.height - y);
-        for (let column = 0; column < columns; column++) {
-            const x = column * limit;
-            const width = Math.min(limit, entry.width - x);
-            tiles.push({
-                width,
-                height,
-                x: 0,
-                y: 0,
-                hash: `${rect.hash}:${column},${row}`,
-                data: { entry, source: { x, y, width, height } },
-            });
+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);
     }
-    return tiles;
 }
 /**
- * Draws one packed bin onto a canvas and maps its rects back onto the defs that wanted them. The
- * `resizable` flag is not this function's to set — {@link packGroup} stamps it from the group's kind.
- * @param bin - The packed bin, already sized to its content.
- * @param createCanvas - Makes the canvas to draw on.
- * @returns The atlas, less its `resizable` flag.
+ * 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.
  */
-function renderAtlas(bin, createCanvas) {
-    const canvas = createCanvas(bin.width, bin.height);
-    const context = contextOf(canvas);
-    // Nothing downstream can recover from this: every atlas would upload blank, so the images would
-    // silently draw as nothing at all. Better to fail where the cause is still visible.
-    if (!context)
-        throw new Error(`atlas-packer: no 2d context for a ${bin.width}x${bin.height} atlas`);
-    const images = [];
-    for (const rect of bin.rects) {
-        const { entry, source } = rect.data;
-        // The copied region is the tile when there is one and the whole image otherwise — both read
-        // from the source's own axes. It happens to equal the packed rect's size today (tiles are
-        // placed 1:1, unrotated), but taking it from the destination would only be right by accident.
-        // Kept apart from `source` itself, which stays undefined for an unsplit image so the placement
-        // below does not report a region the caller has no use for.
-        const region = source ?? { x: 0, y: 0, width: entry.width, height: entry.height };
-        context.drawImage(entry.source, region.x, region.y, region.width, region.height, rect.x, rect.y, rect.width, rect.height);
-        // The rect is in canvas pixels and uv keeps the canvas's axes, so this is a plain normalization
-        // with no vertical inversion (see {@link UvRect}). Shared by every def on this rect — dedup is
-        // the whole point.
-        const uv = {
-            u0: rect.x / bin.width,
-            v0: rect.y / bin.height,
-            u1: (rect.x + rect.width) / bin.width,
-            v1: (rect.y + rect.height) / bin.height,
-        };
-        for (const def of entry.defs)
-            images.push(source ? { def, uv, source } : { def, uv });
-    }
-    return { canvas, images };
+async function decodeSources(sources) {
+    return Promise.all(sources.map((source) => decodeSource(source).catch(() => null)));
 }
 /**
- * Makes an atlas canvas in the document, the default when the caller supplies no factory.
- * @param width - The atlas width in pixels.
- * @param height - The atlas height in pixels.
- * @returns The canvas.
+ * 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 createDomCanvas(width, height) {
-    const canvas = document.createElement('canvas');
-    canvas.width = width;
-    canvas.height = height;
-    return canvas;
+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();
+    }
 }
 /**
- * Resolves an atlas canvas's 2D context, asking one canvas kind at a time.
- *
- * Deliberately not `canvas.getContext('2d')` on the union. The two kinds' overload lists disagree
- * at the end — `HTMLCanvasElement` closes with `getContext(id: string): RenderingContext | null`,
- * `OffscreenCanvas` with an `OffscreenRenderingContextId` one — and resolving across the union can
- * combine one kind's `"2d"` overload with the other's catch-all, yielding
- * `OffscreenCanvasRenderingContext2D | RenderingContext`: a type covering bitmap and WebGL contexts
- * that have no `drawImage`. It surfaces only on incremental rebuilds (any compile error in this
- * file leaves the bad resolution cached in `.tsbuildinfo`, where it outlives the error that caused
- * it), so a clean build hides it and a working tree quietly breaks. Narrowed first, each branch has
- * one concrete type whose `"2d"` overload is the only candidate, and the result is stable either
- * way.
- * @param canvas - The atlas canvas.
- * @returns Its 2D context, or `null` when the canvas cannot provide one.
+ * 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.
  */
-function contextOf(canvas) {
-    // `in` rather than `instanceof`: in a worker there is no `HTMLCanvasElement` global to test
-    // against, and an `instanceof` against a missing global throws.
-    if ('convertToBlob' in canvas)
-        return canvas.getContext('2d');
-    return canvas.getContext('2d');
+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

@@ -1,7 +1,7 @@
 import { type InstancedMeshImpl, type InstancedMeshImplParams } from '../../core/instanced/InstancedMesh';
 import { type ImageDef } from '../../types/defs';
 import { SlotContainer } from '../containers';
-import { type Atlas, type PackedImage } from './atlas-packer';
+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
@@ -42,9 +42,20 @@ export declare class ImageContainer extends SlotContainer<PackedImage, Instanced
      * 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 atlas - The packed atlas this container draws; only its image count sizes the mesh.
+     * @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(atlas: Atlas);
+    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;
     protected addInstance(packed: PackedImage): number;
     protected removeInstance(slot: number): void;
 }