iso2x-wasm 0.1.0

package/dist/attach.d.ts

@@ -0,0 +1,10 @@
+import type { SourceOptions, SourcePart, SourceReadFn } from './types.js';
+/**
+ * Builds a bootable "default.xbe" attach stub for an OGX (original Xbox)
+ * source.
+ *
+ * Throws if `source` resolves to a GoD (Xbox 360 / XEX) source - this
+ * only makes sense for OGX, and the wasm side enforces that regardless
+ * of what the UI does.
+ */
+export declare function generateAttachXbe(readFn: SourceReadFn, fileSize: number, source: SourceOptions, sourceParts?: SourcePart[]): Uint8Array;

package/dist/attach.js

@@ -0,0 +1,12 @@
+import { generateAttachXbe as rawGenerateAttachXbe } from './wasm/iso2x_wasm.js';
+/**
+ * Builds a bootable "default.xbe" attach stub for an OGX (original Xbox)
+ * source.
+ *
+ * Throws if `source` resolves to a GoD (Xbox 360 / XEX) source - this
+ * only makes sense for OGX, and the wasm side enforces that regardless
+ * of what the UI does.
+ */
+export function generateAttachXbe(readFn, fileSize, source, sourceParts) {
+    return rawGenerateAttachXbe(readFn, fileSize, source, sourceParts);
+}

package/dist/constants.d.ts

@@ -0,0 +1,53 @@
+import type { IsoRootOffsetCandidate } from './types.js';
+export declare function mhtSize(): number;
+export declare function cisoSectorSize(): number;
+export declare function cisoSizingBatchSectors(): number;
+export declare function cciSectorSize(): number;
+/**
+ * Sectors processed per `hashNextPart()` call while sizing 'cci' output -
+ * same role as `cisoSizingBatchSectors()`, kept separate since the two
+ * formats' sizing loops are independent and their batch sizes aren't
+ * guaranteed to match.
+ */
+export declare function cciSizingBatchSectors(): number;
+/**
+ * Threshold (0xffbf6000, ~4.29 GB) at which ciso output splits across
+ * "name.1.cso", "name.2.cso", etc.
+ */
+export declare function cisoFileSplitPoint(): number;
+/**
+ * Byte modulus (0x400) every ciso split part's on-disk size is padded up
+ * to.
+ */
+export declare function cisoFilePaddingModulus(): number;
+/**
+ * Threshold (0xFF000000, ~4.28 GB) at which cci output splits across
+ * "name.1.cci", "name.2.cci", etc., once a part's output crosses it.
+ * Unlike ciso, each cci part is fully self-contained - its own header and
+ * index - rather than sharing one index in part 1.
+ */
+export declare function cciFileSplitPoint(): number;
+/**
+ * Threshold (0xFF000000, ~4.28 GB) at which xiso output splits across
+ * "name.1.xiso.iso", "name.2.xiso.iso", etc., when the `split` option is
+ * enabled. Numerically the same boundary as `cciFileSplitPoint()` - both
+ * are chosen to keep each part under the ~4 GiB FATX/FAT32 single-file
+ * limit - but xiso applies it to a raw sector stream with no per-part
+ * header, unlike cci's self-contained parts.
+ */
+export declare function xisoSplitMargin(): number;
+/**
+ * The fixed set of root_offset values probed when detecting where the
+ * XDVDFS volume starts within a file, returned in the order they're
+ * checked. Shared by 'xiso', 'god', and 'extracted' detection - not an
+ * arbitrary or sector-by-sector scan, only these candidates are ever
+ * tried. Exposed so tests/tooling needing a real, detectable nonzero
+ * offset can pull one from here instead of hardcoding the magic number.
+ */
+export declare function isoRootOffsetCandidates(): IsoRootOffsetCandidate[];
+/**
+ * Uncompressed size of one ZAR data block (`_ZARCHIVE::COMPRESSED_BLOCK_SIZE`
+ * in the reference implementation) - every block of a ZAR archive's input
+ * data is compressed independently at this size.
+ */
+export declare function zarBlockSize(): number;

package/dist/constants.js

