@rpgm-tools/neo-angband-core 0.10.0

package/dist/session/save.js

@@ -0,0 +1,1306 @@
+/**
+ * JSON save/load (PORT_PLAN.md decision 9): the entity serializers that
+ * turn a live GameState into plain JSON and back. The format is the port's
+ * own (the C binary blocks of save.c/load.c are replaced by design); WHAT
+ * is saved follows upstream savefile semantics - notably the RNG state is
+ * persisted (save.c wr_randomizer), which is what the no-save-scum posture
+ * rides on (decisions 16/22): reloading resumes the same stream.
+ *
+ * References into bound registries (races, kinds, egos, artifacts, trap
+ * kinds, classes) are saved as stable indices/names and re-resolved against
+ * the pack on load, so a save is data + pack, never code. Raw effect chains
+ * and kind-owned text re-point at the kind on load rather than being
+ * copied into the save.
+ *
+ * Integrity: serializeGame produces the JSON payload; callers stamp/verify
+ * bytes with save/integrity.ts (stampSavefile / verifyStampedSavefile),
+ * the decision-16b tamper deterrent.
+ *
+ * BLOCK MAP (save.c wr_* / load.c rd_* -> the field this file writes). There is
+ * deliberately no per-block function pair: the C block table is replaced by one
+ * JSON document, so W1's question is field coverage, not symbol presence. Each
+ * row is proved by save-fields.test.ts, the C-derived coverage guard.
+ *
+ *   wr_description   (save.c:49)   -> not a FIELD: the exact string is ported in
+ *                                    save/description.ts and derived from
+ *                                    fullName / lev / race / class / depth,
+ *                                    which this document already carries. In a
+ *                                    JSON save it need not be stored at all, and
+ *                                    storing it would create the second source
+ *                                    of truth upstream's own readers avoid by
+ *                                    scanning a directory and asking each file.
+ *   wr_randomizer    (save.c:286)  -> SavedGame.rng
+ *   wr_options       (save.c:314)  -> SavedGame.options (SIDEBAR_MODE is UI)
+ *   wr_messages      (save.c:339)  -> SavedGame.messages
+ *   wr_monster_memory(save.c:356)  -> SavedGame.lore (whole record, not just
+ *                                    pkills/thefts: the port has no lore.txt)
+ *   wr_object_memory (save.c:377)  -> flavor.aware / .tried, everseen.kinds,
+ *                                    ignore.kindAware / .kindUnaware
+ *   wr_quests        (save.c:405)  -> player.quests
+ *   wr_player        (save.c:418)  -> SavedPlayer + SavedGame.actor / arena /
+ *                                    nameSuffix / skipCmdCoercion / unignoring /
+ *                                    restingTurn
+ *   wr_ignore        (save.c:514)  -> SavedGame.ignore, .autoinscriptions,
+ *                                    everseen.egos. GAP: the rune-note block
+ *                                    (save.c:589-605) has no counterpart -
+ *                                    rune_note is a ledgered deferral.
+ *   wr_misc          (save.c:610)  -> randartSeed, seedFlavor, player.totalWinner,
+ *                                    player.noscore, isDead, turn, player.objKnown
+ *   wr_artifacts     (save.c:674)  -> artifactsCreated / Seen / Everseen
+ *   wr_player_hp     (save.c:692)  -> player.playerHp
+ *   wr_player_spells (save.c:702)  -> player.spellFlags / .spellOrder
+ *   wr_gear_aux      (save.c:715)  -> gear (+ player.equipment slot map)
+ *   wr_gear          (save.c:737)  -> ditto; the gear_k known twin is N/A
+ *   wr_stores        (save.c:744)  -> SavedGame.stores
+ *   wr_dungeon_aux   (save.c:774)  -> ChunkSquaresData (+ currentJoins)
+ *   wr_objects_aux   (save.c:873)  -> SavedGame.floor
+ *   wr_monsters_aux  (save.c:915)  -> SavedGame.monsters / .groups
+ *   wr_traps_aux     (save.c:933)  -> SavedGame.traps
+ *   wr_dungeon       (save.c:959)  -> dungeonDepth, daycount, actor.grid
+ *   wr_objects       (save.c:980)  -> floor      (player->cave twin N/A)
+ *   wr_monsters      (save.c:986)  -> monsters   (player->cave twin N/A)
+ *   wr_traps         (save.c:992)  -> traps      (player->cave twin N/A)
+ *   wr_chunks        (save.c:1001) -> levelCache + townChunk
+ *   wr_history       (save.c:1048) -> player.hist
+ *   wr_item          (save.c:69)   -> SavedObject      (obj->oidx N/A)
+ *   wr_monster       (save.c:201)  -> SavedMonster
+ *   wr_trap          (save.c:261)  -> SavedTrap
+ */
+import { loc } from "../loc.js";
+import { FlagSet } from "../bitflag.js";
+import { Chunk, SQUARE_SIZE } from "../world/chunk.js";
+import { buildRuneList, runeKey } from "../obj/knowledge.js";
+import { blankMonster, GROUP_MAX } from "../mon/monster.js";
+import { blankPlayer } from "../player/player.js";
+import { MessageLog } from "../msg.js";
+import { newKnownMap } from "../game/known.js";
+import { fnv1aIntegrity, stampSavefile, verifyStampedSavefile, } from "../save/integrity.js";
+import { applyCodec, findCodec, stripCodec } from "../save/compress.js";
+import { PY_MAX_LEVEL, TMD_MAX } from "../player/types.js";
+/**
+ * The save format version this build writes. Version 2 replaced every numeric
+ * content index (kidx/eidx/aidx/ridx/tidx/feat, and the positional curse/
+ * brand/slay arrays) with the namespaced string ids of mod/ids.ts, the
+ * load-bearing rule of the mod substrate (MOD_LIFECYCLE decision 1). Version 3
+ * finished that job: `flavor`, `everseen` and `ignore` were the last blocks
+ * still keyed by raw kidx/eidx, and the rune-autoinscription block of wr_ignore
+ * (save.c:586-605) arrived with them. Older saves are not migrated: the game is
+ * pre-1.0 and the save format is still settling, so loadGame rejects them and
+ * the host starts a fresh game.
+ */
+export const SAVE_VERSION = 3;
+export function serializeObject(obj, ids) {
+    return {
+        kindId: ids.kindId(obj.kind.kidx),
+        egoId: obj.ego ? ids.egoId(obj.ego.eidx) : null,
+        artifactId: obj.artifact ? ids.artifactId(obj.artifact.aidx) : null,
+        grid: obj.grid ? { x: obj.grid.x, y: obj.grid.y } : null,
+        tval: obj.tval,
+        sval: obj.sval,
+        pval: obj.pval,
+        ...(obj.knownPval !== undefined ? { knownPval: obj.knownPval } : {}),
+        weight: obj.weight,
+        dd: obj.dd,
+        ds: obj.ds,
+        ac: obj.ac,
+        toA: obj.toA,
+        toH: obj.toH,
+        toD: obj.toD,
+        flags: Array.from(obj.flags.bits),
+        modifiers: [...obj.modifiers],
+        elInfo: obj.elInfo.map((e) => ({ ...e })),
+        brands: serializeBrandList(obj.brands, ids),
+        slays: serializeSlayList(obj.slays, ids),
+        curses: serializeCurseList(obj.curses, ids),
+        time: { ...obj.time },
+        timeout: obj.timeout,
+        number: obj.number,
+        notice: obj.notice,
+        heldMIdx: obj.heldMIdx,
+        mimickingMIdx: obj.mimickingMIdx,
+        origin: obj.origin,
+        originDepth: obj.originDepth,
+        originRaceId: obj.originRace ? ids.raceId(obj.originRace) : null,
+        note: obj.note,
+        effectPresent: obj.effect !== null,
+        activationIndex: obj.activation?.index ?? 0,
+    };
+}
+/** Brand booleans -> the ids of the set brands (drops the dense zeroes). */
+function serializeBrandList(brands, ids) {
+    if (!brands)
+        return null;
+    const out = [];
+    for (let i = 1; i < brands.length; i++)
+        if (brands[i])
+            out.push(ids.brandId(i));
+    return out;
+}
+/** Slay booleans -> the ids of the set slays. */
+function serializeSlayList(slays, ids) {
+    if (!slays)
+        return null;
+    const out = [];
+    for (let i = 1; i < slays.length; i++)
+        if (slays[i])
+            out.push(ids.slayId(i));
+    return out;
+}
+/** Curse data array -> {id,power,timeout} for the powered curses only. */
+function serializeCurseList(curses, ids) {
+    if (!curses)
+        return null;
+    const out = [];
+    for (let i = 1; i < curses.length; i++) {
+        const c = curses[i];
+        if (c && c.power > 0) {
+            out.push({ id: ids.curseId(i), power: c.power, timeout: c.timeout });
+        }
+    }
+    return out.length > 0 ? out : null;
+}
+/** obj_k->curses (power 1 = rune known) -> the ids of the known curses. */
+function serializeKnownCurseList(curses, ids) {
+    const out = [];
+    for (let i = 1; i < curses.length; i++)
+        if (curses[i])
+            out.push(ids.curseId(i));
+    return out;
+}
+export function deserializeObject(data, reg, ids) {
+    const kidx = ids.kindIndex(data.kindId);
+    const kind = kidx !== undefined ? reg.kinds[kidx] : undefined;
+    if (!kind)
+        throw new Error(`save: unknown object kind ${data.kindId}`);
+    const aIdx = data.artifactId !== null ? ids.artifactIndex(data.artifactId) : undefined;
+    const artifact = aIdx !== undefined ? (reg.artifacts[aIdx] ?? null) : null;
+    const eIdx = data.egoId !== null ? ids.egoIndex(data.egoId) : undefined;
+    const ego = eIdx !== undefined ? (reg.egos[eIdx] ?? null) : null;
+    const originIdx = data.originRaceId !== null ? ids.raceIndex(data.originRaceId) : undefined;
+    const effectPresent = data.effectPresent ?? true;
+    /* load.c:223-232 resolves the saved activation index, not kind defaults. */
+    const activation = data.activationIndex !== undefined
+        ? data.activationIndex > 0
+            ? (reg.activations[data.activationIndex] ?? null)
+            : null
+        : (artifact?.activation ?? kind.activation);
+    return {
+        kind,
+        ego,
+        artifact,
+        grid: data.grid ? loc(data.grid.x, data.grid.y) : null,
+        tval: data.tval,
+        sval: data.sval,
+        pval: data.pval,
+        ...(data.knownPval !== undefined ? { knownPval: data.knownPval } : {}),
+        weight: data.weight,
+        dd: data.dd,
+        ds: data.ds,
+        ac: data.ac,
+        toA: data.toA,
+        toH: data.toH,
+        toD: data.toD,
+        flags: new FlagSet(Uint8Array.from(data.flags)),
+        modifiers: [...data.modifiers],
+        elInfo: data.elInfo.map((e) => ({ ...e })),
+        brands: deserializeBrandList(data.brands, reg, ids),
+        slays: deserializeSlayList(data.slays, reg, ids),
+        curses: deserializeCurseList(data.curses, reg, ids),
+        /* Kind-owned data re-points at the bound kind. */
+        effect: effectPresent ? kind.effect : null,
+        effectMsg: effectPresent ? kind.effectMsg : "",
+        activation,
+        time: { ...data.time },
+        timeout: data.timeout,
+        number: data.number,
+        notice: data.notice,
+        heldMIdx: data.heldMIdx,
+        mimickingMIdx: data.mimickingMIdx,
+        origin: data.origin,
+        originDepth: data.originDepth,
+        originRace: originIdx ?? 0,
+        note: data.note,
+    };
+}
+/** Brand ids -> the dense boolean array (length brandMax), or null. */
+function deserializeBrandList(saved, reg, ids) {
+    if (!saved)
+        return null;
+    const out = new Array(reg.brandMax).fill(false);
+    for (const id of saved) {
+        const i = ids.brandIndex(id);
+        if (i !== undefined)
+            out[i] = true;
+    }
+    return out;
+}
+/** Slay ids -> the dense boolean array (length slayMax), or null. */
+function deserializeSlayList(saved, reg, ids) {
+    if (!saved)
+        return null;
+    const out = new Array(reg.slayMax).fill(false);
+    for (const id of saved) {
+        const i = ids.slayIndex(id);
+        if (i !== undefined)
+            out[i] = true;
+    }
+    return out;
+}
+/** Curse id list -> the dense CurseData array (length curseMax), or null. */
+function deserializeCurseList(saved, reg, ids) {
+    if (!saved)
+        return null;
+    const out = [];
+    for (let i = 0; i < reg.curseMax; i++)
+        out.push({ power: 0, timeout: 0 });
+    for (const c of saved) {
+        const i = ids.curseIndex(c.id);
+        if (i !== undefined)
+            out[i] = { power: c.power, timeout: c.timeout };
+    }
+    return out;
+}
+/** Known-curse ids -> the dense obj_k->curses array (power 1 = known). */
+function deserializeKnownCurseList(saved, reg, ids) {
+    const out = new Array(reg.curseMax).fill(0);
+    for (const id of saved) {
+        const i = ids.curseIndex(id);
+        if (i !== undefined)
+            out[i] = 1;
+    }
+    return out;
+}
+export function serializeMonster(mon, ids) {
+    return {
+        raceId: ids.raceId(mon.race.ridx),
+        originalRaceId: mon.originalRace ? ids.raceId(mon.originalRace.ridx) : null,
+        midx: mon.midx,
+        grid: { x: mon.grid.x, y: mon.grid.y },
+        hp: mon.hp,
+        maxhp: mon.maxhp,
+        mTimed: Array.from(mon.mTimed),
+        mspeed: mon.mspeed,
+        energy: mon.energy,
+        cdis: mon.cdis,
+        mflag: Array.from(mon.mflag.bits),
+        mimickedObj: mon.mimickedObj,
+        heldObj: mon.heldObj.map((o) => serializeObject(o, ids)),
+        attr: mon.attr,
+        target: {
+            grid: { x: mon.target.grid.x, y: mon.target.grid.y },
+            midx: mon.target.midx,
+        },
+        groupInfo: mon.groupInfo.map((g) => ({ ...g })),
+        minRange: mon.minRange,
+        bestRange: mon.bestRange,
+        knownPstateFlags: Array.from(mon.knownPstate.flags.bits),
+        knownPstateElInfo: Array.from(mon.knownPstate.elInfo),
+    };
+}
+/** rd_monster (load.c:259), over JSON instead of the binary block. */
+export function deserializeMonster(data, monsters, objects, ids) {
+    const ridx = ids.raceIndex(data.raceId);
+    const race = ridx !== undefined ? monsters.races[ridx] : undefined;
+    if (!race)
+        throw new Error(`save: unknown race ${data.raceId}`);
+    const mon = blankMonster(race);
+    const origRidx = data.originalRaceId !== null
+        ? ids.raceIndex(data.originalRaceId)
+        : undefined;
+    mon.originalRace = origRidx !== undefined ? (monsters.races[origRidx] ?? null) : null;
+    mon.midx = data.midx;
+    mon.grid = loc(data.grid.x, data.grid.y);
+    mon.hp = data.hp;
+    mon.maxhp = data.maxhp;
+    mon.mTimed.set(data.mTimed);
+    mon.mspeed = data.mspeed;
+    mon.energy = data.energy;
+    mon.cdis = data.cdis;
+    mon.mflag.bits.set(data.mflag);
+    if (data.knownPstateFlags) {
+        /* load.c:302 restores known_pstate.flags before the monster goes live. */
+        mon.knownPstate.flags.bits.set(data.knownPstateFlags);
+    }
+    if (data.knownPstateElInfo) {
+        /* load.c:305 restores known_pstate.el_info[].res_level before live use. */
+        mon.knownPstate.elInfo.set(data.knownPstateElInfo);
+    }
+    mon.mimickedObj = data.mimickedObj;
+    mon.heldObj = data.heldObj.map((o) => deserializeObject(o, objects, ids));
+    mon.attr = data.attr;
+    mon.target = {
+        grid: loc(data.target.grid.x, data.target.grid.y),
+        midx: data.target.midx,
+    };
+    for (let i = 0; i < GROUP_MAX; i++) {
+        const g = data.groupInfo[i];
+        if (g)
+            mon.groupInfo[i] = { ...g };
+    }
+    mon.minRange = data.minRange;
+    mon.bestRange = data.bestRange;
+    return mon;
+}
+export function serializePlayer(p, ids) {
+    return {
+        raceName: p.race.name,
+        clsName: p.cls.name,
+        hitdie: p.hitdie,
+        expFactor: p.expFactor,
+        age: p.age,
+        ht: p.ht,
+        wt: p.wt,
+        au: p.au,
+        maxLev: p.maxLev,
+        lev: p.lev,
+        maxExp: p.maxExp,
+        exp: p.exp,
+        expFrac: p.expFrac,
+        maxDepth: p.maxDepth,
+        recallDepth: p.recallDepth,
+        wordRecall: p.wordRecall,
+        deepDescent: p.deepDescent,
+        mhp: p.mhp,
+        chp: p.chp,
+        chpFrac: p.chpFrac,
+        msp: p.msp,
+        csp: p.csp,
+        cspFrac: p.cspFrac,
+        statMax: [...p.statMax],
+        statCur: [...p.statCur],
+        statMap: [...p.statMap],
+        statBirth: [...p.statBirth],
+        timed: Array.from(p.timed),
+        spellFlags: [...p.spellFlags],
+        spellOrder: [...p.spellOrder],
+        playerHp: [...p.playerHp],
+        auBirth: p.auBirth,
+        htBirth: p.htBirth,
+        wtBirth: p.wtBirth,
+        fullName: p.fullName,
+        diedFrom: p.diedFrom,
+        noscore: p.noscore,
+        history: p.history,
+        hist: p.hist.map((e) => ({
+            type: e.type,
+            dlev: e.dlev,
+            clev: e.clev,
+            artifactName: ids.artifactName(e.aIdx) ?? "",
+            turn: e.turn,
+            event: e.event,
+        })),
+        equipment: [...p.equipment],
+        objKnown: {
+            modifiers: [...p.objKnown.modifiers],
+            toA: p.objKnown.toA,
+            toH: p.objKnown.toH,
+            toD: p.objKnown.toD,
+            dd: p.objKnown.dd,
+            ds: p.objKnown.ds,
+            ac: p.objKnown.ac,
+            elInfo: p.objKnown.elInfo.map((e) => ({ ...e })),
+            flags: Array.from(p.objKnown.flags.bits),
+            /* The learned runes save as the ids of the known brands/slays/curses. */
+            brands: serializeBrandList(p.objKnown.brands, ids) ?? [],
+            slays: serializeSlayList(p.objKnown.slays, ids) ?? [],
+            curses: serializeKnownCurseList(p.objKnown.curses, ids),
+        },
+        shapeName: p.shape ? p.shape.name : null,
+        skills: [...p.skills],
+        upkeep: { ...p.upkeep },
+        quests: p.quests.map((q) => ({ ...q })),
+        totalWinner: p.totalWinner,
+    };
+}
+export function deserializePlayer(data, players, objReg, ids) {
+    const race = players.raceByName(data.raceName);
+    const cls = players.classByName(data.clsName);
+    if (!race || !cls) {
+        throw new Error(`save: unknown race/class ${data.raceName}/${data.clsName}`);
+    }
+    const body = players.bodies[race.body] ?? players.bodies[0];
+    const p = blankPlayer(race, cls, body);
+    p.hitdie = data.hitdie;
+    p.expFactor = data.expFactor;
+    p.age = data.age;
+    p.ht = data.ht;
+    p.wt = data.wt;
+    p.au = data.au;
+    /* load.c:767-780 rejects levels outside 1..PY_MAX_LEVEL. */
+    if (data.lev < 1 || data.lev > PY_MAX_LEVEL) {
+        throw new Error(`save: invalid player level ${data.lev}`);
+    }
+    /* load.c:785-789 repairs max_lev, max_depth and recall_depth. */
+    p.maxLev = data.maxLev < data.lev ? data.lev : data.maxLev;
+    p.lev = data.lev;
+    p.maxExp = data.maxExp;
+    p.exp = data.exp;
+    p.expFrac = data.expFrac;
+    p.maxDepth = data.maxDepth ?? 0;
+    if (p.maxDepth < 0)
+        p.maxDepth = 1;
+    p.recallDepth = data.recallDepth ?? 0;
+    if (p.recallDepth <= 0)
+        p.recallDepth = p.maxDepth;
+    p.wordRecall = data.wordRecall ?? 0;
+    p.deepDescent = data.deepDescent ?? 0;
+    p.mhp = data.mhp;
+    p.chp = data.chp;
+    p.chpFrac = data.chpFrac;
+    p.msp = data.msp;
+    p.csp = data.csp;
+    p.cspFrac = data.cspFrac;
+    p.statMax = [...data.statMax];
+    p.statCur = [...data.statCur];
+    p.statMap = [...data.statMap];
+    p.statBirth = [...data.statBirth];
+    /* load.c:807-823 reads only supported timed entries and discards extras. */
+    p.timed.set(data.timed.slice(0, TMD_MAX));
+    p.spellFlags = [...data.spellFlags];
+    p.spellOrder = [...data.spellOrder];
+    p.playerHp = [...data.playerHp];
+    p.auBirth = data.auBirth;
+    p.htBirth = data.htBirth;
+    p.wtBirth = data.wtBirth;
+    /* full_name / died_from / noscore (load.c:661, load.c:966): absent in saves
+     * predating the fields, which restore the blankPlayer defaults ("" / "" / 0). */
+    p.fullName = data.fullName ?? "";
+    /* load.c:791-793 resets died_from whenever HP is non-negative. */
+    p.diedFrom = p.chp >= 0 ? "(alive and well)" : (data.diedFrom ?? "");
+    p.noscore = data.noscore ?? 0;
+    p.history = data.history;
+    p.hist = [];
+    for (const e of data.hist ?? []) {
+        let aIdx = 0;
+        const artifactName = e.artifactName ?? "";
+        if (artifactName) {
+            const artifact = objReg.artifacts.find((a) => a?.name === artifactName);
+            if (!artifact)
+                continue;
+            aIdx = artifact.aidx;
+        }
+        else if (e.aIdx !== undefined) {
+            /* Tolerate the pre-fix JSON shape, while all new saves use names. */
+            aIdx = e.aIdx;
+        }
+        p.hist.push({
+            type: e.type,
+            dlev: e.dlev,
+            clev: e.clev,
+            aIdx,
+            turn: e.turn,
+            event: e.event,
+        });
+    }
+    p.equipment = [...data.equipment];
+    if (data.objKnown) {
+        p.objKnown = {
+            modifiers: [...data.objKnown.modifiers],
+            toA: data.objKnown.toA,
+            toH: data.objKnown.toH,
+            toD: data.objKnown.toD,
+            /* Default to 1 for pre-field saves: dd/ds/ac are obvious birth knowledge
+             * (player_outfit), always 1, so an absent value restores exactly. */
+            dd: data.objKnown.dd ?? 1,
+            ds: data.objKnown.ds ?? 1,
+            ac: data.objKnown.ac ?? 1,
+            elInfo: data.objKnown.elInfo.map((e) => ({ ...e })),
+            flags: new FlagSet(Uint8Array.from(data.objKnown.flags)),
+            brands: deserializeBrandList(data.objKnown.brands, objReg, ids) ?? [],
+            slays: deserializeSlayList(data.objKnown.slays, objReg, ids) ?? [],
+            curses: deserializeKnownCurseList(data.objKnown.curses, objReg, ids),
+        };
+    }
+    else if (data.objKnownModifiers) {
+        /* Legacy pre-#13 save: only the modifier runes were tracked. */
+        p.objKnown.modifiers = [...data.objKnownModifiers];
+    }
+    p.shape =
+        data.shapeName !== null
+            ? (players.shapes.find((s) => s.name === data.shapeName) ?? null)
+            : null;
+    p.skills = [...data.skills];
+    p.upkeep = { ...data.upkeep };
+    p.quests = data.quests ? data.quests.map((q) => ({ ...q })) : [];
+    p.totalWinner = data.totalWinner ?? false;
+    return p;
+}
+/**
+ * Serialize the rolling message log (wr_messages, save.c:339-353): the newest
+ * `cap` messages (default 80, the upstream limit) written oldest-first, each as
+ * text + type. Returns undefined for an empty / absent log so a clean save omits
+ * the block. Faithful to the C: the per-entry repeat count is dropped, so a
+ * reload recollapses through MessageLog.add and every count resets to 1.
+ */
+export function serializeMessages(log, cap = 80) {
+    if (!log || log.num() === 0)
+        return undefined;
+    const num = Math.min(log.num(), cap);
+    const out = [];
+    /* save.c:349 dumps oldest-of-the-kept first (i = num - 1 down to 0). */
+    for (let age = num - 1; age >= 0; age--) {
+        out.push({ str: log.str(age), type: log.type(age) });
+    }
+    return out;
+}
+/**
+ * Rebuild a message log from its saved form (rd_messages, load.c:471-495):
+ * re-add each entry oldest-first via MessageLog.add, exactly as upstream calls
+ * message_add in a forward loop. An absent block (older save / empty log) yields
+ * a fresh empty log.
+ */
+export function deserializeMessages(data) {
+    const log = new MessageLog();
+    if (!data)
+        return log;
+    for (const m of data)
+        log.add(m.str, m.type);
+    return log;
+}
+/** Build the feature legend for every fidx appearing in the terrain grids. */
+function buildFeatLegend(feats, known, ids) {
+    const present = new Set();
+    for (const f of feats)
+        present.add(f);
+    for (const f of known)
+        present.add(f);
+    const legend = [];
+    for (const f of present) {
+        /* Skip sentinels (an unset cell is -1): they carry no feature id and are
+         * pack-independent, so remapFeats leaves them untouched. */
+        const id = ids.featIdOrNull(f);
+        if (id !== null)
+            legend.push([f, id]);
+    }
+    return legend;
+}
+/** aup_info boolean[] (by aidx) -> the ids of the created artifacts. */
+function serializeArtifactsCreated(created, ids) {
+    const out = [];
+    for (let i = 1; i < created.length; i++) {
+        if (created[i])
+            out.push(ids.artifactId(i));
+    }
+    return out;
+}
+/** Serialize one aup_info boolean field as stable artifact names. */
+function serializeArtifactFlags(flags, ids) {
+    const out = [];
+    for (let i = 1; i < flags.length; i++) {
+        if (flags[i])
+            out.push(ids.artifactId(i));
+    }
+    return out;
+}
+/** Serialize a live game (state + flavor knowledge) into plain JSON data. */
+export function serializeGame(state, flavor, seedFlavor, ids, randartSeed = 0, everseen) {
+    const floor = [];
+    for (const pile of state.floor.values()) {
+        const head = pile[0];
+        if (!head || !head.grid)
+            continue;
+        floor.push({
+            x: head.grid.x,
+            y: head.grid.y,
+            objs: pile.map((o) => serializeObject(o, ids)),
+        });
+    }
+    const traps = [];
+    for (const list of state.traps.values()) {
+        const head = list[0];
+        if (!head)
+            continue;
+        traps.push({
+            x: head.grid.x,
+            y: head.grid.y,
+            traps: list.map((t) => ({
+                trapId: ids.trapId(t.tidx),
+                grid: { x: t.grid.x, y: t.grid.y },
+                power: t.power,
+                timeout: t.timeout,
+                flags: Array.from(t.flags.bits),
+            })),
+        });
+    }
+    /* The noise/scent seam (mod/hooks.ts saveNoiseScent). Faithful 4.2.6 omits the
+     * heatmaps from the save - that is upstream's behaviour and upstream's bug - so
+     * with no hook installed the `?? false` below IS the faithful answer. */
+    const chunk = state.chunk.snapshotSquares(state.modHooks?.saveNoiseScent?.() ?? false);
+    const knownFeat = Array.from(state.known.feat);
+    const savedLevelCache = serializeLevelCache(state.levelCache, ids);
+    const autoinscriptions = state.autoinscribe
+        ? serializeAutoinscriptions(state.autoinscribe, ids)
+        : undefined;
+    /* wr_ignore's rune-autoinscription block (save.c:586-605): the count of runes
+     * carrying a note, then `wr_s16b(k)` + the note string for each. The index is
+     * converted to its pack-stable runeKey (see obj/knowledge.ts runeKey); a rune
+     * the running pack no longer builds is dropped. */
+    const runeNoteEntries = [];
+    const liveRuneNotes = state.runeNotes?.entries() ?? [];
+    if (liveRuneNotes.length > 0) {
+        const runes = buildRuneList(state.runeEnv);
+        for (const [i, note] of liveRuneNotes) {
+            const rune = runes[i];
+            if (!rune)
+                continue;
+            runeNoteEntries.push([runeKey(rune), note]);
+        }
+    }
+    const runeNotes = runeNoteEntries.length > 0 ? runeNoteEntries : undefined;
+    return {
+        version: SAVE_VERSION,
+        player: serializePlayer(state.actor.player, ids),
+        actor: {
+            grid: { x: state.actor.grid.x, y: state.actor.grid.y },
+            energy: state.actor.energy,
+            totalEnergy: state.actor.totalEnergy,
+        },
+        gear: {
+            next: state.gear.next,
+            pack: [...state.gear.pack],
+            store: Array.from(state.gear.store.entries()).map(([h, obj]) => [
+                h,
+                serializeObject(obj, ids),
+            ]),
+        },
+        /* C save.c:873-1045 omits the live dungeon objects, monsters, traps and
+         * chunk-list data for a dead player. */
+        ...(state.isDead
+            ? { dungeonDepth: state.chunk.depth }
+            : {
+                chunk,
+                featLegend: buildFeatLegend(chunk.feats, knownFeat, ids),
+                monsters: state.monsters.map((m) => m ? serializeMonster(m, ids) : null),
+                groups: state.groups.map((g) => g ? { index: g.index, leader: g.leader, members: [...g.members] } : null),
+                floor,
+                traps,
+            }),
+        rng: state.rng.getState(),
+        turn: state.turn,
+        playing: state.playing,
+        isDead: state.isDead,
+        flavor: (() => {
+            const raw = flavor.snapshot();
+            return {
+                aware: kidxSetToIds(raw.aware, ids),
+                tried: kidxSetToIds(raw.tried, ids),
+            };
+        })(),
+        ...(everseen
+            ? {
+                everseen: (() => {
+                    const raw = everseen.snapshot();
+                    const egos = [];
+                    for (const eidx of raw.egos) {
+                        const id = ids.egoIdOrNull(eidx);
+                        if (id !== null)
+                            egos.push(id);
+                    }
+                    return { kinds: kidxSetToIds(raw.kinds, ids), egos };
+                })(),
+            }
+            : {}),
+        seedFlavor,
+        ...(state.options ? { options: state.options.snapshot() } : {}),
+        ...(randartSeed ? { randartSeed } : {}),
+        ...(state.artifacts
+            ? {
+                artifactsCreated: serializeArtifactsCreated(state.artifacts.snapshot(), ids),
+                artifactsSeen: serializeArtifactFlags(state.artifacts.snapshotState().seen, ids),
+                artifactsEverseen: serializeArtifactFlags(state.artifacts.snapshotState().everseen, ids),
+            }
+            : {}),
+        ...(!state.isDead && savedLevelCache ? { levelCache: savedLevelCache } : {}),
+        /* chunk->join of the level in play (gap 9.4/9.6): persisted so a first-visit
+         * persistent level aligns its stairs after a reload. Omitted when empty. */
+        ...(!state.isDead && state.currentJoins && state.currentJoins.length > 0
+            ? {
+                currentJoins: state.currentJoins.map((j) => ({
+                    x: j.grid.x,
+                    y: j.grid.y,
+                    feat: j.feat,
+                    /* save.c:850-866 writes x, y, feature and every SQUARE_SIZE byte. */
+                    info: Array.from({ length: SQUARE_SIZE }, (_, i) => j.info?.[i] ?? 0),
+                })),
+            }
+            : {}),
+        ...(autoinscriptions ? { autoinscriptions } : {}),
+        ...(runeNotes ? { runeNotes } : {}),
+        /*
+         * Terrain-only Town cache (wr_chunks, save.c:1001-1044): C always writes
+         * the Town chunk even when birth_levels_persist is off, so a dungeon save
+         * after leaving town reloads the same shops/stairs without redrawing.
+         */
+        ...(() => {
+            if (state.isDead || !state.townChunk)
+                return {};
+            const tc = state.townChunk.snapshotSquares();
+            return {
+                townChunk: tc,
+                townFeatLegend: buildFeatLegend(tc.feats, [], ids),
+            };
+        })(),
+        /* Town stores + accrued daycount (wr_stores / save.c:963). Persisted so the
+         * home stash and shop stock survive save/load (gaps 12.1/12.2/12.3). */
+        ...(() => {
+            const stores = serializeStores(state.stores, ids);
+            return stores ? { stores } : {};
+        })(),
+        ...(state.daycount ? { daycount: state.daycount } : {}),
+        /* Minor persisted player fields (gap 12.6, wr_player). Omitted when at their
+         * defaults so a clean save stays clean and old saves load with 0. */
+        ...(state.restingTurn ? { restingTurn: state.restingTurn } : {}),
+        ...(state.skipCmdCoercion ? { skipCmdCoercion: state.skipCmdCoercion } : {}),
+        ...(state.unignoring ? { unignoring: state.unignoring } : {}),
+        ...(state.nameSuffix ? { nameSuffix: state.nameSuffix } : {}),
+        /* Running message log (gap 12.8, wr_messages): the 80 newest messages,
+         * oldest-first. Omitted for an empty log. */
+        ...(() => {
+            const messages = serializeMessages(state.messages);
+            return messages ? { messages } : {};
+        })(),
+        ...(!state.isDead
+            ? {
+                known: {
+                    feat: knownFeat,
+                    objects: Array.from(state.known.objects.entries()).map(([i, m]) => [
+                        i,
+                        { ch: m.ch, attr: m.attr },
+                    ]),
+                },
+            }
+            : {}),
+        ...(state.arenaLevel
+            ? {
+                arena: {
+                    oldGrid: {
+                        x: state.oldGrid?.x ?? state.actor.grid.x,
+                        y: state.oldGrid?.y ?? state.actor.grid.y,
+                    },
+                },
+            }
+            : {}),
+        ignore: serializeIgnore(state.ignore.snapshot(), ids),
+        lore: Array.from(state.lore.entries()).map(([ridx, l]) => [
+            ids.raceId(ridx),
+            {
+                sights: l.sights,
+                deaths: l.deaths,
+                pkills: l.pkills,
+                thefts: l.thefts,
+                tkills: l.tkills,
+                wake: l.wake,
+                ignore: l.ignore,
+                dropGold: l.dropGold,
+                dropItem: l.dropItem,
+                castInnate: l.castInnate,
+                castSpell: l.castSpell,
+                blowTimesSeen: [...l.blowTimesSeen],
+                blowKnown: [...l.blowKnown],
+                flags: Array.from(l.flags.bits),
+                spellFlags: Array.from(l.spellFlags.bits),
+                allKnown: l.allKnown,
+                armourKnown: l.armourKnown,
+                dropKnown: l.dropKnown,
+                sleepKnown: l.sleepKnown,
+                spellFreqKnown: l.spellFreqKnown,
+                innateFreqKnown: l.innateFreqKnown,
+            },
+        ]),
+    };
+}
+/** Rebuild the monster memory (absent in older saves: none). */
+export function deserializeLore(data, ids) {
+    const store = new Map();
+    if (!data)
+        return store;
+    for (const [raceId, l] of data) {
+        const ridx = ids.raceIndex(raceId);
+        if (ridx === undefined)
+            continue; // race gone (mod removed): drop its lore
+        store.set(ridx, {
+            sights: l.sights,
+            deaths: l.deaths,
+            pkills: l.pkills,
+            thefts: l.thefts,
+            tkills: l.tkills,
+            wake: l.wake,
+            ignore: l.ignore,
+            dropGold: l.dropGold,
+            dropItem: l.dropItem,
+            castInnate: l.castInnate,
+            castSpell: l.castSpell,
+            blowTimesSeen: [...l.blowTimesSeen],
+            blowKnown: [...l.blowKnown],
+            flags: new FlagSet(Uint8Array.from(l.flags)),
+            spellFlags: new FlagSet(Uint8Array.from(l.spellFlags)),
+            allKnown: l.allKnown,
+            armourKnown: l.armourKnown,
+            dropKnown: l.dropKnown,
+            sleepKnown: l.sleepKnown,
+            spellFreqKnown: l.spellFreqKnown,
+            innateFreqKnown: l.innateFreqKnown,
+        });
+    }
+    return store;
+}
+/**
+ * Serialize the per-kind autoinscription registry (obj/knowledge.ts): every
+ * kind with a registered note, keyed by its namespaced kind id (mod-stable,
+ * like serializeObject). Returns undefined when nothing is registered, so a
+ * clean game omits the block entirely. A kind whose id no longer resolves
+ * (unbound in this pack) is dropped.
+ */
+export function serializeAutoinscriptions(registry, ids) {
+    const out = [];
+    for (const [kidx, note] of registry.entries()) {
+        const kindId = ids.kindIdOrNull(kidx);
+        if (kindId === null)
+            continue; // kind unbound in this pack: drop
+        const entry = { kindId };
+        if (note.aware !== undefined)
+            entry.aware = note.aware;
+        if (note.unaware !== undefined)
+            entry.unaware = note.unaware;
+        out.push(entry);
+    }
+    return out.length > 0 ? out : undefined;
+}
+/**
+ * Restore serialized autoinscriptions into a registry (absent in older saves:
+ * nothing to restore). A kind whose id is gone (its defining pack was removed)
+ * is dropped, exactly like deserializeLore drops a removed race's memory.
+ */
+export function deserializeAutoinscriptions(data, registry, ids) {
+    for (const entry of data) {
+        const kidx = ids.kindIndex(entry.kindId);
+        if (kidx === undefined)
+            continue; // kind gone (mod removed): drop its notes
+        if (entry.aware !== undefined)
+            registry.set(kidx, entry.aware, true);
+        if (entry.unaware !== undefined)
+            registry.set(kidx, entry.unaware, false);
+    }
+}
+/**
+ * Convert an IgnoreSettings.snapshot() (raw kidx/eidx, the runtime keying
+ * upstream also uses) into the id-keyed savefile form. A kind or ego the
+ * running pack no longer binds is dropped, like deserializeAutoinscriptions.
+ */
+export function serializeIgnore(data, ids) {
+    const ego = [];
+    for (const key of data.ego) {
+        const sep = key.indexOf(":");
+        const eidx = Number(key.slice(0, sep));
+        const itype = Number(key.slice(sep + 1));
+        const egoId = ids.egoIdOrNull(eidx);
+        if (egoId === null)
+            continue;
+        ego.push([egoId, itype]);
+    }
+    const kindIds = (kidxs) => {
+        const out = [];
+        for (const kidx of kidxs) {
+            const id = ids.kindIdOrNull(kidx);
+            if (id !== null)
+                out.push(id);
+        }
+        return out;
+    };
+    return {
+        level: [...data.level],
+        ego,
+        kindAware: kindIds(data.kindAware),
+        kindUnaware: kindIds(data.kindUnaware),
+        unignoring: data.unignoring ?? false,
+    };
+}
+/** The inverse of serializeIgnore; an id the pack no longer binds is dropped. */
+export function deserializeIgnore(data, ids) {
+    const ego = [];
+    for (const [egoId, itype] of data.ego) {
+        const eidx = ids.egoIndex(egoId);
+        if (eidx === undefined)
+            continue;
+        ego.push(`${eidx}:${itype}`);
+    }
+    const kidxs = (idList) => {
+        const out = [];
+        for (const id of idList) {
+            const kidx = ids.kindIndex(id);
+            if (kidx !== undefined)
+                out.push(kidx);
+        }
+        return out;
+    };
+    return {
+        level: [...data.level],
+        ego,
+        kindAware: kidxs(data.kindAware),
+        kindUnaware: kidxs(data.kindUnaware),
+        unignoring: data.unignoring ?? false,
+    };
+}
+/**
+ * kind->aware / kind->tried (wr_object_memory) and kind/ego ->everseen, by id.
+ * Same reasoning as serializeIgnore: upstream writes them positionally, the
+ * port's document keys them by namespaced id.
+ */
+function kidxSetToIds(kidxs, ids) {
+    const out = [];
+    for (const kidx of kidxs) {
+        const id = ids.kindIdOrNull(kidx);
+        if (id !== null)
+            out.push(id);
+    }
+    return out;
+}
+function idsToKidxSet(idList, ids) {
+    const out = [];
+    for (const id of idList) {
+        const kidx = ids.kindIndex(id);
+        if (kidx !== undefined)
+            out.push(kidx);
+    }
+    return out;
+}
+/** Restore the id-keyed flavor block into the raw-kidx form FlavorKnowledge takes. */
+export function deserializeFlavor(data, ids) {
+    return {
+        aware: idsToKidxSet(data.aware, ids),
+        tried: idsToKidxSet(data.tried, ids),
+    };
+}
+/** Restore the id-keyed everseen block into the raw-index form it takes. */
+export function deserializeEverseen(data, ids) {
+    const egos = [];
+    for (const id of data.egos) {
+        const eidx = ids.egoIndex(id);
+        if (eidx !== undefined)
+            egos.push(eidx);
+    }
+    return { kinds: idsToKidxSet(data.kinds, ids), egos };
+}
+/**
+ * Build the feature index remap from a save's legend: each saved fidx maps to
+ * the current pack's index for the same feature id. When the save and the
+ * running pack agree (the common case), every entry is the identity; the map
+ * is still applied so a re-ordered or extended terrain set loads correctly.
+ * Throws on a legend id the current pack cannot resolve (a removed terrain -
+ * graceful degradation is a Phase 2 quarantine concern).
+ */
+export function buildFeatRemap(legend, ids) {
+    const remap = new Map();
+    if (!legend)
+        return remap;
+    for (const [oldFidx, id] of legend) {
+        const newFidx = ids.featIndex(id);
+        if (newFidx === undefined) {
+            throw new Error(`save: unknown terrain feature ${id}`);
+        }
+        remap.set(oldFidx, newFidx);
+    }
+    return remap;
+}
+/** Apply a feature remap to a terrain index array in place (identity-safe). */
+function remapFeats(feats, remap) {
+    if (remap.size === 0)
+        return [...feats];
+    return feats.map((feat) => remap.get(feat) ?? feat);
+}
+/** Rebuild the map knowledge (absent in older saves: all unknown). */
+export function deserializeKnown(data, width, height, featRemap) {
+    const known = newKnownMap(width, height);
+    if (!data)
+        return known;
+    const feat = remapFeats(data.feat.slice(0, known.feat.length), featRemap);
+    known.feat.set(feat);
+    for (const [i, m] of data.objects) {
+        known.objects.set(i, { ch: m.ch, attr: m.attr });
+    }
+    return known;
+}
+/** Rebuild a Gear store from its saved form. */
+export function deserializeGear(data, reg, ids) {
+    const store = new Map();
+    for (const [h, saved] of data.store) {
+        store.set(h, deserializeObject(saved, reg, ids));
+    }
+    return { store, next: data.next, pack: [...data.pack] };
+}
+/** Rebuild the floor pile map (grid-keyed, pile order preserved). */
+export function deserializeFloor(data, reg, width, ids) {
+    const floor = new Map();
+    for (const entry of data ?? []) {
+        floor.set(entry.y * width + entry.x, entry.objs.map((o) => deserializeObject(o, reg, ids)));
+    }
+    return floor;
+}
+/**
+ * Rebuild the trap map from saved instances against the bound kinds. This is
+ * rd_trap (load.c:359) plus its caller rd_traps_aux (L1473): the per-trap read
+ * is not a separate function here because the port stores traps per grid rather
+ * than as a linked list off the square.
+ */
+export function deserializeTraps(data, kinds, width, ids, onDecoy) {
+    const traps = new Map();
+    for (const entry of data ?? []) {
+        traps.set(entry.y * width + entry.x, entry.traps.map((t) => {
+            const tidx = ids.trapIndex(t.trapId);
+            const kind = tidx !== undefined ? kinds[tidx] : undefined;
+            if (kind === undefined || tidx === undefined) {
+                throw new Error(`save: unknown trap kind ${t.trapId}`);
+            }
+            const grid = loc(t.grid.x, t.grid.y);
+            if (kind.name === "decoy" || kind.desc === "decoy")
+                onDecoy?.(grid);
+            return {
+                tidx,
+                kind,
+                grid,
+                power: t.power,
+                timeout: t.timeout,
+                flags: new FlagSet(Uint8Array.from(t.flags)),
+            };
+        }));
+    }
+    return traps;
+}
+/**
+ * Serialize the live town stores (wr_stores): each shop's proprietor and stock,
+ * in registry order. Returns undefined when the game has no stores yet (never
+ * reached town), so a fresh dungeon-start save omits the block entirely.
+ */
+export function serializeStores(stores, ids) {
+    if (!stores || stores.length === 0)
+        return undefined;
+    return stores.map((store) => ({
+        ownerIndex: store.owner.index,
+        stock: store.stock.map((o) => serializeObject(o, ids)),
+    }));
+}
+/**
+ * Rebuild the live town stores (rd_stores): re-bind each store's immutable
+ * tables from the pack (owners, stocking tables, buy list, bounds) and overlay
+ * the saved proprietor + stock. Matches upstream's positional keying (store i
+ * <-> saved i). Draws NO RNG - the caller has already restored the exact
+ * stream, so store restore must not perturb it (decision 22). A saved store
+ * beyond the current registry length is dropped; a registry store with no saved
+ * counterpart keeps an empty, default-owner shell (re-stocked on town entry).
+ */
+export function deserializeStores(bound, saved, reg, ids, storeInvenMax) {
+    return bound.map((b, i) => {
+        const s = saved?.[i];
+        const owner = (s ? b.owners.find((o) => o.index === s.ownerIndex) : undefined) ??
+            b.owners[0];
+        if (!owner)
+            throw new Error(`save: store ${b.featName} has no owners`);
+        return {
+            feat: b.feat,
+            featName: b.featName,
+            owners: b.owners,
+            owner,
+            alwaysTable: b.alwaysTable,
+            normalTable: b.normalTable,
+            buy: b.buy,
+            turnover: b.turnover,
+            normalStockMin: b.normalStockMin,
+            normalStockMax: b.normalStockMax,
+            stock: s ? s.stock.map((o) => deserializeObject(o, reg, ids)) : [],
+            stockSize: storeInvenMax,
+        };
+    });
+}
+/** aup_info id list -> the boolean[] by aidx that ArtifactState.restore wants. */
+export function deserializeArtifactsCreated(saved, length, ids) {
+    const out = new Array(length).fill(false);
+    if (!saved)
+        return out;
+    for (const id of saved) {
+        const i = ids.artifactIndex(id);
+        if (i !== undefined && i < length)
+            out[i] = true;
+    }
+    return out;
+}
+/** Restore one aup_info boolean field from stable artifact ids. */
+export function deserializeArtifactFlags(saved, length, ids) {
+    const out = new Array(length).fill(false);
+    for (const id of saved ?? []) {
+        const i = ids.artifactIndex(id);
+        if (i !== undefined && i < length)
+            out[i] = true;
+    }
+    return out;
+}
+/**
+ * Rebuild a chunk of the saved dimensions and restore its squares, remapping
+ * the terrain grid through the save's feature legend so feature references
+ * survive a pack change.
+ */
+export function deserializeChunk(data, features, featRemap) {
+    const chunk = new Chunk(features, data.height, data.width);
+    /* load.c:1307-1355 decodes into a fresh cave. Keep the JSON source intact
+     * while applying the equivalent feature remap to fresh data. */
+    const remapped = featRemap.size > 0
+        ? { ...data, feats: remapFeats(data.feats, featRemap) }
+        : data;
+    chunk.restoreSquares(remapped);
+    return chunk;
+}
+/** Serialize one frozen level, reusing the current-level serializers. */
+function serializeStoredLevel(depth, level, ids) {
+    const floor = [];
+    for (const pile of level.floor.values()) {
+        const head = pile[0];
+        if (!head || !head.grid)
+            continue;
+        floor.push({
+            x: head.grid.x,
+            y: head.grid.y,
+            objs: pile.map((o) => serializeObject(o, ids)),
+        });
+    }
+    const traps = [];
+    for (const list of level.traps.values()) {
+        const head = list[0];
+        if (!head)
+            continue;
+        traps.push({
+            x: head.grid.x,
+            y: head.grid.y,
+            traps: list.map((t) => ({
+                trapId: ids.trapId(t.tidx),
+                grid: { x: t.grid.x, y: t.grid.y },
+                power: t.power,
+                timeout: t.timeout,
+                flags: Array.from(t.flags.bits),
+            })),
+        });
+    }
+    const chunk = level.chunk.snapshotSquares();
+    const knownFeat = Array.from(level.known.feat);
+    return {
+        depth,
+        turn: level.turn,
+        chunk,
+        featLegend: buildFeatLegend(chunk.feats, knownFeat, ids),
+        monsters: level.monsters.map((m) => (m ? serializeMonster(m, ids) : null)),
+        groups: level.groups.map((g) => g ? { index: g.index, leader: g.leader, members: [...g.members] } : null),
+        floor,
+        traps,
+        known: {
+            feat: knownFeat,
+            objects: Array.from(level.known.objects.entries()).map(([i, m]) => [
+                i,
+                { ch: m.ch, attr: m.attr },
+            ]),
+        },
+        decoy: level.decoy ? { x: level.decoy.x, y: level.decoy.y } : null,
+        join: level.join.map((j) => ({
+            x: j.grid.x,
+            y: j.grid.y,
+            feat: j.feat,
+            info: Array.from({ length: SQUARE_SIZE }, (_, i) => j.info?.[i] ?? 0),
+        })),
+    };
+}
+/** Serialize the whole frozen-level cache (empty / absent => omitted). */
+export function serializeLevelCache(cache, ids) {
+    if (!cache || cache.size === 0)
+        return undefined;
+    return Array.from(cache.entries()).map(([depth, level]) => serializeStoredLevel(depth, level, ids));
+}
+/**
+ * Rebuild the frozen-level cache (absent in older / default saves: empty).
+ * Reuses the current-level deserializers so a cached level round-trips exactly
+ * like the live one, including per-level feature-legend remapping.
+ */
+export function deserializeLevelCache(data, features, monsters, objects, traps, ids) {
+    const cache = new Map();
+    if (!data)
+        return cache;
+    for (const entry of data) {
+        const featRemap = buildFeatRemap(entry.featLegend, ids);
+        const chunk = deserializeChunk(entry.chunk, features, featRemap);
+        chunk.turn = entry.turn;
+        cache.set(entry.depth, {
+            chunk,
+            monsters: entry.monsters.map((m) => m ? deserializeMonster(m, monsters, objects, ids) : null),
+            groups: entry.groups.map((g) => g
+                ? { index: g.index, leader: g.leader, members: [...g.members] }
+                : null),
+            floor: deserializeFloor(entry.floor, objects, chunk.width, ids),
+            traps: traps
+                ? deserializeTraps(entry.traps, traps, chunk.width, ids)
+                : new Map(),
+            known: deserializeKnown(entry.known, chunk.width, chunk.height, featRemap),
+            decoy: entry.decoy ? loc(entry.decoy.x, entry.decoy.y) : null,
+            turn: entry.turn,
+            /* chunk->join stair connectors; tolerate absence for pre-field saves. */
+            /* load.c:1366-1383 restores connector info; load.c:1653-1678 remaps
+             * the saved feature through the current feature table. */
+            join: (entry.join ?? []).map((j) => ({
+                grid: loc(j.x, j.y),
+                feat: featRemap.get(j.feat) ?? j.feat,
+                ...(j.info ? { info: [...j.info] } : {}),
+            })),
+        });
+    }
+    return cache;
+}
+/* ------------------------------------------------------------------ *
+ * Stamped bytes (the file/localStorage form).
+ * ------------------------------------------------------------------ */
+/**
+ * JSON-encode a save, optionally compress it, and stamp it with the integrity
+ * trailer (16b).
+ *
+ * ORDER: JSON -> codec -> stamp. The digest therefore covers the bytes that are
+ * actually stored, and the trailer stays findable without running a decompressor
+ * first - which matters because an unknown codec must still be diagnosable.
+ * Passing no codec writes the bare JSON every earlier build wrote.
+ */
+export function encodeSavedGame(save, provider = fnv1aIntegrity, codec) {
+    const json = new TextEncoder().encode(JSON.stringify(save));
+    return stampSavefile(codec ? applyCodec(json, codec) : json, provider);
+}
+/**
+ * Verify and parse stamped save bytes. A failed digest still parses (the
+ * warn-and-label posture of decision 16b - the deterrent is honest, not a
+ * lock), with verified=false for the caller to surface.
+ *
+ * `codecs` are the compressors this build can run. An uncompressed save needs
+ * none, so a caller that never compresses can keep ignoring this argument.
+ */
+export function decodeSavedGame(bytes, provider = fnv1aIntegrity, codecs = []) {
+    const result = verifyStampedSavefile(bytes, provider);
+    const { codecId, body } = stripCodec(result.payload);
+    const base = {
+        verified: result.verified,
+        unstamped: result.unstamped ?? false,
+        codecId,
+    };
+    let payload = body;
+    if (codecId !== null) {
+        const codec = findCodec(codecId, codecs);
+        if (!codec)
+            return { ...base, save: null, unknownCodec: codecId };
+        try {
+            payload = codec.decompress(body);
+        }
+        catch {
+            /* A codec we HAVE that cannot read these bytes is genuine damage. */
+            return { ...base, save: null };
+        }
+    }
+    let save = null;
+    try {
+        save = JSON.parse(new TextDecoder().decode(payload));
+    }
+    catch {
+        save = null;
+    }
+    return { ...base, save };
+}
+//# sourceMappingURL=save.js.map