@datamoc/mw_games 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -7,6 +7,58 @@ the public API may still change between minor versions.
 
 ## [Unreleased]
 
+## [0.15.0] - 2026-09-19
+
+### Added
+
+- `mwl.MwlTableReference` and `MwlValidationOptions.tableReferences` - declarative
+  cross-table reference checks (item 362, from the Pixel Dungeon study's proposal P21). A
+  table column declares `references: { table, column }` or `oneOf: [...]`, and
+  `validateCatalog` checks every cell once for all tables, reporting `MWL_TABLE_REFERENCE`
+  with the table, the row, and the offending value. The declarations' contents (which column
+  points where, which set is legal) stay game data in the consuming repository; absent or
+  empty cells are skipped and a `list` cell checks each entry under the table's own
+  delimiter.
+
+- `core.Settings`/`GameSettings`/`SettingsOptions`/`CustomSettingValue` - persisted
+  player settings (item 363): music and sound-effect levels, master mute, zoom
+  preference, key bindings applied to `Input` on load, and a game-defined `custom` bag
+  (`hints`, `violence`, ...). `defaultSettings` names the fresh-game values,
+  `effectiveMusicVolume`/`effectiveSfxVolume` read 0 while muted, and corrupt storage
+  reads as defaults.
+
+- `two-d/ui.SettingsScreen`/`SettingsCustomRow` - a ready-made settings screen over
+  `core.Settings` (item 364): music/sfx sliders, mute checkbox, zoom slider, one row
+  per `custom` descriptor (boolean/number/choice), an embedded controls page that
+  writes rebinds back into `Settings` on exit, and a reset row.
+
+- Auto-pause and auto-mute on page hide (item 365): `Game` suspends the loop and
+  silences its `audio` rig while hidden and resumes both on show (`autoPause`, on by
+  default), via `suspend`/`resume` that park the clock at 0 and route through the top
+  scene's `onSuspend`/`onResume`. `Music`/`Sound`/`Orchestrator` gain matching
+  `suspend`/`resume`, and the player's own mute setting is never touched.
+
+- Frame-time quality scaling over the static device fit (item 366): a `QualityScaler`
+  steps the backing-store ratio down after sustained over-budget frames and back up
+  only after a much longer streak inside budget, wired to `Game` via the
+  `qualityScaling` option (off unless given) with the fitted ratio as its ceiling.
+
+- Audio ducking for dialogue and menus (item 367): `Music.duck` glides to an
+  attenuated level until `unduck`, through the existing fade path, with tracks started
+  while ducked starting ducked and pending fades retargeted. `Sound` is untouched.
+
+- A discrete meter widget, `two-d/ui.Meter` (item 368): N icons with a value filled,
+  the heart row or star rating to `Bar`'s continuous fill. Fractions clip mid-icon
+  through a mask, so halves need no extra art; flat theme pips by default, a
+  game-supplied filled/empty texture pair otherwise.
+
+- Animate only what is on screen, `two-d/render.SpriteGroup`/`isOnScreen` (item 369):
+  `update(camera, dt)` advances the members inside `camera.view` (plus `margin`) and leaves
+  the rest on their current frame. Members are `AnimatedSprite`s, `ParticleEmitter`s, or
+  anything with `x`/`y` in world units plus `update(dt)`; skipped members resume where they
+  left off, and a rotated camera tests the same over-inclusive box `TileMap.cull` uses, so
+  nothing visible ever freezes.
+
 ## [0.14.0] - 2026-09-15
 
 ### Added

package/dist/audio/Music.d.ts

