@rpgm-tools/neo-angband-core 0.10.0

package/dist/save/buffer.js

@@ -0,0 +1,238 @@
+/**
+ * Savefile serialization primitives - a faithful port of the block-based
+ * reader/writer in reference/src/savefile.c.
+ *
+ * The upstream format (unchanged here):
+ * - A 4-byte file magic {83,97,118,101} = "Save", then a 4-byte version
+ *   stamp.
+ * - A sequence of blocks. Each block is a 28-byte header (16-byte
+ *   zero-padded name, u32 version, u32 payload size, u32 checksum) then
+ *   the payload, then zero-to-three padding bytes so the payload aligns
+ *   to a 4-byte boundary. Padding is not part of the payload or checksum.
+ * - Every multi-byte value is little-endian.
+ * - The block checksum is a running uint32 additive sum of every payload
+ *   byte, matching savefile.c's `buffer_check += v`. It detects
+ *   CORRUPTION; it is trivially recomputable and is NOT tamper-proof.
+ *   For a tamper deterrent, see ./integrity (a whole-file hash seam);
+ *   for real anti-tamper, saves must be server-authoritative.
+ *
+ * Parity note: the upstream 4-byte alignment padding is the literal byte
+ * 'x' (0x78). We reproduce that so byte streams match upstream exactly.
+ */
+/** File magic: the ASCII bytes of "Save". */
+export const SAVEFILE_MAGIC = [83, 97, 118, 101];
+/** Fixed block-header size: 16-byte name + three u32 fields. */
+export const SAVEFILE_HEAD_SIZE = 28;
+/** The upstream alignment padding byte ('x'). */
+const PAD_BYTE = 0x78;
+/**
+ * Writes a single block's payload while maintaining the additive
+ * checksum, exactly like savefile.c's sf_put path.
+ */
+export class SaveWriter {
+    buf = [];
+    check = 0;
+    /** wr_byte: append one byte and fold it into the checksum. */
+    putByte(v) {
+        const b = v & 0xff;
+        this.buf.push(b);
+        this.check = (this.check + b) >>> 0;
+    }
+    /** wr_u16b: little-endian unsigned 16-bit. */
+    putU16(v) {
+        this.putByte(v & 0xff);
+        this.putByte((v >> 8) & 0xff);
+    }
+    /** wr_s16b: signed 16-bit (same bytes as u16). */
+    putS16(v) {
+        this.putU16(v & 0xffff);
+    }
+    /** wr_u32b: little-endian unsigned 32-bit. */
+    putU32(v) {
+        this.putByte(v & 0xff);
+        this.putByte((v >>> 8) & 0xff);
+        this.putByte((v >>> 16) & 0xff);
+        this.putByte((v >>> 24) & 0xff);
+    }
+    /** wr_s32b: signed 32-bit (same bytes as u32). */
+    putS32(v) {
+        this.putU32(v >>> 0);
+    }
+    /** wr_string: bytes of the string then a null terminator. */
+    putString(str) {
+        for (let i = 0; i < str.length; i++) {
+            this.putByte(str.charCodeAt(i) & 0xff);
+        }
+        this.putByte(0);
+    }
+    /** pad_bytes: n zero bytes (checksummed, as upstream pads inside blocks). */
+    pad(n) {
+        for (let i = 0; i < n; i++)
+            this.putByte(0);
+    }
+    /** Current checksum (uint32) over everything written so far. */
+    checksum() {
+        return this.check >>> 0;
+    }
+    /** The payload bytes written so far. */
+    payload() {
+        return Uint8Array.from(this.buf);
+    }
+    /** Byte length of the payload. */
+    get length() {
+        return this.buf.length;
+    }
+}
+/**
+ * Reads a block's payload while maintaining the additive checksum, so a
+ * caller can compare it against the header's stored checksum. Mirrors
+ * savefile.c's sf_get path. Reading past the end throws, matching the
+ * upstream "Broken savefile" quit.
+ */
+export class SaveReader {
+    buf;
+    pos = 0;
+    check = 0;
+    constructor(buf) {
+        this.buf = buf;
+    }
+    next() {
+        if (this.pos >= this.buf.length) {
+            throw new RangeError("Broken savefile: read past end of block");
+        }
+        const b = this.buf[this.pos++];
+        this.check = (this.check + b) >>> 0;
+        return b;
+    }
+    /** rd_byte. */
+    getByte() {
+        return this.next();
+    }
+    /** rd_u16b: little-endian unsigned 16-bit. */
+    getU16() {
+        const lo = this.next();
+        const hi = this.next();
+        return (lo | (hi << 8)) >>> 0;
+    }
+    /** rd_s16b: signed 16-bit. */
+    getS16() {
+        const v = this.getU16();
+        return v >= 0x8000 ? v - 0x10000 : v;
+    }
+    /** rd_u32b: little-endian unsigned 32-bit. */
+    getU32() {
+        const b0 = this.next();
+        const b1 = this.next();
+        const b2 = this.next();
+        const b3 = this.next();
+        return (b0 | (b1 << 8) | (b2 << 16) | (b3 << 24)) >>> 0;
+    }
+    /** rd_s32b: signed 32-bit. */
+    getS32() {
+        return this.getU32() | 0;
+    }
+    /** rd_string: read up to a null terminator, capping at max chars. */
+    getString(max) {
+        let out = "";
+        for (;;) {
+            const b = this.next();
+            if (b === 0)
+                break;
+            if (out.length < max - 1)
+                out += String.fromCharCode(b);
+        }
+        return out;
+    }
+    /** strip_bytes: discard n bytes (still checksummed). */
+    strip(n) {
+        for (let i = 0; i < n; i++)
+            this.next();
+    }
+    /** Running checksum (uint32) over everything read so far. */
+    checksum() {
+        return this.check >>> 0;
+    }
+    /** Bytes consumed so far. */
+    get position() {
+        return this.pos;
+    }
+}
+function writeU32LE(out, v) {
+    out.push(v & 0xff, (v >>> 8) & 0xff, (v >>> 16) & 0xff, (v >>> 24) & 0xff);
+}
+/**
+ * Assemble the full savefile byte stream: magic + version stamp + each
+ * block framed exactly as try_save does (28-byte header, payload,
+ * 4-byte alignment padding of 'x').
+ */
+export function writeSavefile(version, blocks) {
+    const out = [...SAVEFILE_MAGIC];
+    writeU32LE(out, version);
+    for (const block of blocks) {
+        const w = new SaveWriter();
+        block.write(w);
+        const payload = w.payload();
+        // 16-byte zero-padded name.
+        for (let i = 0; i < 16; i++) {
+            out.push(i < block.name.length ? block.name.charCodeAt(i) & 0xff : 0);
+        }
+        writeU32LE(out, block.version);
+        writeU32LE(out, payload.length);
+        writeU32LE(out, w.checksum());
+        for (const b of payload)
+            out.push(b);
+        // Align the payload to a 4-byte boundary with 'x' padding.
+        const rem = payload.length % 4;
+        if (rem)
+            for (let i = 0; i < 4 - rem; i++)
+                out.push(PAD_BYTE);
+    }
+    return Uint8Array.from(out);
+}
+function readU32LE(buf, pos) {
+    return ((buf[pos] |
+        (buf[pos + 1] << 8) |
+        (buf[pos + 2] << 16) |
+        (buf[pos + 3] << 24)) >>>
+        0);
+}
+/**
+ * Split a savefile stream into blocks and VERIFY each block's additive
+ * checksum. Throws on a bad magic or a checksum mismatch (the corruption
+ * signal). Callers then feed each payload to a SaveReader + BlockLoader.
+ */
+export function readSavefile(buf) {
+    for (let i = 0; i < 4; i++) {
+        if (buf[i] !== SAVEFILE_MAGIC[i]) {
+            throw new Error("Not a Neo Angband savefile (bad magic)");
+        }
+    }
+    const version = readU32LE(buf, 4);
+    let pos = 8;
+    const blocks = [];
+    while (pos < buf.length) {
+        let name = "";
+        for (let i = 0; i < 16; i++) {
+            const c = buf[pos + i];
+            if (c)
+                name += String.fromCharCode(c);
+        }
+        const bversion = readU32LE(buf, pos + 16);
+        const size = readU32LE(buf, pos + 20);
+        const check = readU32LE(buf, pos + 24);
+        pos += SAVEFILE_HEAD_SIZE;
+        const payload = buf.subarray(pos, pos + size);
+        let sum = 0;
+        for (const b of payload)
+            sum = (sum + b) >>> 0;
+        if (sum !== check) {
+            throw new Error(`Savefile block "${name}" failed its checksum`);
+        }
+        blocks.push({ header: { name, version: bversion, size, check }, payload });
+        pos += size;
+        if (size % 4)
+            pos += 4 - (size % 4);
+    }
+    return { version, blocks };
+}
+//# sourceMappingURL=buffer.js.map

