@woosh/meep-engine 3.14.1 → 3.14.3

package/src/engine/asset/loaders/image/avif/encode_image_source.js

@@ -0,0 +1,117 @@
+import { Av1EncodeContext } from '../../../../../format/image/avif/av1/encode/Av1EncodeContext.js';
+import { EFFORT_BALANCED, EFFORT_FAST, EFFORT_THOROUGH, apply_effort } from '../../../../../format/image/avif/av1/encode/encode_effort.js';
+import { encode_avif } from '../../../../../format/image/avif/api/encode_avif.js';
+import { sampler2d_to_avif } from '../../../../graphics/texture/sampler/sampler2d_to_avif.js';
+
+/**
+ * Encoding one image source, whichever side of a worker boundary it happens on.
+ *
+ * The encoder is meep's own, under `./native` — pure JavaScript, synchronous and portable — so the
+ * same two functions serve the worker pool and the fallback for environments that have no workers.
+ * Keeping them here rather than in the worker is what stops the two paths from drifting apart.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * The effort a caller's `speed` asks for.
+ *
+ * `speed` is the dial the WebAssembly encoder took: zero is slowest and best, ten is fastest. The
+ * native encoder names three points on that curve instead of eleven, because those are the three
+ * that measure differently; this maps one onto the other so that existing callers keep meaning what
+ * they meant.
+ *
+ * @param {number} [speed] `0 .. 10`
+ * @returns {number} one of the `EFFORT_*` constants
+ */
+export function effort_of_speed(speed) {
+    if (speed === undefined) {
+        return EFFORT_BALANCED;
+    }
+
+    if (speed <= 2) {
+        return EFFORT_THOROUGH;
+    }
+
+    if (speed <= 7) {
+        return EFFORT_BALANCED;
+    }
+
+    return EFFORT_FAST;
+}
+
+/**
+ * An encode context to hand back to the functions below.
+ *
+ * One per worker, or one per process for the inline path: it holds the planes and contexts an
+ * encode needs, and reusing it is what keeps a run of encodes from allocating a fresh set each time.
+ *
+ * @returns {Av1EncodeContext}
+ */
+export function create_encoder() {
+    return new Av1EncodeContext();
+}
+
+/**
+ * Encode an image bitmap.
+ *
+ * Needs a canvas to read the bitmap's samples back out — a bitmap is an opaque handle, and drawing
+ * it is the only way to see it. That is a platform capability rather than a codec one, which is why
+ * this is the operation that can be unavailable where the other cannot.
+ *
+ * @param {{bitmap: ImageBitmap, quality: number, speed: (number|undefined)}} request the bitmap is
+ *   closed once it has been read
+ * @param {Av1EncodeContext} encoder
+ * @returns {ArrayBuffer}
+ */
+export function encode_bitmap_source(request, encoder) {
+    const { bitmap, quality, speed } = request;
+
+    if (typeof OffscreenCanvas === 'undefined') {
+        bitmap.close();
+
+        throw new Error('encoding an ImageBitmap needs OffscreenCanvas, which this environment does not have');
+    }
+
+    const canvas = new OffscreenCanvas(bitmap.width, bitmap.height);
+    const context = canvas.getContext('2d');
+
+    context.drawImage(bitmap, 0, 0);
+
+    const image_data = context.getImageData(0, 0, canvas.width, canvas.height);
+
+    bitmap.close();
+
+    apply_effort(encoder, effort_of_speed(speed));
+
+    const file = encode_avif({
+        data: image_data.data,
+        width: image_data.width,
+        height: image_data.height
+    }, { quality: Math.ceil(quality * 100) }, encoder);
+
+    return file.buffer;
+}
+
+/**
+ * Encode a sampler.
+ *
+ * Half float samplers are taken as linear light in the renderer's normalisation and coded through
+ * the PQ transfer function; eight bit ones are coded as ordinary sRGB. Which of the two it is comes
+ * from the data itself, so it survives being posted to a worker.
+ *
+ * @param {{data: TypedArray, width: number, height: number, item_size: number, quality: number,
+ *   speed: (number|undefined)}} request
+ * @param {Av1EncodeContext} encoder
+ * @returns {ArrayBuffer}
+ */
+export function encode_sampler_source(request, encoder) {
+    const { data, width, height, item_size, quality, speed } = request;
+
+    apply_effort(encoder, effort_of_speed(speed));
+
+    const file = sampler2d_to_avif({ data, width, height, itemSize: item_size }, quality, {}, encoder);
+
+    return file.buffer;
+}