@@ -0,0 +1,75 @@
+import { mhtSize as rawMhtSize, cisoSectorSize as rawCisoSectorSize, cciSectorSize as rawCciSectorSize, cisoSizingBatchSectors as rawCisoSizingBatchSectors, cciSizingBatchSectors as rawCciSizingBatchSectors, cisoFileSplitPoint as rawCisoFileSplitPoint, cciFileSplitPoint as rawCciFileSplitPoint, cisoFilePaddingModulus as rawCisoFilePaddingModulus, xisoSplitMargin as rawXisoSplitMargin, isoRootOffsetCandidates as rawIsoRootOffsetCandidates, zarBlockSize as rawZarBlockSize, } from './wasm/iso2x_wasm.js';
+export function mhtSize() {
+    return rawMhtSize();
+}
+export function cisoSectorSize() {
+    return rawCisoSectorSize();
+}
+export function cisoSizingBatchSectors() {
+    return rawCisoSizingBatchSectors();
+}
+export function cciSectorSize() {
+    return rawCciSectorSize();
+}
+/**
+ * Sectors processed per `hashNextPart()` call while sizing 'cci' output -
+ * same role as `cisoSizingBatchSectors()`, kept separate since the two
+ * formats' sizing loops are independent and their batch sizes aren't
+ * guaranteed to match.
+ */
+export function cciSizingBatchSectors() {
+    return rawCciSizingBatchSectors();
+}
+/**
+ * Threshold (0xffbf6000, ~4.29 GB) at which ciso output splits across
+ * "name.1.cso", "name.2.cso", etc.
+ */
+export function cisoFileSplitPoint() {
+    return rawCisoFileSplitPoint();
+}
+/**
+ * Byte modulus (0x400) every ciso split part's on-disk size is padded up
+ * to.
+ */
+export function cisoFilePaddingModulus() {
+    return rawCisoFilePaddingModulus();
+}
+/**
+ * Threshold (0xFF000000, ~4.28 GB) at which cci output splits across
+ * "name.1.cci", "name.2.cci", etc., once a part's output crosses it.
+ * Unlike ciso, each cci part is fully self-contained - its own header and
+ * index - rather than sharing one index in part 1.
+ */
+export function cciFileSplitPoint() {
+    return rawCciFileSplitPoint();
+}
+/**
+ * Threshold (0xFF000000, ~4.28 GB) at which xiso output splits across
+ * "name.1.xiso.iso", "name.2.xiso.iso", etc., when the `split` option is
+ * enabled. Numerically the same boundary as `cciFileSplitPoint()` - both
+ * are chosen to keep each part under the ~4 GiB FATX/FAT32 single-file
+ * limit - but xiso applies it to a raw sector stream with no per-part
+ * header, unlike cci's self-contained parts.
+ */
+export function xisoSplitMargin() {
+    return rawXisoSplitMargin();
+}
+/**
+ * The fixed set of root_offset values probed when detecting where the
+ * XDVDFS volume starts within a file, returned in the order they're
+ * checked. Shared by 'xiso', 'god', and 'extracted' detection - not an
+ * arbitrary or sector-by-sector scan, only these candidates are ever
+ * tried. Exposed so tests/tooling needing a real, detectable nonzero
+ * offset can pull one from here instead of hardcoding the magic number.
+ */
+export function isoRootOffsetCandidates() {
+    return rawIsoRootOffsetCandidates();
+}
+/**
+ * Uncompressed size of one ZAR data block (`_ZARCHIVE::COMPRESSED_BLOCK_SIZE`
+ * in the reference implementation) - every block of a ZAR archive's input
+ * data is compressed independently at this size.
+ */
+export function zarBlockSize() {
+    return rawZarBlockSize();
+}

package/dist/detect.d.ts