package/dist/save/buffer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buffer.js","sourceRoot":"","sources":["../../src/save/buffer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,6CAA6C;AAC7C,MAAM,CAAC,MAAM,cAAc,GAAsB,CAAC,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;AAEpE,gEAAgE;AAChE,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,CAAC;AAErC,iDAAiD;AACjD,MAAM,QAAQ,GAAG,IAAI,CAAC;AAUtB;;;GAGG;AACH,MAAM,OAAO,UAAU;IACb,GAAG,GAAa,EAAE,CAAC;IACnB,KAAK,GAAG,CAAC,CAAC;IAElB,8DAA8D;IAC9D,OAAO,CAAC,CAAS;QACf,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;QACnB,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACjB,IAAI,CAAC,KAAK,GAAG,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;IACtC,CAAC;IAED,8CAA8C;IAC9C,MAAM,CAAC,CAAS;QACd,IAAI,CAAC,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;QACvB,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAChC,CAAC;IAED,kDAAkD;IAClD,MAAM,CAAC,CAAS;QACd,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC;IAC1B,CAAC;IAED,8CAA8C;IAC9C,MAAM,CAAC,CAAS;QACd,IAAI,CAAC,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;QACvB,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;QAC/B,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;QAChC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;IAClC,CAAC;IAED,kDAAkD;IAClD,MAAM,CAAC,CAAS;QACd,IAAI,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;IACvB,CAAC;IAED,6DAA6D;IAC7D,SAAS,CAAC,GAAW;QACnB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACpC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;QACzC,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,6EAA6E;IAC7E,GAAG,CAAC,CAAS;QACX,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE;YAAE,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAC9C,CAAC;IAED,gEAAgE;IAChE,QAAQ;QACN,OAAO,IAAI,CAAC,KAAK,KAAK,CAAC,CAAC;IAC1B,CAAC;IAED,wCAAwC;IACxC,OAAO;QACL,OAAO,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACnC,CAAC;IAED,kCAAkC;IAClC,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC;IACzB,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,UAAU;IAIQ;IAHrB,GAAG,GAAG,CAAC,CAAC;IACR,KAAK,GAAG,CAAC,CAAC;IAElB,YAA6B,GAAe;QAAf,QAAG,GAAH,GAAG,CAAY;IAAG,CAAC;IAExC,IAAI;QACV,IAAI,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC;YAChC,MAAM,IAAI,UAAU,CAAC,yCAAyC,CAAC,CAAC;QAClE,CAAC;QACD,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,CAAW,CAAC;QACzC,IAAI,CAAC,KAAK,GAAG,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;QACpC,OAAO,CAAC,CAAC;IACX,CAAC;IAED,eAAe;IACf,OAAO;QACL,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC;IACrB,CAAC;IAED,8CAA8C;IAC9C,MAAM;QACJ,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QACvB,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QACvB,OAAO,CAAC,EAAE,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IAChC,CAAC;IAED,8BAA8B;IAC9B,MAAM;QACJ,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QACxB,OAAO,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;IACvC,CAAC;IAED,8CAA8C;IAC9C,MAAM;QACJ,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QACvB,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QACvB,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QACvB,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QACvB,OAAO,CAAC,EAAE,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;IAC1D,CAAC;IAED,8BAA8B;IAC9B,MAAM;QACJ,OAAO,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC3B,CAAC;IAED,qEAAqE;IACrE,SAAS,CAAC,GAAW;QACnB,IAAI,GAAG,GAAG,EAAE,CAAC;QACb,SAAS,CAAC;YACR,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;YACtB,IAAI,CAAC,KAAK,CAAC;gBAAE,MAAM;YACnB,IAAI,GAAG,CAAC,MAAM,GAAG,GAAG,GAAG,CAAC;gBAAE,GAAG,IAAI,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QAC1D,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED,wDAAwD;IACxD,KAAK,CAAC,CAAS;QACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE;YAAE,IAAI,CAAC,IAAI,EAAE,CAAC;IAC1C,CAAC;IAED,6DAA6D;IAC7D,QAAQ;QACN,OAAO,IAAI,CAAC,KAAK,KAAK,CAAC,CAAC;IAC1B,CAAC;IAED,6BAA6B;IAC7B,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,GAAG,CAAC;IAClB,CAAC;CACF;AAYD,SAAS,UAAU,CAAC,GAAa,EAAE,CAAS;IAC1C,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;AAC7E,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,OAAe,EAAE,MAAmB;IAChE,MAAM,GAAG,GAAa,CAAC,GAAG,cAAc,CAAC,CAAC;IAC1C,UAAU,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAEzB,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,CAAC,GAAG,IAAI,UAAU,EAAE,CAAC;QAC3B,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QACf,MAAM,OAAO,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC;QAE5B,4BAA4B;QAC5B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;YAC5B,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACxE,CAAC;QACD,UAAU,CAAC,GAAG,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;QAC/B,UAAU,CAAC,GAAG,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;QAChC,UAAU,CAAC,GAAG,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC;QAE9B,KAAK,MAAM,CAAC,IAAI,OAAO;YAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAErC,2DAA2D;QAC3D,MAAM,GAAG,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;QAC/B,IAAI,GAAG;YAAE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE;gBAAE,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAChE,CAAC;IACD,OAAO,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC9B,CAAC;AAQD,SAAS,SAAS,CAAC,GAAe,EAAE,GAAW;IAC7C,OAAO,CACL,CAAE,GAAG,CAAC,GAAG,CAAY;QACnB,CAAE,GAAG,CAAC,GAAG,GAAG,CAAC,CAAY,IAAI,CAAC,CAAC;QAC/B,CAAE,GAAG,CAAC,GAAG,GAAG,CAAC,CAAY,IAAI,EAAE,CAAC;QAChC,CAAE,GAAG,CAAC,GAAG,GAAG,CAAC,CAAY,IAAI,EAAE,CAAC,CAAC;QACnC,CAAC,CACF,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,GAAe;IAC1C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3B,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,cAAc,CAAC,CAAC,CAAC,EAAE,CAAC;YACjC,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;QAC5D,CAAC;IACH,CAAC;IACD,MAAM,OAAO,GAAG,SAAS,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IAClC,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,MAAM,MAAM,GAA6B,EAAE,CAAC;IAE5C,OAAO,GAAG,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC;QACxB,IAAI,IAAI,GAAG,EAAE,CAAC;QACd,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;YAC5B,MAAM,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC,CAAW,CAAC;YACjC,IAAI,CAAC;gBAAE,IAAI,IAAI,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QACxC,CAAC;QACD,MAAM,QAAQ,GAAG,SAAS,CAAC,GAAG,EAAE,GAAG,GAAG,EAAE,CAAC,CAAC;QAC1C,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,EAAE,GAAG,GAAG,EAAE,CAAC,CAAC;QACtC,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,EAAE,GAAG,GAAG,EAAE,CAAC,CAAC;QACvC,GAAG,IAAI,kBAAkB,CAAC;QAE1B,MAAM,OAAO,GAAG,GAAG,CAAC,QAAQ,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI,CAAC,CAAC;QAC9C,IAAI,GAAG,GAAG,CAAC,CAAC;QACZ,KAAK,MAAM,CAAC,IAAI,OAAO;YAAE,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;QAC/C,IAAI,GAAG,KAAK,KAAK,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CAAC,mBAAmB,IAAI,uBAAuB,CAAC,CAAC;QAClE,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;QAE3E,GAAG,IAAI,IAAI,CAAC;QACZ,IAAI,IAAI,GAAG,CAAC;YAAE,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC;IACtC,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;AAC7B,CAAC"}