@@ -26,6 +26,8 @@ export declare class Music {
     private trackQueue;
     private playlistFade;
     volume: number;
+    private suspended_;
+    private duckLevel_;
     constructor(options?: MusicOptions);
     /** @param fadeDuration seconds; 0 switches immediately with no crossfade */
     play(path: string, fadeDuration?: number): void;
@@ -38,6 +40,31 @@ export declare class Music {
     private startNextTrack;
     private start;
     stop(fadeDuration?: number): void;
+    /**
+     * Silences everything for a page hide: pauses the current track and every fading one,
+     * and freezes `update` until `resume`, so a crossfade mid-flight continues where it
+     * stopped rather than finishing inaudibly in a background tab. Idempotent.
+     */
+    suspend(): void;
+    /**
+     * The counterpart to `suspend`: restarts the current track where it paused. A track
+     * stopped (not suspended) while hidden stays stopped - resume only resumes.
+     */
+    resume(): void;
+    /**
+     * Ducks the music under dialogue or a menu: the current track glides to
+     * `volume * level` over `fadeDuration` and stays there until `unduck`, and tracks
+     * started while ducked start ducked. Pending fades are retargeted proportionally, so
+     * ducking mid-crossfade still lands quiet. `Sound` is untouched. Idempotent.
+     *
+     * @param level 0 (silent) to 1 (full); clamped, 0.5 by default
+     */
+    duck(level?: number, fadeDuration?: number): void;
+    /** releases a `duck` back to full volume through the same fade path */
+    unduck(fadeDuration?: number): void;
+    /** the held duck attenuation, 1 when full */
+    get duckLevel(): number;
+    get isSuspended(): boolean;
     update(dt: number): void;
 }
 //# sourceMappingURL=Music.d.ts.map

package/dist/audio/Music.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Music.d.ts","sourceRoot":"","sources":["../../src/audio/Music.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAW3D,MAAM,WAAW,YAAY;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,QAAQ,CAAC;CACpC;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,KAAK;IACjB,OAAO,CAAC,OAAO,CAAyB;IACxC,OAAO,CAAC,KAAK,CAAc;IAC3B,OAAO,CAAC,MAAM,CAA6B;IAC3C,OAAO,CAAC,UAAU,CAAyB;IAC3C,OAAO,CAAC,YAAY,CAAK;IACzB,MAAM,EAAE,MAAM,CAAC;IAEf,YAAY,OAAO,GAAE,YAAiB,EAGrC;IAED,4EAA4E;IAC5E,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,SAAI,GAAG,IAAI,CAGzC;IAED;;;;OAIG;IACH,UAAU,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,YAAY,SAAI,GAAG,IAAI,CAQ3D;IAED,OAAO,CAAC,cAAc;IAOtB,OAAO,CAAC,KAAK;IA8Cb,IAAI,CAAC,YAAY,SAAI,GAAG,IAAI,CAW3B;IAED,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAevB;CACD"}
+{"version":3,"file":"Music.d.ts","sourceRoot":"","sources":["../../src/audio/Music.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAW3D,MAAM,WAAW,YAAY;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,QAAQ,CAAC;CACpC;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,KAAK;IACjB,OAAO,CAAC,OAAO,CAAyB;IACxC,OAAO,CAAC,KAAK,CAAc;IAC3B,OAAO,CAAC,MAAM,CAA6B;IAC3C,OAAO,CAAC,UAAU,CAAyB;IAC3C,OAAO,CAAC,YAAY,CAAK;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,UAAU,CAAK;IAEvB,YAAY,OAAO,GAAE,YAAiB,EAGrC;IAED,4EAA4E;IAC5E,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,SAAI,GAAG,IAAI,CAGzC;IAED;;;;OAIG;IACH,UAAU,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,YAAY,SAAI,GAAG,IAAI,CAQ3D;IAED,OAAO,CAAC,cAAc;IAOtB,OAAO,CAAC,KAAK;IA8Cb,IAAI,CAAC,YAAY,SAAI,GAAG,IAAI,CAW3B;IAED;;;;OAIG;IACH,OAAO,IAAI,IAAI,CAId;IAED;;;OAGG;IACH,MAAM,IAAI,IAAI,CAIb;IAED;;;;;;;OAOG;IACH,IAAI,CAAC,KAAK,SAAM,EAAE,YAAY,SAAM,GAAG,IAAI,CAqB1C;IAED,uEAAuE;IACvE,MAAM,CAAC,YAAY,SAAM,GAAG,IAAI,CAE/B;IAED,6CAA6C;IAC7C,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAgBvB;CACD"}

package/dist/audio/Music.js

@@ -21,6 +21,8 @@ export class Music {
         this.fades = [];
         this.trackQueue = null;
         this.playlistFade = 1;
+        this.suspended_ = false;
+        this.duckLevel_ = 1;
         this.volume = options.volume ?? 1;
         this.create = options.create ?? createAudio;
     }
@@ -63,7 +65,7 @@ export class Music {
         const previous = this.current;
         this.current = incoming;
         if (fadeDuration <= 0) {
-            incoming.volume = this.volume;
+            incoming.volume = this.volume * this.duckLevel_;
             // a rejection here means the switch itself (or the previous.pause() right below)
             // interrupted this play()'s own in-flight load - expected during a track switch,
             // so swallow it the standard way rather than let it surface as unhandled.
@@ -78,7 +80,7 @@ export class Music {
             elapsed: 0,
             duration: fadeDuration,
             from: 0,
-            to: this.volume,
+            to: this.volume * this.duckLevel_,
             stopAtEnd: false,
         });
         if (previous) {
@@ -104,7 +106,73 @@ export class Music {
         }
         this.fades.push({ audio, elapsed: 0, duration: fadeDuration, from: audio.volume, to: 0, stopAtEnd: true });
     }
+    /**
+     * Silences everything for a page hide: pauses the current track and every fading one,
+     * and freezes `update` until `resume`, so a crossfade mid-flight continues where it
+     * stopped rather than finishing inaudibly in a background tab. Idempotent.
+     */
+    suspend() {
+        this.suspended_ = true;
+        this.current?.pause();
+        for (const fade of this.fades)
+            fade.audio.pause();
+    }
+    /**
+     * The counterpart to `suspend`: restarts the current track where it paused. A track
+     * stopped (not suspended) while hidden stays stopped - resume only resumes.
+     */
+    resume() {
+        if (!this.suspended_)
+            return;
+        this.suspended_ = false;
+        if (this.current)
+            void Promise.resolve(this.current.play()).catch(() => { });
+    }
+    /**
+     * Ducks the music under dialogue or a menu: the current track glides to
+     * `volume * level` over `fadeDuration` and stays there until `unduck`, and tracks
+     * started while ducked start ducked. Pending fades are retargeted proportionally, so
+     * ducking mid-crossfade still lands quiet. `Sound` is untouched. Idempotent.
+     *
+     * @param level 0 (silent) to 1 (full); clamped, 0.5 by default
+     */
+    duck(level = 0.5, fadeDuration = 0.5) {
+        const next = Number.isFinite(level) ? Math.max(0, Math.min(1, level)) : 1;
+        const previous = this.duckLevel_;
+        this.duckLevel_ = next;
+        for (const fade of this.fades) {
+            fade.to = previous > 0 ? (fade.to / previous) * next : this.volume * next;
+        }
+        if (this.current) {
+            const target = this.volume * next;
+            if (fadeDuration <= 0)
+                this.current.volume = target;
+            else {
+                this.fades.push({
+                    audio: this.current,
+                    elapsed: 0,
+                    duration: fadeDuration,
+                    from: this.current.volume,
+                    to: target,
+                    stopAtEnd: false,
+                });
+            }
+        }
+    }
+    /** releases a `duck` back to full volume through the same fade path */
+    unduck(fadeDuration = 0.5) {
+        this.duck(1, fadeDuration);
+    }
+    /** the held duck attenuation, 1 when full */
+    get duckLevel() {
+        return this.duckLevel_;
+    }
+    get isSuspended() {
+        return this.suspended_;
+    }
     update(dt) {
+        if (this.suspended_)
+            return;
         //iterate a copy: a fade finishing may not touch the list, but this stays safe if one day it does
         for (const fade of [...this.fades]) {
             fade.elapsed += dt;

package/dist/audio/Music.js.map

@@ -1 +1 @@
-{"version":3,"file":"Music.js","sourceRoot":"","sources":["../../src/audio/Music.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Music.js","sourceRoot":"","sources":["../../src/audio/Music.ts"],"names":[],"mappings":"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"}

package/dist/audio/Orchestrator.d.ts

@@ -50,5 +50,9 @@ export declare class Orchestrator {
     on(event: string, cue: Sound): void;
     /** plays the sound registered for `event`, if any; silently does nothing otherwise */
     trigger(event: string): void;
+    /** suspends the music and every cue - the rig a `Game` silences on page hide */
+    suspend(): void;
+    /** resumes the music and every cue after `suspend` */
+    resume(): void;
 }
 //# sourceMappingURL=Orchestrator.d.ts.map

package/dist/audio/Orchestrator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Orchestrator.d.ts","sourceRoot":"","sources":["../../src/audio/Orchestrator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC,2GAA2G;AAC3G,MAAM,WAAW,iBAAiB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,YAAY;IACxB,OAAO,CAAC,MAAM,CAAwC;IACtD,OAAO,CAAC,IAAI,CAA4B;IACxC,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,KAAK,CAAQ;IAErB,YAAY,KAAK,EAAE,KAAK,EAEvB;IAED,oDAAoD;IACpD,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAEtD;IAED,yFAAyF;IACzF,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAQzB;IAED,8DAA8D;IAC9D,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,GAAG,IAAI,CAElC;IAED,sFAAsF;IACtF,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAE3B;CACD"}
+{"version":3,"file":"Orchestrator.d.ts","sourceRoot":"","sources":["../../src/audio/Orchestrator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC,2GAA2G;AAC3G,MAAM,WAAW,iBAAiB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,YAAY;IACxB,OAAO,CAAC,MAAM,CAAwC;IACtD,OAAO,CAAC,IAAI,CAA4B;IACxC,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,KAAK,CAAQ;IAErB,YAAY,KAAK,EAAE,KAAK,EAEvB;IAED,oDAAoD;IACpD,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAEtD;IAED,yFAAyF;IACzF,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAQzB;IAED,8DAA8D;IAC9D,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,GAAG,IAAI,CAElC;IAED,sFAAsF;IACtF,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAE3B;IAED,gFAAgF;IAChF,OAAO,IAAI,IAAI,CAGd;IAED,sDAAsD;IACtD,MAAM,IAAI,IAAI,CAGb;CACD"}

package/dist/audio/Orchestrator.js

@@ -58,5 +58,17 @@ export class Orchestrator {
     trigger(event) {
         this.cues.get(event)?.play();
     }
+    /** suspends the music and every cue - the rig a `Game` silences on page hide */
+    suspend() {
+        this.music.suspend();
+        for (const cue of this.cues.values())
+            cue.suspend();
+    }
+    /** resumes the music and every cue after `suspend` */
+    resume() {
+        this.music.resume();
+        for (const cue of this.cues.values())
+            cue.resume();
+    }
 }
 //# sourceMappingURL=Orchestrator.js.map

package/dist/audio/Orchestrator.js.map

@@ -1 +1 @@
-{"version":3,"file":"Orchestrator.js","sourceRoot":"","sources":["../../src/audio/Orchestrator.ts"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,OAAO,YAAY;IAMxB,YAAY,KAAY;QALhB,WAAM,GAAG,IAAI,GAAG,EAA6B,CAAC;QAC9C,SAAI,GAAG,IAAI,GAAG,EAAiB,CAAC;QAChC,iBAAY,GAAkB,IAAI,CAAC;QAI1C,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACpB,CAAC;IAED,oDAAoD;IACpD,MAAM,CAAC,KAAa,EAAE,OAA0B;QAC/C,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACjC,CAAC;IAED,yFAAyF;IACzF,KAAK,CAAC,KAAa;QAClB,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACvC,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,KAAK,CAAC,uCAAuC,KAAK,GAAG,CAAC,CAAC;QAE/E,IAAI,OAAO,CAAC,KAAK,KAAK,IAAI,CAAC,YAAY;YAAE,OAAO;QAEhD,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;QACrD,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,KAAK,CAAC;IACnC,CAAC;IAED,8DAA8D;IAC9D,EAAE,CAAC,KAAa,EAAE,GAAU;QAC3B,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAC3B,CAAC;IAED,sFAAsF;IACtF,OAAO,CAAC,KAAa;QACpB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;IAC9B,CAAC;CACD"}
+{"version":3,"file":"Orchestrator.js","sourceRoot":"","sources":["../../src/audio/Orchestrator.ts"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,OAAO,YAAY;IAMxB,YAAY,KAAY;QALhB,WAAM,GAAG,IAAI,GAAG,EAA6B,CAAC;QAC9C,SAAI,GAAG,IAAI,GAAG,EAAiB,CAAC;QAChC,iBAAY,GAAkB,IAAI,CAAC;QAI1C,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACpB,CAAC;IAED,oDAAoD;IACpD,MAAM,CAAC,KAAa,EAAE,OAA0B;QAC/C,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACjC,CAAC;IAED,yFAAyF;IACzF,KAAK,CAAC,KAAa;QAClB,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACvC,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,KAAK,CAAC,uCAAuC,KAAK,GAAG,CAAC,CAAC;QAE/E,IAAI,OAAO,CAAC,KAAK,KAAK,IAAI,CAAC,YAAY;YAAE,OAAO;QAEhD,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;QACrD,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,KAAK,CAAC;IACnC,CAAC;IAED,8DAA8D;IAC9D,EAAE,CAAC,KAAa,EAAE,GAAU;QAC3B,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAC3B,CAAC;IAED,sFAAsF;IACtF,OAAO,CAAC,KAAa;QACpB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;IAC9B,CAAC;IAED,gFAAgF;IAChF,OAAO;QACN,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;QACrB,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE;YAAE,GAAG,CAAC,OAAO,EAAE,CAAC;IACrD,CAAC;IAED,sDAAsD;IACtD,MAAM;QACL,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;QACpB,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE;YAAE,GAAG,CAAC,MAAM,EAAE,CAAC;IACpD,CAAC;CACD"}

package/dist/audio/Sound.d.ts

@@ -26,6 +26,7 @@ export declare class Sound {
     private pool;
     private next;
     private caption?;
+    private suspended_;
     volume: number;
     constructor(path: string, options?: SoundOptions);
     /**
@@ -42,5 +43,13 @@ export declare class Sound {
      */
     play(gain?: number, pitch?: number): void;
     stopAll(): void;
+    /**
+     * Cuts in-flight one-shots and silences later `play` calls until `resume` - the page-hide
+     * half of `Music.suspend`. One-shots have nothing to restart, so resume only re-enables.
+     */
+    suspend(): void;
+    /** re-enables `play` after `suspend` */
+    resume(): void;
+    get isSuspended(): boolean;
 }
 //# sourceMappingURL=Sound.d.ts.map

package/dist/audio/Sound.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Sound.d.ts","sourceRoot":"","sources":["../../src/audio/Sound.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAG3D,MAAM,WAAW,YAAY;IAC5B,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,8FAA8F;IAC9F,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,QAAQ,CAAC;IAEpC,2FAA2F;IAC3F,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,KAAK;IACjB,OAAO,CAAC,IAAI,CAAa;IACzB,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,OAAO,CAAC,CAAS;IACzB,MAAM,EAAE,MAAM,CAAC;IAEf,YAAY,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,EAMnD;IAED;;;;;;;;;;;OAWG;IACH,IAAI,CAAC,IAAI,SAAI,EAAE,KAAK,SAAI,GAAG,IAAI,CAa9B;IAED,OAAO,IAAI,IAAI,CAKd;CACD"}
+{"version":3,"file":"Sound.d.ts","sourceRoot":"","sources":["../../src/audio/Sound.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAG3D,MAAM,WAAW,YAAY;IAC5B,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,8FAA8F;IAC9F,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,QAAQ,CAAC;IAEpC,2FAA2F;IAC3F,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,KAAK;IACjB,OAAO,CAAC,IAAI,CAAa;IACzB,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,OAAO,CAAC,CAAS;IACzB,OAAO,CAAC,UAAU,CAAS;IAC3B,MAAM,EAAE,MAAM,CAAC;IAEf,YAAY,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,EAMnD;IAED;;;;;;;;;;;OAWG;IACH,IAAI,CAAC,IAAI,SAAI,EAAE,KAAK,SAAI,GAAG,IAAI,CAc9B;IAED,OAAO,IAAI,IAAI,CAKd;IAED;;;OAGG;IACH,OAAO,IAAI,IAAI,CAGd;IAED,wCAAwC;IACxC,MAAM,IAAI,IAAI,CAEb;IAED,IAAI,WAAW,IAAI,OAAO,CAEzB;CACD"}

package/dist/audio/Sound.js

@@ -17,6 +17,7 @@ import { onCaption } from './Captions.js';
 export class Sound {
     constructor(path, options = {}) {
         this.next = 0;
+        this.suspended_ = false;
         const size = Math.max(1, options.poolSize ?? 4);
         const create = options.create ?? createAudio;
         this.volume = options.volume ?? 1;
@@ -36,6 +37,8 @@ export class Sound {
      * than own a panner node a game does not necessarily want - the same reasoning applies here.
      */
     play(gain = 1, pitch = 1) {
+        if (this.suspended_)
+            return;
         const audio = this.pool[this.next];
         this.next = (this.next + 1) % this.pool.length;
         audio.volume = this.volume * gain;
@@ -54,5 +57,20 @@ export class Sound {
             audio.currentTime = 0;
         }
     }
+    /**
+     * Cuts in-flight one-shots and silences later `play` calls until `resume` - the page-hide
+     * half of `Music.suspend`. One-shots have nothing to restart, so resume only re-enables.
+     */
+    suspend() {
+        this.suspended_ = true;
+        this.stopAll();
+    }
+    /** re-enables `play` after `suspend` */
+    resume() {
+        this.suspended_ = false;
+    }
+    get isSuspended() {
+        return this.suspended_;
+    }
 }
 //# sourceMappingURL=Sound.js.map

package/dist/audio/Sound.js.map

@@ -1 +1 @@
-{"version":3,"file":"Sound.js","sourceRoot":"","sources":["../../src/audio/Sound.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAiB,MAAM,eAAe,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAc1C;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,KAAK;IAMjB,YAAY,IAAY,EAAE,OAAO,GAAiB,EAAE;QAJ5C,SAAI,GAAG,CAAC,CAAC;QAKhB,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,QAAQ,IAAI,CAAC,CAAC,CAAC;QAChD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,WAAW,CAAC;QAC7C,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC;QAClC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IAC9D,CAAC;IAED;;;;;;;;;;;OAWG;IACH,IAAI,CAAC,IAAI,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC;QACvB,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnC,IAAI,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC;QAE/C,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QAClC,KAAK,CAAC,YAAY,GAAG,KAAK,CAAC;QAC3B,KAAK,CAAC,WAAW,GAAG,CAAC,CAAC;QACtB,mFAAmF;QACnF,qFAAqF;QACrF,wFAAwF;QACxF,KAAK,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAEnD,IAAI,IAAI,CAAC,OAAO;YAAE,SAAS,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;IAC9D,CAAC;IAED,OAAO;QACN,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YAC/B,KAAK,CAAC,KAAK,EAAE,CAAC;YACd,KAAK,CAAC,WAAW,GAAG,CAAC,CAAC;QACvB,CAAC;IACF,CAAC;CACD"}
+{"version":3,"file":"Sound.js","sourceRoot":"","sources":["../../src/audio/Sound.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAiB,MAAM,eAAe,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAc1C;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,KAAK;IAOjB,YAAY,IAAY,EAAE,OAAO,GAAiB,EAAE;QAL5C,SAAI,GAAG,CAAC,CAAC;QAET,eAAU,GAAG,KAAK,CAAC;QAI1B,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,QAAQ,IAAI,CAAC,CAAC,CAAC;QAChD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,WAAW,CAAC;QAC7C,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC;QAClC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IAC9D,CAAC;IAED;;;;;;;;;;;OAWG;IACH,IAAI,CAAC,IAAI,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC;QACvB,IAAI,IAAI,CAAC,UAAU;YAAE,OAAO;QAC5B,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnC,IAAI,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC;QAE/C,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QAClC,KAAK,CAAC,YAAY,GAAG,KAAK,CAAC;QAC3B,KAAK,CAAC,WAAW,GAAG,CAAC,CAAC;QACtB,mFAAmF;QACnF,qFAAqF;QACrF,wFAAwF;QACxF,KAAK,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAEnD,IAAI,IAAI,CAAC,OAAO;YAAE,SAAS,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;IAC9D,CAAC;IAED,OAAO;QACN,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YAC/B,KAAK,CAAC,KAAK,EAAE,CAAC;YACd,KAAK,CAAC,WAAW,GAAG,CAAC,CAAC;QACvB,CAAC;IACF,CAAC;IAED;;;OAGG;IACH,OAAO;QACN,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;QACvB,IAAI,CAAC,OAAO,EAAE,CAAC;IAChB,CAAC;IAED,wCAAwC;IACxC,MAAM;QACL,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC;IACzB,CAAC;IAED,IAAI,WAAW;QACd,OAAO,IAAI,CAAC,UAAU,CAAC;IACxB,CAAC;CACD"}

package/dist/core/Settings.d.ts

@@ -0,0 +1,96 @@
+import { type SaveStorage } from './Save.ts';
+import { type Action } from './Input.ts';
+/** a game-defined value: hints on/off, a violence level, anything JSON-flat */
+export type CustomSettingValue = string | number | boolean;
+/** the player-facing values `Settings` persists; everything is renderer-free on purpose */
+export interface GameSettings {
+    /** background-music level, 0 to 1 */
+    musicVolume: number;
+    /** sound-effect level, 0 to 1 */
+    sfxVolume: number;
+    /** master mute: both effective volumes read 0 while true, levels are kept */
+    muted: boolean;
+    /** the zoom a game applies to its own `Camera`; never below 0.01, like `Camera` itself */
+    zoom: number;
+    /** key bindings, in the shape `Input.exportBindings` writes and `importBindings` reads */
+    bindings: Record<Action, string[]>;
+    /** game-defined values beyond the built-ins above (`hints`, `violence`, ...), keyed by name */
+    custom: Record<string, CustomSettingValue>;
+}
+export interface SettingsOptions {
+    /** namespaces the storage key, so two games sharing an origin never collide */
+    namespace?: string;
+    storage?: SaveStorage;
+}
+/**
+ * The values a fresh game starts with: full volume, unmuted, zoom 1, default bindings.
+ *
+ * @example
+ * ```ts
+ * import { defaultSettings } from '@datamoc/mw_games/core';
+ *
+ * console.log(defaultSettings().zoom); // 1
+ * ```
+ */
+export declare function defaultSettings(): GameSettings;
+/** what a game hands its own audio objects: 0 while muted, the stored level otherwise */
+export declare function effectiveMusicVolume(settings: Pick<GameSettings, 'musicVolume' | 'muted'>): number;
+/** what a game hands its own sound effects: 0 while muted, the stored level otherwise */
+export declare function effectiveSfxVolume(settings: Pick<GameSettings, 'sfxVolume' | 'muted'>): number;
+/**
+ * Persisted player settings: music and sound-effect levels, master mute, zoom preference,
+ * and key bindings, read back on the next launch.
+ *
+ * The values live in `core` so they stay renderer-free; the wiring stays with the game,
+ * which assigns them onto its own `Music`/`Sound`/`Camera` (see the example). Bindings are
+ * the exception: they are applied to `Input` on load and on every bindings mutation,
+ * since persisted keys that a game must remember to apply would silently do nothing.
+ *
+ * Corrupt storage reads as defaults rather than throwing: a settings screen should show
+ * the defaults, not a crash.
+ *
+ * @example
+ * ```ts
+ * import { Settings, effectiveMusicVolume, effectiveSfxVolume } from '@datamoc/mw_games/core';
+ *
+ * const settings = new Settings({ namespace: 'my-game' });
+ * settings.update({ musicVolume: 0.7, zoom: 2 });
+ * settings.setCustom('hints', true);
+ *
+ * const music = { volume: 1 };
+ * const camera = { zoom: 1 };
+ * music.volume = effectiveMusicVolume(settings.current);
+ * camera.zoom = settings.current.zoom;
+ * console.log(effectiveSfxVolume(settings.current), settings.getCustom('hints', false));
+ * ```
+ */
+export declare class Settings {
+    private readonly storage;
+    private readonly key;
+    private value;
+    constructor(options?: SettingsOptions);
+    /** a copy of the current values; mutating it writes nothing back, use the setters */
+    get current(): GameSettings;
+    /** a game-defined value (`hints`, `violence`, ...), or `fallback` when never set */
+    getCustom(key: string, fallback: CustomSettingValue): CustomSettingValue;
+    /** stores a game-defined value and persists it */
+    setCustom(key: string, value: CustomSettingValue): void;
+    setMusicVolume(volume: number): void;
+    setSfxVolume(volume: number): void;
+    setMuted(muted: boolean): void;
+    setZoom(zoom: number): void;
+    setBindings(bindings: Readonly<Record<Action, readonly string[]>>): void;
+    update(patch: {
+        musicVolume?: number;
+        sfxVolume?: number;
+        muted?: boolean;
+        zoom?: number;
+        bindings?: Readonly<Record<Action, readonly string[]>>;
+        custom?: Readonly<Record<string, CustomSettingValue>>;
+    }): void;
+    /** re-applies the stored bindings to `Input`, for a game that installed its own after this was built */
+    applyBindings(): void;
+    /** back to full volume, unmuted, zoom 1 and the default bindings, persisted */
+    reset(): void;
+}
+//# sourceMappingURL=Settings.d.ts.map

package/dist/core/Settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Settings.d.ts","sourceRoot":"","sources":["../../src/core/Settings.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7D,OAAO,EAAoC,KAAK,MAAM,EAAE,MAAM,YAAY,CAAC;AAG3E,+EAA+E;AAC/E,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE3D,2FAA2F;AAC3F,MAAM,WAAW,YAAY;IAC5B,qCAAqC;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,KAAK,EAAE,OAAO,CAAC;IACf,0FAA0F;IAC1F,IAAI,EAAE,MAAM,CAAC;IACb,0FAA0F;IAC1F,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACnC,+FAA+F;IAC/F,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,eAAe;IAC/B,+EAA+E;IAC/E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,IAAI,YAAY,CAS9C;AAED,yFAAyF;AACzF,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,IAAI,CAAC,YAAY,EAAE,aAAa,GAAG,OAAO,CAAC,GAAG,MAAM,CAElG;AAED,yFAAyF;AACzF,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,IAAI,CAAC,YAAY,EAAE,WAAW,GAAG,OAAO,CAAC,GAAG,MAAM,CAE9F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,QAAQ;IACpB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;IACtC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,KAAK,CAAe;IAE5B,YAAY,OAAO,GAAE,eAAoB,EAKxC;IAED,qFAAqF;IACrF,IAAI,OAAO,IAAI,YAAY,CAE1B;IAED,oFAAoF;IACpF,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,kBAAkB,GAAG,kBAAkB,CAEvE;IAED,kDAAkD;IAClD,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAGtD;IAED,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAEnC;IAED,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAEjC;IAED,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAE7B;IAED,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAE1B;IAED,WAAW,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,GAAG,IAAI,CAEvE;IAED,MAAM,CAAC,KAAK,EAAE;QACb,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC;QACvD,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC;KACtD,GAAG,IAAI,CAWP;IAED,wGAAwG;IACxG,aAAa,IAAI,IAAI,CAEpB;IAED,+EAA+E;IAC/E,KAAK,IAAI,IAAI,CAIZ;CACD"}

package/dist/core/Settings.js

@@ -0,0 +1,189 @@
+import { defaultStorage } from './Save.js';
+import { DEFAULT_BINDINGS, importBindings } from './Input.js';
+import { clamp } from './Math.js';
+/**
+ * The values a fresh game starts with: full volume, unmuted, zoom 1, default bindings.
+ *
+ * @example
+ * ```ts
+ * import { defaultSettings } from '@datamoc/mw_games/core';
+ *
+ * console.log(defaultSettings().zoom); // 1
+ * ```
+ */
+export function defaultSettings() {
+    return {
+        musicVolume: 1,
+        sfxVolume: 1,
+        muted: false,
+        zoom: 1,
+        bindings: copyBindings(DEFAULT_BINDINGS),
+        custom: {},
+    };
+}
+/** what a game hands its own audio objects: 0 while muted, the stored level otherwise */
+export function effectiveMusicVolume(settings) {
+    return settings.muted ? 0 : settings.musicVolume;
+}
+/** what a game hands its own sound effects: 0 while muted, the stored level otherwise */
+export function effectiveSfxVolume(settings) {
+    return settings.muted ? 0 : settings.sfxVolume;
+}
+/**
+ * Persisted player settings: music and sound-effect levels, master mute, zoom preference,
+ * and key bindings, read back on the next launch.
+ *
+ * The values live in `core` so they stay renderer-free; the wiring stays with the game,
+ * which assigns them onto its own `Music`/`Sound`/`Camera` (see the example). Bindings are
+ * the exception: they are applied to `Input` on load and on every bindings mutation,
+ * since persisted keys that a game must remember to apply would silently do nothing.
+ *
+ * Corrupt storage reads as defaults rather than throwing: a settings screen should show
+ * the defaults, not a crash.
+ *
+ * @example
+ * ```ts
+ * import { Settings, effectiveMusicVolume, effectiveSfxVolume } from '@datamoc/mw_games/core';
+ *
+ * const settings = new Settings({ namespace: 'my-game' });
+ * settings.update({ musicVolume: 0.7, zoom: 2 });
+ * settings.setCustom('hints', true);
+ *
+ * const music = { volume: 1 };
+ * const camera = { zoom: 1 };
+ * music.volume = effectiveMusicVolume(settings.current);
+ * camera.zoom = settings.current.zoom;
+ * console.log(effectiveSfxVolume(settings.current), settings.getCustom('hints', false));
+ * ```
+ */
+export class Settings {
+    constructor(options = {}) {
+        this.storage = options.storage ?? defaultStorage();
+        this.key = `mwg-settings:${options.namespace ?? 'default'}`;
+        this.value = readSettings(this.storage, this.key);
+        importBindings(this.value.bindings);
+    }
+    /** a copy of the current values; mutating it writes nothing back, use the setters */
+    get current() {
+        return { ...this.value, bindings: copyBindings(this.value.bindings), custom: { ...this.value.custom } };
+    }
+    /** a game-defined value (`hints`, `violence`, ...), or `fallback` when never set */
+    getCustom(key, fallback) {
+        return this.value.custom[key] ?? fallback;
+    }
+    /** stores a game-defined value and persists it */
+    setCustom(key, value) {
+        this.value.custom[key] = value;
+        writeSettings(this.storage, this.key, this.value);
+    }
+    setMusicVolume(volume) {
+        this.update({ musicVolume: volume });
+    }
+    setSfxVolume(volume) {
+        this.update({ sfxVolume: volume });
+    }
+    setMuted(muted) {
+        this.update({ muted });
+    }
+    setZoom(zoom) {
+        this.update({ zoom });
+    }
+    setBindings(bindings) {
+        this.update({ bindings });
+    }
+    update(patch) {
+        if (patch.musicVolume !== undefined)
+            this.value.musicVolume = clampVolume(patch.musicVolume);
+        if (patch.sfxVolume !== undefined)
+            this.value.sfxVolume = clampVolume(patch.sfxVolume);
+        if (patch.muted !== undefined)
+            this.value.muted = patch.muted;
+        if (patch.zoom !== undefined)
+            this.value.zoom = clampZoom(patch.zoom);
+        if (patch.bindings !== undefined) {
+            this.value.bindings = sanitizeBindings(patch.bindings);
+            importBindings(this.value.bindings);
+        }
+        if (patch.custom !== undefined)
+            this.value.custom = sanitizeCustom(patch.custom);
+        writeSettings(this.storage, this.key, this.value);
+    }
+    /** re-applies the stored bindings to `Input`, for a game that installed its own after this was built */
+    applyBindings() {
+        importBindings(this.value.bindings);
+    }
+    /** back to full volume, unmuted, zoom 1 and the default bindings, persisted */
+    reset() {
+        this.value = defaultSettings();
+        importBindings(this.value.bindings);
+        writeSettings(this.storage, this.key, this.value);
+    }
+}
+function clampVolume(value) {
+    return Number.isFinite(value) ? clamp(value, 0, 1) : 1;
+}
+function clampZoom(value) {
+    return Number.isFinite(value) ? Math.max(0.01, value) : 1;
+}
+function copyBindings(bindings) {
+    const out = {};
+    for (const [action, keys] of Object.entries(bindings))
+        out[action] = [...keys];
+    return out;
+}
+function sanitizeBindings(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        return copyBindings(DEFAULT_BINDINGS);
+    const out = {};
+    for (const [action, keys] of Object.entries(raw)) {
+        if (!Array.isArray(keys))
+            continue;
+        const codes = keys.filter((key) => typeof key === 'string');
+        if (codes.length > 0)
+            out[action] = codes;
+    }
+    return Object.keys(out).length > 0 ? out : copyBindings(DEFAULT_BINDINGS);
+}
+function isCustomValue(raw) {
+    const kind = typeof raw;
+    return kind === 'string' || kind === 'number' || kind === 'boolean';
+}
+function sanitizeCustom(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        return {};
+    const out = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (isCustomValue(value))
+            out[key] = value;
+    }
+    return out;
+}
+function sanitizeSettings(raw) {
+    const defaults = defaultSettings();
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        return defaults;
+    const candidate = raw;
+    return {
+        musicVolume: typeof candidate.musicVolume === 'number' ? clampVolume(candidate.musicVolume) : defaults.musicVolume,
+        sfxVolume: typeof candidate.sfxVolume === 'number' ? clampVolume(candidate.sfxVolume) : defaults.sfxVolume,
+        muted: typeof candidate.muted === 'boolean' ? candidate.muted : defaults.muted,
+        zoom: typeof candidate.zoom === 'number' ? clampZoom(candidate.zoom) : defaults.zoom,
+        bindings: sanitizeBindings(candidate.bindings),
+        custom: sanitizeCustom(candidate.custom),
+    };
+}
+function readSettings(storage, key) {
+    const raw = storage.read(key);
+    if (!raw)
+        return defaultSettings();
+    try {
+        return sanitizeSettings(JSON.parse(raw));
+    }
+    catch {
+        return defaultSettings();
+    }
+}
+function writeSettings(storage, key, value) {
+    storage.write(key, JSON.stringify(value));
+}
+//# sourceMappingURL=Settings.js.map