@woosh/meep-engine 3.18.0 → 3.19.0

package/src/format/image/png/PNGReader.d.ts

@@ -49,9 +49,9 @@ export class PNGReader {
      * chunk  =  length bytes
      * crc    =  4      bytes
      *
-     * @returns {string} chunk type
+     * @returns {Promise<string>} chunk type, after any compressed metadata has been decoded
      */
-    decodeChunk(): string;
+    decodeChunk(): Promise<string>;
     /**
      * https://www.w3.org/TR/2003/REC-PNG-20031110/#11sRGB
      * @param {Uint8Array} chunk
@@ -107,8 +107,9 @@ export class PNGReader {
     decodeIEND(): void;
     /**
      * Uncompress IDAT chunks
+     * @returns {Promise<void>}
      */
-    decodePixels(): void;
+    decodePixels(): Promise<void>;
     /**
      * Reconstruct a non-interlaced image.
      *
@@ -148,10 +149,10 @@ export class PNGReader {
      */
     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;
     /**
-     * Parse the PNG file
-     * @returns {PNG}
+     * Parse the PNG file. Keep this reader and its input buffer unchanged until the promise settles.
+     * @returns {Promise<PNG>}
      */
-    parse(): PNG;
+    parse(): Promise<PNG>;
 }
 import { PNG } from './PNG.js';
 import { BinaryBuffer } from "../../../core/binary/BinaryBuffer.js";

package/src/format/image/png/PNGReader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PNGReader.d.ts","sourceRoot":"","sources":["../../../../../src/format/image/png/PNGReader.js"],"names":[],"mappings":"AAyCA;;;;GAIG;AACH,iCAHW,WAAW,QAgCrB;;IAlCD;;;;OAIG;IACH,mBAHW,WAAW,EAgCrB;IA5BG;;;OAGG;IACH,KAFU,GAAG,CAEO;IAEpB;;;OAGG;IACH,YAFU,UAAU,EAAE,CAEF;IAEpB;;;OAGG;IACH,QAFU,YAAY,CAEU;IAOhC;;;OAGG;IACH,aAFU,OAAO,CAEO;IAG5B;;;;OAIG;IACH,kBAHW,MAAM,GACL,UAAU,CAarB;IAED;;OAEG;IACH,qBAcC;IAED;;;;;;;;;OASG;IACH,eAFa,MAAM,CA4ElB;IAGD;;;OAGG;IACH,kBAFW,UAAU,QAOpB;IAED;;;OAGG;IACH,kBAFW,UAAU,QAapB;IAED;;;OAGG;IACH,kBAFW,UAAU,QASpB;IACD;;;;OAIG;IACH,kBAFW,UAAU,QAwBpB;IAED;;;;;;;;;;;OAWG;IACH,6BAWC;IAED;;;;OAIG;IACH,kBAFW,UAAU,QAIpB;IAED;;OAEG;IACH,6BAGC;IAED;;;OAGG;IACH,kBAFW,UAAU,QAIpB;IAED;;OAEG;IACH,mBACC;IAED;;OAEG;IACH,qBA0BC;IAID;;;;;;;;;OASG;IACH,oBAHW,UAAU,GACR,UAAU,CAkDtB;IAsDD;;;;;;;;;OASG;IACH,qBAHW,UAAU,GACR,UAAU,CAgHtB;IAID;;;;;;;;;;;;;;OAcG;IACH,sBAXW,MAAM,QACN,UAAU,oBACV,MAAM,UACN,UAAU,mBACV,MAAM,iBACN,MAAM,0BACN,MAAM,UACN,MAAM,QAwBhB;IAED;;;OAGG;IACH,SAFa,GAAG,CAqBf;;oBAjoBmB,UAAU;6BAXD,sCAAsC"}
+{"version":3,"file":"PNGReader.d.ts","sourceRoot":"","sources":["../../../../../src/format/image/png/PNGReader.js"],"names":[],"mappings":"AAyCA;;;;GAIG;AACH,iCAHW,WAAW,QAgCrB;;IAlCD;;;;OAIG;IACH,mBAHW,WAAW,EAgCrB;IA5BG;;;OAGG;IACH,KAFU,GAAG,CAEO;IAEpB;;;OAGG;IACH,YAFU,UAAU,EAAE,CAEF;IAEpB;;;OAGG;IACH,QAFU,YAAY,CAEU;IAOhC;;;OAGG;IACH,aAFU,OAAO,CAEO;IAG5B;;;;OAIG;IACH,kBAHW,MAAM,GACL,UAAU,CAarB;IAED;;OAEG;IACH,qBAcC;IAED;;;;;;;;;OASG;IACH,eAFa,QAAQ,MAAM,CAAC,CA4E3B;IAGD;;;OAGG;IACH,kBAFW,UAAU,QAOpB;IAED;;;OAGG;IACH,kBAFW,UAAU,QAapB;IAED;;;OAGG;IACH,kBAFW,UAAU,QASpB;IACD;;;;OAIG;IACH,kBAFW,UAAU,QAwBpB;IAED;;;;;;;;;;;OAWG;IACH,6BAWC;IAED;;;;OAIG;IACH,kBAFW,UAAU,QAIpB;IAED;;OAEG;IACH,6BAGC;IAED;;;OAGG;IACH,kBAFW,UAAU,QAIpB;IAED;;OAEG;IACH,mBACC;IAED;;;OAGG;IACH,gBAFa,QAAQ,IAAI,CAAC,CA4BzB;IAID;;;;;;;;;OASG;IACH,oBAHW,UAAU,GACR,UAAU,CAkDtB;IAsDD;;;;;;;;;OASG;IACH,qBAHW,UAAU,GACR,UAAU,CAgHtB;IAID;;;;;;;;;;;;;;OAcG;IACH,sBAXW,MAAM,QACN,UAAU,oBACV,MAAM,UACN,UAAU,mBACV,MAAM,iBACN,MAAM,0BACN,MAAM,UACN,MAAM,QAwBhB;IAED;;;OAGG;IACH,SAFa,QAAQ,GAAG,CAAC,CAqBxB;;oBAloBmB,UAAU;6BAXD,sCAAsC"}

