@expofp/renderer 3.37.0 → 3.38.0

package/dist/objects/images/worker/client.d.ts

@@ -0,0 +1,62 @@
+import { type SourceReport } from '../pack-sources';
+import { type WorkerAtlas, type WorkerSource } from './atlas-worker';
+/** Options for {@link packInWorker}. */
+export interface PackInWorkerOptions {
+    /** Abandons the pack. The worker is told to drop it, and a reply that still arrives is thrown away. */
+    signal?: AbortSignal;
+    /**
+     * Makes the pooled worker, on the first pack that needs it. Defaults to the bundled atlas worker,
+     * and exists so a spec can drive the protocol against a fake one without a browser. It is ignored
+     * once a worker is pooled.
+     */
+    createWorker?: () => Worker;
+}
+/**
+ * Packs a set of sources in a web worker.
+ *
+ * **One worker serves every pack, and no pack ever stops it.** The atlases come back as
+ * `ImageBitmap`s that `OffscreenCanvas.transferToImageBitmap()` produced, and Chrome backs those
+ * with GPU memory the worker owns. `Images` re-reads an atlas's pixels on every texture-budget
+ * move, and disposing a texture forces a fresh upload, so the producing worker has to outlive every
+ * bitmap it made, not only the first upload of it. Terminating the worker used to run before this
+ * function resolved, which destroyed those pixels and left booth logos blank on real GPUs.
+ *
+ * The one `terminate()` in this file is in `retire`, and it only ever stops a worker that broke
+ * before it handed out an atlas. A worker that has produced pixels is dropped from the pool and
+ * left running. The worker script is inlined into the bundle, so starting one resolves no URL at
+ * runtime, which matters because the SDK is loaded from origins it does not control.
+ *
+ * Each pack carries an `id`, because a shared worker can hold two layers' packs at once and a reply
+ * has to find its own caller. An abandoned pack is settled here and its `id` forgotten, so a reply
+ * that still arrives is discarded — and its atlases are closed, or each superseded pack would leak
+ * a layer's worth of GPU memory.
+ *
+ * The sources go over in batches so the main thread is never blocked for long by one structured
+ * clone, and so the worker can decode the early batches while the later ones are still being sent.
+ * A closing message tells it every source has arrived.
+ * @param sources - The unique sources to pack, in the caller's order; placements address them by
+ *   their index in this array.
+ * @param maxDimension - Largest atlas edge in pixels.
+ * @param options - The abort signal, and the worker factory a spec overrides.
+ * @returns The packed atlases and one report per source.
+ */
+export declare function packInWorker(sources: readonly WorkerSource[], maxDimension: number, options?: PackInWorkerOptions): Promise<{
+    atlases: WorkerAtlas[];
+    reports: SourceReport[];
+}>;
+/**
+ * Forgets the pooled worker without stopping it, and abandons every pack waiting on it.
+ *
+ * Only a spec calls this. Each spec drives its own fake worker, and the pool would otherwise hand
+ * the first spec's fake to every spec after it.
+ */
+export declare function resetAtlasWorkerPool(): void;
+/**
+ * How many sources one `postMessage` carries.
+ *
+ * Sending every source in one message left 18 dropped frames at a thousand logos on a 4x-throttled
+ * CPU; sending them in batches of 25 left one. Chunking is what removes the last stall, so this is
+ * the number that matters most in this file — tune it against the benchmark, not by taste.
+ */
+export declare const SOURCE_CHUNK_SIZE = 25;
+//# sourceMappingURL=client.d.ts.map

package/dist/objects/images/worker/client.js

