@expofp/renderer 3.37.0 → 3.38.0

package/dist/objects/images/pack-sources.d.ts

@@ -0,0 +1,190 @@
+/**
+ * A source that the packer can draw from without decoding it further. It is already decoded, and
+ * it reports its own pixel size. A `Blob` is the one image source that meets neither condition, so
+ * code decodes each `Blob` into one of these types before it reaches this module.
+ */
+export type DecodedSource = ImageBitmap | HTMLCanvasElement | OffscreenCanvas;
+/**
+ * A canvas that one atlas is drawn onto. This type includes `OffscreenCanvas`, so packing can
+ * later move into a worker.
+ */
+export type AtlasCanvas = HTMLCanvasElement | OffscreenCanvas;
+/**
+ * Creates the backing canvas for one atlas, sized to that atlas exactly.
+ * @param width - The atlas width in pixels.
+ * @param height - The atlas height in pixels.
+ * @returns The canvas to draw on.
+ */
+export type CreateAtlasCanvas = (width: number, height: number) => AtlasCanvas;
+/**
+ * A region of a source image, in **source pixels with a top-left origin**. These are the same axes
+ * as `ImageDef.bounds`, and they are the exact `sx, sy, sw, sh` values that the packer passes to
+ * `drawImage`. This type keeps pixels instead of normalized values, so code cannot mistake it for
+ * a {@link UvRect}, whose origin is the opposite corner.
+ */
+export interface SourceRect {
+    /** Distance from the source's left edge, in pixels. */
+    x: number;
+    /** Distance from the source's top edge, in pixels. */
+    y: number;
+    /** Region width in pixels. */
+    width: number;
+    /** Region height in pixels. */
+    height: number;
+}
+/**
+ * A region of an atlas, **normalized in the canvas's own axes: a top-left origin, with v running
+ * down**.
+ *
+ * A texture with `flipY = false` consumes these values. That setting maps canvas row 0 to `v = 0`,
+ * so these numbers feed a uv transform directly, with no vertical inversion. This is deliberate.
+ * The scene already uses a y axis that points down, because it follows SVG coordinates and the
+ * camera matches them. A uv space that also runs down keeps every axis in the pipeline pointing
+ * the same way. If only one end inverts, images come out upside down.
+ */
+export interface UvRect {
+    /** Left edge, `0` at the atlas's left. */
+    u0: number;
+    /** Top edge, `0` at the atlas's top. */
+    v0: number;
+    /** Right edge. */
+    u1: number;
+    /** Bottom edge. */
+    v1: number;
+}
+/**
+ * One source, or one tile of a split source, placed on an atlas. Each placement carries an array
+ * index instead of the source object as its address, because this data crosses a `postMessage`
+ * boundary, and object identity does not survive that boundary.
+ */
+export interface Placement {
+    /** Index into the `sources` array that the caller gave {@link packSources}. */
+    index: number;
+    /** Where the pixels sit on the atlas. */
+    uv: UvRect;
+    /**
+     * Which part of the source this placement holds. This is undefined when the source packs
+     * whole, which is the common case. It is set only on the tiles of a split source.
+     */
+    source?: SourceRect;
+}
+/** One packed atlas, before its placements are mapped back onto the defs that wanted them. */
+export interface SourceAtlas {
+    /** The canvas holding the packed pixels. Its `width`/`height` are the atlas's size. */
+    canvas: AtlasCanvas;
+    /** Every placement on this atlas. */
+    placements: Placement[];
+    /**
+     * Whether this atlas's pixels can shrink to fit a memory budget. Bitmaps pack into resizable
+     * atlases, canvases pack into fixed ones, and an atlas never mixes the two.
+     */
+    resizable: boolean;
+}
+/**
+ * What one source contributed to a pack. The caller holds the defs, so only the caller can warn
+ * about them. This report gives the caller the measurements it needs to do that.
+ */
+export interface SourceReport {
+    /** The source's intrinsic width in pixels. */
+    width: number;
+    /** The source's intrinsic height in pixels. */
+    height: number;
+    /**
+     * How many rects this source packed into. It is `0` when the source had no pixels and code
+     * dropped it. It is `1` when the source packed whole. Otherwise it is the tile count, for a
+     * source too big for one atlas that code had to cut.
+     */
+    tiles: number;
+}
+/**
+ * Whether a source is a `Blob`, which is also true of a `File`.
+ *
+ * The test looks for `slice`, and it must keep looking for `slice`. `slice` is Chrome 21, Chrome
+ * Android 25, Safari 7 and iOS Safari 7, so every build target has it. `arrayBuffer` reads better
+ * and is wrong: it is Chrome 76 and Chrome Android 76, above this package's `chrome66` floor, so on
+ * the old Android WebViews it is `undefined` and every real `Blob` would fail this test and reach
+ * the packer undecoded (`packages/floorplan/src/components/Maplibre/utils/pmtiles-range-fallback.ts`
+ * works around the same floor). No other image source carries either method: not an `<img>`, a
+ * canvas, an offscreen canvas or a bitmap.
+ *
+ * A property test rather than `instanceof`, so this never reaches for a global that can be absent.
+ *
+ * This is the one home of the test. It decides both what needs a decode and what may cross to the
+ * atlas worker, so a second copy could drift from this one, and the drift would only show on the
+ * oldest targets.
+ * @param source - The source to classify.
+ * @returns Whether the source needs a decode.
+ */
+export declare function isBlob(source: object): source is Blob;
+/**
+ * Whether a source's pixels can shrink to fit a memory budget. This is `true` for decoded images
+ * and bitmaps. It is `false` for canvases, because a canvas's pixels belong to the caller. The
+ * code counts a canvas at full size and never compresses it (see the scene's `memoryLimit`).
+ *
+ * The check looks for the absence of `getContext`. `HTMLCanvasElement` and `OffscreenCanvas` both
+ * have it. `ImageBitmap` and `Blob` do not. This is a property test, not an
+ * `instanceof` check, because the SDK runs in WebViews. There, `OffscreenCanvas` and `ImageBitmap`
+ * can be missing as globals, and an `instanceof` check against a missing global throws an error.
+ * @param source - The source to classify.
+ * @returns Whether the source can shrink.
+ */
+export declare function isResizableSource(source: object): boolean;
+/**
+ * Makes the canvas that one atlas draws onto. The function returns an `OffscreenCanvas` where one
+ * exists, and a DOM canvas otherwise.
+ *
+ * This is the only place in the package that builds an atlas canvas, so the `OffscreenCanvas`
+ * guard lives here alone. The guard uses this plain form because `eslint-plugin-compat`
+ * understands it and flags only an unguarded construction. Nothing here needs hiding from the
+ * linter.
+ * @param width - The canvas width in pixels.
+ * @param height - The canvas height in pixels.
+ * @returns The canvas.
+ */
+export declare function createAtlasCanvas(width: number, height: number): AtlasCanvas;
+/**
+ * Packs decoded sources into atlas canvases and reports where each one landed.
+ *
+ * The code splits sources by kind first: resizable ones (bitmaps and images) apart from fixed ones
+ * (canvases). Each kind packs on its own, so no atlas ever mixes the two kinds. This lets a memory
+ * budget scale a whole resizable atlas without touching a canvas's pixels. Within one kind, the
+ * code offers each source to the packer whole. Anything too big for an atlas comes back parked in
+ * a bin of its own natural size, and the packer flags that bin. Those are the only sources that get
+ * cut into tiles, and the tiles go back through the same packer. Letting the packer decide keeps
+ * the guarantee that no atlas exceeds `maxDimension`, with no need to measure every image up
+ * front.
+ *
+ * This function does **not** deduplicate sources. The caller must collect unique sources before it
+ * decodes them, so every entry in `sources` is already distinct.
+ *
+ * This module runs unchanged on the main thread and inside the atlas worker. It must not use
+ * `document`, the def types, or the logger.
+ * @param sources - The decoded sources to pack, in the order the caller gives them.
+ * @param maxDimension - The largest atlas edge in pixels. The function floors this to a positive
+ *   integer.
+ * @param createCanvas - Makes each atlas canvas. Defaults to {@link createAtlasCanvas}.
+ * @returns The atlases in packing order (resizable first, then fixed), and one report for each
+ *   source, aligned by index with `sources`.
+ */
+export declare function packSources(sources: readonly (DecodedSource | null)[], maxDimension: number, createCanvas?: CreateAtlasCanvas): {
+    atlases: SourceAtlas[];
+    reports: SourceReport[];
+};
+/**
+ * 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.
+ */
+export declare function contextOf(canvas: AtlasCanvas): CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D | null;
+//# sourceMappingURL=pack-sources.d.ts.map

