@expofp/renderer 3.37.1 → 3.39.0

package/dist/objects/images/Images.js

@@ -3,22 +3,27 @@ import { useThree } from '@react-three/fiber';
 import { use, useEffect, useRef, useState } from 'react';
 import { CanvasTexture, SRGBColorSpace } from 'three';
 import { InstancedMesh } from '../../core/instanced/InstancedMesh';
+import { BatchedSprites } from '../../core/sprites/BatchedSprites';
+import { createLogger } from '../../utils/logging';
 import { defKey, useContainer } from '../containers';
 import { TextureMaterial } from '../materials/TextureMaterial';
-import { packAtlases } from './atlas-packer';
+import { packAtlases, } from './atlas-packer';
 import { ImageContainer, UV_OFFSET_UNIFORM } from './image-container';
 import { ImageInstance } from './ImageInstance';
+import { contextOf, createAtlasCanvas } from './pack-sources';
 import { TextureBudgetContext, useResizeFactor } from './texture-budget';
+const logger = createLogger('images');
 /**
- * Draws a collection of images as textured quads, packing their pixels into one or more atlases and
- * drawing each atlas as a single `InstancedMesh` — so a layer of many images costs a handful of
- * draw calls, not one per image.
+ * Draws a collection of images as textured quads, packing their pixels into one or more atlases.
+ * Each atlas draws through up to two meshes that share its texture, so a layer of many images still
+ * costs a handful of draw calls, not one per image.
  *
  * Unlike a shape layer, an image layer can span **several meshes**: bin-packing splits the images
- * across as many atlases as their pixels need, and each atlas gets its own mesh, batch, and
- * texture (an {@link ImageAtlas}). A def whose source is too big for one atlas is cut into tiles
- * that may land on different atlases, so one def can drive several instances — the atlas iterates
- * its packed placements, not the defs.
+ * across as many atlases as their pixels need, and each atlas gets its own texture drawn through up
+ * to two meshes, a flat `InstancedMesh` and a camera-facing `BatchedSprites` (an
+ * {@link ImageAtlas}). An unmixed layer still mounts only one mesh. A def whose source is too big
+ * for one atlas is cut into tiles that may land on different atlases, so one def can drive several
+ * instances. The atlas iterates its packed placements, not the defs.
  *
  * Packing has no incremental path, so a change to the **set** of images **repacks from scratch**: a
  * fresh atlas set under fresh keys, remounting every mesh and instance. A **reorder** of the same
@@ -30,56 +35,104 @@ import { TextureBudgetContext, useResizeFactor } from './texture-budget';
  * 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 } = 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, via the "adjust state on prop change" pattern. The
-    // comparison is by content, not identity: `useStagedChildren` rebuilds its snapshot on *every*
-    // `update(layer)` — including one that only flipped the layer's own `hidden` — so identity alone
-    // would repack for changes that touched no image at all. 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 each atlas does below. Set equality is O(n) over a list already in cache,
-    // against a repack that redraws every canvas.
-    const [packed, setPacked] = useState(() => packImages(defs, maxTextureSize, 0));
-    if (!sameSet(packed.defs, defs)) {
-        setPacked((current) => packImages(defs, maxTextureSize, current.generation + 1));
-    }
+    // 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)))) }));
 }
 /**
- * Draws one atlas as an `InstancedMesh`: the R3F-owned mesh with the atlas texture as its
- * `TextureMaterial`, plus one {@link ImageInstance} per placement on the atlas. Its set of images is
- * fixed for its lifetime — a repack remounts the whole component — so the batch and texture are
- * built once from state and released together on unmount. Paint order is not fixed: a reorder keeps
- * this atlas and re-labels its instances through the effect below.
+ * Owns one atlas's texture and its flat/sprite split, and draws each non-empty side as its own
+ * `AtlasMesh`. The atlas's set of images is fixed for its lifetime. A repack remounts the whole
+ * component, so the texture is built once from state and released on unmount.
+ *
+ * The uploaded texture is not fixed. 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 uploaded texture is not fixed either: a resizable atlas registers with the scene's texture
- * budget and re-derives a downscaled copy of its canvas whenever the shared resize factor moves (see
- * {@link resizeTexture}). That is a texture re-upload, not a repack — the mesh, container,
- * instances, and their normalized uv regions all stand, since uv is invariant to the canvas's pixel
- * size.
+ * The flat/sprite split is a second kind of state, held here rather than derived every render. A
+ * def's `screenSpace` is an ordinary slot write that never re-renders this component, so an
+ * `AtlasMesh` calls `repartition` when it finds a member that no longer matches its kind.
  * @param props - The atlas and the layer's images in paint order.
- * @returns The mesh and one instance component per placement.
+ * @returns One `AtlasMesh` per non-empty kind, sharing this atlas's texture.
  */
 function ImageAtlas(props) {
     const { atlas, defs } = props;
-    // Only the placements are staged; the container and the texture are built from the whole atlas.
     const mounted = props.mounted ?? atlas.images.length;
-    const [texture] = useState(() => makeAtlasTexture(atlas.canvas));
-    const container = useContainer(() => new ImageContainer(atlas), defs);
+    const [texture] = useState(() => makeAtlasTexture(atlas.image));
     const invalidate = useThree((state) => state.invalidate);
     const budget = use(TextureBudgetContext);
     const factor = useResizeFactor(budget, atlas);
-    const displayRef = useRef(undefined);
+    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
@@ -88,21 +141,97 @@ function ImageAtlas(props) {
         invalidate();
         return () => texture.dispose();
     }, [texture, invalidate]);