@@ -0,0 +1,249 @@
+/* eslint-disable-next-line import/default -- Vite answers this specifier with a module it
+generates, whose default export is a `Worker` subclass. The ESLint resolver drops the query and
+reads the worker entry instead, which exports no default of its own. `vite/client` declares the
+real shape, so tsc sees it. */
+import AtlasWorker from './atlas-worker?worker&inline';
+/**
+ * Packs a set of sources in a web worker.
+ *
+ * **One worker serves every pack, and no pack ever stops it.** The atlases come back as
+ * `ImageBitmap`s that `OffscreenCanvas.transferToImageBitmap()` produced, and Chrome backs those
+ * with GPU memory the worker owns. `Images` re-reads an atlas's pixels on every texture-budget
+ * move, and disposing a texture forces a fresh upload, so the producing worker has to outlive every
+ * bitmap it made, not only the first upload of it. Terminating the worker used to run before this
+ * function resolved, which destroyed those pixels and left booth logos blank on real GPUs.
+ *
+ * The one `terminate()` in this file is in `retire`, and it only ever stops a worker that broke
+ * before it handed out an atlas. A worker that has produced pixels is dropped from the pool and
+ * left running. The worker script is inlined into the bundle, so starting one resolves no URL at
+ * runtime, which matters because the SDK is loaded from origins it does not control.
+ *
+ * Each pack carries an `id`, because a shared worker can hold two layers' packs at once and a reply
+ * has to find its own caller. An abandoned pack is settled here and its `id` forgotten, so a reply
+ * that still arrives is discarded — and its atlases are closed, or each superseded pack would leak
+ * a layer's worth of GPU memory.
+ *
+ * The sources go over in batches so the main thread is never blocked for long by one structured
+ * clone, and so the worker can decode the early batches while the later ones are still being sent.
+ * A closing message tells it every source has arrived.
+ * @param sources - The unique sources to pack, in the caller's order; placements address them by
+ *   their index in this array.
+ * @param maxDimension - Largest atlas edge in pixels.
+ * @param options - The abort signal, and the worker factory a spec overrides.
+ * @returns The packed atlases and one report per source.
+ */
+export function packInWorker(sources, maxDimension, options = {}) {
+    const { signal, createWorker = createAtlasWorker } = options;
+    return new Promise((resolve, reject) => {
+        // Read the signal before anything is sent. A pack that is already abandoned must cost the
+        // worker nothing, so it posts no message at all.
+        if (signal?.aborted) {
+            reject(abandoned());
+            return;
+        }
+        let worker;
+        try {
+            worker = pooledWorker(createWorker);
+        }
+        catch (error) {
+            // A host page whose `script-src` forbids `blob:` and `data:` makes `new Worker()` throw. The
+            // caller falls back to an inline pack.
+            reject(asError(error));
+            return;
+        }
+        const id = ++lastRequestId;
+        // Every exit runs through here. Dropping this pack's entry is what stops delivery, because the
+        // worker is shared and goes on running.
+        const done = (settle) => {
+            signal?.removeEventListener('abort', onAbort);
+            pending.delete(id);
+            settle();
+        };
+        // A plain Error, not `signal.reason`, which Chrome 66 and Safari 15 do not have. Nothing
+        // branches on the error's type: every caller reads `signal.aborted` instead.
+        const onAbort = () => {
+            done(() => {
+                cancel(worker, id);
+                reject(abandoned());
+            });
+        };
+        pending.set(id, (message) => {
+            done(() => {
+                if (message.type === 'failed')
+                    reject(new Error(message.message));
+                else
+                    resolve({ atlases: message.atlases, reports: message.reports });
+            });
+        });
+        signal?.addEventListener('abort', onAbort);
+        try {
+            for (let start = 0; start < sources.length; start += SOURCE_CHUNK_SIZE) {
+                post(worker, {
+                    type: 'sources',
+                    id,
+                    sources: sources.slice(start, start + SOURCE_CHUNK_SIZE),
+                });
+            }
+            post(worker, { type: 'pack', id, maxDimension });
+        }
+        catch (error) {
+            // `postMessage` throws when the platform refuses to copy a source. The worker keeps the
+            // batches that did arrive until it is told otherwise, and the closing message never comes.
+            done(() => {
+                cancel(worker, id);
+                reject(asError(error));
+            });
+        }
+    });
+}
+/**
+ * Forgets the pooled worker without stopping it, and abandons every pack waiting on it.
+ *
+ * Only a spec calls this. Each spec drives its own fake worker, and the pool would otherwise hand
+ * the first spec's fake to every spec after it.
+ */
+export function resetAtlasWorkerPool() {
+    pool = null;
+    pending.clear();
+}
+/**
+ * Hands back the one worker every pack runs on, starting it on the first call.
+ *
+ * The reply handler lives on the worker and not on a pack, because the worker outlives every pack
+ * it serves and a reply for a pack nobody wants still has pixels to free.
+ * @param createWorker - Makes the worker, if there is not one yet.
+ * @returns The pooled worker.
+ */
+function pooledWorker(createWorker) {
+    if (pool)
+        return pool.worker;
+    // Not stored until it exists: a factory that throws must be retried by the next pack, not cached.
+    const started = { worker: createWorker(), produced: false };
+    started.worker.onmessage = (event) => {
+        const message = event.data;
+        const deliver = pending.get(message.id);
+        if (deliver) {
+            // These pixels are about to be mounted, so from here on this worker must not be stopped.
+            if (message.type === 'packed' && message.atlases.length > 0)
+                started.produced = true;
+            deliver(message);
+            return;
+        }
+        // Nobody is waiting: this pack was abandoned after the worker had already replied. An
+        // `ImageBitmap` holds its pixels outside the JavaScript heap and nothing else will ever close
+        // these, so every superseded pack would leak a layer's worth of GPU memory.
+        if (message.type === 'packed')
+            for (const atlas of message.atlases)
+                atlas.bitmap.close();
+    };
+    started.worker.onerror = (event) => {
+        retire(started);
+        failAll(event.message || 'atlas-worker: failed to start');
+    };
+    started.worker.onmessageerror = () => {
+        // This never fires on the primary target. `Worker`'s `messageerror` is `false` for Chrome,
+        // Chrome Android and Android WebView, and Safari only added it in 16.4, which is above the
+        // `safari15`/`ios15` floor (checked against `@mdn/browser-compat-data@6.1.5`, as installed
+        // here). Assigning it is free and Firefox has had it since 57, so it is kept for the browsers
+        // that do support it. It is not a guard the build targets can rely on.
+        //
+        // A reply that does not deserialize is lost, and it carries no id, so there is no way to tell
+        // whose it was. Without this the layer waits for a reply that never comes and stays blank.
+        retire(started);
+        failAll('atlas-worker: a reply could not be read');
+    };
+    pool = started;
+    return started.worker;
+}
+/**
+ * Drops a broken worker, so the next pack starts a fresh one.
+ *
+ * A worker that has handed out an atlas is dropped and left running. Stopping it would destroy the
+ * GPU memory behind every bitmap it made, which is the failure this whole file is shaped around. A
+ * worker that produced nothing is stopped, because nothing depends on it.
+ * @param broken - The pooled worker to drop.
+ */
+function retire(broken) {
+    if (pool === broken)
+        pool = null;
+    if (!broken.produced)
+        broken.worker.terminate();
+}
+/**
+ * Abandons every pack waiting on the worker that just broke.
+ * @param message - What to reject each of them with.
+ */
+function failAll(message) {
+    for (const [id, deliver] of [...pending])
+        deliver({ type: 'failed', id, message });
+}
+/**
+ * Tells the worker to drop a pack nobody wants any more.
+ *
+ * Termination used to do this. Now that the worker outlives its packs, a superseded pack would
+ * otherwise run to the end and hold the worker off the next one.
+ * @param worker - The pooled worker.
+ * @param id - The pack to drop.
+ */
+function cancel(worker, id) {
+    try {
+        post(worker, { type: 'cancel', id });
+    }
+    catch {
+        // A worker that will not take this message is already unusable, and the pack it would have
+        // dropped is dropped either way.
+    }
+}
+/**
+ * Sends one request to the worker.
+ *
+ * **Nothing is ever transferred.** A `Blob` is a handle to an immutable, reference-counted byte
+ * store, so a structured clone copies the handle and not the bytes. Being cheap to clone is the
+ * property that matters here; being transferable is not, and transferring a Blob is not a thing the
+ * platform offers. A `Blob` is also the only source that reaches this function, so no object a def
+ * owns is ever detached by a pack.
+ *
+ * The typed parameter is why this function exists: `postMessage` takes `any`, so a message built at
+ * the call site would go unchecked.
+ * @param worker - The worker to send to.
+ * @param request - The message.
+ */
+function post(worker, request) {
+    worker.postMessage(request);
+}
+/**
+ * Makes the bundled atlas worker.
+ * @returns A fresh worker.
+ */
+function createAtlasWorker() {
+    return new AtlasWorker();
+}
+/**
+ * The error every abandoned pack rejects with.
+ * @returns The error.
+ */
+function abandoned() {
+    return new Error('atlas-worker: the pack was abandoned');
+}
+/**
+ * Turns whatever was thrown into an `Error`.
+ * @param error - What was thrown.
+ * @returns An error.
+ */
+function asError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+/**
+ * How many sources one `postMessage` carries.
+ *
+ * Sending every source in one message left 18 dropped frames at a thousand logos on a 4x-throttled
+ * CPU; sending them in batches of 25 left one. Chunking is what removes the last stall, so this is
+ * the number that matters most in this file — tune it against the benchmark, not by taste.
+ */
+export const SOURCE_CHUNK_SIZE = 25;
+/** Every pack that has been sent and is waiting for its reply, by request id. */
+const pending = new Map();
+/** The worker every pack runs on, once the first pack has started it. */
+let pool = null;
+/** The last id handed to a pack. Ids only ever climb, so no reply can find the wrong caller. */
+let lastRequestId = 0;

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

