@woosh/meep-engine 3.9.0 → 3.10.0

package/src/engine/asset/loaders/image/png/filter/png_filter_unFilterNone.js

@@ -1,55 +1,30 @@
 /**
- * With the None filter, the scanline is transmitted unmodified; it is only necessary to insert a filter type byte before the data.
+ * With the `None` filter the scanline is transmitted unmodified, so reconstruction is a byte copy.
  *
- * For depths < 8 the scanline byte is unpacked into individual samples; for depths 8 and 16 the bytes are copied straight through
- * (16-bit samples are stored as two big-endian bytes per channel — the filter layer still operates byte-wise).
+ * Byte-wise, like every other filter: at bit depths below eight a scanline carries several samples
+ * per byte, and unpacking them is {@link png_unpack_samples}' job, done after reconstruction. The
+ * two were once fused here, which is why `None` was the only filter that worked at those depths.
  *
- * @param {Uint8Array} data
- * @param {number} scanline_address
- * @param {Uint8Array} output
- * @param {number} output_offset
- * @param {number} length number of bytes (depth >= 8) or samples (depth < 8) to produce
- * @param {number} bit_depth one of 1, 2, 4, 8, 16
+ * @param {Uint8Array} scanline raw data
+ * @param {number} scanline_offset
+ * @param {Uint8Array} pixels processed output
+ * @param {number} bpp bytes-per-pixel, unused by this filter
+ * @param {number} offset
+ * @param {number} output_offset_previous unused by this filter
+ * @param {number} length number of bytes to reconstruct
  *
  * @see https://www.w3.org/TR/PNG-Filters.html
  */
 export function png_filter_unFilterNone(
-    data,
-    scanline_address,
-    output,
-    output_offset,
-    length,
-    bit_depth
+    scanline,
+    scanline_offset,
+    pixels,
+    bpp,
+    offset,
+    output_offset_previous,
+    length
 ) {
-    if (bit_depth === 1) {
-        for (let x = 0; x < length; x++) {
-            const q = x >>> 3;
-            const datum = data[q + scanline_address];
-            const shift = ((~x) & 0x7);
-            const out_value = (datum >>> shift) & 0x1;
-            output[output_offset + x] = out_value;
-        }
-    } else if (bit_depth === 2) {
-        for (let x = 0; x < length; x++) {
-            const q = x >>> 2;
-            const datum = data[q + scanline_address];
-            const shift = ((~x) & 0x3) << 1;
-            const out_value = (datum >>> shift) & 0x3;
-            output[output_offset + x] = out_value;
-        }
-    } else if (bit_depth === 4) {
-        for (let x = 0; x < length; x++) {
-            const q = x >>> 1;
-            const datum = data[q + scanline_address];
-            const shift = ((~x) & 0x1) << 2;
-            const out_value = (datum >>> shift) & 0xF;
-            output[output_offset + x] = out_value;
-        }
-    } else if (bit_depth === 8 || bit_depth === 16) {
-        for (let x = 0; x < length; x++) {
-            output[output_offset + x] = data[x + scanline_address];
-        }
-    } else {
-        throw new Error(`unsupported bit depth ${bit_depth}`);
+    for (let i = 0; i < length; i++) {
+        pixels[offset + i] = scanline[scanline_offset + i];
     }
 }

package/src/engine/asset/loaders/image/png/filter/png_filter_unFilterSub.d.ts

@@ -8,8 +8,9 @@
  * @param {Uint8Array} pixels processed output
  * @param {number} bpp bytes-per-pixel
  * @param {number} offset
+ * @param {number} output_offset_previous unused by this filter
  * @param {number} length
  * @see https://www.w3.org/TR/PNG-Filters.html
  */
-export function png_filter_unFilterSub(scanline: Uint8Array, scanline_offset: number, pixels: Uint8Array, bpp: number, offset: number, length: number): void;
+export function png_filter_unFilterSub(scanline: Uint8Array, scanline_offset: number, pixels: Uint8Array, bpp: number, offset: number, output_offset_previous: number, length: number): void;
 //# sourceMappingURL=png_filter_unFilterSub.d.ts.map

package/src/engine/asset/loaders/image/png/filter/png_filter_unFilterSub.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"png_filter_unFilterSub.d.ts","sourceRoot":"","sources":["../../../../../../../../src/engine/asset/loaders/image/png/filter/png_filter_unFilterSub.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,iDARW,UAAU,mBACV,MAAM,UACN,UAAU,OACV,MAAM,UACN,MAAM,UACN,MAAM,QAuBhB"}
+{"version":3,"file":"png_filter_unFilterSub.d.ts","sourceRoot":"","sources":["../../../../../../../../src/engine/asset/loaders/image/png/filter/png_filter_unFilterSub.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,iDATW,UAAU,mBACV,MAAM,UACN,UAAU,OACV,MAAM,UACN,MAAM,0BACN,MAAM,UACN,MAAM,QAwBhB"}

package/src/engine/asset/loaders/image/png/filter/png_filter_unFilterSub.js

@@ -8,6 +8,7 @@
  * @param {Uint8Array} pixels processed output
  * @param {number} bpp bytes-per-pixel
  * @param {number} offset
+ * @param {number} output_offset_previous unused by this filter
  * @param {number} length
  * @see https://www.w3.org/TR/PNG-Filters.html
  */
@@ -17,6 +18,7 @@ export function png_filter_unFilterSub(
     pixels,
     bpp,
     offset,
+    output_offset_previous,
     length
 ) {
 

package/src/engine/asset/loaders/image/png/filter/png_filter_unFilterUp.d.ts

@@ -7,10 +7,11 @@
  * @param {Uint8Array} scanline raw data
  * @param {number} scanline_offset
  * @param {Uint8Array} pixels processed output
+ * @param {number} bpp bytes-per-pixel, unused by this filter
  * @param {number} offset
  * @param {number} output_offset_previous pass a negative value when there is no previous scanline
  * @param {number} length
  * @see https://www.w3.org/TR/PNG-Filters.html
  */
-export function png_filter_unFilterUp(scanline: Uint8Array, scanline_offset: number, pixels: Uint8Array, offset: number, output_offset_previous: number, length: number): void;
+export function png_filter_unFilterUp(scanline: Uint8Array, scanline_offset: number, pixels: Uint8Array, bpp: number, offset: number, output_offset_previous: number, length: number): void;
 //# sourceMappingURL=png_filter_unFilterUp.d.ts.map

package/src/engine/asset/loaders/image/png/filter/png_filter_unFilterUp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"png_filter_unFilterUp.d.ts","sourceRoot":"","sources":["../../../../../../../../src/engine/asset/loaders/image/png/filter/png_filter_unFilterUp.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,gDARW,UAAU,mBACV,MAAM,UACN,UAAU,UACV,MAAM,0BACN,MAAM,UACN,MAAM,QAkChB"}
+{"version":3,"file":"png_filter_unFilterUp.d.ts","sourceRoot":"","sources":["../../../../../../../../src/engine/asset/loaders/image/png/filter/png_filter_unFilterUp.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,gDATW,UAAU,mBACV,MAAM,UACN,UAAU,OACV,MAAM,UACN,MAAM,0BACN,MAAM,UACN,MAAM,QAmChB"}

package/src/engine/asset/loaders/image/png/filter/png_filter_unFilterUp.js

@@ -7,6 +7,7 @@
  * @param {Uint8Array} scanline raw data
  * @param {number} scanline_offset
  * @param {Uint8Array} pixels processed output
+ * @param {number} bpp bytes-per-pixel, unused by this filter
  * @param {number} offset
  * @param {number} output_offset_previous pass a negative value when there is no previous scanline
  * @param {number} length
@@ -16,6 +17,7 @@ export function png_filter_unFilterUp(
     scanline,
     scanline_offset,
     pixels,
+    bpp,
     offset,
     output_offset_previous,
     length

package/src/engine/asset/loaders/image/png/filter/png_unfilter.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Reconstruct one filtered scanline.
+ *
+ * Operates on bytes throughout. At bit depths below eight the reconstructed bytes still hold
+ * several samples each, and {@link png_unpack_samples} separates them afterwards — which is what
+ * the specification means by filtering happening on the "corresponding byte" rather than on the
+ * sample.
+ *
+ * @param {number} filter_type `0 .. 4`
+ * @param {Uint8Array} data
+ * @param {number} scanline_address index of the first byte of the filtered scanline
+ * @param {Uint8Array} output
+ * @param {number} bytes_per_pixel the specification's `bpp`: whole bytes per pixel, at least one
+ * @param {number} output_offset where this scanline's reconstruction begins in `output`
+ * @param {number} output_offset_previous where the previous scanline's reconstruction begins;
+ *   negative when there is none
+ * @param {number} length number of bytes to reconstruct
+ *
+ * @see https://www.w3.org/TR/PNG-Filters.html
+ */
+export function png_unfilter(filter_type: number, data: Uint8Array, scanline_address: number, output: Uint8Array, bytes_per_pixel: number, output_offset: number, output_offset_previous: number, length: number): void;
+//# sourceMappingURL=png_unfilter.d.ts.map

package/src/engine/asset/loaders/image/png/filter/png_unfilter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"png_unfilter.d.ts","sourceRoot":"","sources":["../../../../../../../../src/engine/asset/loaders/image/png/filter/png_unfilter.js"],"names":[],"mappings":"AAwBA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,0CAZW,MAAM,QACN,UAAU,oBACV,MAAM,UACN,UAAU,mBACV,MAAM,iBACN,MAAM,0BACN,MAAM,UAEN,MAAM,QA2BhB"}

package/src/engine/asset/loaders/image/png/filter/png_unfilter.js

@@ -0,0 +1,68 @@
+import { assert } from "../../../../../../core/assert.js";
+import { png_filter_unFilterAverage } from "./png_filter_unFilterAverage.js";
+import { png_filter_unFilterNone } from "./png_filter_unFilterNone.js";
+import { png_filter_unFilterPaeth } from "./png_filter_unFilterPaeth.js";
+import { png_filter_unFilterSub } from "./png_filter_unFilterSub.js";
+import { png_filter_unFilterUp } from "./png_filter_unFilterUp.js";
+
+/**
+ * The five reconstruction filters, indexed by the filter type byte that precedes a scanline.
+ *
+ * They share one signature so this can be a table rather than a switch that assembles a different
+ * argument list per case; each filter ignores the arguments it has no use for.
+ *
+ * @type {ReadonlyArray<function(Uint8Array, number, Uint8Array, number, number, number, number): void>}
+ * @see https://www.w3.org/TR/PNG-Filters.html
+ */
+const PNG_UNFILTER = Object.freeze([
+    png_filter_unFilterNone,
+    png_filter_unFilterSub,
+    png_filter_unFilterUp,
+    png_filter_unFilterAverage,
+    png_filter_unFilterPaeth
+]);
+
+/**
+ * Reconstruct one filtered scanline.
+ *
+ * Operates on bytes throughout. At bit depths below eight the reconstructed bytes still hold
+ * several samples each, and {@link png_unpack_samples} separates them afterwards — which is what
+ * the specification means by filtering happening on the "corresponding byte" rather than on the
+ * sample.
+ *
+ * @param {number} filter_type `0 .. 4`
+ * @param {Uint8Array} data
+ * @param {number} scanline_address index of the first byte of the filtered scanline
+ * @param {Uint8Array} output
+ * @param {number} bytes_per_pixel the specification's `bpp`: whole bytes per pixel, at least one
+ * @param {number} output_offset where this scanline's reconstruction begins in `output`
+ * @param {number} output_offset_previous where the previous scanline's reconstruction begins;
+ *   negative when there is none
+ * @param {number} length number of bytes to reconstruct
+ *
+ * @see https://www.w3.org/TR/PNG-Filters.html
+ */
+export function png_unfilter(
+    filter_type,
+    data,
+    scanline_address,
+    output,
+    bytes_per_pixel,
+    output_offset,
+    output_offset_previous,
+    length
+) {
+    assert.isInteger(filter_type, 'filter_type');
+    assert.isNonNegativeInteger(scanline_address, 'scanline_address');
+    assert.isNonNegativeInteger(bytes_per_pixel, 'bytes_per_pixel');
+    assert.isNonNegativeInteger(output_offset, 'output_offset');
+    assert.isNonNegativeInteger(length, 'length');
+
+    const filter = PNG_UNFILTER[filter_type];
+
+    if (filter === undefined) {
+        throw new Error(`unknown filtered scanline type '${filter_type}'`);
+    }
+
+    filter(data, scanline_address, output, bytes_per_pixel, output_offset, output_offset_previous, length);
+}

package/src/engine/asset/loaders/image/png/png_inflate.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Inflate a zlib-framed stream that arrived as one or more chunks.
+ *
+ * PNG splits a single zlib stream across however many `IDAT` chunks the encoder felt like, so the
+ * multi-chunk form is the general one; a `zTXt` or `iTXt` payload is simply a stream of one.
+ *
+ * `lenient` abandons the adler32 check, which is the only thing that would otherwise notice a
+ * flipped bit inside the payload: a stream that needs the fallback may decode to wrong bytes rather
+ * than to an error. That trade is deliberate for image data — see the caller — and wrong for
+ * anything where a silently wrong answer is worse than none.
+ *
+ * @param {Uint8Array[]} chunks pieces of one zlib stream, in order
+ * @param {boolean} [lenient] accept a stream whose adler32 trailer does not check out
+ * @returns {Uint8Array}
+ * @throws {Error} if the deflate payload itself cannot be read
+ *
+ * @copyright Company Named Limited (c) 2026
+ */
+export function png_inflate(chunks: Uint8Array[], lenient?: boolean): Uint8Array;
+//# sourceMappingURL=png_inflate.d.ts.map

package/src/engine/asset/loaders/image/png/png_inflate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"png_inflate.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/asset/loaders/image/png/png_inflate.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AACH,oCAPW,UAAU,EAAE,YACZ,OAAO,GACL,UAAU,CAwCtB"}

package/src/engine/asset/loaders/image/png/png_inflate.js

@@ -0,0 +1,85 @@
+import zlib from "pako";
+
+/**
+ * Inflate a zlib-framed stream that arrived as one or more chunks.
+ *
+ * PNG splits a single zlib stream across however many `IDAT` chunks the encoder felt like, so the
+ * multi-chunk form is the general one; a `zTXt` or `iTXt` payload is simply a stream of one.
+ *
+ * `lenient` abandons the adler32 check, which is the only thing that would otherwise notice a
+ * flipped bit inside the payload: a stream that needs the fallback may decode to wrong bytes rather
+ * than to an error. That trade is deliberate for image data — see the caller — and wrong for
+ * anything where a silently wrong answer is worse than none.
+ *
+ * @param {Uint8Array[]} chunks pieces of one zlib stream, in order
+ * @param {boolean} [lenient] accept a stream whose adler32 trailer does not check out
+ * @returns {Uint8Array}
+ * @throws {Error} if the deflate payload itself cannot be read
+ *
+ * @copyright Company Named Limited (c) 2026
+ */
+export function png_inflate(chunks, lenient = false) {
+    const chunk_count = chunks.length;
+
+    // the framed form first: it verifies the adler32 trailer, which is the right behaviour for a
+    // spec-compliant stream
+    const inflator = new zlib.Inflate();
+
+    for (let i = 0; i < chunk_count; i++) {
+        inflator.push(chunks[i]);
+    }
+
+    if (inflator.err === 0) {
+        if (inflator.result === undefined) {
+            // pako reports no error but never saw the end of the stream, which means the chunks
+            // ran out mid-payload
+            throw new Error("truncated zlib stream: no end marker in the chunks supplied");
+        }
+
+        return inflator.result;
+    }
+
+    if (!lenient) {
+        throw new Error(`failed to inflate zlib stream: ${inflator.msg || inflator.err}`);
+    }
+
+    // Some real-world encoders emit streams with a corrupt adler32 trailer while the deflate
+    // payload itself is fine. Chrome and libpng accept those, so mirror that leniency: strip the
+    // two byte zlib header and inflate as raw deflate, which does not check the trailer.
+    try {
+        return zlib.inflateRaw(concatenate(chunks).subarray(2));
+    } catch (raw_error) {
+        // the deflate payload is broken too; report pako's original diagnosis rather than the
+        // fallback's, which only says that raw inflate of a non-raw stream failed
+        throw new Error(`failed to inflate zlib stream: ${inflator.msg || inflator.err}`);
+    }
+}
+
+/**
+ * @param {Uint8Array[]} chunks
+ * @returns {Uint8Array}
+ */
+function concatenate(chunks) {
+    const chunk_count = chunks.length;
+
+    if (chunk_count === 1) {
+        return chunks[0];
+    }
+
+    let total = 0;
+
+    for (let i = 0; i < chunk_count; i++) {
+        total += chunks[i].length;
+    }
+
+    const result = new Uint8Array(total);
+
+    let offset = 0;
+
+    for (let i = 0; i < chunk_count; i++) {
+        result.set(chunks[i], offset);
+        offset += chunks[i].length;
+    }
+
+    return result;
+}

package/src/engine/asset/loaders/image/png/png_unpack_samples.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Expand samples packed several to a byte into one byte each.
+ *
+ * PNG codes bit depths of 1, 2 and 4 by packing samples into bytes, most significant bits first,
+ * with each scanline starting on a byte boundary. Filtering happens before this, on the packed
+ * bytes; everything downstream — the palette lookup, the sampler the loader builds — wants one
+ * byte per sample.
+ *
+ * Values come out as the depth coded them, not scaled to `0 .. 255`: a palette index has to stay
+ * an index, and rescaling a greyscale sample is a display decision rather than a decoding one.
+ *
+ * @param {Uint8Array} source packed bytes
+ * @param {number} source_offset index of the byte holding the first sample
+ * @param {number} bit_depth `1`, `2` or `4`
+ * @param {number} sample_count number of samples to unpack
+ * @param {Uint8Array} destination
+ * @param {number} destination_offset
+ *
+ * @see https://www.w3.org/TR/2003/REC-PNG-20031110/#7Scanline
+ */
+export function png_unpack_samples(source: Uint8Array, source_offset: number, bit_depth: number, sample_count: number, destination: Uint8Array, destination_offset: number): void;
+//# sourceMappingURL=png_unpack_samples.d.ts.map

package/src/engine/asset/loaders/image/png/png_unpack_samples.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"png_unpack_samples.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/asset/loaders/image/png/png_unpack_samples.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,2CATW,UAAU,iBACV,MAAM,aACN,MAAM,gBACN,MAAM,eACN,UAAU,sBACV,MAAM,QAqBhB"}

package/src/engine/asset/loaders/image/png/png_unpack_samples.js

@@ -0,0 +1,38 @@
+/**
+ * Expand samples packed several to a byte into one byte each.
+ *
+ * PNG codes bit depths of 1, 2 and 4 by packing samples into bytes, most significant bits first,
+ * with each scanline starting on a byte boundary. Filtering happens before this, on the packed
+ * bytes; everything downstream — the palette lookup, the sampler the loader builds — wants one
+ * byte per sample.
+ *
+ * Values come out as the depth coded them, not scaled to `0 .. 255`: a palette index has to stay
+ * an index, and rescaling a greyscale sample is a display decision rather than a decoding one.
+ *
+ * @param {Uint8Array} source packed bytes
+ * @param {number} source_offset index of the byte holding the first sample
+ * @param {number} bit_depth `1`, `2` or `4`
+ * @param {number} sample_count number of samples to unpack
+ * @param {Uint8Array} destination
+ * @param {number} destination_offset
+ *
+ * @see https://www.w3.org/TR/2003/REC-PNG-20031110/#7Scanline
+ */
+export function png_unpack_samples(source, source_offset, bit_depth, sample_count, destination, destination_offset) {
+    if (bit_depth !== 1 && bit_depth !== 2 && bit_depth !== 4) {
+        throw new Error(`only bit depths below 8 are packed, got ${bit_depth}`);
+    }
+
+    const mask = (1 << bit_depth) - 1;
+
+    for (let i = 0; i < sample_count; i++) {
+        const bit = i * bit_depth;
+
+        const byte = source[source_offset + (bit >> 3)];
+
+        // most significant bits first, so the first sample in a byte sits at the top of it
+        const shift = 8 - bit_depth - (bit & 7);
+
+        destination[destination_offset + i] = (byte >>> shift) & mask;
+    }
+}

package/src/engine/graphics/ecs/sprite/SpriteSystemPE.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SpriteSystemPE.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/sprite/SpriteSystemPE.js"],"names":[],"mappings":"AA6HA;IAGI,cAEC;IAJD,mDAAmC;CAKtC;sCAhIqC,8CAA8C;0BAE1D,qCAAqC;uBAQxC,aAAa"}
+{"version":3,"file":"SpriteSystemPE.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/sprite/SpriteSystemPE.js"],"names":[],"mappings":"AAgIA;IAGI,cAEC;IAJD,mDAAmC;CAKtC;sCAnIqC,8CAA8C;0BAE1D,qCAAqC;uBAQxC,aAAa"}