-    // Re-derive the uploaded pixels for the current resize factor. Runs on mount and every factor
-    // move; a fixed atlas reads `1` forever, so this settles once for it and never fires again.
+    // 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.canvas, displayRef, factor);
+        resizeTexture(texture, atlas.image, scaledRef, factor);
         invalidate();
     }, [texture, atlas, factor, invalidate]);
-    // `args` is a frozen snapshot so R3F never rebuilds the mesh; the `ref` arrow (not
-    // `ref={container.bind}`) keeps the React Compiler from inferring `container` itself as a ref and
+    // 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.
-    // The quad and the material are children so R3F creates, attaches, and disposes both — the args
-    // pair are placeholders the constructor demands (see `ImageMeshArgs`). The material has to be per
-    // mesh: `InstancedMeshImpl` wraps whatever it draws with in a closure over its own textures, and two
-    // instanced meshes on one material would both render against the first one's.
-    return (_jsxs(_Fragment, { children: [_jsxs(InstancedMesh, { args: container.args, ref: (mesh) => container.bind(mesh), sortObjects: true, customSort: container.customSort, perObjectFrustumCulled: true, children: [_jsx("planeGeometry", {}), _jsx(TextureMaterial, { map: texture, uvOffset: UV_OFFSET_UNIFORM })] }), atlas.images.slice(0, mounted).map((packed) => (_jsx(ImageInstance, { def: packed.def, packed: packed, container: container }, `${defKey(packed.def)}:${packed.uv.u0}:${packed.uv.v0}`)))] }));
+    const mesh = kind === 'sprite' ? (_jsx(BatchedSprites, { args: container.args, ref: (instance) => container.bind(instance), sortObjects: true, customSort: container.customSort, perObjectFrustumCulled: true, renderOrder: renderOrder, children: _jsx(TextureMaterial, { map: texture, uvOffset: UV_OFFSET_UNIFORM }) })) : (_jsxs(InstancedMesh, { args: container.args, ref: (instance) => container.bind(instance), sortObjects: true, customSort: container.customSort, perObjectFrustumCulled: true, renderOrder: renderOrder, children: [_jsx("planeGeometry", {}), _jsx(TextureMaterial, { map: texture, uvOffset: UV_OFFSET_UNIFORM })] }));
+    return (_jsxs(_Fragment, { children: [mesh, placements.slice(0, mounted).map((packed) => (_jsx(ImageInstance, { def: packed.def, packed: packed, container: container }, `${defKey(packed.def)}:${packed.uv.u0}:${packed.uv.v0}`)))] }));
 }