package/dist/objects/images/pack-sources.js

@@ -0,0 +1,272 @@
+import { MaxRectsPacker } from 'maxrects-packer';
+/**
+ * Whether a source is a `Blob`, which is also true of a `File`.
+ *
+ * The test looks for `slice`, and it must keep looking for `slice`. `slice` is Chrome 21, Chrome
+ * Android 25, Safari 7 and iOS Safari 7, so every build target has it. `arrayBuffer` reads better
+ * and is wrong: it is Chrome 76 and Chrome Android 76, above this package's `chrome66` floor, so on
+ * the old Android WebViews it is `undefined` and every real `Blob` would fail this test and reach
+ * the packer undecoded (`packages/floorplan/src/components/Maplibre/utils/pmtiles-range-fallback.ts`
+ * works around the same floor). No other image source carries either method: not an `<img>`, a
+ * canvas, an offscreen canvas or a bitmap.
+ *
+ * A property test rather than `instanceof`, so this never reaches for a global that can be absent.
+ *
+ * This is the one home of the test. It decides both what needs a decode and what may cross to the
+ * atlas worker, so a second copy could drift from this one, and the drift would only show on the
+ * oldest targets.
+ * @param source - The source to classify.
+ * @returns Whether the source needs a decode.
+ */
+export function isBlob(source) {
+    return typeof source.slice === 'function';
+}
+/**
+ * Whether a source's pixels can shrink to fit a memory budget. This is `true` for decoded images
+ * and bitmaps. It is `false` for canvases, because a canvas's pixels belong to the caller. The
+ * code counts a canvas at full size and never compresses it (see the scene's `memoryLimit`).
+ *
+ * The check looks for the absence of `getContext`. `HTMLCanvasElement` and `OffscreenCanvas` both
+ * have it. `ImageBitmap` and `Blob` do not. This is a property test, not an
+ * `instanceof` check, because the SDK runs in WebViews. There, `OffscreenCanvas` and `ImageBitmap`
+ * can be missing as globals, and an `instanceof` check against a missing global throws an error.
+ * @param source - The source to classify.
+ * @returns Whether the source can shrink.
+ */
+export function isResizableSource(source) {
+    return !('getContext' in source);
+}
+/**
+ * Makes the canvas that one atlas draws onto. The function returns an `OffscreenCanvas` where one
+ * exists, and a DOM canvas otherwise.
+ *
+ * This is the only place in the package that builds an atlas canvas, so the `OffscreenCanvas`
+ * guard lives here alone. The guard uses this plain form because `eslint-plugin-compat`
+ * understands it and flags only an unguarded construction. Nothing here needs hiding from the
+ * linter.
+ * @param width - The canvas width in pixels.
+ * @param height - The canvas height in pixels.
+ * @returns The canvas.
+ */
+export function createAtlasCanvas(width, height) {
+    if (typeof OffscreenCanvas !== 'undefined')
+        return new OffscreenCanvas(width, height);
+    const canvas = document.createElement('canvas');
+    canvas.width = width;
+    canvas.height = height;
+    return canvas;
+}
+/**
+ * Packs decoded sources into atlas canvases and reports where each one landed.
+ *
+ * The code splits sources by kind first: resizable ones (bitmaps and images) apart from fixed ones
+ * (canvases). Each kind packs on its own, so no atlas ever mixes the two kinds. This lets a memory
+ * budget scale a whole resizable atlas without touching a canvas's pixels. Within one kind, the
+ * code offers each source to the packer whole. Anything too big for an atlas comes back parked in
+ * a bin of its own natural size, and the packer flags that bin. Those are the only sources that get
+ * cut into tiles, and the tiles go back through the same packer. Letting the packer decide keeps
+ * the guarantee that no atlas exceeds `maxDimension`, with no need to measure every image up
+ * front.
+ *
+ * This function does **not** deduplicate sources. The caller must collect unique sources before it
+ * decodes them, so every entry in `sources` is already distinct.
+ *
+ * This module runs unchanged on the main thread and inside the atlas worker. It must not use
+ * `document`, the def types, or the logger.
+ * @param sources - The decoded sources to pack, in the order the caller gives them.
+ * @param maxDimension - The largest atlas edge in pixels. The function floors this to a positive
+ *   integer.
+ * @param createCanvas - Makes each atlas canvas. Defaults to {@link createAtlasCanvas}.
+ * @returns The atlases in packing order (resizable first, then fixed), and one report for each
+ *   source, aligned by index with `sources`.
+ */
+export function packSources(sources, maxDimension, createCanvas = createAtlasCanvas) {
+    const limit = Math.max(1, Math.floor(maxDimension));
+    // Every member of `DecodedSource` reports its own pixel size, so nothing here needs to duck-type
+    // a size. That was only ever needed because an `<img>` reports its layout size as `width`. A
+    // source that fails to decode arrives as `null` and reports `0 x 0`. Code skips that source the
+    // same way it skips a zero-sized canvas.
+    const reports = sources.map((source) => source
+        ? { width: source.width, height: source.height, tiles: 0 }
+        : { width: 0, height: 0, tiles: 0 });
+    const resizable = [];
+    const fixed = [];
+    for (let index = 0; index < sources.length; index++) {
+        const source = sources[index];
+        // A source that failed to decode is dropped later by the size check in `packGroup`. Code
+        // groups it with the resizable sources, so it never lands in an atlas of canvases on its way
+        // to being skipped.
+        (!source || isResizableSource(source) ? resizable : fixed).push(index);
+    }
+    // One packer serves both groups, reset between them. The configuration (size, padding, options)
+    // is the same for each, so reusing the packer spares an allocation per pack. The packer cannot
+    // carry over across pack calls, though, because `limit` is fixed at construction and changes
+    // from call to call.
+    // `pot: false`, because WebGL 2 samples non-power-of-two textures without restriction. Rounding
+    // each atlas up only wastes memory. `smart` stays on (the default), which shrinks every bin to
+    // its content. That is why the code reads the size back off the bin instead of assuming
+    // `limit`.
+    const packer = new MaxRectsPacker(limit, limit, PADDING, { pot: false });
+    const atlases = [
+        ...packGroup(packer, sources, resizable, reports, limit, createCanvas, true),
+        ...packGroup(packer, sources, fixed, reports, limit, createCanvas, false),
+    ];
+    return { atlases, reports };
+}
+/**
+ * The gap between neighboring images on an atlas. This gap stops linear filtering at one image's
+ * edge from reaching into the next image's pixels. The packer applies this gap *between* rects
+ * only, so atlas edges stay flush against the pixels. This is also why a tile exactly
+ * `maxDimension` across still fits in a bin.
+ */
+const PADDING = 1;
+/**
+ * Packs one kind of source, either all resizable or all fixed, into atlases. The function tags
+ * each atlas with the group's kind and records each source's tile count in `reports`.
+ * @param packer - The shared packer. It is reset to empty before this group is added.
+ * @param sources - Every source, indexed by the entries in `indices`.
+ * @param indices - The indices of this kind. This list can be empty, and then nothing packs.
+ * @param reports - Per-source reports. This function fills in each report's `tiles` count.
+ * @param limit - The largest atlas edge, in pixels.
+ * @param createCanvas - Makes each atlas canvas.
+ * @param resizable - The kind, stamped onto every atlas that this call produces.
+ * @returns The atlases this group produced.
+ */
+function packGroup(packer, sources, indices, reports, limit, createCanvas, resizable) {
+    const rects = [];
+    for (const index of indices) {
+        const { width, height } = reports[index];
+        // A `drawImage` call throws in some browsers when the source region has zero width or zero
+        // height. So code drops an image that has not decoded, or a canvas sized to nothing, instead
+        // of drawing it. Its report keeps `tiles: 0`, and that value tells the caller to warn about
+        // it.
+        if (width <= 0 || height <= 0)
+            continue;
+        rects.push({ width, height, x: 0, y: 0, hash: `${index}`, data: { index } });
+    }
+    // Clear whatever the previous group left in the packer, keeping its configuration.
+    packer.reset();
+    // `addArray` sorts by longest edge before it places rects, which packs far tighter than
+    // insertion order.
+    packer.addArray(rects);
+    // The packer tags whatever it must park in an oversized bin. The packer decides what needs
+    // cutting, not a separate measurement in this code. The tiles are ordinary rects, and they pack
+    // into the bins that the first pass already opened.
+    const oversized = rects.filter((rect) => rect.oversized);
+    if (oversized.length > 0) {
+        packer.addArray(oversized.flatMap((rect) => cutTiles(rect, reports[rect.data.index], limit)));
+    }
+    // Every oversized bin now has its tiles standing in for it, so the code drops the bin instead of
+    // returning it. Handing back a canvas larger than the caller's limit is the exact problem this
+    // code exists to prevent.
+    const bins = packer.bins.filter((bin) => !bin.rects.some((rect) => rect.oversized));
+    const atlases = bins.map((bin) => ({
+        ...renderAtlas(bin, sources, reports, createCanvas),
+        resizable,
+    }));
+    // Count what actually landed. This lets code tell a dropped source apart from a split one.
+    for (const bin of bins)
+        for (const rect of bin.rects)
+            reports[rect.data.index].tiles++;
+    return atlases;
+}
+/**
+ * Cuts a source that did not fit in the packer into a grid of tiles. No tile is larger than one
+ * atlas. Tiles are exact and do not overlap. Each tile ends up alone, or beside its own sibling
+ * tiles, in an atlas. Nothing can bleed across the cut, so the code needs no overlap column to
+ * hide a seam.
+ * @param rect - The oversized rect that names the source to cut.
+ * @param report - That source's measured size.
+ * @param limit - The largest tile edge, in pixels.
+ * @returns The tiles to pack in its place.
+ */
+function cutTiles(rect, report, limit) {
+    const columns = Math.ceil(report.width / limit);
+    const rows = Math.ceil(report.height / limit);
+    const tiles = [];
+    for (let row = 0; row < rows; row++) {
+        const y = row * limit;
+        const height = Math.min(limit, report.height - y);
+        for (let column = 0; column < columns; column++) {
+            const x = column * limit;
+            const width = Math.min(limit, report.width - x);
+            tiles.push({
+                width,
+                height,
+                x: 0,
+                y: 0,
+                hash: `${rect.hash}:${column},${row}`,
+                data: { index: rect.data.index, source: { x, y, width, height } },
+            });
+        }
+    }
+    return tiles;
+}
+/**
+ * Draws one packed bin onto a canvas and records where each rect landed.
+ * @param bin - The packed bin, already sized to its content.
+ * @param sources - Every source, indexed by each rect's tile.
+ * @param reports - Per-source sizes, for the whole-image draw region.
+ * @param createCanvas - Makes the canvas to draw on.
+ * @returns The atlas, less its `resizable` flag.
+ */
+function renderAtlas(bin, sources, reports, createCanvas) {
+    const canvas = createCanvas(bin.width, bin.height);
+    const context = contextOf(canvas);
+    // Nothing downstream can recover from a missing context. Every atlas then uploads blank, and
+    // the images silently draw as nothing at all. It is better to fail here, where the cause stays
+    // visible.
+    if (!context)
+        throw new Error(`pack-sources: no 2d context for a ${bin.width}x${bin.height} atlas`);
+    const placements = [];
+    for (const rect of bin.rects) {
+        const { index, source } = rect.data;
+        // The copied region is the tile when the rect has one, and the whole image otherwise. Both
+        // read from the source's own axes. This region happens to match the packed rect's size today,
+        // because tiles are placed 1:1 and unrotated. Reading the size from the destination instead
+        // is correct only by accident, not by design. The code keeps this region apart from `source`
+        // itself, which stays undefined for an unsplit image, so the placement below does not report
+        // a region that the caller has no use for.
+        const { width, height } = reports[index];
+        const region = source ?? { x: 0, y: 0, width, height };
+        // This value is never null, by construction. A source that fails to decode reports `0 x 0`
+        // and never reaches the packer, so every rect in a bin has a drawable source behind it.
+        const decoded = sources[index];
+        if (!decoded)
+            continue;
+        context.drawImage(decoded, region.x, region.y, region.width, region.height, rect.x, rect.y, rect.width, rect.height);
+        // The rect uses canvas pixels, and uv keeps the canvas's axes, so this is a plain
+        // normalization with no vertical inversion (see {@link UvRect}).
+        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,
+        };
+        placements.push(source ? { index, uv, source } : { index, uv });
+    }
+    return { canvas, placements };
+}
+/**
+ * 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.
+ */
+export 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');
+}