package/dist/save/compress.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Save compression: the third word of PORT_PLAN decision 9 ("versioned,
+ * schema-validated, compressed JSON"), which the format had never had.
+ *
+ * This is a PLATFORM ACCOMMODATION, not a nicety, so it belongs in core (the
+ * owner's rule, 2026-07-28: what the new platform makes necessary is part of the
+ * port; what merely makes the game nicer is a QoL mod candidate). The reason is
+ * measured rather than assumed. A freshly born character serializes to:
+ *
+ *     depth  0   135 KiB JSON   ->  180 KiB once base64'd for localStorage
+ *     depth 20   337 KiB        ->  449 KiB
+ *     depth 50   391 KiB        ->  521 KiB
+ *
+ * A `localStorage` origin gets about 5 MB in every current browser, so the web
+ * build ran out of room at roughly NINE characters - and that is before
+ * `birth_levels_persist`, whose `levelCache` adds another level-sized block per
+ * remembered floor and can exhaust the quota with a single character. Under the
+ * no-save-scum, death-is-permanent policy (decision 16) a quota failure is not an
+ * inconvenience: it is a dead character. gzip measures at ratio 0.04 on this data
+ * (the chunk grids and the known-map arrays are enormously repetitive), turning
+ * 521 KiB into 22 KiB and the ceiling from ~9 characters into hundreds.
+ *
+ * WHY A SEAM RATHER THAN A COMPRESSOR IN CORE. `packages/core` has zero runtime
+ * dependencies and stays environment-neutral, and the two things that can
+ * actually deflate bytes are split by environment: Node has `zlib.gzipSync`,
+ * browsers have `CompressionStream` - which is ASYNC, and the save path is
+ * synchronous all the way down because `z-file.c` is (see host/io.ts). So core
+ * owns the FORMAT - the envelope, the id, the sniffing, and the rule that an
+ * unknown codec is reported rather than guessed - and a front end supplies the
+ * codec it can actually run. Same shape as save/integrity.ts's SaveIntegrity
+ * provider, and for the same reason.
+ *
+ * BACKWARD COMPATIBILITY IS THE POINT OF THE HEADER. Saves written before this
+ * existed are bare JSON, and a bare JSON document cannot begin with the magic
+ * (it begins with `{`), so `stripCodec` distinguishes them with certainty rather
+ * than by heuristic. An older build reading a NEWER compressed save is the case
+ * that actually needs care: it will find a codec id it has never heard of, and
+ * must say so instead of reporting a corrupt save, because the two call for
+ * opposite responses from a player.
+ */
+/**
+ * A pluggable save compressor. Both directions must be synchronous, which is
+ * the whole reason this is injected rather than implemented here.
+ *
+ * `decompress` MUST throw on input it cannot decode rather than returning
+ * partial output: a truncated save that parses into a plausible-but-wrong game
+ * is the one outcome worse than a save that fails to load.
+ */
+export interface SaveCodec {
+    /**
+     * Stable codec identifier, recorded in the envelope and used to pick the
+     * decoder on the way back. Lower-case, `[a-z0-9-]`, no colon and no newline
+     * (both are envelope delimiters) - `assertCodecId` enforces it.
+     */
+    readonly id: string;
+    compress(bytes: Uint8Array): Uint8Array;
+    decompress(bytes: Uint8Array): Uint8Array;
+}
+/** Guard a codec id against the envelope's own delimiters. */
+export declare function assertCodecId(id: string): void;
+/** Wrap compressed bytes in the envelope that names the codec that made them. */
+export declare function applyCodec(json: Uint8Array, codec: SaveCodec): Uint8Array;
+/** What `stripCodec` found at the front of a savefile payload. */
+export interface StrippedCodec {
+    /** The codec id from the envelope, or null for an uncompressed save. */
+    codecId: string | null;
+    /** The bytes after the envelope (the whole input when codecId is null). */
+    body: Uint8Array;
+}
+/**
+ * Split the codec envelope off a payload.
+ *
+ * A payload with no envelope is returned as-is with `codecId: null` - that is
+ * every save written before compression existed, and it stays loadable forever.
+ */
+export declare function stripCodec(payload: Uint8Array): StrippedCodec;
+/** Pick the codec for an id out of the codecs a build has, or undefined. */
+export declare function findCodec(id: string, codecs: readonly SaveCodec[]): SaveCodec | undefined;
+//# sourceMappingURL=compress.d.ts.map

package/dist/save/compress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compress.d.ts","sourceRoot":"","sources":["../../src/save/compress.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS;IACxB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CAAC;IACxC,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CAAC;CAC3C;AAYD,8DAA8D;AAC9D,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAM9C;AAED,iFAAiF;AACjF,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,SAAS,GAAG,UAAU,CAQzE;AAED,kEAAkE;AAClE,MAAM,WAAW,aAAa;IAC5B,wEAAwE;IACxE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,2EAA2E;IAC3E,IAAI,EAAE,UAAU,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,UAAU,GAAG,aAAa,CAmB7D;AAED,4EAA4E;AAC5E,wBAAgB,SAAS,CACvB,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,SAAS,SAAS,EAAE,GAC3B,SAAS,GAAG,SAAS,CAEvB"}

package/dist/save/compress.js

@@ -0,0 +1,97 @@
+/**
+ * Save compression: the third word of PORT_PLAN decision 9 ("versioned,
+ * schema-validated, compressed JSON"), which the format had never had.
+ *
+ * This is a PLATFORM ACCOMMODATION, not a nicety, so it belongs in core (the
+ * owner's rule, 2026-07-28: what the new platform makes necessary is part of the
+ * port; what merely makes the game nicer is a QoL mod candidate). The reason is
+ * measured rather than assumed. A freshly born character serializes to:
+ *
+ *     depth  0   135 KiB JSON   ->  180 KiB once base64'd for localStorage
+ *     depth 20   337 KiB        ->  449 KiB
+ *     depth 50   391 KiB        ->  521 KiB
+ *
+ * A `localStorage` origin gets about 5 MB in every current browser, so the web
+ * build ran out of room at roughly NINE characters - and that is before
+ * `birth_levels_persist`, whose `levelCache` adds another level-sized block per
+ * remembered floor and can exhaust the quota with a single character. Under the
+ * no-save-scum, death-is-permanent policy (decision 16) a quota failure is not an
+ * inconvenience: it is a dead character. gzip measures at ratio 0.04 on this data
+ * (the chunk grids and the known-map arrays are enormously repetitive), turning
+ * 521 KiB into 22 KiB and the ceiling from ~9 characters into hundreds.
+ *
+ * WHY A SEAM RATHER THAN A COMPRESSOR IN CORE. `packages/core` has zero runtime
+ * dependencies and stays environment-neutral, and the two things that can
+ * actually deflate bytes are split by environment: Node has `zlib.gzipSync`,
+ * browsers have `CompressionStream` - which is ASYNC, and the save path is
+ * synchronous all the way down because `z-file.c` is (see host/io.ts). So core
+ * owns the FORMAT - the envelope, the id, the sniffing, and the rule that an
+ * unknown codec is reported rather than guessed - and a front end supplies the
+ * codec it can actually run. Same shape as save/integrity.ts's SaveIntegrity
+ * provider, and for the same reason.
+ *
+ * BACKWARD COMPATIBILITY IS THE POINT OF THE HEADER. Saves written before this
+ * existed are bare JSON, and a bare JSON document cannot begin with the magic
+ * (it begins with `{`), so `stripCodec` distinguishes them with certainty rather
+ * than by heuristic. An older build reading a NEWER compressed save is the case
+ * that actually needs care: it will find a codec id it has never heard of, and
+ * must say so instead of reporting a corrupt save, because the two call for
+ * opposite responses from a player.
+ */
+/**
+ * Envelope prefix: `NGSC1:<id>\n` then the codec's bytes. Versioned in the magic
+ * itself (`1`) so a future envelope change is a different magic rather than a
+ * silent reinterpretation of these bytes.
+ */
+const CODEC_MAGIC = "NGSC1:";
+/** The envelope delimiters, which a codec id therefore may not contain. */
+const CODEC_ID_RE = /^[a-z0-9-]+$/;
+/** Guard a codec id against the envelope's own delimiters. */
+export function assertCodecId(id) {
+    if (!CODEC_ID_RE.test(id)) {
+        throw new Error(`invalid save codec id ${JSON.stringify(id)}: expected [a-z0-9-]+`);
+    }
+}
+/** Wrap compressed bytes in the envelope that names the codec that made them. */
+export function applyCodec(json, codec) {
+    assertCodecId(codec.id);
+    const body = codec.compress(json);
+    const head = new TextEncoder().encode(`${CODEC_MAGIC}${codec.id}\n`);
+    const out = new Uint8Array(head.length + body.length);
+    out.set(head, 0);
+    out.set(body, head.length);
+    return out;
+}
+/**
+ * Split the codec envelope off a payload.
+ *
+ * A payload with no envelope is returned as-is with `codecId: null` - that is
+ * every save written before compression existed, and it stays loadable forever.
+ */
+export function stripCodec(payload) {
+    const magic = new TextEncoder().encode(CODEC_MAGIC);
+    if (payload.length < magic.length)
+        return { codecId: null, body: payload };
+    for (let i = 0; i < magic.length; i++) {
+        if (payload[i] !== magic[i])
+            return { codecId: null, body: payload };
+    }
+    /* The id runs to the first newline. Bound the search so a payload that begins
+     * with the magic but carries no terminator cannot scan the whole file. */
+    const limit = Math.min(payload.length, magic.length + 64);
+    for (let i = magic.length; i < limit; i++) {
+        if (payload[i] === 0x0a) {
+            const id = new TextDecoder().decode(payload.subarray(magic.length, i));
+            return { codecId: id, body: payload.subarray(i + 1) };
+        }
+    }
+    /* Magic present, no terminator: a corrupt header. Reported as an unknown
+     * codec ("") rather than silently treated as JSON, which would fail to parse
+     * and blame the wrong thing. */
+    return { codecId: "", body: payload.subarray(magic.length) };
+}
+/** Pick the codec for an id out of the codecs a build has, or undefined. */
+export function findCodec(id, codecs) {
+    return codecs.find((c) => c.id === id);
+}
+//# sourceMappingURL=compress.js.map

package/dist/save/compress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compress.js","sourceRoot":"","sources":["../../src/save/compress.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAqBH;;;;GAIG;AACH,MAAM,WAAW,GAAG,QAAQ,CAAC;AAE7B,2EAA2E;AAC3E,MAAM,WAAW,GAAG,cAAc,CAAC;AAEnC,8DAA8D;AAC9D,MAAM,UAAU,aAAa,CAAC,EAAU;IACtC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CACb,yBAAyB,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,uBAAuB,CACnE,CAAC;IACJ,CAAC;AACH,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,UAAU,CAAC,IAAgB,EAAE,KAAgB;IAC3D,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACxB,MAAM,IAAI,GAAG,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAClC,MAAM,IAAI,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,GAAG,WAAW,GAAG,KAAK,CAAC,EAAE,IAAI,CAAC,CAAC;IACrE,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;IACtD,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IACjB,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IAC3B,OAAO,GAAG,CAAC;AACb,CAAC;AAUD;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,OAAmB;IAC5C,MAAM,KAAK,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IACpD,IAAI,OAAO,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM;QAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAC3E,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,IAAI,OAAO,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC;YAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IACvE,CAAC;IACD;8EAC0E;IAC1E,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IAC1D,KAAK,IAAI,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;QAC1C,IAAI,OAAO,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;YACxB,MAAM,EAAE,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;YACvE,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;QACxD,CAAC;IACH,CAAC;IACD;;oCAEgC;IAChC,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;AAC/D,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,SAAS,CACvB,EAAU,EACV,MAA4B;IAE5B,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;AACzC,CAAC"}

package/dist/save/description.d.ts

@@ -0,0 +1,61 @@
+/**
+ * wr_description (save.c:47-66): the one-line summary stored INSIDE a savefile.
+ *
+ * Upstream writes this as its own "description" block, and reads it back without
+ * loading the game: `savefile_get_description` (savefile.c:596-621) opens the
+ * file, walks blocks until it finds that one, and returns the string. Two places
+ * show the result to a player:
+ *
+ *   - `list_saves` (main.c:322-328), the `-l` switch: ` %-15s  %s` with the
+ *     description, or ` %-15s` for a file that has none;
+ *   - `get_savefile_selection` (ui-game.c:1258), the `-c` savefile menu.
+ *
+ * Which is why the description lives in the FILE rather than in an index beside
+ * the saves: both readers start from a directory scan and ask each file what it
+ * is. An index would be a second source of truth that can disagree with the
+ * files it describes, and under the no-save-scumming policy (decision 16) the
+ * disagreement costs a character - an orphaned save is one nothing can offer.
+ *
+ * Nothing calls this yet: the savefiles it describes are still localStorage
+ * entries, so there is no file for a description to live in and no directory to
+ * scan (Phase 5, parity/PLATFORM.md). It is ported now, cordoned per the
+ * convention in `player/spell.ts`, because it is the FORMAT the rest of that work
+ * is measured against - two exact player-visible strings the port had nowhere,
+ * and the kind of string neither census can see (both are `%s`-anchored, so a
+ * literal search finds no anchor to miss).
+ */
+/** Exactly the `player` fields wr_description reads. */
+export interface SaveDescriptionSource {
+    /** player->full_name. */
+    readonly fullName: string;
+    /** player->is_dead. */
+    readonly isDead: boolean;
+    /** player->died_from. Only read on the dead branch. */
+    readonly diedFrom: string;
+    /** player->lev. */
+    readonly level: number;
+    /** player->race->name. */
+    readonly raceName: string;
+    /** player->class->name. */
+    readonly className: string;
+    /** player->depth. */
+    readonly depth: number;
+}
+/**
+ * `savefile_desc` is `char[120]` (savefile.c:588) and `rd_string` truncates into
+ * it, so a description read back from a savefile is at most 119 characters plus
+ * the terminator. Applied on the WRITE side here, which is where upstream's
+ * `buf[1024]` would have let a long name through: reading it back would silently
+ * shorten it, and a value that changes when it makes a round trip is a value two
+ * screens can disagree about.
+ */
+export declare const SAVEFILE_DESC_LEN = 120;
+/**
+ * The description string for a savefile.
+ *
+ * Both branches are verbatim from save.c:53-63. The dead one names what killed
+ * the character rather than where they were, because a tombstone's depth is not
+ * what a player is looking for in a list of saves.
+ */
+export declare function saveDescription(p: SaveDescriptionSource): string;
+//# sourceMappingURL=description.d.ts.map

package/dist/save/description.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"description.d.ts","sourceRoot":"","sources":["../../src/save/description.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,wDAAwD;AACxD,MAAM,WAAW,qBAAqB;IACpC,yBAAyB;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,uBAAuB;IACvB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,uDAAuD;IACvD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,mBAAmB;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,0BAA0B;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2BAA2B;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,qBAAqB;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,qBAAqB,GAAG,MAAM,CAOhE"}

package/dist/save/description.js

@@ -0,0 +1,51 @@
+/**
+ * wr_description (save.c:47-66): the one-line summary stored INSIDE a savefile.
+ *
+ * Upstream writes this as its own "description" block, and reads it back without
+ * loading the game: `savefile_get_description` (savefile.c:596-621) opens the
+ * file, walks blocks until it finds that one, and returns the string. Two places
+ * show the result to a player:
+ *
+ *   - `list_saves` (main.c:322-328), the `-l` switch: ` %-15s  %s` with the
+ *     description, or ` %-15s` for a file that has none;
+ *   - `get_savefile_selection` (ui-game.c:1258), the `-c` savefile menu.
+ *
+ * Which is why the description lives in the FILE rather than in an index beside
+ * the saves: both readers start from a directory scan and ask each file what it
+ * is. An index would be a second source of truth that can disagree with the
+ * files it describes, and under the no-save-scumming policy (decision 16) the
+ * disagreement costs a character - an orphaned save is one nothing can offer.
+ *
+ * Nothing calls this yet: the savefiles it describes are still localStorage
+ * entries, so there is no file for a description to live in and no directory to
+ * scan (Phase 5, parity/PLATFORM.md). It is ported now, cordoned per the
+ * convention in `player/spell.ts`, because it is the FORMAT the rest of that work
+ * is measured against - two exact player-visible strings the port had nowhere,
+ * and the kind of string neither census can see (both are `%s`-anchored, so a
+ * literal search finds no anchor to miss).
+ */
+/**
+ * `savefile_desc` is `char[120]` (savefile.c:588) and `rd_string` truncates into
+ * it, so a description read back from a savefile is at most 119 characters plus
+ * the terminator. Applied on the WRITE side here, which is where upstream's
+ * `buf[1024]` would have let a long name through: reading it back would silently
+ * shorten it, and a value that changes when it makes a round trip is a value two
+ * screens can disagree about.
+ */
+export const SAVEFILE_DESC_LEN = 120;
+/**
+ * The description string for a savefile.
+ *
+ * Both branches are verbatim from save.c:53-63. The dead one names what killed
+ * the character rather than where they were, because a tombstone's depth is not
+ * what a player is looking for in a list of saves.
+ */
+export function saveDescription(p) {
+    const desc = p.isDead
+        ? /* "%s, dead (%s)" (L54-56) */
+            `${p.fullName}, dead (${p.diedFrom})`
+        : /* "%s, L%d %s %s, at DL%d" (L58-63) */
+            `${p.fullName}, L${p.level} ${p.raceName} ${p.className}, at DL${p.depth}`;
+    return desc.slice(0, SAVEFILE_DESC_LEN - 1);
+}
+//# sourceMappingURL=description.js.map

package/dist/save/description.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"description.js","sourceRoot":"","sources":["../../src/save/description.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAoBH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAErC;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,CAAwB;IACtD,MAAM,IAAI,GAAG,CAAC,CAAC,MAAM;QACnB,CAAC,CAAC,8BAA8B;YAC9B,GAAG,CAAC,CAAC,QAAQ,WAAW,CAAC,CAAC,QAAQ,GAAG;QACvC,CAAC,CAAC,uCAAuC;YACvC,GAAG,CAAC,CAAC,QAAQ,MAAM,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,SAAS,UAAU,CAAC,CAAC,KAAK,EAAE,CAAC;IAC/E,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,iBAAiB,GAAG,CAAC,CAAC,CAAC;AAC9C,CAAC"}

package/dist/save/integrity.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Save integrity: a tamper-DETERRENT layer over the raw savefile bytes.
+ *
+ * Context (see ./buffer and the save-scum policy): upstream Angband
+ * stamps each block with a 32-bit additive checksum for corruption
+ * detection. That is trivially recomputable. This module adds an
+ * optional whole-file digest so that a casual hand-edit of the stored
+ * bytes (e.g. via browser DevTools on an IndexedDB save) no longer
+ * verifies, which raises the bar against save-scumming.
+ *
+ * HONEST CEILING: any verifier that runs on the client also ships to the
+ * client, so a determined user can read it and recompute the digest.
+ * This is a DETERRENT, not real protection. Unforgeable anti-tamper
+ * requires a secret the client never holds - i.e. server-authoritative
+ * saves, which belong to the networking seam (a plugin), not core.
+ *
+ * MODDABILITY: the digest is a seam. A host or mod may inject a stronger
+ * provider (for example SHA-256 via SubtleCrypto, or an HMAC keyed by a
+ * server secret in a networked deployment) by implementing SaveIntegrity.
+ */
+/** A pluggable save-integrity provider. Digests are hex strings. */
+export interface SaveIntegrity {
+    /** Stable identifier persisted alongside the digest. */
+    readonly id: string;
+    /** Compute a digest over the given bytes. */
+    digest(bytes: Uint8Array): string;
+}
+/**
+ * The built-in default: FNV-1a (64-bit, emitted as 16 hex chars). It is
+ * a NON-CRYPTOGRAPHIC hash - far more diffusing than an additive sum, so
+ * it catches casual edits, but not a security primitive. Zero-dependency
+ * and synchronous so core stays environment-neutral.
+ */
+export declare const fnv1aIntegrity: SaveIntegrity;
+/**
+ * Append an integrity trailer (provider id + digest) to a savefile byte
+ * stream. The trailer sits after the block data and is excluded from the
+ * digest, so verification digests exactly the original bytes.
+ */
+export declare function stampSavefile(bytes: Uint8Array, provider?: SaveIntegrity): Uint8Array;
+/** The outcome of checking a stamped savefile. */
+export interface IntegrityResult {
+    /** The original savefile bytes with the trailer removed. */
+    payload: Uint8Array;
+    /** True when a trailer was present and its digest matched. */
+    verified: boolean;
+    /** True when no trailer was found (an unstamped/legacy save). */
+    unstamped: boolean;
+    /** Provider id recorded in the trailer, if any. */
+    providerId?: string;
+}
+/**
+ * Split off and verify an integrity trailer. A caller decides policy: a
+ * no-save-scum build should reject `verified === false`, while still
+ * tolerating `unstamped` legacy saves if it chooses. Verification uses
+ * the supplied provider (whose id must match the trailer's).
+ */
+export declare function verifyStampedSavefile(bytes: Uint8Array, provider?: SaveIntegrity): IntegrityResult;
+//# sourceMappingURL=integrity.d.ts.map

package/dist/save/integrity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"integrity.d.ts","sourceRoot":"","sources":["../../src/save/integrity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,oEAAoE;AACpE,MAAM,WAAW,aAAa;IAC5B,wDAAwD;IACxD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAAC;CACnC;AAED;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,aA4B5B,CAAC;AAKF;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,UAAU,EACjB,QAAQ,GAAE,aAA8B,GACvC,UAAU,CAQZ;AAED,kDAAkD;AAClD,MAAM,WAAW,eAAe;IAC9B,4DAA4D;IAC5D,OAAO,EAAE,UAAU,CAAC;IACpB,8DAA8D;IAC9D,QAAQ,EAAE,OAAO,CAAC;IAClB,iEAAiE;IACjE,SAAS,EAAE,OAAO,CAAC;IACnB,mDAAmD;IACnD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,UAAU,EACjB,QAAQ,GAAE,aAA8B,GACvC,eAAe,CAcjB"}