package/src/engine/asset/loaders/image/avif/encoder_worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encoder_worker.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/asset/loaders/image/avif/encoder_worker.js"],"names":[],"mappings":""}

package/src/engine/asset/loaders/image/avif/threaded_image_encoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"threaded_image_encoder.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/asset/loaders/image/avif/threaded_image_encoder.js"],"names":[],"mappings":"AAsRA;;GAEG;AACH,8CAFa,oBAAoB,CAOhC;AA1ND;IACI;;OAEG;IACH,gDAFW;QAAE,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,eAAe,CAAC,EAAE,MAAM,CAAA;KAAE,EAmB7D;IAbG,qBAAgC;IAChC,wBAAsC;IAEtC,kCAAkC;IAClC,OADW,UAAU,EAAE,GAAG,IAAI,CACb;IACjB,mBAAmB;IACnB,4BAA6B;IAE7B,wFAAwF;IACxF,QADW,OAAO,CACC;IAEnB,iEAAiE;IACjE,SADW,mBAAiB,IAAI,CACb;IA6GvB;;;;;OAKG;IACH,sBALW,WAAW,WACX,MAAM,UACN,MAAM,GACJ,QAAQ,WAAW,CAAC,CAYhC;IAED;;;;;;;OAOG;IACH;;eAPsC,MAAM;gBAAU,MAAM;kBAAY,MAAM;gBAGnE,MAAM,UACN,MAAM,GACJ,QAAQ,WAAW,CAAC,CAuBhC;IAED,iBASC;;CACJ;AA9OD;IACI,0CAcC;IAbG,YAAoB;IACpB,yBAA0B;IAC1B,gBAA4B;IA8BhC,2EAKC;IAED,4BAEC;IAED,kBAEC;;CACJ"}

package/src/engine/asset/loaders/image/codec/AvifCodec.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The in-tree AVIF decoder, behind the {@link Codec} door.
+ *
+ * The codec itself is `format/image/avif` — pure JavaScript, synchronous, runs wherever the engine
+ * does. Until now it reached the engine through one path only: `avif_to_sampler2d`, called directly
+ * by the scene deserialiser. This puts the same decode behind the interface the asset loader speaks,
+ * so that a `.avif` asset loads through {@link ImageRGBADataLoader} like a PNG does.
+ *
+ * **Same door, one decoder.** `decode` is `avif_to_sampler2d`'s SDR path unwrapped, not a second set
+ * of decoder options: that function is the engine's authority on how an AVIF becomes samples in the
+ * engine's normalisation (which chroma upsampling, which colour space, what white), and it is the
+ * exact inverse of `sampler2d_to_avif`. The review that proposed this codec had the dependency the
+ * other way round — the adapter wrapping the codec — but the adapter is the one with the HDR path
+ * and the reusable decoder context, and neither belongs in an 8-bit asset codec. So the codec wraps
+ * the adapter, and the two cannot disagree about what a pixel means.
+ *
+ * **After {@link NativeImageDecoder} in the chain**, like {@link JpegCodec} and for the same reason:
+ * a browser's own AVIF decoder is faster than this one. Where there is no browser — node, a worker
+ * without `Image` — the native codec throws and this one answers.
+ *
+ * Always RGBA, always 8-bit here; an HDR AVIF decodes to its SDR signal. The HDR reading — half
+ * floats in linear light — is `avif_to_sampler2d(buffer, { hdr: true })` and is what the scene
+ * deserialiser asks for by name.
+ *
+ * @extends {Codec<DecodedImage>}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class AvifCodec extends Codec<DecodedImage> {
+    constructor();
+}
+import { Codec } from "../../../codec/Codec.js";
+//# sourceMappingURL=AvifCodec.d.ts.map

package/src/engine/asset/loaders/image/codec/AvifCodec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AvifCodec.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/asset/loaders/image/codec/AvifCodec.js"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH;;CAqCC;sBAnFqB,yBAAyB"}

package/src/engine/asset/loaders/image/codec/AvifCodec.js