package/dist/objects/images/texture-budget.js

@@ -203,8 +203,8 @@ export function useResizeFactor(budget, atlas) {
         if (!active)
             return;
         const entry = {
-            width: atlas.canvas.width,
-            height: atlas.canvas.height,
+            width: atlas.image.width,
+            height: atlas.image.height,
             resizable: atlas.resizable,
         };
         budget.register(entry);

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

@@ -0,0 +1,56 @@
+import { type Placement, type SourceReport } from '../pack-sources';
+/**
+ * The one source the worker takes: a `Blob`.
+ *
+ * The worker could draw a bitmap or an offscreen canvas too, but it never receives one. A `Blob` is
+ * the only source that crosses by copy. Its handle clones and the bytes stay put, so the def that
+ * owns the source keeps it. Any other source would have to move, a moved source is dead on the main
+ * thread, and the next repack of that layer would then find nothing to draw. Tier selection keeps
+ * those sources on the main thread, where they pack inline.
+ */
+export type WorkerSource = Blob;
+/**
+ * What the main thread sends.
+ *
+ * Every message carries the `id` of the pack it belongs to. One worker serves every pack, so two
+ * layers can be in flight at once and the worker must keep their sources apart.
+ */
+export type AtlasWorkerRequest = 
+/** One batch of sources, in the order they were collected. Sent as many times as needed. */
+{
+    type: 'sources';
+    id: number;
+    sources: WorkerSource[];
+}
+/** No more batches: decode what has arrived, pack it, and reply. */
+ | {
+    type: 'pack';
+    id: number;
+    maxDimension: number;
+}
+/** Nobody wants this pack any more. Drop it and reply nothing. */
+ | {
+    type: 'cancel';
+    id: number;
+};
+/** One atlas the worker packed. The bitmap is transferred out, not cloned. */
+export interface WorkerAtlas {
+    /** The atlas's pixels, moved out of the offscreen canvas they were drawn into. */
+    bitmap: ImageBitmap;
+    /** Every placement on this atlas, addressing sources by their index in the batches. */
+    placements: Placement[];
+    /** Whether these pixels may be downscaled to fit a memory budget. */
+    resizable: boolean;
+}
+/** What the worker sends back — at most one of these per pack, carrying that pack's `id`. */
+export type AtlasWorkerResponse = {
+    type: 'packed';
+    id: number;
+    atlases: WorkerAtlas[];
+    reports: SourceReport[];
+} | {
+    type: 'failed';
+    id: number;
+    message: string;
+};
+//# sourceMappingURL=atlas-worker.d.ts.map

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

@@ -0,0 +1,123 @@
+import { packSources, } from '../pack-sources';
+/**
+ * Waits for every batch to decode, packs them, and moves each atlas's pixels out of its canvas.
+ * @param id - Which pack to run.
+ * @param maxDimension - Largest atlas edge in pixels.
+ * @returns The reply to post back, or null when the pack was canceled and nothing is owed.
+ */
+async function pack(id, maxDimension) {
+    // `requestFor` and not `requests.get`, because a layer with no sources sends its closing message
+    // and nothing else. That is an empty pack, and it still owes a reply: without one the layer
+    // waits forever and draws nothing. The only other way to reach this with no state is a cancel
+    // that arrived first, and that happens only when the closing message was never sent, so the
+    // empty reply it produces goes to a caller that has already forgotten the id and is discarded.
+    const request = requestFor(id);
+    request.packing = true;
+    const decoded = await Promise.all(request.decoding);
+    requests.delete(id);
+    // The only yield point in a pack. `packSources` runs straight through once it starts, so this is
+    // the last moment a cancel can save the worker's time for the next pack.
+    if (request.canceled) {
+        closeDecoded(decoded);
+        return null;
+    }
+    // `createAtlasCanvas` returns an `OffscreenCanvas` here and never takes its fallback branch. A
+    // worker runs at all only because `selectTier` found `OffscreenCanvas` on the main thread, and
+    // the constructor is exposed to both globals or to neither. No fallback is worth writing: a
+    // worker has no `document`, so without `OffscreenCanvas` it could build no canvas at all.
+    const { atlases, reports } = packSources(decoded, maxDimension);
+    // `transferToImageBitmap` moves the canvas's backing bitmap out instead of copying it, which is
+    // what makes an atlas cheap to return. The canvas is left blank, and this code drops it anyway.
+    const packed = atlases.map((atlas) => ({
+        bitmap: atlas.canvas.transferToImageBitmap(),
+        placements: atlas.placements,
+        resizable: atlas.resizable,
+    }));
+    // The atlases hold the pixels now, so every decoded bitmap is dead. This worker decoded all of
+    // them and owns all of them. Close them rather than leaving a thousand to the collector.
+    closeDecoded(decoded);
+    return { type: 'packed', id, atlases: packed, reports };
+}
+/**
+ * Abandons one pack.
+ *
+ * A pack that has not reached {@link pack} yet is dropped here, because nothing else will ever read
+ * its decodes. A pack that is already running is only marked: it reads the mark at its one yield
+ * point and cleans up there.
+ * @param id - Which pack to abandon.
+ */
+function cancel(id) {
+    const request = requests.get(id);
+    // Already replied, or never started. Either way this worker holds nothing for that pack.
+    if (!request)
+        return;
+    request.canceled = true;
+    if (request.packing)
+        return;
+    requests.delete(id);
+    void Promise.all(request.decoding).then(closeDecoded);
+}
+/**
+ * Frees decoded pixels this worker owns.
+ *
+ * An `ImageBitmap` holds its pixels outside the JavaScript heap, where collection does not reclaim
+ * them promptly. A canceled pack of a thousand logos would otherwise sit on a thousand of them.
+ * @param decoded - What the sources decoded into.
+ */
+function closeDecoded(decoded) {
+    for (const source of decoded)
+        if (source && 'close' in source)
+            source.close();
+}
+/**
+ * Finds a pack's state, starting it on the first batch that arrives.
+ * @param id - Which pack the batch belongs to.
+ * @returns That pack's state.
+ */
+function requestFor(id) {
+    let request = requests.get(id);
+    if (!request) {
+        request = { decoding: [], canceled: false, packing: false };
+        requests.set(id, request);
+    }
+    return request;
+}
+/**
+ * Every pack this worker is working on, by request id.
+ *
+ * The main thread does not terminate this worker once it has returned an atlas, because those
+ * atlases are backed by GPU memory the worker owns. It stops a worker only when that worker broke
+ * before it produced anything. So one worker serves every pack of every layer, for the life of the
+ * page, and each pack's state has to be kept apart from the others'. An entry is deleted as soon
+ * as its pack replies or is canceled.
+ */
+const requests = new Map();
+/** This worker's global scope. */
+const scope = self;
+scope.onmessage = (event) => {
+    const message = event.data;
+    if (message.type === 'sources') {
+        const request = requestFor(message.id);
+        // Null rather than a rejection, so one set of bytes that is not an image drops its own def
+        // instead of failing the whole layer's pack. `packSources` skips it as a source with no pixels.
+        for (const source of message.sources) {
+            request.decoding.push(createImageBitmap(source).catch(() => null));
+        }
+        return;
+    }
+    if (message.type === 'cancel') {
+        cancel(message.id);
+        return;
+    }
+    const { id } = message;
+    pack(id, message.maxDimension).then((response) => {
+        // Nothing is owed for a canceled pack. The main thread has already settled it.
+        if (!response)
+            return;
+        // The bitmaps move rather than copy. After this the worker holds nothing for this pack.
+        scope.postMessage(response, response.atlases.map((atlas) => atlas.bitmap));
+    }, (error) => {
+        requests.delete(id);
+        scope.postMessage({ type: 'failed', id, message: String(error) });
+    });
+};