+/**
+ * Splits an atlas's placements by orientation.
+ *
+ * A filter over an array the component already holds. The packing, the canvas, the uv regions and the
+ * texture budget are all untouched, so nothing repacks. That is what makes flipping a def's
+ * screenSpace cheaper here than a shape's kind change, where a re-split rebuilds partitions.
+ * @param images - The atlas's placements, in packing order.
+ * @returns The two subsets, each still in packing order.
+ */
+function partitionImages(images) {
+    const flat = [];
+    const sprite = [];
+    for (const packed of images)
+        (packed.def.screenSpace === true ? sprite : flat).push(packed);
+    return { flat, sprite };
+}
+/** The atlas's two meshes, in draw order: flats first, then the camera-facing ones. */
+const IMAGE_KINDS = ['flat', 'sprite'];
 /**
  * Whether two snapshots hold the same *set* of images, order aside — the question "does this need a
  * repack". Order is excluded on purpose: packing reads only pixels, so a reorder produces the same
@@ -136,34 +265,48 @@ function atlasKey(atlas, generation) {
     return `${generation}:${defKey(first.def)}:${first.uv.u0}:${first.uv.v0}${region}`;
 }
 /**
- * Packs a set of images into atlases. Paint order is not recorded here — it is a layer-wide property
- * the atlases relabel from the current `defs` on every update, so a reorder never repacks.
- * @param defs - The images to pack.
- * @param maxDimension - Largest atlas edge, the GPU's max texture size.
- * @param generation - The repack counter for this pack.
- * @returns The pack.
+ * 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 packImages(defs, maxDimension, generation) {
-    return { defs, atlases: packAtlases(defs, maxDimension), generation };
+function closeAtlases(atlases) {
+    for (const atlas of atlases) {
+        if ('close' in atlas.image)
+            atlas.image.close();
+    }
 }
 /**
- * Points an atlas texture at the pixels it should upload for the current resize factor: the full
- * canvas at `factor >= 1`, or a downscaled copy of it below that.
+ * Points an atlas texture at the pixels for the current resize factor.
  *
- * The copy lives in `displayRef`, created on first need and resized in place after — so a factor that
- * later climbs back (a budget freed up) re-derives from the untouched full canvas, never upscaling
- * pixels already thrown away. The full canvas is retained regardless (the atlas holds it), so this
- * costs one extra canvas only while actually scaling. UVs are untouched throughout: they are
- * normalized, so the same regions address the smaller canvas unchanged.
+ * 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 canvas, never mutated.
- * @param displayRef - Holds the downscaled copy across factor changes.
- * @param factor - The linear factor to scale by, in `(0, 1]`.
+ * @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, displayRef, factor) {
+function resizeTexture(texture, full, scaledRef, factor) {
+    const scaled = scaledRef.current;
     if (factor >= 1) {
-        // Point back at the full canvas; a copy from an earlier, smaller factor is left for GC.
+        // 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;
         }
@@ -171,41 +314,81 @@ function resizeTexture(texture, full, displayRef, factor) {
     }
     const width = Math.max(1, Math.round(full.width * factor));
     const height = Math.max(1, Math.round(full.height * factor));
-    const display = (displayRef.current ??= document.createElement('canvas'));
+    const atlasCanvas = (scaled.canvas ??= createAtlasCanvas(width, height));
     // Setting the size also clears the canvas, so the downscale draws onto a blank surface.
-    display.width = width;
-    display.height = height;
-    const context = display.getContext('2d');
-    // No 2d context is the same dead end as a blank atlas: fall back to the full canvas so the images
-    // still draw — over budget — rather than not at all.
+    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);
-    texture.image = display;
+    // 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;
 }
 /**
- * Wraps an atlas canvas as a texture for `MeshBasicMaterial.map`.
+ * 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 readily as far in, and without them 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 canvas - The packed atlas canvas.
+ * 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(canvas) {
-    const texture = new CanvasTexture(canvas);
+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 rather than three's default vertical flip, so v runs
-    // down the atlas — the same direction as the packer's uv regions and as the scene's y axis. Every
-    // axis in the chain then points the same way; flip at one end only and images come out upside
-    // down.
+    // 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 };