@@ -0,0 +1,85 @@
+import { avif_to_sampler2d } from "../../../../graphics/texture/sampler/avif_to_sampler2d.js";
+import { Codec } from "../../../codec/Codec.js";
+
+/**
+ * Where the `ftyp` box's major brand sits: past the box size and the box type.
+ * @readonly
+ * @type {number}
+ */
+const BRAND_OFFSET = 8;
+
+/**
+ * The two brands an AVIF file may open with — a still image, or an image sequence whose first frame
+ * the decoder reads.
+ * @readonly
+ * @type {string[]}
+ */
+const BRANDS = ["avif", "avis"];
+
+/**
+ * The in-tree AVIF decoder, behind the {@link Codec} door.
+ *
+ * The codec itself is `format/image/avif` — pure JavaScript, synchronous, runs wherever the engine
+ * does. Until now it reached the engine through one path only: `avif_to_sampler2d`, called directly
+ * by the scene deserialiser. This puts the same decode behind the interface the asset loader speaks,
+ * so that a `.avif` asset loads through {@link ImageRGBADataLoader} like a PNG does.
+ *
+ * **Same door, one decoder.** `decode` is `avif_to_sampler2d`'s SDR path unwrapped, not a second set
+ * of decoder options: that function is the engine's authority on how an AVIF becomes samples in the
+ * engine's normalisation (which chroma upsampling, which colour space, what white), and it is the
+ * exact inverse of `sampler2d_to_avif`. The review that proposed this codec had the dependency the
+ * other way round — the adapter wrapping the codec — but the adapter is the one with the HDR path
+ * and the reusable decoder context, and neither belongs in an 8-bit asset codec. So the codec wraps
+ * the adapter, and the two cannot disagree about what a pixel means.
+ *
+ * **After {@link NativeImageDecoder} in the chain**, like {@link JpegCodec} and for the same reason:
+ * a browser's own AVIF decoder is faster than this one. Where there is no browser — node, a worker
+ * without `Image` — the native codec throws and this one answers.
+ *
+ * Always RGBA, always 8-bit here; an HDR AVIF decodes to its SDR signal. The HDR reading — half
+ * floats in linear light — is `avif_to_sampler2d(buffer, { hdr: true })` and is what the scene
+ * deserialiser asks for by name.
+ *
+ * @extends {Codec<DecodedImage>}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class AvifCodec extends Codec {
+    /**
+     * @param {Uint8Array} data
+     * @returns {Promise<boolean>} whether the bytes open with an ISOBMFF `ftyp` box of an AVIF brand
+     */
+    async test(data) {
+        if (data.length < BRAND_OFFSET + 4) {
+            return false;
+        }
+
+        // bytes 4..8 are the box type
+        if (data[4] !== 0x66 || data[5] !== 0x74 || data[6] !== 0x79 || data[7] !== 0x70) {
+            return false;
+        }
+
+        const brand = String.fromCharCode(
+            data[BRAND_OFFSET], data[BRAND_OFFSET + 1], data[BRAND_OFFSET + 2], data[BRAND_OFFSET + 3]
+        );
+
+        return BRANDS.includes(brand);
+    }
+
+    /**
+     * @param {Uint8Array} data
+     * @returns {Promise<DecodedImage>}
+     */
+    async decode(data) {
+        const sampler = avif_to_sampler2d(data);
+
+        return {
+            data: sampler.data,
+            width: sampler.width,
+            height: sampler.height,
+            itemSize: sampler.itemSize,
+            bitDepth: 8
+        };
+    }
+}

package/src/engine/asset/loaders/image/codec/JpegCodec.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The in-tree JPEG decoder, behind the {@link Codec} door.
+ *
+ * `format/image/jpeg` decodes baseline and progressive JPEG to interleaved 8-bit samples — it is
+ * pure JavaScript and runs wherever the engine does. Until this class existed it was reachable from
+ * nothing but its own specs: `guessAssetType` maps `.jpg` to `"image"`, and the image loader's codec
+ * chain sniffed PNG for the worker and handed everything else to the browser's own decoder through a
+ * canvas. That is the right thing where there is a browser — the platform's JPEG decoder is faster
+ * than this one and does not run on the main thread's budget — so this codec sits **after**
+ * {@link NativeImageDecoder} in {@link ImageRGBADataLoader}'s chain, not before it. In a browser
+ * nothing changes; in node, or in a worker with no `Image`, the native decoder throws,
+ * {@link CodecWithFallback} moves on, and a JPEG decodes here.
+ *
+ * Three channels, always. JFIF carries no alpha, and `jpeg_decode` writes RGB; a consumer that wants
+ * RGBA widens it the way it would widen an RGB PNG.
+ *
+ * @extends {Codec<DecodedImage>}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class JpegCodec extends Codec<DecodedImage> {
+    constructor();
+}
+import { Codec } from "../../../codec/Codec.js";
+//# sourceMappingURL=JpegCodec.d.ts.map