@@ -0,0 +1,53 @@
+import type { ConversionFormat, ResolvedSource, SourcePart, SourceReadFn, SplitCciResult, SplitXisoResult } from './types.js';
+/**
+ * Single dropped file: cheap magic-byte detection (xiso/ciso/cci). Reads
+ * only the first 4 bytes via `readFn`, so it's safe to call speculatively
+ * on every file drop.
+ */
+export declare function detectFormat(readFn: SourceReadFn, fileSize: number): ConversionFormat;
+/**
+ * Dropped folder: shape-based detection (god/extracted). `entries` is the
+ * path of every regular file in the folder, relative to the folder root
+ * and forward-slash separated - e.g. `.webkitRelativePath` values from a
+ * `webkitdirectory` input.
+ *
+ * Returns `undefined` if the folder is neither god- nor extracted-shaped -
+ * treat that as a batch dir and resolve entries individually with
+ * `detectFormat`.
+ */
+export declare function detectDirFormat(entries: string[]): ConversionFormat | undefined;
+/**
+ * Resolves a dropped input to a format once, before anything is opened.
+ * Every downstream call (`inspectSource`, `ConversionSession.open`) should
+ * be given the `format` this returns rather than being left to guess.
+ */
+export declare function resolveSource(input: {
+    readFn: SourceReadFn;
+    fileSize: number;
+} | {
+    entries: string[];
+    parts: SourcePart[];
+}): ResolvedSource;
+/**
+ * CCI-specific split detection. Unlike a raw XISO split - where part 2 is
+ * just a continuation of part 1's byte stream and carries no header of its
+ * own - each CCI part is fully self-contained (own magic, own header, own
+ * index). A genuine ".1.cci"/".2.cci" pair should have both files
+ * independently detect as 'cci'; if not, surface that as an error rather
+ * than silently opening a broken source.
+ */
+export declare function findCciSplitParts(entries: string[], makeReadFn: (name: string) => SourceReadFn, fileSize: (name: string) => number): SplitCciResult | null;
+/**
+ * Raw XISO split detection. Part 2+ carry no magic of their own - just the
+ * continuation of part 1's sector stream - so there's nothing to
+ * independently verify the way findCciSplitParts does. This only confirms
+ * the pair exists; detectFormat still only needs to run against part 1.
+ */
+export declare function findXisoSplitParts(entries: string[]): SplitXisoResult | null;
+/**
+ * Resolves one entry of a batch dir: checks for a CCI split pair first
+ * (self-verifying, so a mislabeled pair fails loudly here rather than
+ * deeper inside the writer), then an XISO split pair, then falls back to
+ * plain single-file resolution.
+ */
+export declare function resolveBatchEntry(entries: string[], makeReadFn: (name: string) => SourceReadFn, fileSize: (name: string) => number): Promise<ResolvedSource>;

package/dist/detect.js