package/src/format/image/png/PNGReader.js

@@ -120,9 +120,9 @@ PNGReader.prototype.decodeHeader = function () {
  * chunk  =  length bytes
  * crc    =  4      bytes
  *
- * @returns {string} chunk type
+ * @returns {Promise<string>} chunk type, after any compressed metadata has been decoded
  */
-PNGReader.prototype.decodeChunk = function () {
+PNGReader.prototype.decodeChunk = async function () {
 
     const buffer = this.buffer;
 
@@ -183,10 +183,10 @@ PNGReader.prototype.decodeChunk = function () {
             this.decodetIME(chunk);
             break;
         case 'zTXt':
-            png_chunk_decode_zTXt(chunk);
+            await png_chunk_decode_zTXt(chunk);
             break;
         case 'iTXt':
-            png_chunk_decode_iTXt(chunk);
+            await png_chunk_decode_iTXt(chunk);
             break;
         default:
             // skip unknown block
@@ -325,15 +325,16 @@ PNGReader.prototype.decodeIEND = function () {
 };
 
 /**
- * Uncompress IDAT chunks
+ * Uncompress IDAT chunks
+ * @returns {Promise<void>}
  */
-PNGReader.prototype.decodePixels = function () {
+PNGReader.prototype.decodePixels = async function () {
     const png = this.png;
 
     // leniently: a corrupt adler32 trailer over a sound deflate payload is common enough in the
     // wild that Chrome and libpng both accept it, and a texture that refuses to load is worse than
     // one whose checksum nobody reads
-    const decompressed_data = png_inflate(this.dataChunks, true);
+    const decompressed_data = await png_inflate(this.dataChunks, true);
 
     // https://www.w3.org/TR/png-3/#8InterlaceMethods
     if (png.getInterlaceMethod() === 0) {
@@ -631,16 +632,16 @@ PNGReader.prototype.unFilter = function (
 }
 
 /**
- * Parse the PNG file
- * @returns {PNG}
+ * Parse the PNG file. Keep this reader and its input buffer unchanged until the promise settles.
+ * @returns {Promise<PNG>}
  */
-PNGReader.prototype.parse = function () {
+PNGReader.prototype.parse = async function () {
 
     this.decodeHeader();
 
     for (; ;) {
 
-        const type = this.decodeChunk();
+        const type = await this.decodeChunk();
 
         if (type === 'IEND') {
             // reached the end
@@ -649,7 +650,7 @@ PNGReader.prototype.parse = function () {
 
     }
 
-    this.decodePixels();
+    await this.decodePixels();
 
     return this.png;
 

package/src/format/image/png/chunk/png_chunk_decode_iTXt.d.ts

@@ -2,11 +2,12 @@
  * International textual data
  * @see https://www.w3.org/TR/2003/REC-PNG-20031110/
  * @param {Uint8Array} chunk
+ * @returns {Promise<{keyword: string, language_tag: string, translated_keyword: string, text: string}>}
  */
-export function png_chunk_decode_iTXt(chunk: Uint8Array): {
+export function png_chunk_decode_iTXt(chunk: Uint8Array): Promise<{
     keyword: string;
     language_tag: string;
     translated_keyword: string;
     text: string;
-};
+}>;
 //# sourceMappingURL=png_chunk_decode_iTXt.d.ts.map

package/src/format/image/png/chunk/png_chunk_decode_iTXt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"png_chunk_decode_iTXt.d.ts","sourceRoot":"","sources":["../../../../../../src/format/image/png/chunk/png_chunk_decode_iTXt.js"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,6CAFW,UAAU;;;;;EA8CpB"}
+{"version":3,"file":"png_chunk_decode_iTXt.d.ts","sourceRoot":"","sources":["../../../../../../src/format/image/png/chunk/png_chunk_decode_iTXt.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,6CAHW,UAAU;aACU,MAAM;kBAAgB,MAAM;wBAAsB,MAAM;UAAQ,MAAM;GA8CpG"}

package/src/format/image/png/chunk/png_chunk_decode_iTXt.js

@@ -4,9 +4,10 @@ import { png_inflate } from "../png_inflate.js";
 /**
  * International textual data
  * @see https://www.w3.org/TR/2003/REC-PNG-20031110/
- * @param {Uint8Array} chunk
+ * @param {Uint8Array} chunk
+ * @returns {Promise<{keyword: string, language_tag: string, translated_keyword: string, text: string}>}
  */
-export function png_chunk_decode_iTXt(chunk) {
+export async function png_chunk_decode_iTXt(chunk) {
     const chunk_size = chunk.byteLength;
     const chunk_buffer = chunk.buffer;
     const chunk_byte_offset = chunk.byteOffset;
@@ -35,7 +36,7 @@ export function png_chunk_decode_iTXt(chunk) {
             throw new Error('only compression_method 0 is supported');
         }
 
-        const decoded = png_inflate([new Uint8Array(buffer.data, buffer.position, remaining_bytes)]);
+        const decoded = await png_inflate([new Uint8Array(buffer.data, buffer.position, remaining_bytes)]);
 
         buffer.fromArrayBuffer(decoded.buffer);
 
@@ -50,4 +51,4 @@ export function png_chunk_decode_iTXt(chunk) {
         translated_keyword,
         text
     }
-}
+}

package/src/format/image/png/chunk/png_chunk_decode_zTXt.d.ts

@@ -2,9 +2,10 @@
  * Compressed textual data
  * @see https://www.w3.org/TR/2003/REC-PNG-20031110/#11zTXt
  * @param {Uint8Array} chunk
+ * @returns {Promise<{keyword: string, text: string}>}
  */
-export function png_chunk_decode_zTXt(chunk: Uint8Array): {
+export function png_chunk_decode_zTXt(chunk: Uint8Array): Promise<{
     keyword: string;
     text: string;
-};
+}>;
 //# sourceMappingURL=png_chunk_decode_zTXt.d.ts.map

package/src/format/image/png/chunk/png_chunk_decode_zTXt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"png_chunk_decode_zTXt.d.ts","sourceRoot":"","sources":["../../../../../../src/format/image/png/chunk/png_chunk_decode_zTXt.js"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,6CAFW,UAAU;;;EAmCpB"}
+{"version":3,"file":"png_chunk_decode_zTXt.d.ts","sourceRoot":"","sources":["../../../../../../src/format/image/png/chunk/png_chunk_decode_zTXt.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,6CAHW,UAAU;aACU,MAAM;UAAQ,MAAM;GAmClD"}

package/src/format/image/png/chunk/png_chunk_decode_zTXt.js

@@ -4,9 +4,10 @@ import { png_inflate } from "../png_inflate.js";
 /**
  * Compressed textual data
  * @see https://www.w3.org/TR/2003/REC-PNG-20031110/#11zTXt
- * @param {Uint8Array} chunk
+ * @param {Uint8Array} chunk
+ * @returns {Promise<{keyword: string, text: string}>}
  */
-export function png_chunk_decode_zTXt(chunk) {
+export async function png_chunk_decode_zTXt(chunk) {
     const chunk_size = chunk.byteLength;
     const chunk_buffer = chunk.buffer;
     const chunk_byte_offset = chunk.byteOffset;
@@ -26,7 +27,7 @@ export function png_chunk_decode_zTXt(chunk) {
         const local_offset = buffer.position - chunk_byte_offset;
         const encoded_chunk = new Uint8Array(chunk_buffer, buffer.position, chunk_size  - local_offset);
 
-        const decompressed_data = png_inflate([encoded_chunk]);
+        const decompressed_data = await png_inflate([encoded_chunk]);
 
         buffer.fromArrayBuffer(decompressed_data.buffer);
 
@@ -39,4 +40,4 @@ export function png_chunk_decode_zTXt(chunk) {
         keyword: keyword,
         text: value
     }
-}
+}

package/src/format/image/png/png_inflate.d.ts

@@ -9,12 +9,12 @@
  * 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 {Uint8Array[]} chunks pieces of one zlib stream, in order; keep unchanged until completion
  * @param {boolean} [lenient] accept a stream whose adler32 trailer does not check out
- * @returns {Uint8Array}
+ * @returns {Promise<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;
+export function png_inflate(chunks: Uint8Array[], lenient?: boolean): Promise<Uint8Array>;
 //# sourceMappingURL=png_inflate.d.ts.map

package/src/format/image/png/png_inflate.d.ts.map

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

package/src/format/image/png/png_inflate.js

@@ -1,4 +1,4 @@
-import zlib from "pako";
+import { decompress_bytes } from "../../../core/binary/compression/decompress_bytes.js";
 
 /**
  * Inflate a zlib-framed stream that arrived as one or more chunks.
@@ -11,49 +11,39 @@ import zlib from "pako";
  * 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 {Uint8Array[]} chunks pieces of one zlib stream, in order; keep unchanged until completion
  * @param {boolean} [lenient] accept a stream whose adler32 trailer does not check out
- * @returns {Uint8Array}
+ * @returns {Promise<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}`);
-    }
-}
+export async function png_inflate(chunks, lenient = false) {
+    try {
+        return await decompress_bytes(chunks);
+    } catch (error) {
+        if (lenient) {
+            const bytes = concatenate(chunks);
+
+            // Only abandon the checksum of a zlib-framed stream. PNG forbids a preset dictionary.
+            // Native raw deflate rejects trailing bytes, so remove the four-byte Adler32 as well
+            // as the two-byte header. A missing trailer or broken payload must still reject.
+            const cmf = bytes[0];
+            const flg = bytes[1];
+
+            if (bytes.length >= 6 && (cmf & 0x0f) === 8 && (cmf >>> 4) <= 7
+                && ((cmf << 8) | flg) % 31 === 0 && (flg & 0x20) === 0) {
+                try {
+                    return await decompress_bytes([bytes.subarray(2, bytes.length - 4)], "deflate-raw");
+                } catch {
+                    // Keep the framed stream's diagnosis if the raw payload also failed.
+                }
+            }
+        }
+
+        throw new Error(`failed to inflate zlib stream: ${error?.message || "invalid or truncated data"}`);
+    }
+}
 
 /**
  * @param {Uint8Array[]} chunks

package/src/format/texture/ktx2/ktx2_read.d.ts

@@ -25,7 +25,7 @@
  * what to do with them to the caller: the engine's adapter refuses what its texture type cannot yet
  * hold, and a reader that refused for it would be refusing well-formed files on another tier's behalf.
  *
- * Any of them may be wrapped: {@link SupercompressionScheme.ZLIB} is undone by `pako` and
+ * Any of them may be wrapped: {@link SupercompressionScheme.ZLIB} is undone by `DecompressionStream` and
  * {@link SupercompressionScheme.Zstandard} by {@link zstd_decompress}. Wrapping is a property of the
  * file rather than of the payload, so it is undone before anything looks at what is inside.
  *
@@ -69,7 +69,7 @@
  * is the overwhelming majority of a texture file, and copying it to hand it to `writeTexture` would
  * double the peak memory of every texture load for nothing.
  *
- * @param {ArrayBuffer|Uint8Array} bytes the whole file
+ * @param {ArrayBuffer|Uint8Array} bytes the whole file; keep unchanged until the promise settles
  * @param {TextureFormat|TextureFormat[]} [transcode_target] what a Basis payload should be
  * transcoded into. Required for such a file and ignored for every other; see above for why it is not
  * defaulted.
@@ -79,7 +79,7 @@
  * a caller that names a single three-channel format for a payload that turns out to have alpha gets a
  * refusal where it could have got its second choice. Given the list, this passes over the targets that
  * cannot hold what the file contains and takes the first that can
- * @returns {TexelPayload}
+ * @returns {Promise<TexelPayload>}
  * @throws {Error} naming the feature, for a file this reader does not read; naming the field, for a
  * file that is truncated or self-inconsistent
  *
@@ -87,7 +87,7 @@
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
-export function ktx2_read(bytes: ArrayBuffer | Uint8Array, transcode_target?: TextureFormat | TextureFormat[]): TexelPayload;
+export function ktx2_read(bytes: ArrayBuffer | Uint8Array, transcode_target?: TextureFormat | TextureFormat[]): Promise<TexelPayload>;
 export type Ktx2LevelIndexEntry = {
     /**
      * where this level's bytes are, from the start of the file

package/src/format/texture/ktx2/ktx2_read.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ktx2_read.d.ts","sourceRoot":"","sources":["../../../../../src/format/texture/ktx2/ktx2_read.js"],"names":[],"mappings":"AAwEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwFG;AACH,iCAlBW,WAAW,GAAC,UAAU,qBACtB,gBAAc,eAAe,GAS3B,YAAY,CAgLxB;;;;;iBAgda,MAAM;;;;iBACN,MAAM;;;;8BACN,MAAM"}
+{"version":3,"file":"ktx2_read.d.ts","sourceRoot":"","sources":["../../../../../src/format/texture/ktx2/ktx2_read.js"],"names":[],"mappings":"AAwEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwFG;AACH,iCAlBW,WAAW,GAAC,UAAU,qBACtB,gBAAc,eAAe,GAS3B,QAAQ,YAAY,CAAC,CAoLjC;;;;;iBAgda,MAAM;;;;iBACN,MAAM;;;;8BACN,MAAM"}

package/src/format/texture/ktx2/ktx2_read.js

@@ -1,4 +1,4 @@
-import pako from "pako";
+import { decompress_bytes } from "../../../core/binary/compression/decompress_bytes.js";
 import { assert } from "../../../core/assert.js";
 import { ByteCursor } from "../../../core/binary/ByteCursor.js";
 import { align_4 } from "../../../core/binary/align_4.js";
@@ -97,7 +97,7 @@ const SUPPORTED_ORIENTATION = "rdi";
  * what to do with them to the caller: the engine's adapter refuses what its texture type cannot yet
  * hold, and a reader that refused for it would be refusing well-formed files on another tier's behalf.
  *
- * Any of them may be wrapped: {@link SupercompressionScheme.ZLIB} is undone by `pako` and
+ * Any of them may be wrapped: {@link SupercompressionScheme.ZLIB} is undone by `DecompressionStream` and
  * {@link SupercompressionScheme.Zstandard} by {@link zstd_decompress}. Wrapping is a property of the
  * file rather than of the payload, so it is undone before anything looks at what is inside.
  *
@@ -141,7 +141,7 @@ const SUPPORTED_ORIENTATION = "rdi";
  * is the overwhelming majority of a texture file, and copying it to hand it to `writeTexture` would
  * double the peak memory of every texture load for nothing.
  *
- * @param {ArrayBuffer|Uint8Array} bytes the whole file
+ * @param {ArrayBuffer|Uint8Array} bytes the whole file; keep unchanged until the promise settles
  * @param {TextureFormat|TextureFormat[]} [transcode_target] what a Basis payload should be
  * transcoded into. Required for such a file and ignored for every other; see above for why it is not
  * defaulted.
@@ -151,7 +151,7 @@ const SUPPORTED_ORIENTATION = "rdi";
  * a caller that names a single three-channel format for a payload that turns out to have alpha gets a
  * refusal where it could have got its second choice. Given the list, this passes over the targets that
  * cannot hold what the file contains and takes the first that can
- * @returns {TexelPayload}
+ * @returns {Promise<TexelPayload>}
  * @throws {Error} naming the feature, for a file this reader does not read; naming the field, for a
  * file that is truncated or self-inconsistent
  *
@@ -159,7 +159,7 @@ const SUPPORTED_ORIENTATION = "rdi";
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
-export function ktx2_read(bytes, transcode_target = undefined) {
+export async function ktx2_read(bytes, transcode_target = undefined) {
     assert.defined(bytes, 'bytes');
     assert.notNull(bytes, 'bytes');
 
@@ -266,9 +266,13 @@ export function ktx2_read(bytes, transcode_target = undefined) {
 
     const level_index = read_level_index(cursor, Math.max(level_count, 1));
 
-    const levels = level_index.map(
-        (entry, level) => read_level(cursor, entry, level, supercompression_scheme)
-    );
+    const levels = [];
+
+    // Keep cursor access and decompression sequential, preserving level order and avoiding
+    // simultaneous inflation of every mip. Unwrapped levels still refer directly to the input.
+    for (let level = 0; level < level_index.length; level++) {
+        levels.push(await read_level(cursor, level_index[level], level, supercompression_scheme));
+    }
 
     if (uastc) {
         /*
@@ -825,11 +829,11 @@ function read_level_index(cursor, entry_count) {
  * @param {Ktx2LevelIndexEntry} entry
  * @param {number} level `0` is the base
  * @param {SupercompressionScheme|number} scheme already known to be one of the two supported ones
- * @returns {Uint8Array} a view onto the file where the scheme is `None`, its own memory otherwise
+ * @returns {Promise<Uint8Array>} a view onto the file where the scheme is `None`, its own memory otherwise
  * @throws {Error} naming the level, for one that runs past the end of the file or inflates to the
  * wrong size
  */
-function read_level(cursor, entry, level, scheme) {
+async function read_level(cursor, entry, level, scheme) {
     const { byte_offset, byte_length, uncompressed_byte_length } = entry;
 
     /*
@@ -863,15 +867,8 @@ function read_level(cursor, entry, level, scheme) {
     }
 
     /*
-     `pako.inflate` rather than `png_inflate`: what that function adds over this call is PNG's two
-     peculiarities — a stream split across IDAT chunks, and a fallback that abandons the adler32
-     check because real encoders get it wrong. A KTX2 level is one stream, and a texture payload
-     whose checksum fails should fail rather than decode to blocks nobody verified.
-
-     What it also adds, and what this has to do for itself: **pako throws a bare string.** Not an
-     Error — `"incorrect header check"`, with no stack, no `.message`, and nothing saying which file
-     or which level it came from. Letting that escape would make the one path this reader adds beyond
-     the plan the one path that does not refuse by name.
+     KTX2 requires a strict zlib stream: PNG's lenient checksum fallback does not apply here.
+     Await decompression inside the try/catch so native stream failures retain the level context.
     */
     let inflated;
 
@@ -891,10 +888,10 @@ function read_level(cursor, entry, level, scheme) {
         }
     } else {
         try {
-            inflated = pako.inflate(stored);
+            inflated = await decompress_bytes([stored]);
         } catch (error) {
             throw new Error(
-                `KTX2: level ${level} is not a readable zlib stream: ${error?.message ?? error}`
+                `KTX2: level ${level} is not a readable zlib stream: ${error?.message || "invalid or truncated data"}`
             );
         }
     }