package/src/engine/asset/loaders/image/codec/JpegCodec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"JpegCodec.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/asset/loaders/image/codec/JpegCodec.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;;CAkCC;sBAhEqB,yBAAyB"}

package/src/engine/asset/loaders/image/codec/JpegCodec.js

@@ -0,0 +1,66 @@
+import { jpeg_decode } from "../../../../../format/image/jpeg/jpeg_decode.js";
+import { Codec } from "../../../codec/Codec.js";
+
+/**
+ * The two bytes every JPEG file opens with: the SOI marker, `0xFF 0xD8`.
+ * @readonly
+ * @type {number[]}
+ */
+const JPEG_SOI_BYTES = [0xFF, 0xD8];
+
+/**
+ * The in-tree JPEG decoder, behind the {@link Codec} door.
+ *
+ * `format/image/jpeg` decodes baseline and progressive JPEG to interleaved 8-bit samples — it is
+ * pure JavaScript and runs wherever the engine does. Until this class existed it was reachable from
+ * nothing but its own specs: `guessAssetType` maps `.jpg` to `"image"`, and the image loader's codec
+ * chain sniffed PNG for the worker and handed everything else to the browser's own decoder through a
+ * canvas. That is the right thing where there is a browser — the platform's JPEG decoder is faster
+ * than this one and does not run on the main thread's budget — so this codec sits **after**
+ * {@link NativeImageDecoder} in {@link ImageRGBADataLoader}'s chain, not before it. In a browser
+ * nothing changes; in node, or in a worker with no `Image`, the native decoder throws,
+ * {@link CodecWithFallback} moves on, and a JPEG decodes here.
+ *
+ * Three channels, always. JFIF carries no alpha, and `jpeg_decode` writes RGB; a consumer that wants
+ * RGBA widens it the way it would widen an RGB PNG.
+ *
+ * @extends {Codec<DecodedImage>}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class JpegCodec extends Codec {
+    /**
+     * @param {Uint8Array} data
+     * @returns {Promise<boolean>} whether the bytes open with a JPEG SOI marker
+     */
+    async test(data) {
+        if (data.length < JPEG_SOI_BYTES.length) {
+            return false;
+        }
+
+        for (let i = 0; i < JPEG_SOI_BYTES.length; i++) {
+            if (data[i] !== JPEG_SOI_BYTES[i]) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    /**
+     * @param {Uint8Array} data
+     * @returns {Promise<DecodedImage>}
+     */
+    async decode(data) {
+        const image = jpeg_decode(data);
+
+        return {
+            data: image.data,
+            width: image.width,
+            height: image.height,
+            itemSize: 3,
+            bitDepth: 8
+        };
+    }
+}

package/src/engine/asset/loaders/image/codec/NativeImageDecoder.d.ts

@@ -1,27 +1,15 @@
 /**
  * Uses the browser's native image decoder
- * @extends {Codec<{width:number, height:number, data: Uint8Array, itemSize: number, bitDepth:number}>}
+ * @extends {Codec<DecodedImage>}
  */
-export class NativeImageDecoder extends Codec<{
-    width: number;
-    height: number;
-    data: Uint8Array;
-    itemSize: number;
-    bitDepth: number;
-}> {
+export class NativeImageDecoder extends Codec<DecodedImage> {
     constructor();
     /**
      *
      * @param {Uint8Array} data
-     * @return {{data: Uint8Array, width: number, height: number, itemSize: number, bitDepth: number}}
+     * @return {DecodedImage}
      */
-    decodeSync(data: Uint8Array): {
-        data: Uint8Array;
-        width: number;
-        height: number;
-        itemSize: number;
-        bitDepth: number;
-    };
+    decodeSync(data: Uint8Array): DecodedImage;
     decode(data: any): Promise<{
         data: Uint8Array;
         width: number;
@@ -30,5 +18,5 @@ export class NativeImageDecoder extends Codec<{
         bitDepth: number;
     }>;
 }
-import { Codec } from "./Codec.js";
+import { Codec } from "../../../codec/Codec.js";
 //# sourceMappingURL=NativeImageDecoder.d.ts.map

package/src/engine/asset/loaders/image/codec/NativeImageDecoder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NativeImageDecoder.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/asset/loaders/image/codec/NativeImageDecoder.js"],"names":[],"mappings":"AA4DA;;;GAGG;AACH;WAF0B,MAAM;YAAS,MAAM;UAAQ,UAAU;cAAY,MAAM;cAAW,MAAM;;;IAGhG;;;;OAIG;IACH,iBAHW,UAAU,GACT;QAAC,IAAI,EAAE,UAAU,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAC,CAgBhG;IAED;;;;;;OAiBC;CACJ;sBAxGqB,YAAY"}
+{"version":3,"file":"NativeImageDecoder.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/asset/loaders/image/codec/NativeImageDecoder.js"],"names":[],"mappings":"AA4DA;;;GAGG;AACH;;IACI;;;;OAIG;IACH,iBAHW,UAAU,GACT,YAAY,CAgBvB;IAED;;;;;;OAiBC;CACJ;sBAxGqB,yBAAyB"}

package/src/engine/asset/loaders/image/codec/NativeImageDecoder.js

@@ -1,4 +1,4 @@
-import { Codec } from "./Codec.js";
+import { Codec } from "../../../codec/Codec.js";
 
 /**
  *
@@ -60,13 +60,13 @@ function data_to_url(data){
 
 /**
  * Uses the browser's native image decoder
- * @extends {Codec<{width:number, height:number, data: Uint8Array, itemSize: number, bitDepth:number}>}
+ * @extends {Codec<DecodedImage>}
  */
 export class NativeImageDecoder extends Codec {
     /**
      *
      * @param {Uint8Array} data
-     * @return {{data: Uint8Array, width: number, height: number, itemSize: number, bitDepth: number}}
+     * @return {DecodedImage}
      */
     decodeSync(data) {
         const image = new Image();

package/src/engine/asset/loaders/image/codec/ThreadedImageDecoder.d.ts

@@ -1,4 +1,24 @@
-export class ThreadedImageDecoder extends Codec<any> {
+/**
+ * PNG, decoded off the main thread by the rollup-built worker bundle.
+ *
+ * **PNG only, and measured to stay that way.** The in-tree JPEG decoder could run in the same worker
+ * — the codec is engine-free and the bundle would take it — and it was measured against the browser's
+ * own decoder on 1024×1024 Sponza textures (`shade/playground/image_decode_bench`, 2026-09-02): the
+ * platform decodes one in 6–11 ms wall with about 1.5 ms of that on the main thread; the in-tree
+ * decoder takes 128–178 ms wall wherever it runs, and a worker saves only the 1.5 ms. Fifteen to
+ * twenty times the latency for a read-back's worth of main-thread time is the wrong trade for a
+ * loader, so a JPEG falls through this codec's `test` to {@link NativeImageDecoder}, and reaches the
+ * in-tree {@link JpegCodec} only where there is no browser decoder to fall to. Re-run the bench if the
+ * decoder gets within about 2× of the platform's; the change is one sniff here and one arm in
+ * `ImageDecoderWorker`.
+ *
+ * PNG is different: the browser's PNG path is the same canvas round-trip and yields 8-bit RGBA only,
+ * while `PNGReader` keeps 16-bit samples and the channel count the file has, which is what the
+ * heightfields and masks this loader serves are made of.
+ *
+ * @extends {Codec<DecodedImage>}
+ */
+export class ThreadedImageDecoder extends Codec<DecodedImage> {
     /**
      *
      * @param {string} [worker_path]
@@ -12,6 +32,6 @@ export class ThreadedImageDecoder extends Codec<any> {
     test(data: any): Promise<boolean>;
     decode(data: any): Promise<any>;
 }
-import { Codec } from "./Codec.js";
+import { Codec } from "../../../codec/Codec.js";
 import { OnDemandWorkerManager } from "../../../../../core/process/worker/OnDemandWorkerManager.js";
 //# sourceMappingURL=ThreadedImageDecoder.d.ts.map

package/src/engine/asset/loaders/image/codec/ThreadedImageDecoder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ThreadedImageDecoder.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/asset/loaders/image/codec/ThreadedImageDecoder.js"],"names":[],"mappings":"AAMA;IACI;;;OAGG;IACH,8BAFW,MAAM,EAwBhB;IARG;;;OAGG;IACH,QAFU,qBAAqB,CAE+B;IAMlE,kCAaC;IAED,gCAEC;CACJ;sBAjDqB,YAAY;sCAHI,6DAA6D"}
+{"version":3,"file":"ThreadedImageDecoder.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/asset/loaders/image/codec/ThreadedImageDecoder.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IACI;;;OAGG;IACH,8BAFW,MAAM,EAwBhB;IARG;;;OAGG;IACH,QAFU,qBAAqB,CAE+B;IAMlE,kCAaC;IAED,gCAEC;CACJ;sBArEqB,yBAAyB;sCAHT,6DAA6D"}

package/src/engine/asset/loaders/image/codec/ThreadedImageDecoder.js

@@ -1,9 +1,29 @@
 import { assert } from "../../../../../core/assert.js";
 import { OnDemandWorkerManager } from "../../../../../core/process/worker/OnDemandWorkerManager.js";
 import WorkerBuilder from "../../../../../core/process/worker/WorkerBuilder.js";
-import { PNG_HEADER_BYTES } from "../png/PNG_HEADER_BYTES.js";
-import { Codec } from "./Codec.js";
+import { PNG_HEADER_BYTES } from "../../../../../format/image/png/PNG_HEADER_BYTES.js";
+import { Codec } from "../../../codec/Codec.js";
 
+/**
+ * PNG, decoded off the main thread by the rollup-built worker bundle.
+ *
+ * **PNG only, and measured to stay that way.** The in-tree JPEG decoder could run in the same worker
+ * — the codec is engine-free and the bundle would take it — and it was measured against the browser's
+ * own decoder on 1024×1024 Sponza textures (`shade/playground/image_decode_bench`, 2026-09-02): the
+ * platform decodes one in 6–11 ms wall with about 1.5 ms of that on the main thread; the in-tree
+ * decoder takes 128–178 ms wall wherever it runs, and a worker saves only the 1.5 ms. Fifteen to
+ * twenty times the latency for a read-back's worth of main-thread time is the wrong trade for a
+ * loader, so a JPEG falls through this codec's `test` to {@link NativeImageDecoder}, and reaches the
+ * in-tree {@link JpegCodec} only where there is no browser decoder to fall to. Re-run the bench if the
+ * decoder gets within about 2× of the platform's; the change is one sniff here and one arm in
+ * `ImageDecoderWorker`.
+ *
+ * PNG is different: the browser's PNG path is the same canvas round-trip and yields 8-bit RGBA only,
+ * while `PNGReader` keeps 16-bit samples and the channel count the file has, which is what the
+ * heightfields and masks this loader serves are made of.
+ *
+ * @extends {Codec<DecodedImage>}
+ */
 export class ThreadedImageDecoder extends Codec {
     /**
      *

package/src/engine/asset/loaders/image/prototypePNG.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prototypePNG.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/asset/loaders/image/prototypePNG.js"],"names":[],"mappings":""}

package/src/engine/asset/loaders/image/prototypePNG.js

@@ -0,0 +1,37 @@
+import { Sampler2D } from "../../../graphics/texture/sampler/Sampler2D.js";
+import sampler2D2Canvas from "../../../graphics/texture/sampler/sampler2d_to_html_canvas.js";
+import { AssetRequestScope } from "../../AssetRequestScope.js";
+import { ArrayBufferLoader } from "../ArrayBufferLoader.js";
+import { PNGReader } from "../../../../format/image/png/PNGReader.js";
+
+const array_loader = new ArrayBufferLoader();
+
+
+// const path = 'moicon/ISO 7010 - Safety Signs (3)/ISO 7010 - Safety Signs/Emergency/400px/E001 – Emergency exit (left hand).png';
+// const path = 'data/textures/utility/vt/uv_map_reference/5-2-1.png';
+// const path = 'data/textures/utility/vt/uv_map_reference/6-62-60.png';
+// const path = 'data/textures/utility/vt/uv_map_reference/5-11-5.png';
+// const path = 'data/textures/utility/vt/uv_map_reference/1-0-0.png';
+// const path = 'data/textures/utility/vt/uv_map_reference/5-3-0.png';
+// const path = 'data/textures/utility/vt/uv_map_reference/5-21-14.png';
+const path = 'data/textures/utility/vt/uv_map_reference/6-39-33.png';
+
+array_loader.load(new AssetRequestScope(), path, (asset) => {
+
+    const array = asset.create();
+
+    const reader = new PNGReader(array);
+
+    const png = reader.parse();
+
+    console.log(png);
+
+    const uint8Data = png.getUint8Data();
+
+    const sampler = new Sampler2D(uint8Data.data, uint8Data.itemSize, png.getWidth(), png.getHeight());
+
+    const canvas = sampler2D2Canvas(sampler, 1, 0);
+
+    document.body.appendChild(canvas);
+
+});

package/src/engine/asset/preloader/extractAssetListFromManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extractAssetListFromManager.d.ts","sourceRoot":"","sources":["../../../../../src/engine/asset/preloader/extractAssetListFromManager.js"],"names":[],"mappings":"AAEA;;;GAGG;AACH,+EA+CC"}
+{"version":3,"file":"extractAssetListFromManager.d.ts","sourceRoot":"","sources":["../../../../../src/engine/asset/preloader/extractAssetListFromManager.js"],"names":[],"mappings":"AAEA;;;GAGG;AACH,+EAgDC"}

package/src/engine/asset/preloader/extractAssetListFromManager.js

@@ -15,7 +15,8 @@ export function extractAssetListFromManager(assetManager) {
         [GameAssetType.JSON]: 1,
         [GameAssetType.ArrayBuffer]: 1,
         [GameAssetType.ModelGLTF_JSON]: 2,
-        [GameAssetType.ModelGLTF]: 2
+        [GameAssetType.ModelGLTF]: 2,
+        [GameAssetType.ModelUSD]: 2
     };
 
     function getLevel(type) {

package/src/engine/graphics/ecs/mesh/assetTypeByPath.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"assetTypeByPath.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/mesh/assetTypeByPath.js"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,qCAHW,MAAM,GACL,SAAO,IAAI,CAsBtB"}
+{"version":3,"file":"assetTypeByPath.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/mesh/assetTypeByPath.js"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,qCAHW,MAAM,GACL,SAAO,IAAI,CA4BtB"}

package/src/engine/graphics/ecs/mesh/assetTypeByPath.js

@@ -18,6 +18,12 @@ export function assetTypeByPath(url) {
                 return "model/gltf";
             case "gltf":
                 return "model/gltf+json";
+            // all four under the one type, as `guessAssetType` has them
+            case "usd":
+            case "usda":
+            case "usdc":
+            case "usdz":
+                return "model/vnd.usd";
             default:
                 console.warn(`Unknown 3d mesh format extension: '${ext}'`);
                 return null;

package/src/engine/graphics/texture/atlas/TextureAtlas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TextureAtlas.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/texture/atlas/TextureAtlas.js"],"names":[],"mappings":"AAkBA;IAcI;;;;;;OAMG;IACH,mBALW,MAAM,cACN,cAAc,kBACd,MAAM,EA6ChB;IA9DD;;;OAGG;IACH,gBAAa;IAEb;;;;OAIG;IACH,sBAAsB;IAgBlB;;;;OAIG;IACH,eAA0B;IAE1B;;;OAGG;IACH,eAFU,OAAO,CAEkB;IAInC;;;;OAIG;IACH,2BAAgH;IAEhH;;;OAGG;IACH,eAAiD;IAEjD;;QAEI;;WAEG;;MAEN;IAGL;;;OAGG;IACH,yBAEC;IAED;;;;OAIG;IACH,kBAHW,SAAS,GACP,UAAU,GAAC,SAAS,CAYhC;IAED;;;OAGG;IACH,eAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,gBAHW,UAAU,GACR,OAAO,CAQnB;IAED;;OAEG;IACH,cAkBC;IAED;;;;;OAKG;IACH,UAJW,MAAM,KACN,MAAM,GACJ,OAAO,CA0CnB;IAED;;;;OAIG;IACH,mBAqBC;IAED;;;;OAIG;IACH,mBAaC;IAED;;;;;;OAMG;IACH,kBAIC;IAED;;;;;OAKG;IACH,aAJW,SAAS,YACT,MAAM,GACL,UAAU,CAgCrB;IAED;;;;;OAKG;IACH,YAJW,MAAM,KACN,MAAM,GACJ,OAAO,CAInB;IAED;;;;OAIG;IACH,cAHW,UAAU,GACT,OAAO,CAiClB;IAED;;;OAGG;IACH,UAFa,OAAO,CAyBnB;IAED;;;;OAIG;IACH,aAqGC;IAED;;OAEG;IACH,cA6BC;IAsDD;;OAEG;IACH,cAQC;CACJ;qCAxjBoC,2BAA2B;oBAN5C,kCAAkC;mBAFnC,0CAA0C;0BAMnC,yBAAyB;2BAGxB,iBAAiB;+BAbb,gDAAgD"}
+{"version":3,"file":"TextureAtlas.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/texture/atlas/TextureAtlas.js"],"names":[],"mappings":"AAkBA;IAcI;;;;;;OAMG;IACH,mBALW,MAAM,cACN,cAAc,kBACd,MAAM,EA6ChB;IA9DD;;;OAGG;IACH,gBAAa;IAEb;;;;OAIG;IACH,sBAAsB;IAgBlB;;;;OAIG;IACH,eAA0B;IAE1B;;;OAGG;IACH,eAFU,OAAO,CAEkB;IAInC;;;;OAIG;IACH,2BAAgH;IAEhH;;;OAGG;IACH,eAAiD;IAEjD;;QAEI;;WAEG;;MAEN;IAGL;;;OAGG;IACH,yBAEC;IAED;;;;OAIG;IACH,kBAHW,SAAS,GACP,UAAU,GAAC,SAAS,CAYhC;IAED;;;OAGG;IACH,eAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,gBAHW,UAAU,GACR,OAAO,CAQnB;IAED;;OAEG;IACH,cAqBC;IAED;;;;;OAKG;IACH,UAJW,MAAM,KACN,MAAM,GACJ,OAAO,CA0CnB;IAED;;;;OAIG;IACH,mBAqBC;IAED;;;;OAIG;IACH,mBAaC;IAED;;;;;;OAMG;IACH,kBAIC;IAED;;;;;OAKG;IACH,aAJW,SAAS,YACT,MAAM,GACL,UAAU,CAgCrB;IAED;;;;;OAKG;IACH,YAJW,MAAM,KACN,MAAM,GACJ,OAAO,CAInB;IAED;;;;OAIG;IACH,cAHW,UAAU,GACT,OAAO,CAiClB;IAED;;;OAGG;IACH,UAFa,OAAO,CAyBnB;IAED;;;;OAIG;IACH,aAqGC;IAED;;OAEG;IACH,cAsCC;IAsDD;;OAEG;IACH,cASC;CACJ;qCArkBoC,2BAA2B;oBAN5C,kCAAkC;mBAFnC,0CAA0C;0BAMnC,yBAAyB;2BAGxB,iBAAiB;+BAbb,gDAAgD"}

package/src/engine/graphics/texture/atlas/TextureAtlas.js

@@ -147,6 +147,9 @@ export class TextureAtlas extends AbstractTextureAtlas {
         //erase data
         this.__sampler.data.fill(0);
 
+        // written through `data` rather than through the sampler, so the version is moved by hand
+        this.__sampler.version++;
+
         this.__needsUpdate = true;
     }
 
@@ -511,6 +514,15 @@ export class TextureAtlas extends AbstractTextureAtlas {
         // console.timeEnd('TextureAtlas.paint');
 
         if (paintCount > 0) {
+            /*
+             The atlas's own pixels have changed, and everything that mirrors them -- a GPU texture,
+             a debug canvas -- decides whether to re-read by comparing this version. The bump belongs
+             here rather than in `paintPatch`, because that is the method subclasses override: one
+             that paints into `data` itself, as `DecalAtlas` does for its borders, never reaches the
+             copy helper that would otherwise have moved the version for it.
+            */
+            this.__sampler.version++;
+
             //notify that atlas was painted
             this.on.painted.send0();
         }
@@ -573,6 +585,7 @@ export class TextureAtlas extends AbstractTextureAtlas {
      */
     reset() {
         this.__sampler.data.fill(0);
+        this.__sampler.version++;
 
         this.patches = [];
 

package/src/engine/graphics/texture/sampler/avif_to_sampler2d.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Decode an AVIF file into a sampler the renderer can use.
+ *
+ * High dynamic range images come back as half floats holding linear light, which is what the
+ * renderer's textures are; everything else comes back as eight bit samples.
+ *
+ * The linear normalisation is the renderer's: `1.0` is SDR reference white,
+ * {@link SDR_WHITE_NITS} nits per ITU-R BT.2408, which is the unit every sampler in the engine is
+ * already in. Naming it to the decoder is what makes this the exact inverse of
+ * {@link sampler2d_to_avif}, which names the same white to the encoder.
+ *
+ * @param {ArrayBuffer|Uint8Array} buffer
+ * @param {object} [options]
+ * @param {boolean} [options.hdr] decode to linear half floats rather than eight bit samples
+ * @param {AvifDecoder} [decoder] pass one back in to decode many images without reallocating
+ * @returns {Sampler2D}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function avif_to_sampler2d(buffer: ArrayBuffer | Uint8Array, options?: {
+    hdr?: boolean;
+}, decoder?: AvifDecoder): Sampler2D;
+import { Sampler2D } from "./Sampler2D.js";
+//# sourceMappingURL=avif_to_sampler2d.d.ts.map

package/src/engine/graphics/texture/sampler/avif_to_sampler2d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"avif_to_sampler2d.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/texture/sampler/avif_to_sampler2d.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,0CATW,WAAW,GAAC,UAAU;IAEJ,GAAG,GAArB,OAAO;2BAEL,SAAS,CAqBrB;0BAvCyB,gBAAgB"}