@@ -0,0 +1,128 @@
+import { detectFormat as rawDetectFormat, detectDirFormat as rawDetectDirFormat, } from './wasm/iso2x_wasm.js';
+/**
+ * Single dropped file: cheap magic-byte detection (xiso/ciso/cci). Reads
+ * only the first 4 bytes via `readFn`, so it's safe to call speculatively
+ * on every file drop.
+ */
+export function detectFormat(readFn, fileSize) {
+    return rawDetectFormat(readFn, fileSize);
+}
+/**
+ * Dropped folder: shape-based detection (god/extracted). `entries` is the
+ * path of every regular file in the folder, relative to the folder root
+ * and forward-slash separated - e.g. `.webkitRelativePath` values from a
+ * `webkitdirectory` input.
+ *
+ * Returns `undefined` if the folder is neither god- nor extracted-shaped -
+ * treat that as a batch dir and resolve entries individually with
+ * `detectFormat`.
+ */
+export function detectDirFormat(entries) {
+    return rawDetectDirFormat(entries);
+}
+/**
+ * Resolves a dropped input to a format once, before anything is opened.
+ * Every downstream call (`inspectSource`, `ConversionSession.open`) should
+ * be given the `format` this returns rather than being left to guess.
+ */
+export function resolveSource(input) {
+    if ('readFn' in input) {
+        const format = detectFormat(input.readFn, input.fileSize);
+        return {
+            kind: 'file',
+            format,
+            readFn: input.readFn,
+            fileSize: input.fileSize,
+        };
+    }
+    const format = detectDirFormat(input.entries);
+    if (!format) {
+        throw new Error('folder does not look like a God or Extracted source');
+    }
+    return { kind: 'dir', format, parts: input.parts };
+}
+/**
+ * Locates a two-file split source named "<stem>.1.<ext>" / "<stem>.2.<ext>"
+ * for one specific extension (case-insensitive). Generic building block -
+ * findCciSplitParts/findXisoSplitParts add their own format-specific
+ * validation on top, since a matching part 2 name means different things
+ * for each format.
+ */
+function findSplitParts(entries, extension) {
+    const ext = extension.replace(/^\./, '').toLowerCase();
+    const re = new RegExp(`\\.1\\.${ext}$`, 'i');
+    const part1 = entries.find((e) => re.test(e));
+    if (!part1)
+        return null;
+    const part2 = part1.replace(/\.1\.([^.]+)$/i, '.2.$1');
+    const match = entries.find((e) => e.toLowerCase() === part2.toLowerCase());
+    return match ? [part1, match] : null;
+}
+/**
+ * CCI-specific split detection. Unlike a raw XISO split - where part 2 is
+ * just a continuation of part 1's byte stream and carries no header of its
+ * own - each CCI part is fully self-contained (own magic, own header, own
+ * index). A genuine ".1.cci"/".2.cci" pair should have both files
+ * independently detect as 'cci'; if not, surface that as an error rather
+ * than silently opening a broken source.
+ */
+export function findCciSplitParts(entries, makeReadFn, fileSize) {
+    const found = findSplitParts(entries, 'cci');
+    if (!found)
+        return null;
+    const [name1, name2] = found;
+    const format1 = detectFormat(makeReadFn(name1), fileSize(name1));
+    const format2 = detectFormat(makeReadFn(name2), fileSize(name2));
+    if (format1 !== 'cci' || format2 !== 'cci') {
+        throw new Error(`found "${name1}"/"${name2}" but one or both parts don't have a ` +
+            `valid CCI header - refusing to treat this as a split CCI source`);
+    }
+    return { kind: 'cci-split', parts: [name1, name2] };
+}
+/**
+ * Raw XISO split detection. Part 2+ carry no magic of their own - just the
+ * continuation of part 1's sector stream - so there's nothing to
+ * independently verify the way findCciSplitParts does. This only confirms
+ * the pair exists; detectFormat still only needs to run against part 1.
+ */
+export function findXisoSplitParts(entries) {
+    const found = findSplitParts(entries, 'iso');
+    if (!found)
+        return null;
+    return { kind: 'xiso-split', parts: found };
+}
+/**
+ * Resolves one entry of a batch dir: checks for a CCI split pair first
+ * (self-verifying, so a mislabeled pair fails loudly here rather than
+ * deeper inside the writer), then an XISO split pair, then falls back to
+ * plain single-file resolution.
+ */
+export async function resolveBatchEntry(entries, makeReadFn, fileSize) {
+    const cci = findCciSplitParts(entries, makeReadFn, fileSize);
+    if (cci) {
+        return {
+            kind: 'dir',
+            format: 'cci',
+            parts: cci.parts.map((name) => ({
+                name,
+                size: fileSize(name),
+                readFn: makeReadFn(name),
+            })),
+        };
+    }
+    const xiso = findXisoSplitParts(entries);
+    if (xiso) {
+        const format = detectFormat(makeReadFn(xiso.parts[0]), fileSize(xiso.parts[0]));
+        return {
+            kind: 'dir',
+            format,
+            parts: xiso.parts.map((name) => ({
+                name,
+                size: fileSize(name),
+                readFn: makeReadFn(name),
+            })),
+        };
+    }
+    const [name] = entries;
+    return resolveSource({ readFn: makeReadFn(name), fileSize: fileSize(name) });
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+import initWasm, { chainMhtDigest } from './wasm/iso2x_wasm.js';
+export default initWasm;
+export { chainMhtDigest };
+export * from './types.js';
+export * from './constants.js';
+export * from './detect.js';
+export * from './inspect.js';
+export * from './session.js';
+export * from './attach.js';

package/dist/index.js

@@ -0,0 +1,9 @@
+import initWasm, { chainMhtDigest } from './wasm/iso2x_wasm.js';
+export default initWasm;
+export { chainMhtDigest };
+export * from './types.js';
+export * from './constants.js';
+export * from './detect.js';
+export * from './inspect.js';
+export * from './session.js';
+export * from './attach.js';

package/dist/inspect.d.ts

@@ -0,0 +1,2 @@
+import type { SourceInfoResult, SourceOptions, SourcePart, SourceReadFn } from './types.js';
+export declare function inspectSource(readFn: SourceReadFn, fileSize: number, source: SourceOptions, sourceParts?: SourcePart[]): SourceInfoResult;

package/dist/inspect.js

@@ -0,0 +1,14 @@
+import { inspectSource as rawInspectSource } from './wasm/iso2x_wasm.js';
+export function inspectSource(readFn, fileSize, source, sourceParts) {
+    const info = rawInspectSource(readFn, fileSize, source, sourceParts);
+    try {
+        return {
+            titleId: info.titleId(),
+            contentType: info.contentType(),
+            detectedTitle: info.detectedTitle(),
+        };
+    }
+    finally {
+        info.free();
+    }
+}

package/dist/session.d.ts

@@ -0,0 +1,117 @@
+import type { OpenConversionSessionOptions, SourceOptions, SourcePart, SourceReadFn } from './types.js';
+/**
+ * One pull-based session type for every output format.
+ *
+ * Usage is identical regardless of format:
+ *
+ *   const resolved = resolveSource({ readFn, fileSize });
+ *   const session = ConversionSession.open(readFn, fileSize, options, { format: resolved.format });
+ *   while (!session.isDone()) {
+ *     const chunk = session.nextChunk(maxBytes);
+ *     if (chunk) yield chunk;
+ *   }
+ *   session.free();
+ *
+ * For 'god', 'ciso', and 'cci', hashing/sizing must be driven to completion
+ * before any nextChunk() calls (see hashNextPart()). For 'extracted',
+ * 'ciso', and 'cci', call currentEntryName() after each nextChunk() to know
+ * which output file the chunk belongs to - always route by
+ * currentEntryName() for these three rather than special-casing "no split
+ * happened". 'god' and 'xiso' return null there, since they're always a
+ * single anonymous output stream. 'zar' also always returns a single
+ * stream, but currentEntryName() there is non-null - see the method's own
+ * doc comment.
+ */
+export declare class ConversionSession {
+    private readonly raw;
+    private constructor();
+    /**
+     * `source` is required, not optional - an omitted `source` no longer
+     * defaults to xiso. Resolve it first via `resolveSource`/
+     * `detectFormat`/`detectDirFormat`.
+     */
+    static open(readFn: SourceReadFn, fileSize: number, options: OpenConversionSessionOptions, source: SourceOptions, sourceParts?: SourcePart[]): ConversionSession;
+    /**
+     * For 'god', 'ciso', and 'cci': hashes/sizes exactly one more part (or
+     * sizing batch) and returns whether that pre-streaming pass is now
+     * complete. For 'ciso' this drives the sizing pass that determines
+     * exact split boundaries and `outputManifest()`; for 'cci' it
+     * additionally has to finish sizing each split part before that part's
+     * header/index bytes can be built - nextChunk() throws if called before
+     * this returns true. For 'xiso', 'extracted', and 'zar' this is a no-op
+     * that returns true immediately, so it's safe to call unconditionally.
+     *
+     * Bounded cost per call is the point: call this in a loop with an await
+     * between calls (e.g. `await new Promise(r => setTimeout(r, 0))`) so
+     * the caller's event loop gets control back regularly.
+     */
+    hashNextPart(): boolean;
+    /** Returns the next chunk, or null once the session is exhausted. */
+    nextChunk(maxBytes: number): Uint8Array<ArrayBuffer> | null;
+    isDone(): boolean;
+    /**
+     * Authoritative count of `totalUnits()` completed so far, for formats
+     * where `nextChunk()`'s returned byte length isn't a reliable progress
+     * proxy (currently only 'zar' - its chunks are compressed output
+     * bytes, while `totalUnits()` is raw input bytes). `null` for every
+     * other format; callers should keep deriving progress from received
+     * chunk bytes in that case.
+     */
+    unitsDone(): number | null;
+    /**
+     * Sectors for xiso, parts for god, file count for extracted/ciso/cci,
+     * total input bytes for zar (there's no fixed-size unit to count -
+     * every file is addressed by name and packed byte-for-byte, so bytes
+     * is the most meaningful progress denominator).
+     */
+    totalUnits(): number;
+    /**
+     * `{ name, size }` per output file for formats that produce more than
+     * one (god, extracted, ciso, cci) - feed this straight into your
+     * zip-download tooling's file-list metadata. 'zar' also populates this,
+     * even though it only ever produces one output file: its final size
+     * isn't known until streaming reaches the footer phase (it depends on
+     * every block's actual compressed size), so - like ciso/cci - it stays
+     * empty until then rather than reporting a size up front.
+     *
+     * For 'god' and 'extracted', safe to call any time after open(). For
+     * 'ciso', 'cci', and 'zar', empty until hashNextPart()/streaming
+     * reaches completion: exact sizes depend on per-sector/per-block
+     * compression. Even a non-split ciso/cci output reports one entry once
+     * sizing is done, and zar always reports exactly one entry once done.
+     * Empty array for 'xiso' - use `totalUnits() * 2048` for its predicted
+     * size instead.
+     */
+    outputManifest(): {
+        name: string;
+        size: number;
+    }[];
+    /**
+     * Name of the file the most recent nextChunk() call's bytes belong to.
+     * Meaningful for 'extracted', 'ciso', and 'cci'; null for 'god' and
+     * 'xiso'. For 'zar' this is also non-null, but - unlike
+     * extracted/ciso/cci - it never changes across the session's lifetime,
+     * since zar only ever produces the one output stream; it's still worth
+     * reading (rather than treated as null-equivalent) since it reports the
+     * output filename stem rather than being merely anonymous.
+     */
+    currentEntryName(): string | null;
+    free(): void;
+}
+/**
+ * Drop-in async generator for a chunk-streaming loop. Yields bytes in
+ * order for any format.
+ *
+ * This generator doesn't route chunks to different output files - it just
+ * yields bytes in order. For 'extracted', 'ciso', and 'cci', the caller
+ * must additionally check session.currentEntryName() after each chunk and
+ * switch output files when it changes; a chunk never straddles two entry
+ * names, so it's safe to check once per yielded chunk. 'zar' also reports
+ * a non-null currentEntryName(), but it never changes, so no switching
+ * logic is needed for it.
+ *
+ * For 'god', 'ciso', and 'cci' sessions, the caller is responsible for
+ * driving session.hashNextPart() to completion before iterating this
+ * generator.
+ */
+export declare function chunksFromSession(session: ConversionSession, maxBytes: number, waitForRoom: () => Promise<void>): AsyncGenerator<Uint8Array>;

package/dist/session.js

@@ -0,0 +1,143 @@
+import { openConversionSession as rawOpenConversionSession, } from './wasm/iso2x_wasm.js';
+/**
+ * One pull-based session type for every output format.
+ *
+ * Usage is identical regardless of format:
+ *
+ *   const resolved = resolveSource({ readFn, fileSize });
+ *   const session = ConversionSession.open(readFn, fileSize, options, { format: resolved.format });
+ *   while (!session.isDone()) {
+ *     const chunk = session.nextChunk(maxBytes);
+ *     if (chunk) yield chunk;
+ *   }
+ *   session.free();
+ *
+ * For 'god', 'ciso', and 'cci', hashing/sizing must be driven to completion
+ * before any nextChunk() calls (see hashNextPart()). For 'extracted',
+ * 'ciso', and 'cci', call currentEntryName() after each nextChunk() to know
+ * which output file the chunk belongs to - always route by
+ * currentEntryName() for these three rather than special-casing "no split
+ * happened". 'god' and 'xiso' return null there, since they're always a
+ * single anonymous output stream. 'zar' also always returns a single
+ * stream, but currentEntryName() there is non-null - see the method's own
+ * doc comment.
+ */
+export class ConversionSession {
+    raw;
+    constructor(raw) {
+        this.raw = raw;
+    }
+    /**
+     * `source` is required, not optional - an omitted `source` no longer
+     * defaults to xiso. Resolve it first via `resolveSource`/
+     * `detectFormat`/`detectDirFormat`.
+     */
+    static open(readFn, fileSize, options, source, sourceParts) {
+        return new ConversionSession(rawOpenConversionSession(readFn, fileSize, options, source, sourceParts));
+    }
+    /**
+     * For 'god', 'ciso', and 'cci': hashes/sizes exactly one more part (or
+     * sizing batch) and returns whether that pre-streaming pass is now
+     * complete. For 'ciso' this drives the sizing pass that determines
+     * exact split boundaries and `outputManifest()`; for 'cci' it
+     * additionally has to finish sizing each split part before that part's
+     * header/index bytes can be built - nextChunk() throws if called before
+     * this returns true. For 'xiso', 'extracted', and 'zar' this is a no-op
+     * that returns true immediately, so it's safe to call unconditionally.
+     *
+     * Bounded cost per call is the point: call this in a loop with an await
+     * between calls (e.g. `await new Promise(r => setTimeout(r, 0))`) so
+     * the caller's event loop gets control back regularly.
+     */
+    hashNextPart() {
+        return this.raw.hashNextPart();
+    }
+    /** Returns the next chunk, or null once the session is exhausted. */
+    nextChunk(maxBytes) {
+        const chunk = this.raw.nextChunk(maxBytes);
+        return chunk ? new Uint8Array(chunk) : null;
+    }
+    isDone() {
+        return this.raw.isDone();
+    }
+    /**
+     * Authoritative count of `totalUnits()` completed so far, for formats
+     * where `nextChunk()`'s returned byte length isn't a reliable progress
+     * proxy (currently only 'zar' - its chunks are compressed output
+     * bytes, while `totalUnits()` is raw input bytes). `null` for every
+     * other format; callers should keep deriving progress from received
+     * chunk bytes in that case.
+     */
+    unitsDone() {
+        return this.raw.unitsDone() ?? null;
+    }
+    /**
+     * Sectors for xiso, parts for god, file count for extracted/ciso/cci,
+     * total input bytes for zar (there's no fixed-size unit to count -
+     * every file is addressed by name and packed byte-for-byte, so bytes
+     * is the most meaningful progress denominator).
+     */
+    totalUnits() {
+        return this.raw.totalUnits();
+    }
+    /**
+     * `{ name, size }` per output file for formats that produce more than
+     * one (god, extracted, ciso, cci) - feed this straight into your
+     * zip-download tooling's file-list metadata. 'zar' also populates this,
+     * even though it only ever produces one output file: its final size
+     * isn't known until streaming reaches the footer phase (it depends on
+     * every block's actual compressed size), so - like ciso/cci - it stays
+     * empty until then rather than reporting a size up front.
+     *
+     * For 'god' and 'extracted', safe to call any time after open(). For
+     * 'ciso', 'cci', and 'zar', empty until hashNextPart()/streaming
+     * reaches completion: exact sizes depend on per-sector/per-block
+     * compression. Even a non-split ciso/cci output reports one entry once
+     * sizing is done, and zar always reports exactly one entry once done.
+     * Empty array for 'xiso' - use `totalUnits() * 2048` for its predicted
+     * size instead.
+     */
+    outputManifest() {
+        return this.raw.outputManifest();
+    }
+    /**
+     * Name of the file the most recent nextChunk() call's bytes belong to.
+     * Meaningful for 'extracted', 'ciso', and 'cci'; null for 'god' and
+     * 'xiso'. For 'zar' this is also non-null, but - unlike
+     * extracted/ciso/cci - it never changes across the session's lifetime,
+     * since zar only ever produces the one output stream; it's still worth
+     * reading (rather than treated as null-equivalent) since it reports the
+     * output filename stem rather than being merely anonymous.
+     */
+    currentEntryName() {
+        return this.raw.currentEntryName() ?? null;
+    }
+    free() {
+        this.raw.free();
+    }
+}
+/**
+ * Drop-in async generator for a chunk-streaming loop. Yields bytes in
+ * order for any format.
+ *
+ * This generator doesn't route chunks to different output files - it just
+ * yields bytes in order. For 'extracted', 'ciso', and 'cci', the caller
+ * must additionally check session.currentEntryName() after each chunk and
+ * switch output files when it changes; a chunk never straddles two entry
+ * names, so it's safe to check once per yielded chunk. 'zar' also reports
+ * a non-null currentEntryName(), but it never changes, so no switching
+ * logic is needed for it.
+ *
+ * For 'god', 'ciso', and 'cci' sessions, the caller is responsible for
+ * driving session.hashNextPart() to completion before iterating this
+ * generator.
+ */
+export async function* chunksFromSession(session, maxBytes, waitForRoom) {
+    while (!session.isDone()) {
+        await waitForRoom();
+        const chunk = session.nextChunk(maxBytes);
+        if (chunk === null)
+            break;
+        yield chunk;
+    }
+}