@@ -0,0 +1,10 @@
+/**
+ * The worker's public face: the main thread's half only.
+ *
+ * The worker entry is deliberately absent. It imports `packSources` and carries the
+ * `?worker&inline` specifier, and nothing outside this directory should pull either in by
+ * reaching past the barrel. Types are the exception, because they are erased at emit.
+ */
+export { type WorkerAtlas, type WorkerSource } from './atlas-worker';
+export { packInWorker, type PackInWorkerOptions, SOURCE_CHUNK_SIZE } from './client';
+//# sourceMappingURL=index.d.ts.map

package/dist/objects/images/worker/index.js

@@ -0,0 +1 @@
+export { packInWorker, SOURCE_CHUNK_SIZE } from './client';

package/dist/objects/materials/TextureMaterial.js

@@ -1,4 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
+import { OneFactor } from 'three';
 import { useDimPatch } from './effects/color-dim';
 import { sharedParams } from './shared';
 /**
@@ -25,5 +26,14 @@ export function TextureMaterial(props) {
         vMapUv = uv * ${uvOffset}.zw + ${uvOffset}.xy;
       `.trim());
     }
-    return _jsx("meshBasicMaterial", { ...sharedParams, map: map, onBeforeCompile: onBeforeCompile });
+    // An atlas texture is premultiplied (see `makeAtlasTexture`'s `premultiplyAlpha` comment), so
+    // this material needs the premultiplied blend, not `sharedParams`'s straight-alpha one.
+    // `blendSrc: OneFactor` is the only change: the source term becomes `1 * (c * a)`, which already
+    // equals the straight blend's own `c * a` source term, so the composited color comes out the
+    // same either way. `blendDst` stays `OneMinusSrcAlphaFactor` from `sharedParams`, since that half
+    // does not depend on how the source is stored.
+    //
+    // The override lives here, not in `sharedParams`, because `ColorMaterial` and `LineMaterial`
+    // share that object and their colors are never premultiplied.
+    return (_jsx("meshBasicMaterial", { ...sharedParams, blendSrc: OneFactor, map: map, onBeforeCompile: onBeforeCompile }));
 }

package/dist/objects/materials/effects/color-dim.js

@@ -166,14 +166,25 @@ const DIM_FUNCTION = 'vec4 dimColor(';
 /**
  * Dimming's file-scope declarations.
  *
- * Dim is a desaturation toward gray, not a darkening — which is why it cannot be baked into a
+ * Dim is a desaturation toward gray, not a darkening. That is why it cannot be baked into a
  * per-instance tint: a texel sampled per fragment has no tint to bake into.
  *
- * `dimColor` takes straight (non-premultiplied) `gl_FragColor` and returns it the same way. The
- * imperative renderer divided rgb by alpha here and multiplied it back at the end; the round-trip
- * cancels — `mix(c, dot(w, c) / k, t)` is linear and homogeneous in `c`, so `f(c / a) * a == f(c)`
- * for every alpha — and it was the one thing that could produce a NaN, at `a == 0`, which SDF text
- * edges generate in quantity. Dropping it changes no pixel.
+ * `dimColor` works on `gl_FragColor` whichever way it is stored, and hands it back stored the same
+ * way. It only ever scales `col.rgb`: `mix(c, dot(w, c) / k, t)` is linear and homogeneous in `c`,
+ * so scaling the input by any constant scales the output by that same constant. That homogeneity
+ * is also why a premultiplied, `SRGBColorSpace`-tagged atlas texture dims to the same composited
+ * pixels as the straight-alpha texture this renderer used before it. Measuring old against new
+ * leaves a small residual: at most about 8 of 255 on one channel, across every alpha and dim
+ * amount tested.
+ *
+ * `stories/objects/layer/Dim.stories.tsx` does not cover any of this. Its image layer draws
+ * `markerCanvas(tint)`, whose whole surface is opaque, so no pixel in that story ever carries a
+ * partial alpha for `dimColor` to distort.
+ *
+ * The imperative renderer divided rgb by alpha here and multiplied it back at the end. The round
+ * trip cancels for the same reason: `f(c / a) * a == f(c)` for every alpha. Dividing by alpha was
+ * also the one step that could produce a NaN, at `a == 0`, which SDF text edges generate in
+ * quantity. Dropping it changes no pixel.
  */
 const DIM_DEFS = /* glsl */ `
   uniform float ${LAYER_DIM};

package/dist/types/defs.d.ts

@@ -2,8 +2,22 @@ import { type Box, type LineLike, type Rect, type Shape } from '@expofp/geometry
 import { type LayoutHandlers, type PointerHandlers } from './events';
 /** A color as a css string or a packed numeric value. */
 export type ColorInput = string | number;
-/** Any image-like source that can be uploaded as a texture. */
-export type ImageSource = HTMLImageElement | HTMLCanvasElement | ImageBitmap | OffscreenCanvas;
+/**
+ * Any image-like source that the renderer can upload as a texture.
+ *
+ * A `Blob` is how anything fetched over the network arrives. It is a handle to an immutable byte
+ * store that the browser reference-counts. `postMessage` clones the handle, not the bytes. That is
+ * what lets atlas packing move to a worker. The renderer decodes the `Blob` itself, off the main
+ * thread wherever the environment allows it.
+ *
+ * `HTMLImageElement` is deliberately absent. Decoding one costs the main thread more than the
+ * packing it feeds: at a thousand logos on a throttled CPU, it stalled the page for two seconds.
+ * Leaving the member in the union would keep that slow path reachable. Pass a `Blob` instead.
+ *
+ * There is no `string` member either. The caller keeps all networking, so the renderer never
+ * learns about URLs, retries, or CORS.
+ */
+export type ImageSource = HTMLCanvasElement | ImageBitmap | OffscreenCanvas | Blob;
 /** Scene definition */
 export interface SceneDef {
     /** Root layer of the scene tree */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expofp/renderer",
-  "version": "3.37.0",
+  "version": "3.38.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/expofp/efp-app.git",
@@ -42,7 +42,7 @@
     "troika-three-text": "^0.52.5",
     "tslib": "^2.3.0",
     "webgl-memory": "^1.1.3",
-    "@expofp/geometry": "3.37.0"
+    "@expofp/geometry": "3.38.0"
   },
   "devDependencies": {
     "@react-three/test-renderer": "^9.1.0",