@expofp/renderer 3.37.1 → 3.38.0

package/README.md

@@ -109,3 +109,37 @@ Two browser extensions make what the renderer draws inspectable:
 ## Running unit tests
 
 Run `nx test @expofp/renderer` to execute the unit tests via [Vitest](https://vitest.dev/).
+
+## Limits of the published package
+
+**`dist` is not supported outside this repository. It does not even resolve.**
+`dist/objects/images/worker/client.js` holds
+`import AtlasWorker from './atlas-worker?worker&inline'`, and `dist/index.js`
+reaches that file. The `?worker&inline` specifier is a Vite instruction, so
+only Vite can answer it. Any other consumer — a different bundler, plain Node,
+a browser loading the files as they are — fails to resolve the import and stops
+there. Nothing in the package loads, so there is no smaller part of it to fall
+back on.
+
+This package has no bundler. Its `build` target is plain `tsc`, so `dist` is
+file-per-module TypeScript output and nothing else runs over it. `tsc` copies
+the specifier through unchanged, which is where the broken import comes from.
+The same absence of a bundler means the React Compiler never runs on `dist`
+either, so the components there ship unoptimized.
+
+Nothing in this repository is affected, because nothing in this repository
+consumes `dist`. The renderer is compiled from its own source instead.
+Floorplan's browser build reaches `src` through the `@expofp/source` condition
+in `vite.config.mts`, so Vite answers the specifier and inlines the worker
+script into the bundle; floorplan also applies its own React Compiler pass.
+This package's own unit tests and Storybook import `src` by relative path, so
+Vite answers the specifier for them too: the Storybook run starts the real
+worker, and the unit tests drive the protocol against a fake one. Wayfinding
+imports types only, which are erased at emit. The offline CLI copies
+floorplan's browser bundle rather than importing anything.
+
+To lift the limit, give this package a Vite library build in the shape
+floorplan already uses. Keep `build` (tsc) for the types. Add `build-browser`
+(Vite) for the bundle. Put a `browser` condition in the exports map, above
+`import`. That answers the worker specifier and runs the React Compiler, so
+both problems above go with it.

package/dist/objects/images/ImageInstance.js

@@ -1,7 +1,6 @@
 import { memo } from 'react';
 import { Matrix4 } from 'three';
 import { shapeToMatrix, useDefSync, writeMatrixIfChanged } from '../containers';
-import { imageSourceSize } from './atlas-packer';
 /**
  * Keeps one image placement current: claims a slot on mount (where the container writes the fixed
  * uv region), writes the def's transform and visibility on mount and after every `update(def)`, and
@@ -47,26 +46,27 @@ function writeImageMatrix(mesh, slot, def, packed) {
     const [originX, originY] = def.origin ?? DEFAULT_ORIGIN;
     matrix.multiply(_origin.makeTranslation(0.5 - originX, 0.5 - originY, 0));
     if (packed.source)
-        applyTile(matrix, packed.source, def);
+        applyTile(matrix, packed);
     writeMatrixIfChanged(mesh, slot, matrix);
 }
 /**
  * Post-multiplies the image transform by the local sub-quad a tile occupies, so a split source's
- * tiles reassemble into the whole image. The tile's fraction of the source (in source pixels) is
- * its fraction of the image, so the sub-quad is that fraction of the unit plane — scaled to the
- * tile's size and translated to its center, both in unit-plane coordinates.
+ * tiles reassemble into the whole image. The tile's fraction of the source, in source pixels, is
+ * also its fraction of the image. So the sub-quad is that same fraction of the unit plane. The
+ * code scales the sub-quad to the tile's size, then moves it so its center lands on that
+ * fraction's center point, in unit-plane coordinates.
  * @param matrix - The image transform, multiplied in place.
- * @param source - The tile's region of the source, in source pixels.
- * @param def - The def whose source supplies the total pixel dimensions.
+ * @param packed - This instance's placement, with the tile's region and the source size to divide
+ *   by.
  */
-function applyTile(matrix, source, def) {
-    const { width, height } = imageSourceSize(def.source);
-    if (width <= 0 || height <= 0)
+function applyTile(matrix, packed) {
+    const { source, size } = packed;
+    if (!source || size.width <= 0 || size.height <= 0)
         return;
-    const fx0 = source.x / width;
-    const fy0 = source.y / height;
-    const fx1 = (source.x + source.width) / width;
-    const fy1 = (source.y + source.height) / height;
+    const fx0 = source.x / size.width;
+    const fy0 = source.y / size.height;
+    const fx1 = (source.x + source.width) / size.width;
+    const fy1 = (source.y + source.height) / size.height;
     _tile
         .makeScale(fx1 - fx0, fy1 - fy0, 1)
         .setPosition((fx0 + fx1) / 2 - 0.5, (fy0 + fy1) / 2 - 0.5, 0);

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

@@ -1,5 +1,6 @@
 import { type ImageDef } from '../../types/defs';
 import { type DefsProps } from '../containers';
+import { type CreateAtlasCanvas } from './atlas-packer';
 /** Props for {@link Images}. */
 export interface ImagesProps extends DefsProps<ImageDef> {
     /**
@@ -8,6 +9,12 @@ export interface ImagesProps extends DefsProps<ImageDef> {
      * value to cap atlas memory below it, or to force splitting deterministically in a test.
      */
     maxAtlasSize?: number;
+    /**
+     * Makes each atlas canvas. Defaults to {@link createAtlasCanvas}, which builds an
+     * `OffscreenCanvas` wherever that global exists and a DOM canvas otherwise. The prop exists so
+     * that a test can pack without a real 2D context. It is not part of the public scene API.
+     */
+    createCanvas?: CreateAtlasCanvas;
 }
 /**
  * Draws a collection of images as textured quads, packing their pixels into one or more atlases and
@@ -30,6 +37,10 @@ export interface ImagesProps extends DefsProps<ImageDef> {
  * 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.
  */

package/dist/objects/images/Images.js

@@ -3,12 +3,15 @@ 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 { createLogger } from '../../utils/logging';
 import { defKey, useContainer } from '../containers';
 import { TextureMaterial } from '../materials/TextureMaterial';
 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
@@ -30,29 +33,77 @@ 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)))) }));
 }
 /**
@@ -74,12 +125,12 @@ 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 [texture] = useState(() => makeAtlasTexture(atlas.image));
     const container = useContainer(() => new ImageContainer(atlas), defs);
     const invalidate = useThree((state) => state.invalidate);
     const budget = use(TextureBudgetContext);
     const factor = useResizeFactor(budget, atlas);
-    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,12 +139,24 @@ 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]);
+    // 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);
+    }, []);
     // `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
     // rejecting its render reads.
@@ -136,34 +199,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 +248,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 };