npm - zx-kit - Versions diffs - 0.15.0 → 0.16.1 - Mend

zx-kit 0.15.0 → 0.16.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/README.md CHANGED Viewed

@@ -30,6 +30,7 @@ The goal is simple: **it should look and sound like a Spectrum, but run like a m
 - **AABB collision resolution** — sprite vs. sprite overlap, sprite vs. tile map wall resolution with directional hit flags
 - **Keyboard input** — configurable key-repeat, single-consume action flags, instant state reset on phase transitions
 - **ZX-style UI widgets** — progress bars with managed lifetime, boxes, frames, panel titles
+- **Typed save / load** — persistent saves via `localStorage` with schema versioning, migrations, slot enumeration, in-memory throttling, and discriminated Result types for every failure mode
 - **Zero dependencies** — only Web platform APIs: `Canvas`, `Web Audio`, `KeyboardEvent`
 - **Tree-shakeable** — `sideEffects: false`, so unused modules are dropped from your production bundle
 - **TypeScript-first** — strict mode, full `.d.ts` declarations, no `any`
@@ -128,6 +129,406 @@ requestAnimationFrame(loop)
 ---
+## Getting Started — Build Your First Game
+This tutorial walks you through building a working game from scratch: a character you can move around the screen with arrow keys, animated walking frames, and a sound effect on every step.
+No prior game development experience needed. You need basic JavaScript/TypeScript knowledge (variables, functions, arrays).
+---
+### What you will need
+| Tool | Where to get it | Why |
+|------|----------------|-----|
+| **Node.js 18+** | [nodejs.org](https://nodejs.org) | Runs npm — the package manager we use to install zx-kit |
+| **A code editor** | [code.visualstudio.com](https://code.visualstudio.com) (free) | Edits your source files |
+| **A terminal** | Built into macOS/Linux; use PowerShell on Windows | Runs commands |
+---
+### Step 1 — Create the project
+Open a terminal and run:
+```bash
+mkdir my-first-game
+cd my-first-game
+npm init -y
+```
+`npm init -y` creates a `package.json` file — the project's identity card. The `-y` flag accepts all defaults so you don't have to answer questions.
+---
+### Step 2 — Install dependencies
+```bash
+npm install zx-kit
+npm install --save-dev vite
+```
+- **zx-kit** — the game engine you are building with
+- **vite** — a development server that reloads the browser whenever you save a file (installed as a dev tool, not part of your shipped game)
+---
+### Step 3 — Configure package.json
+Open `package.json` and replace it with the following. The two key additions are `"type": "module"` (enables modern JavaScript imports) and the `scripts` section (adds the `npm run dev` command):
+```json
+{
+  "name": "my-first-game",
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build"
+  },
+  "dependencies": {
+    "zx-kit": "^0.15.0"
+  },
+  "devDependencies": {
+    "vite": "^6.0.0"
+  }
+}
+```
+---
+### Step 4 — Create index.html
+Create a file called `index.html` in your project root:
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>My First Game</title>
+    <style>
+      body {
+        margin: 0;
+        background: #000;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        height: 100vh;
+      }
+    </style>
+  </head>
+  <body>
+    <canvas id="game"></canvas>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
+```
+The `<canvas>` is the game screen. The `<script>` tag loads your game code.
+---
+### Step 5 — Create the game
+Create the folder `src/` and inside it a file called `main.ts`. We will build it one piece at a time.
+---
+#### 5a — Canvas setup
+A canvas element is just a rectangle of pixels in the browser. `setupCanvas` configures it for pixel-perfect ZX Spectrum-style rendering and returns a drawing context you use to paint everything.
+```ts
+import { setupCanvas, C, CELL } from 'zx-kit'
+const canvas = document.getElementById('game') as HTMLCanvasElement
+const ctx = setupCanvas(canvas, 4)
+// The screen is 256 × 192 game pixels, scaled up 4× in the browser.
+// From here on draw everything in game pixels — setupCanvas handles the scale.
+```
+`C` is the color palette. `CELL` is the size of one sprite: 8 pixels.
+---
+#### 5b — Define a sprite
+Every character and object in zx-kit is an 8×8 pixel bitmap. You define it as 8 numbers, one per row. Each number is 8 bits — one bit per pixel. Bit 7 is the leftmost pixel.
+The binary literal `0b00111100` is the same as the number `60`, but written out as ones and zeros so you can see the pixel pattern directly.
+We will use two walking frames so the character animates when it moves:
+```ts
+//                     76543210  ← bit position (7 = leftmost pixel)
+const WALK_A = new Uint8Array([
+  0b00111100,  //  ..####..   head
+  0b01111110,  //  .######.
+  0b00011000,  //  ...##...   neck
+  0b01111110,  //  .######.   arms + body
+  0b00011000,  //  ...##...   waist
+  0b01011010,  //  .#.##.#.   legs apart
+  0b01000010,  //  .#....#.   feet
+  0b00000000,  //  ........
+])
+const WALK_B = new Uint8Array([
+  0b00111100,  //  ..####..   head
+  0b01111110,  //  .######.
+  0b00011000,  //  ...##...   neck
+  0b01111110,  //  .######.   arms + body
+  0b00011000,  //  ...##...   waist
+  0b00111100,  //  ..####..   legs together
+  0b00011000,  //  ...##...
+  0b00000000,  //  ........
+])
+const FRAMES = [WALK_A, WALK_B]  // frame 0 = legs apart, frame 1 = legs together
+```
+---
+#### 5c — Input
+`initInput()` attaches keyboard listeners. Call it once at startup, not inside the game loop.
+`isHeld(key)` returns `true` while a key is pressed. We use it to check whether an arrow key is being held down each frame.
+```ts
+import { initInput, isHeld } from 'zx-kit'
+initInput()
+```
+---
+#### 5d — Audio
+Browsers will not play any sound until the user has interacted with the page (clicked, tapped, or pressed a key). This is a browser security rule — there is nothing we can do to bypass it. The pattern below waits for the first keydown and initialises audio then:
+```ts
+import { initAudio, getAudioContext, resumeAudio, beep } from 'zx-kit'
+window.addEventListener('keydown', () => initAudio(0.3), { once: true })
+// initAudio(0.3) = master volume 30%.  Called at most once thanks to { once: true }.
+```
+---
+#### 5e — Player state and animation
+```ts
+import { createAnimation, tickAnimation } from 'zx-kit'
+let px = 120       // player x position in game pixels
+let py = 88        // player y position
+const SPEED = 60   // pixels per second
+// A 2-frame looping animation, 150ms per frame = one full step every 300ms
+const walkAnim = createAnimation(2, 150)
+let stepTimer = 0  // footstep sound timer
+```
+---
+#### 5f — The game loop
+Every frame the browser calls `loop`. Inside, we:
+1. Calculate `dt` — how many milliseconds passed since last frame
+2. Move the player based on held keys
+3. Keep the player inside the screen
+4. Pick the right animation frame
+5. Play a footstep sound periodically while moving
+6. Clear the screen and redraw everything
+```ts
+import { drawSprite, drawText } from 'zx-kit'
+let lastTime = 0
+function loop(now: number): void {
+  const dt = Math.min(now - lastTime, 100)
+  // dt is milliseconds since the last frame (usually ~16ms at 60fps).
+  // We cap at 100ms so a background tab returning doesn't cause a huge position jump.
+  lastTime = now
+  // ── Move player ────────────────────────────────────────────────────────────
+  let moving = false
+  if (isHeld('ArrowRight')) { px += SPEED * dt / 1000; moving = true }
+  if (isHeld('ArrowLeft'))  { px -= SPEED * dt / 1000; moving = true }
+  if (isHeld('ArrowDown'))  { py += SPEED * dt / 1000; moving = true }
+  if (isHeld('ArrowUp'))    { py -= SPEED * dt / 1000; moving = true }
+  // SPEED (60) is pixels per second. dt is milliseconds. Divide by 1000 to convert.
+  // Keep inside the 256×192 canvas
+  px = Math.max(0, Math.min(256 - CELL, px))
+  py = Math.max(0, Math.min(192 - CELL, py))
+  // ── Animation ──────────────────────────────────────────────────────────────
+  // tickAnimation advances the timer and returns the current frame index (0 or 1).
+  // When standing still we always use frame 0.
+  const frame = moving ? tickAnimation(walkAnim, dt) : 0
+  // ── Footstep sound ─────────────────────────────────────────────────────────
+  if (moving) {
+    stepTimer -= dt
+    if (stepTimer <= 0) {
+      stepTimer = 250  // play a sound every 250ms while moving
+      const audio = getAudioContext()
+      if (audio) {
+        resumeAudio()                       // un-suspend if the tab was hidden
+        beep(220, 30, audio.currentTime)    // 220 Hz, 30ms — a short thud
+      }
+    }
+  } else {
+    stepTimer = 0  // reset so next movement starts immediately
+  }
+  // ── Draw ───────────────────────────────────────────────────────────────────
+  ctx.fillStyle = C.BLACK
+  ctx.fillRect(0, 0, 256, 192)  // clear the whole screen
+  drawSprite(ctx, FRAMES[frame], Math.round(px), Math.round(py), C.B_CYAN, C.BLACK)
+  //                              ↑ position      ↑ ink color     ↑ paper (background)
+  drawText(ctx, 'ARROW KEYS = MOVE', 8, 184, C.WHITE)
+  // drawText draws one ASCII character per 8px slot, left-to-right.
+  requestAnimationFrame(loop)  // ask the browser to call us again next frame
+}
+requestAnimationFrame(loop)   // kick off the first frame
+```
+---
+### Step 6 — Run the game
+```bash
+npm run dev
+```
+Open [http://localhost:5173](http://localhost:5173) in your browser. Press an arrow key. Your character walks.
+---
+### Complete file
+The full `src/main.ts` all in one place:
+```ts
+import {
+  setupCanvas, C, CELL,
+  drawSprite, drawText,
+  initInput, isHeld,
+  initAudio, getAudioContext, resumeAudio, beep,
+  createAnimation, tickAnimation,
+} from 'zx-kit'
+// ── Canvas ────────────────────────────────────────────────────────────────────
+const canvas = document.getElementById('game') as HTMLCanvasElement
+const ctx = setupCanvas(canvas, 4)
+// ── Sprites ───────────────────────────────────────────────────────────────────
+const WALK_A = new Uint8Array([
+  0b00111100,  //  ..####..   head
+  0b01111110,  //  .######.
+  0b00011000,  //  ...##...   neck
+  0b01111110,  //  .######.   arms + body
+  0b00011000,  //  ...##...   waist
+  0b01011010,  //  .#.##.#.   legs apart
+  0b01000010,  //  .#....#.   feet
+  0b00000000,  //  ........
+])
+const WALK_B = new Uint8Array([
+  0b00111100,  //  ..####..   head
+  0b01111110,  //  .######.
+  0b00011000,  //  ...##...   neck
+  0b01111110,  //  .######.   arms + body
+  0b00011000,  //  ...##...   waist
+  0b00111100,  //  ..####..   legs together
+  0b00011000,  //  ...##...
+  0b00000000,  //  ........
+])
+const FRAMES = [WALK_A, WALK_B]
+// ── Input ─────────────────────────────────────────────────────────────────────
+initInput()
+// ── Audio ─────────────────────────────────────────────────────────────────────
+window.addEventListener('keydown', () => initAudio(0.3), { once: true })
+// ── Player state ──────────────────────────────────────────────────────────────
+let px = 120
+let py = 88
+const SPEED = 60  // pixels per second
+const walkAnim = createAnimation(2, 150)
+let stepTimer = 0
+// ── Game loop ─────────────────────────────────────────────────────────────────
+let lastTime = 0
+function loop(now: number): void {
+  const dt = Math.min(now - lastTime, 100)
+  lastTime = now
+  let moving = false
+  if (isHeld('ArrowRight')) { px += SPEED * dt / 1000; moving = true }
+  if (isHeld('ArrowLeft'))  { px -= SPEED * dt / 1000; moving = true }
+  if (isHeld('ArrowDown'))  { py += SPEED * dt / 1000; moving = true }
+  if (isHeld('ArrowUp'))    { py -= SPEED * dt / 1000; moving = true }
+  px = Math.max(0, Math.min(256 - CELL, px))
+  py = Math.max(0, Math.min(192 - CELL, py))
+  const frame = moving ? tickAnimation(walkAnim, dt) : 0
+  if (moving) {
+    stepTimer -= dt
+    if (stepTimer <= 0) {
+      stepTimer = 250
+      const audio = getAudioContext()
+      if (audio) { resumeAudio(); beep(220, 30, audio.currentTime) }
+    }
+  } else {
+    stepTimer = 0
+  }
+  ctx.fillStyle = C.BLACK
+  ctx.fillRect(0, 0, 256, 192)
+  drawSprite(ctx, FRAMES[frame], Math.round(px), Math.round(py), C.B_CYAN, C.BLACK)
+  drawText(ctx, 'ARROW KEYS = MOVE', 8, 184, C.WHITE)
+  requestAnimationFrame(loop)
+}
+requestAnimationFrame(loop)
+```
+---
+### What to try next
+**Change the sprite.** Edit the binary rows in `WALK_A` / `WALK_B` — each `1` is a pixel, each `0` is background. Draw a spaceship, a gem, or a face.
+**Change the color.** Replace `C.B_CYAN` with any palette color: `C.B_GREEN`, `C.B_YELLOW`, `C.B_RED`, `C.B_MAGENTA`, `C.B_WHITE`. The full list is in the [palette reference](#palettets--color-constants).
+**Add a second character.** Copy the player variables (`px2`, `py2`, `walkAnim2`) and add `W A S D` controls using `isHeld('w')` etc.
+**Add obstacles.** Use `createTileMap` to place solid wall tiles and `resolveX` / `resolveY` to stop the player at them.
+**Add chiptune music.** Call `playAY()` with a note array to play a three-channel melody — see [`ay.ts`](#ayts--ay-3-8912-melodik-audio).
+**Study a complete game.** [Minefield](https://github.com/zrebec/minefield) is built entirely with zx-kit. Every mechanic in this tutorial — sprites, input, animation, audio, tilemap — appears there in a production context.
+---
 ## Modules
 | Module | What it provides |
@@ -142,6 +543,7 @@ requestAnimationFrame(loop)
 | [`animation.ts`](#animationts--frame-timer--tween) | Frame-timer for sprite strips, position tween between two points |
 | [`camera.ts`](#camerats--scrolling-camera) | Viewport that follows a target with lerp + deadzone, world-bounds clamping |
 | [`scene.ts`](#scenets--scene-manager) | Stack-based scene manager with onEnter/onExit/onPause/onResume hooks |
+| [`save.ts`](#savets--typed-save--load) | Typed save/load via callbacks, versioning + migrations, slot enumeration, throttling, Result types |
 | [`tilemap.ts`](#tilemapts--tile-map-engine) | Scrollable maps, solid tiles, O(1) id-index, background swap |
 | [`palette.ts`](#palettets--color-constants) | 15 Spectrum colors, `SpectrumColor` type, `CELL`, `SCALE` |
 | [`font.ts`](#fontts--rom-bitmap-font) | 96-character ROM font, raw bitmap access |
@@ -1134,6 +1536,135 @@ Renders every scene from bottom to top. No-op on an empty manager.
 ---
+## `save.ts` — Typed Save / Load
+Persistent save / load via `localStorage` with versioning, schema migration, slot enumeration, and in-memory throttling. The game declares its state shape through `serialize` / `deserialize` callbacks; the kit handles storage, namespacing, error mapping, and throttle timing. Every operation returns a discriminated Result type — `quota`, `disabled`, `corrupt`, `version_unsupported` and the rest are distinct, so the game can react to each failure mode if it cares.
+```ts
+import {
+  createSaveProfile, writeSave, writeSaveThrottled,
+  readSave, readSaveLatest, saveExists, deleteSave, listSaves,
+} from 'zx-kit'
+type MyGameSave = {
+  score: number
+  lives: number
+  probed: string[]   // Set<string> serialized to array
+}
+const save = createSaveProfile<MyGameSave>({
+  key: 'my-game',
+  version: 1,
+  serialize: () => ({
+    score: game.score,
+    lives: game.lives,
+    probed: [...game.probedCells],
+  }),
+  deserialize: (data) => {
+    game.score = data.score
+    game.lives = data.lives
+    game.probedCells = new Set(data.probed)
+  },
+})
+writeSave(save, 'manual')                       // immediate write to 'manual'
+writeSaveThrottled(save, 'auto', 5000)          // skips if last 'auto' write < 5s ago
+readSaveLatest(save)                            // load newest slot, calls deserialize
+deleteSave(save, 'auto')                        // remove slot + clear its throttle entry
+```
+### Why callbacks, not a "save the whole state" snapshot
+In emulators a full RAM dump round-trips losslessly because RAM is a byte array. JavaScript state is an object graph: `JSON.stringify(gameState)` silently corrupts `Set`, `Map`, class instances and circular references; a snapshot also persists transient runtime state (audio nodes, `requestAnimationFrame` IDs) that has no business surviving. Forcing the game to declare what's in a save via `serialize` keeps the kit state-agnostic and gives the game a place to convert non-JSON values back and forth.
+### `SaveProfileConfig<T>` interface
+| Field | Description |
+|-------|-------------|
+| `key` | Game key — used as namespace in storage. Unique per game. |
+| `version` | Current schema version. Increment when the shape of `T` changes. |
+| `serialize` | Returns the current game state as a JSON-safe `T`. |
+| `deserialize` | Applies a loaded `T` back to the game (side effect — the game owns the mutation). |
+| `migrate?` | `(data: unknown, fromVersion: number) => T` — runs when the loaded envelope is older than `version`. If absent and `fromVersion < version`, load fails with `version_unsupported`. |
+### `SaveResult` / `LoadResult`
+```ts
+type SaveResult =
+  | { ok: true }
+  | { ok: false, reason: 'quota' | 'disabled' | 'serialize_error' | 'throttled', error?: Error }
+type LoadResult =
+  | { ok: true, slot: string }
+  | { ok: false, reason: 'not_found' | 'corrupt' | 'version_unsupported' | 'parse_error' | 'disabled', error?: Error }
+```
+`throttled` is not a true failure — it means the throttle interval hadn't elapsed and the write was skipped. Surfaced as `ok: false` so callers can distinguish skipping from a real success, but typically ignored.
+### `createSaveProfile<T>(config): SaveProfile<T>`
+Registers a save profile. Call once at startup and reuse the returned handle for every operation. The handle also carries in-memory throttle state (per-slot last-write timestamps).
+### `writeSave(profile, slot?): SaveResult`
+Writes immediately. Calls `serialize`, wraps the result as `{ version, timestamp, data }` and stores under `zxkit:<key>:<slot>`. Default slot is `'default'`.
+### `writeSaveThrottled(profile, slot, minIntervalMs): SaveResult`
+Writes only if at least `minIntervalMs` has elapsed since the last successful write to the same slot in this session. The first call to a given slot always proceeds — the throttle only applies once there's a prior write to compare against. Throttle state lives in memory; a page reload resets it.
+### `readSave(profile, slot?): LoadResult`
+Reads a slot, runs `migrate` if the stored version is older than the profile version, then calls `deserialize` with the result. On `ok`, the game state has been restored.
+### `readSaveLatest(profile): LoadResult`
+Enumerates every slot belonging to this profile's key and loads the one with the most recent `timestamp`. Returns `{ ok: false, reason: 'not_found' }` when no slots exist.
+### `saveExists(profile, slot?): boolean`
+True iff the slot key exists in storage. Does not validate envelope shape — use `readSave` for that.
+### `deleteSave(profile, slot?): boolean`
+Removes the slot. Also clears the slot's throttle entry, so the next `writeSaveThrottled` to that slot proceeds immediately. Returns `true` if a slot was actually removed.
+### `listSaves(profile): SlotInfo[]`
+Returns `{ name, timestamp, version, sizeBytes }[]` for every slot belonging to this profile. Corrupt or mis-shaped entries are silently skipped — they will surface as `corrupt` if loaded explicitly via `readSave`.
+### Versioning and migration
+Every saved payload carries `{ version, timestamp, data }`. On load, when the stored version is older than the profile's current version, `migrate` is called with the raw `data` and the version it was saved at. If the stored version is newer than the profile's, the load fails with `version_unsupported` — a downgrade cannot read forward.
+```ts
+createSaveProfile({
+  key: 'my-game',
+  version: 3,
+  migrate: (data, fromVersion) => {
+    let d = data as Record<string, unknown>
+    if (fromVersion < 2) d = { ...d, lives: 3 }       // v1 → v2: gained 'lives'
+    if (fromVersion < 3) d = { ...d, probed: [] }     // v2 → v3: gained 'probed'
+    return d as MyGameSave
+  },
+  deserialize: (data) => { /* always receives v3 shape */ },
+})
+```
+If `migrate` throws, the read fails with `corrupt`.
+### Slot naming — convention, not policy
+The kit places no policy on slot names. A useful pattern for retro-style games:
+- `'auto'` — written via `writeSaveThrottled` at meaningful game events (level complete, checkpoint, after a major state change).
+- `'manual'` — written via `writeSave` when the player hits a save key.
+- Load via `readSaveLatest` to pick whichever is newer.
+This composes a "your last meaningful checkpoint is always available" UX without a load-slot menu.
+---
 ## `tilemap.ts` — Tile Map Engine
 A scrollable, queryable tile map backed by an O(1) id-index. Tiles use the same 8×8 sprite format as `drawSprite`. Supports solid-tile collision queries, viewport-clipped rendering, and smart seasonal background swapping.

package/dist/index.d.ts CHANGED Viewed

@@ -11,4 +11,5 @@ export * from './collision.js';
 export * from './animation.js';
 export * from './camera.js';
 export * from './scene.js';
+export * from './save.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA;AAC5B,cAAc,SAAS,CAAA;AACvB,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,SAAS,CAAA;AACvB,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA"}
1	+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA;AAC5B,cAAc,SAAS,CAAA;AACvB,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,SAAS,CAAA;AACvB,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA"}

package/dist/index.js CHANGED Viewed

@@ -11,4 +11,5 @@ export * from './collision.js';
 export * from './animation.js';
 export * from './camera.js';
 export * from './scene.js';
+export * from './save.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA;AAC5B,cAAc,SAAS,CAAA;AACvB,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,SAAS,CAAA;AACvB,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA"}
1	+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA;AAC5B,cAAc,SAAS,CAAA;AACvB,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,SAAS,CAAA;AACvB,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA"}

package/dist/save.d.ts ADDED Viewed

@@ -0,0 +1,122 @@
+/**
+ * Configuration for a game's save profile.
+ *
+ * @typeParam T - The JSON-safe shape of the saved payload. The game converts
+ *   non-JSON values (Sets, Maps, class instances) inside `serialize` /
+ *   `deserialize`.
+ */
+export interface SaveProfileConfig<T> {
+    /** Game key — used as namespace in storage. Must be unique per game. */
+    key: string;
+    /** Current schema version. Increment when the shape of T changes. */
+    version: number;
+    /** Returns the current game state as a JSON-safe value. */
+    serialize: () => T;
+    /** Applies a loaded snapshot back to the game (side effect). */
+    deserialize: (data: T) => void;
+    /**
+     * Optional migration. Called when the loaded envelope's version is older
+     * than `version`. Receives the raw data and the version it was saved at,
+     * returns data shaped for the current version. If absent and an older
+     * version is encountered, the load fails with `version_unsupported`.
+     */
+    migrate?: (data: unknown, fromVersion: number) => T;
+}
+/**
+ * Returned by {@link createSaveProfile}. Carries config plus in-memory
+ * throttle state. Pass to all save/load operations.
+ *
+ * Throttle state lives only in memory — a page reload resets it, so the
+ * first {@link writeSaveThrottled} after reload always proceeds.
+ */
+export interface SaveProfile<T> {
+    readonly key: string;
+    readonly version: number;
+    readonly config: SaveProfileConfig<T>;
+    /** Per-slot last successful write timestamp (ms). Internal. */
+    lastWrites: Map<string, number>;
+}
+/** Metadata for a single stored slot. */
+export interface SlotInfo {
+    name: string;
+    timestamp: number;
+    version: number;
+    sizeBytes: number;
+}
+/**
+ * Result of a write operation.
+ *
+ * `throttled` indicates the write was intentionally skipped because the
+ * throttle interval had not elapsed — not a true failure. Callers that
+ * only care whether data hit storage can branch on `ok`; callers that
+ * want to distinguish "skipped" from "failed" can check `reason`.
+ */
+export type SaveResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'quota' | 'disabled' | 'serialize_error' | 'throttled';
+    error?: Error;
+};
+/** Result of a read operation. On `ok: true`, `deserialize` has already been called. */
+export type LoadResult = {
+    ok: true;
+    slot: string;
+} | {
+    ok: false;
+    reason: 'not_found' | 'corrupt' | 'version_unsupported' | 'parse_error' | 'disabled';
+    error?: Error;
+};
+/**
+ * Registers a save profile for a game. Call once at startup and reuse the
+ * returned handle for all save/load operations.
+ *
+ * @example
+ * const save = createSaveProfile<MinefieldSave>({
+ *   key: 'minefield',
+ *   version: 1,
+ *   serialize: () => ({ score, lives, probed: [...probedCells] }),
+ *   deserialize: (data) => { score = data.score; probedCells = new Set(data.probed) },
+ * })
+ */
+export declare function createSaveProfile<T>(config: SaveProfileConfig<T>): SaveProfile<T>;
+/**
+ * Writes the current game state to a slot immediately. Calls `serialize`
+ * to obtain the payload, then stores `{ version, timestamp, data }` as JSON.
+ *
+ * @param slot - Slot name; defaults to `'default'`. Games typically use
+ *   convention-based names like `'auto'` or `'manual'`.
+ */
+export declare function writeSave<T>(profile: SaveProfile<T>, slot?: string): SaveResult;
+/**
+ * Writes to `slot` only if at least `minIntervalMs` has elapsed since the
+ * last successful write to the same slot in this session. Otherwise returns
+ * `{ ok: false, reason: 'throttled' }`.
+ *
+ * Throttle state is in-memory; a page reload resets it.
+ */
+export declare function writeSaveThrottled<T>(profile: SaveProfile<T>, slot: string, minIntervalMs: number): SaveResult;
+/**
+ * Reads a slot, runs migration if needed, then calls `deserialize` with
+ * the resulting payload. On success the game state has been restored.
+ */
+export declare function readSave<T>(profile: SaveProfile<T>, slot?: string): LoadResult;
+/**
+ * Reads whichever slot has the newest timestamp. Returns `not_found` if
+ * no slots exist for this profile's key.
+ */
+export declare function readSaveLatest<T>(profile: SaveProfile<T>): LoadResult;
+/** True iff the slot exists in storage. Does not validate envelope shape. */
+export declare function saveExists<T>(profile: SaveProfile<T>, slot?: string): boolean;
+/**
+ * Removes a slot. Returns `true` if a slot was removed, `false` if it
+ * didn't exist or storage is unavailable.
+ */
+export declare function deleteSave<T>(profile: SaveProfile<T>, slot?: string): boolean;
+/**
+ * Enumerates all slots that belong to this profile's key. Corrupt or
+ * mis-shaped entries are silently skipped — they will surface as `corrupt`
+ * if loaded explicitly via {@link readSave}.
+ */
+export declare function listSaves<T>(profile: SaveProfile<T>): SlotInfo[];
+//# sourceMappingURL=save.d.ts.map

package/dist/save.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"save.d.ts","sourceRoot":"","sources":["../src/save.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,wEAAwE;IACxE,GAAG,EAAE,MAAM,CAAA;IACX,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAA;IACf,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAC,CAAA;IAClB,gEAAgE;IAChE,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAA;IAC9B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC,CAAA;CACpD;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAAC,CAAA;IACrC,+DAA+D;IAC/D,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAChC;AAED,yCAAyC;AACzC,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,GAClB;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GACZ;IACE,EAAE,EAAE,KAAK,CAAA;IACT,MAAM,EAAE,OAAO,GAAG,UAAU,GAAG,iBAAiB,GAAG,WAAW,CAAA;IAC9D,KAAK,CAAC,EAAE,KAAK,CAAA;CACd,CAAA;AAEL,wFAAwF;AACxF,MAAM,MAAM,UAAU,GAClB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC1B;IACE,EAAE,EAAE,KAAK,CAAA;IACT,MAAM,EACF,WAAW,GACX,SAAS,GACT,qBAAqB,GACrB,aAAa,GACb,UAAU,CAAA;IACd,KAAK,CAAC,EAAE,KAAK,CAAA;CACd,CAAA;AAwCL;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAOjF;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,CAAC,EACzB,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,EACvB,IAAI,GAAE,MAAqB,GAC1B,UAAU,CAoCZ;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,EACvB,IAAI,EAAE,MAAM,EACZ,aAAa,EAAE,MAAM,GACpB,UAAU,CAMZ;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EACxB,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,EACvB,IAAI,GAAE,MAAqB,GAC1B,UAAU,CAyCZ;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,UAAU,CASrE;AAED,6EAA6E;AAC7E,wBAAgB,UAAU,CAAC,CAAC,EAC1B,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,EACvB,IAAI,GAAE,MAAqB,GAC1B,OAAO,CAQT;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAC1B,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,EACvB,IAAI,GAAE,MAAqB,GAC1B,OAAO,CAaT;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,QAAQ,EAAE,CA+ChE"}

package/dist/save.js ADDED Viewed

@@ -0,0 +1,253 @@
+// ── Save: typed save/load with versioning, throttling, slot enumeration ─────
+const NAMESPACE = 'zxkit';
+const DEFAULT_SLOT = 'default';
+function storageKey(profileKey, slot) {
+    return `${NAMESPACE}:${profileKey}:${slot}`;
+}
+/**
+ * Resolves the localStorage reference, returning null if unavailable
+ * (Node, SSR, private browsing where access itself throws, etc.).
+ */
+function getStorage() {
+    try {
+        if (typeof globalThis === 'undefined')
+            return null;
+        return globalThis.localStorage ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function isValidEnvelope(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const v = value;
+    return (typeof v.version === 'number' &&
+        Number.isFinite(v.version) &&
+        typeof v.timestamp === 'number' &&
+        Number.isFinite(v.timestamp) &&
+        'data' in v);
+}
+/**
+ * Registers a save profile for a game. Call once at startup and reuse the
+ * returned handle for all save/load operations.
+ *
+ * @example
+ * const save = createSaveProfile<MinefieldSave>({
+ *   key: 'minefield',
+ *   version: 1,
+ *   serialize: () => ({ score, lives, probed: [...probedCells] }),
+ *   deserialize: (data) => { score = data.score; probedCells = new Set(data.probed) },
+ * })
+ */
+export function createSaveProfile(config) {
+    return {
+        key: config.key,
+        version: config.version,
+        config,
+        lastWrites: new Map(),
+    };
+}
+/**
+ * Writes the current game state to a slot immediately. Calls `serialize`
+ * to obtain the payload, then stores `{ version, timestamp, data }` as JSON.
+ *
+ * @param slot - Slot name; defaults to `'default'`. Games typically use
+ *   convention-based names like `'auto'` or `'manual'`.
+ */
+export function writeSave(profile, slot = DEFAULT_SLOT) {
+    const storage = getStorage();
+    if (!storage)
+        return { ok: false, reason: 'disabled' };
+    let payload;
+    try {
+        payload = profile.config.serialize();
+    }
+    catch (error) {
+        return { ok: false, reason: 'serialize_error', error: error };
+    }
+    const envelope = {
+        version: profile.version,
+        timestamp: Date.now(),
+        data: payload,
+    };
+    let serialized;
+    try {
+        serialized = JSON.stringify(envelope);
+    }
+    catch (error) {
+        return { ok: false, reason: 'serialize_error', error: error };
+    }
+    try {
+        storage.setItem(storageKey(profile.key, slot), serialized);
+    }
+    catch (error) {
+        const err = error;
+        if (err.name === 'QuotaExceededError' || err.code === 22) {
+            return { ok: false, reason: 'quota', error: err };
+        }
+        return { ok: false, reason: 'disabled', error: err };
+    }
+    profile.lastWrites.set(slot, envelope.timestamp);
+    return { ok: true };
+}
+/**
+ * Writes to `slot` only if at least `minIntervalMs` has elapsed since the
+ * last successful write to the same slot in this session. Otherwise returns
+ * `{ ok: false, reason: 'throttled' }`.
+ *
+ * Throttle state is in-memory; a page reload resets it.
+ */
+export function writeSaveThrottled(profile, slot, minIntervalMs) {
+    const last = profile.lastWrites.get(slot);
+    if (last !== undefined && Date.now() - last < minIntervalMs) {
+        return { ok: false, reason: 'throttled' };
+    }
+    return writeSave(profile, slot);
+}
+/**
+ * Reads a slot, runs migration if needed, then calls `deserialize` with
+ * the resulting payload. On success the game state has been restored.
+ */
+export function readSave(profile, slot = DEFAULT_SLOT) {
+    const storage = getStorage();
+    if (!storage)
+        return { ok: false, reason: 'disabled' };
+    const raw = storage.getItem(storageKey(profile.key, slot));
+    if (raw === null)
+        return { ok: false, reason: 'not_found' };
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        return { ok: false, reason: 'parse_error', error: error };
+    }
+    if (!isValidEnvelope(parsed)) {
+        return { ok: false, reason: 'corrupt' };
+    }
+    let data = parsed.data;
+    if (parsed.version !== profile.version) {
+        if (parsed.version > profile.version) {
+            return { ok: false, reason: 'version_unsupported' };
+        }
+        if (!profile.config.migrate) {
+            return { ok: false, reason: 'version_unsupported' };
+        }
+        try {
+            data = profile.config.migrate(data, parsed.version);
+        }
+        catch (error) {
+            return { ok: false, reason: 'corrupt', error: error };
+        }
+    }
+    try {
+        profile.config.deserialize(data);
+    }
+    catch (error) {
+        return { ok: false, reason: 'corrupt', error: error };
+    }
+    return { ok: true, slot };
+}
+/**
+ * Reads whichever slot has the newest timestamp. Returns `not_found` if
+ * no slots exist for this profile's key.
+ */
+export function readSaveLatest(profile) {
+    const slots = listSaves(profile);
+    if (slots.length === 0)
+        return { ok: false, reason: 'not_found' };
+    let newest = slots[0];
+    for (let i = 1; i < slots.length; i++) {
+        if (slots[i].timestamp > newest.timestamp)
+            newest = slots[i];
+    }
+    return readSave(profile, newest.name);
+}
+/** True iff the slot exists in storage. Does not validate envelope shape. */
+export function saveExists(profile, slot = DEFAULT_SLOT) {
+    const storage = getStorage();
+    if (!storage)
+        return false;
+    try {
+        return storage.getItem(storageKey(profile.key, slot)) !== null;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Removes a slot. Returns `true` if a slot was removed, `false` if it
+ * didn't exist or storage is unavailable.
+ */
+export function deleteSave(profile, slot = DEFAULT_SLOT) {
+    const storage = getStorage();
+    if (!storage)
+        return false;
+    const key = storageKey(profile.key, slot);
+    try {
+        if (storage.getItem(key) === null)
+            return false;
+        storage.removeItem(key);
+    }
+    catch {
+        return false;
+    }
+    profile.lastWrites.delete(slot);
+    return true;
+}
+/**
+ * Enumerates all slots that belong to this profile's key. Corrupt or
+ * mis-shaped entries are silently skipped — they will surface as `corrupt`
+ * if loaded explicitly via {@link readSave}.
+ */
+export function listSaves(profile) {
+    const storage = getStorage();
+    if (!storage)
+        return [];
+    const prefix = `${NAMESPACE}:${profile.key}:`;
+    const slots = [];
+    let length = 0;
+    try {
+        length = storage.length;
+    }
+    catch {
+        return [];
+    }
+    for (let i = 0; i < length; i++) {
+        let key = null;
+        try {
+            key = storage.key(i);
+        }
+        catch {
+            continue;
+        }
+        if (!key || !key.startsWith(prefix))
+            continue;
+        let raw = null;
+        try {
+            raw = storage.getItem(key);
+        }
+        catch {
+            continue;
+        }
+        if (raw === null)
+            continue;
+        try {
+            const parsed = JSON.parse(raw);
+            if (isValidEnvelope(parsed)) {
+                slots.push({
+                    name: key.slice(prefix.length),
+                    timestamp: parsed.timestamp,
+                    version: parsed.version,
+                    sizeBytes: raw.length,
+                });
+            }
+        }
+        catch {
+            // skip corrupt entries
+        }
+    }
+    return slots;
+}
+//# sourceMappingURL=save.js.map

package/dist/save.js.map ADDED Viewed

@@ -0,0 +1 @@

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

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "zx-kit",
-  "version": "0.15.0",
+  "version": "0.16.1",
   "repository": {
     "type": "git",
     "url": "https://github.com/zrebec/zx-kit.git"
@@ -36,11 +36,15 @@
     "node": ">=22"
   },
   "license": "MIT",
+  "overrides": {
+    "npm": ">=11.14.1"
+  },
   "devDependencies": {
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
     "@semantic-release/github": "^12.0.6",
     "@semantic-release/npm": "^13.1.5",
+    "@vitest/coverage-v8": "^4.1.6",
     "jsdom": "^29.1.1",
     "semantic-release": "^25.0.3",
     "typescript": "^6.0.3",