zx-kit 0.10.0 → 0.12.0

package/README.md

@@ -1,384 +1,560 @@
 # zx-kit
 
-Reusable ZX Spectrum primitives for browser games built with Vite + TypeScript + Canvas + Web Audio API.
+> **Build browser games that look and sound like a ZX Spectrum — without any of its limitations.**
 
-Extracted from [Minefield](https://github.com/zrebec/minefield) — a ZX Spectrum-style minesweeper game. All modules enforce strict Spectrum authenticity: 8×8 pixel grid, 15-color palette, 1-bit square-wave audio, bitmap font.
+Three-channel chiptune audio. Pixel-perfect canvas rendering. Authentic 15-color palette. ROM bitmap font. Tile maps with seasonal swapping. Physics-based sprites. Collision detection. A complete retro game engine in a single zero-dependency npm package.
+
+[![npm](https://img.shields.io/npm/v/zx-kit)](https://www.npmjs.com/package/zx-kit)
+[![license](https://img.shields.io/npm/l/zx-kit)](LICENSE)
+
+---
+
+## Why zx-kit?
+
+The ZX Spectrum was a marvel of constraint. Its 8×8 pixel grid, 15-color palette, and 1-bit beeper defined an entire visual and sonic language. Thousands of games were made with nearly nothing — and they were unforgettable.
+
+zx-kit lets you build in that same visual tradition, but with everything the original hardware was too limited to provide: three-channel AY-3-8912 chiptune audio with hardware-accurate envelopes and LFSR noise, smooth canvas rendering, physics-based sprites, and collision detection — all in TypeScript, all in the browser, all with zero dependencies.
+
+The goal is simple: **it should look and sound like a Spectrum, but run like a modern game.**
+
+---
+
+## Key Features
+
+- **AY-3-8912 Melodik emulator** — three independent square-wave channels, LFSR noise generator, all 16 hardware envelope shapes, logarithmic amplitude table accurate to the real chip
+- **ZX Spectrum ROM font** — all 96 printable ASCII characters, 8×8 pixels, byte-for-byte faithful to the original ROM
+- **Authentic 15-color palette** — normal and bright variants, palette-enforced at compile time via the `SpectrumColor` type
+- **Canvas renderer** — pixel-perfect scaled rendering, sprite flipping, text drawing, CRT scanline overlay, animated border flashing
+- **Tile map engine** — scrollable maps, O(1) id-index, smart seasonal background swapping, solid-tile collision queries
+- **Free-roaming sprites** — position, velocity, gravity, `flipX` caching, transparent or opaque background
+- **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
+- **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`
+
+---
+
+## Live Demo
+
+**[Minefield — ZX Spectrum Minesweeper](https://zrebec.github.io/minefield/)** — built entirely with zx-kit.
 
 ---
 
 ## Installation
 
+### From npm (recommended)
+
 ```bash
 npm install zx-kit
 ```
 
-Import from the barrel:
+Then import directly — no Vite alias, no path mapping, no bundler configuration required:
 
 ```ts
-import { C, CELL, setupCanvas, initAudio, playPattern, initInput, tickMovement } from 'zx-kit'
+import { setupCanvas, C, CELL, initAudio, playAY, initInput } from 'zx-kit'
 ```
 
-No Vite alias or path mapping required — the package ships compiled JavaScript (`dist/`).
+The package ships compiled JavaScript (`dist/`) with full TypeScript declarations.
+
+### From source (local / offline development)
+
+Clone the repository and link it into your project:
+
+```bash
+# 1. Clone and build zx-kit
+git clone https://github.com/zrebec/zx-kit.git
+cd zx-kit
+npm install
+npm run build
+
+# 2. In your game project — install from local path
+npm install ../zx-kit
+```
+
+> Use `npm install ../zx-kit --prefer-online` if npm caches the local path aggressively.
+> Switch back to the npm version any time: `npm install zx-kit@latest`
 
 ---
 
-## Quick start
+## Quick Start
+
+A game loop in under 30 lines:
 
 ```ts
-import { setupCanvas, C, CELL, drawText, initAudio, playPattern, initInput, tickMovement } from 'zx-kit'
+import {
+  setupCanvas, C, CELL,
+  drawText, drawSprite,
+  initAudio, createAY,
+  initInput, tickMovement,
+} from 'zx-kit'
 
-// Canvas — one call replaces the manual boilerplate
 const canvas = document.getElementById('game') as HTMLCanvasElement
-const ctx = setupCanvas(canvas, 4)  // scale=4, 256×192 game px → 1024×768 CSS px
+const ctx = setupCanvas(canvas, 4)  // 256×192 game px → 1024×768 CSS px
 
-// Input
 initInput()
 
-// Audio (must be inside a user gesture)
-window.addEventListener('keydown', () => initAudio(), { once: true })
+// Audio must start inside a user gesture (browser policy)
+let ay: ReturnType<typeof createAY> | null = null
+window.addEventListener('keydown', () => {
+  initAudio()
+  ay = createAY()
+  ay.tone('A', 440, 10)  // start a tone on channel A
+}, { once: true })
+
+const PLAYER = new Uint8Array([0x18, 0x3C, 0x7E, 0xFF, 0xFF, 0x7E, 0x24, 0x66])
+let px = 120, py = 88
+
+let last = performance.now()
+function loop(now: number) {
+  const dt = now - last; last = now
 
-// Game loop
-function loop(dt: number) {
   const dir = tickMovement(dt)
-  if (dir) movePlayer(dir)
+  if (dir === 'left')  px -= 1
+  if (dir === 'right') px += 1
+  if (dir === 'up')    py -= 1
+  if (dir === 'down')  py += 1
+
+  ctx.fillStyle = C.BLACK
+  ctx.fillRect(0, 0, 256, 192)
+  drawText(ctx, 'ZX-KIT', 0, 0, C.B_GREEN, C.BLACK)
+  drawSprite(ctx, PLAYER, px, py, C.B_CYAN, C.BLACK)
 
-  drawText(ctx, 'SCORE:00000', 0, 0, C.B_WHITE, C.BLACK)
-  requestAnimationFrame(t => loop(t - lastT))
+  requestAnimationFrame(loop)
 }
+requestAnimationFrame(loop)
 ```
 
 ---
 
 ## Modules
 
-### `palette.ts` — ZX Spectrum color constants
-
-#### Exports
-
-| Export | Type | Description |
-|--------|------|-------------|
-| `SCALE` | `number` | CSS pixel scale factor (1 game pixel = 4 CSS pixels) |
-| `CELL` | `number` | Sprite / character grid size: `8` game pixels |
-| `C` | `object` | All 15 Spectrum colors as `#RRGGBB` hex strings |
-| `SpectrumColor` | `type` | Union of every value in `C` — use for compile-time palette enforcement |
-
-#### Color table
-
-Normal brightness:
-
-| Key | Hex |
-|-----|-----|
-| `C.BLACK` | `#000000` |
-| `C.BLUE` | `#0000CD` |
-| `C.RED` | `#CD0000` |
-| `C.MAGENTA` | `#CD00CD` |
-| `C.GREEN` | `#00CD00` |
-| `C.CYAN` | `#00CDCD` |
-| `C.YELLOW` | `#CDCD00` |
-| `C.WHITE` | `#CDCDCD` |
-
-Bright variants (`B_` prefix):
-
-| Key | Hex |
-|-----|-----|
-| `C.B_BLACK` | `#000000` |
-| `C.B_BLUE` | `#0000FF` |
-| `C.B_RED` | `#FF0000` |
-| `C.B_MAGENTA` | `#FF00FF` |
-| `C.B_GREEN` | `#00FF00` |
-| `C.B_CYAN` | `#00FFFF` |
-| `C.B_YELLOW` | `#FFFF00` |
-| `C.B_WHITE` | `#FFFFFF` |
+| Module | What it provides |
+|--------|-----------------|
+| [`ay.ts`](#ayts--ay-3-8912-melodik-audio) | AY chip emulator: 3-channel tone, LFSR noise, 16 envelope shapes |
+| [`renderer.ts`](#rendererts--canvas-renderer) | Canvas setup, sprites, text, scanlines, border flash |
+| [`audio.ts`](#audiots--beeper-audio) | 1-bit beeper: square-wave notes, patterns, volume control |
+| [`ui.ts`](#uits--ui-widgets) | Progress bars, boxes, frames, panel titles |
+| [`input.ts`](#inputts--keyboard-input) | Movement with key-repeat, action flags, state reset |
+| [`sprite.ts`](#spritets--free-roaming-sprites) | Sprites: position, velocity, gravity, flip, render |
+| [`collision.ts`](#collisionts--aabb-collision) | AABB overlap tests, tile-map wall resolution |
+| [`animation.ts`](#animationts--frame-timer--tween) | Frame-timer for sprite strips, position tween between two points |
+| [`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 |
 
 ---
 
-### `font.ts` — ZX Spectrum ROM bitmap font
+## `ay.ts` — AY-3-8912 Melodik Audio
 
-96 printable characters (ASCII 32–127), each 8×8 pixels. Character 127 is a solid block █.
+The AY-3-8912 chip (sold as the *Melodik* add-on for ZX Spectrum 48K, built into the 128K) gave the Spectrum three independent square-wave channels, a shared LFSR noise generator, and a hardware envelope generator with 16 distinct shapes. This module emulates all of it via the Web Audio API with hardware-accurate logarithmic amplitude values.
 
-#### Exports
+Two usage modes:
 
-| Export | Signature | Description |
-|--------|-----------|-------------|
-| `FONT` | `Uint8Array` | Flat array: 96 chars × 8 bytes. `FONT[(code-32)*8 + row]` = one row bitmap. |
-| `getCharRow` | `(charCode, row) => number` | Bitmap byte for one row of a character (bit 7 = leftmost pixel). |
+| Mode | Function | Use case |
+|------|----------|----------|
+| **Real-time** | `createAY()` | Persistent chip handle — set channels live (SFX, dynamic music) |
+| **Sequencer** | `playAY(pattern)` | Pre-scheduled, fire-and-forget (music tracks, jingles) |
 
-In practice use `drawChar` / `drawText` from `renderer.ts` — you rarely need `getCharRow` directly.
+Both modes route through the zx-kit master `GainNode`, so `setMasterVolume()` works globally.
 
----
+### `AY_CLOCK`
 
-### `renderer.ts` — Canvas drawing primitives
+```ts
+export const AY_CLOCK = 1_773_400  // Hz — ZX Spectrum 128K / Melodik
+```
 
-All functions work in **game pixels**. At `SCALE=4` each game pixel maps to a 4×4 CSS pixel block. Call `setupCanvas` once at startup to configure the canvas correctly.
+The AY-3-8912 master clock. Exported for use in frequency calculations:
+`f_Hz = AY_CLOCK / (16 × period_register)`.
 
-Every draw function follows the ZX Spectrum **ink / paper** model: each 8×8 cell has one foreground (ink) and one background (paper) color.
+### `AY_VOL`
 
-#### `setupCanvas(canvas, scale, width?, height?): CanvasRenderingContext2D`
+```ts
+export const AY_VOL: readonly number[] = [
+  0, 0.0089, 0.0118, 0.0156, 0.0211, 0.0289, 0.0403, 0.0549,
+  0.0744, 0.1060, 0.1518, 0.2139, 0.2969, 0.4259, 0.6098, 1.0,
+]
+```
 
-Initialises a canvas element for pixel-perfect scaled rendering. Sets canvas dimensions, applies CSS size, disables image smoothing, and calls `ctx.scale(scale, scale)` so all subsequent draw calls use game-pixel coordinates. **Replaces the manual canvas setup boilerplate.**
+Hardware-accurate logarithmic amplitude table. Each step ≈ √2 (3 dB), matching the real chip's resistor ladder. Index 0 = silence, index 15 = full amplitude.
 
-- `scale` — CSS pixels per game pixel (`4` = standard ZX Spectrum display)
-- `width` — game pixels wide (default `256`)
-- `height` — game pixels tall (default `192`)
+### `AY_ENVELOPE_SHAPES`
 
 ```ts
-const canvas = document.getElementById('game') as HTMLCanvasElement
-const ctx = setupCanvas(canvas, 4)           // 256×192 game px → 1024×768 CSS px
-const ctx = setupCanvas(canvas, 4, 256, 208) // taller canvas for status rows
-// ctx.imageSmoothingEnabled is already false — no need to set it manually
-// all draw calls use game-pixel coordinates — ctx.scale() is already applied
+export const AY_ENVELOPE_SHAPES: readonly string[]
 ```
 
-#### `mirrorSprite(src): Uint8Array`
+Human-readable names for all 16 R13 envelope shapes — useful for documentation, tooling, and debugging.
+
+| R13 | Shape | Description |
+|-----|-------|-------------|
+| 0–3 | `\_ ` | One-shot decay, hold at zero |
+| 4–7 | `/_ ` | One-shot attack, hold at zero |
+| 8   | `\\\\` | Repeat decay (sawtooth down) |
+| 9   | `\_`  | One-shot decay, hold at zero |
+| 10  | `\/\/` | Alternate down/up (triangle) |
+| 11  | `\‾`  | One-shot decay, hold at maximum |
+| 12  | `//`  | Repeat attack (sawtooth up) |
+| 13  | `/‾`  | One-shot attack, hold at maximum |
+| 14  | `/\/\`| Alternate up/down (triangle) |
+| 15  | `/_`  | One-shot attack, hold at zero |
 
-Flips an 8×8 sprite horizontally. Returns a new `Uint8Array`.
+### `AYChannel` type
 
 ```ts
-export const PLAYER_RIGHT = new Uint8Array([...])
-export const PLAYER_LEFT  = mirrorSprite(PLAYER_RIGHT)
+type AYChannel = 'A' | 'B' | 'C'
 ```
 
-#### `drawSprite(ctx, sprite, x, y, ink, paper): void`
-
-Draws an 8×8 sprite at game coordinates. Always fills the background first.
+### `AYNote` interface
 
 ```ts
-drawSprite(ctx, MINE_SPRITE, col * CELL, row * CELL, C.B_RED, C.BLACK)
+interface AYNote {
+  freq:          number   // Hz — 0 = rest
+  dur:           number   // milliseconds
+  vol?:          number   // 0–15 (default 15). Ignored when envShape is set.
+  noise?:        boolean  // mix LFSR noise alongside tone (default false)
+  noisePeriod?:  number   // 1–31 — higher = darker texture (default 8)
+  envShape?:     number   // 0–15 (R13) — activates envelope, overrides vol
+  envCycleDurMs?: number  // ms for one ramp (15→0 or 0→15). Default = note duration.
+}
 ```
 
-#### `drawChar(ctx, code, x, y, ink, paper?): void`
+### `AYChip` interface
 
-Draws one ASCII character using the ROM font. Omit `paper` for transparent background.
+The handle returned by `createAY()`.
 
 ```ts
-drawChar(ctx, 127, x, y, C.B_GREEN, C.BLACK)  // solid block █
-drawChar(ctx, 'A'.charCodeAt(0), x, y, C.B_WHITE)
+interface AYChip {
+  tone(ch: AYChannel, freq: number, vol?: number): void
+  enableNoise(ch: AYChannel, period?: number): void
+  disableNoise(ch: AYChannel): void
+  envelope(ch: AYChannel, shape: number, cycleDurMs: number): void
+  mute(ch: AYChannel): void
+  muteAll(): void
+  stop(): void
+}
 ```
 
-#### `drawText(ctx, text, x, y, ink, paper?): void`
+### `createAY(): AYChip`
 
-Draws a string left-to-right, one character per `CELL`-wide slot.
+Creates three persistent AY channels wired to the master gain. Each channel has:
+- An independent square-wave oscillator (tone)
+- An LFSR noise path (shared 17-bit noise source, per-channel lowpass filter and gain)
+- `AudioParam` automation for envelope
+
+Must be called inside a user-gesture handler.
 
 ```ts
-drawText(ctx, 'SCORE:00000', 0, statusY, C.B_WHITE, C.BLACK)
+button.addEventListener('click', () => {
+  initAudio()
+  const ay = createAY()
+
+  // Simple tone
+  ay.tone('A', 440, 12)           // channel A: A4, amplitude level 12
+
+  // Tone + noise mix
+  ay.tone('B', 220, 10)
+  ay.enableNoise('B', 16)         // darker noise (higher period = lower cutoff)
+
+  // Envelope — shape 10 = \/\/ triangle, 400ms cycle
+  ay.tone('C', 110, 0)            // oscillator active but tone gain is silent
+  ay.envelope('C', 10, 400)       // envelope drives the amplitude
+
+  setTimeout(() => ay.muteAll(), 3000)
+  setTimeout(() => ay.stop(), 3500)
+})
 ```
 
-#### `drawTextCentered(ctx, text, y, cols, ink, paper?): void`
+#### `ay.tone(ch, freq, vol?)`
+
+Sets the channel oscillator frequency and amplitude. `freq ≤ 0` silences the tone generator (noise can still run). `vol` maps to `AY_VOL` (0–15, default 15). Cancels any running envelope on that channel.
+
+#### `ay.enableNoise(ch, period?)`
 
-Centers a string within `cols` character columns. Bind `cols` once in a helper to avoid repetition.
+Enables LFSR noise on a channel. `period` 1–31 maps to `AY_CLOCK / (16 × period)` Hz as a lowpass cutoff on the noise path. Default period 8 → ~13 kHz (bright, crispy). Period 28 → ~4 kHz (darker, rumble-like).
+
+#### `ay.disableNoise(ch)`
+
+Fades noise out on a channel with a 5ms release.
+
+#### `ay.envelope(ch, shape, cycleDurMs)`
+
+Applies an AY hardware envelope to a channel's amplitude. `shape` 0–15 corresponds to the 16 R13 values. `cycleDurMs` is the duration of one ramp (0→15 or 15→0). Repeating shapes (8, 10, 12, 14) are pre-scheduled for 32 cycles; call again to extend.
 
 ```ts
-// Bind once:
-const centered = (ctx: CanvasRenderingContext2D, text: string, y: number, ink: SpectrumColor) =>
-  drawTextCentered(ctx, text, y, 32, ink)
+// Explosion: channel C, shape 8 (repeat decay), 60ms per cycle
+ay.enableNoise('C', 5)
+ay.envelope('C', 8, 60)
 
-centered(ctx, 'GAME  OVER', y, C.B_RED)
+// Organ: shape 13 (/‾ fast attack, hold high), 20ms attack
+ay.tone('A', 523, 0)
+ay.envelope('A', 13, 20)
 ```
 
-#### `flashBorder(color, times, intervalMs, resetColor?): void`
+#### `ay.mute(ch)` / `ay.muteAll()`
 
-Flashes `document.body.style.backgroundColor` between `color` and `resetColor`. Fire-and-forget — does not block. One flash = one `color → resetColor` cycle. Always resets to `resetColor` on completion (default `C.BLACK`).
+Fade out one or all channels (5ms release). Cancels any pending envelope automation.
+
+#### `ay.stop()`
+
+Stops all oscillators and the noise source, disconnects all Web Audio nodes. Call when discarding the chip instance.
+
+---
+
+### `playAY(pattern, startDelay?): void`
+
+Pre-schedules up to three independent note arrays on the shared `AudioContext`. All channels start at the same wall-clock time. Fire-and-forget — no handle returned. Per-note noise and envelope are fully supported.
 
 ```ts
-flashBorder(C.B_RED, 3, 150)           // explosion — 3 red flashes → black
-flashBorder(C.B_GREEN, 2, 200)         // level complete
-flashBorder(C.B_CYAN, 2, 120, C.BLUE)  // flash → reset to blue border
+// Three-channel chiptune jingle with envelope and noise
+playAY({
+  a: [
+    { freq: 523, dur: 300, envShape: 13, envCycleDurMs: 20 },  // C5, organ attack
+    { freq: 659, dur: 300, envShape: 13, envCycleDurMs: 20 },  // E5
+    { freq: 784, dur: 600, envShape: 12, envCycleDurMs: 100 }, // G5, sawtooth swell
+  ],
+  b: [
+    { freq: 261, dur: 600, vol: 10 },   // C4 bass note
+    { freq: 329, dur: 600, vol: 10 },   // E4
+  ],
+  c: [
+    { freq: 0, dur: 100, noise: true, noisePeriod: 5, envShape: 8, envCycleDurMs: 40 },  // snare hit
+    { freq: 0, dur: 1100 },  // silence
+  ],
+})
+
+// With a 500ms startup delay
+playAY({ a: melody, b: bass }, 500)
 ```
 
 ---
 
-### `audio.ts` — Web Audio engine (ZX Spectrum style)
+## `renderer.ts` — Canvas Renderer
 
-Wraps the Web Audio API for authentic 1-bit square-wave sound. All audio goes through a shared `AudioContext` and a single master `GainNode`.
+All drawing functions operate in **game pixels**. `setupCanvas` applies `ctx.scale(scale, scale)` so every call uses the ZX Spectrum's native coordinate space. Every ink/paper parameter is `SpectrumColor` — the compiler enforces the palette.
 
-**Browser autoplay policy:** `AudioContext` must be created inside a user gesture (click or keydown). Call `initAudio()` from an event handler.
+### `setupCanvas(canvas, scale, width?, height?): CanvasRenderingContext2D`
 
-#### `initAudio(volume?): void`
+One-call canvas initialization. Sets dimensions, CSS size, disables smoothing, applies scale transform.
 
-Creates the `AudioContext` and master gain. Idempotent — safe to call multiple times. `volume` is clamped to 0.0–1.0.
+- `scale` — CSS pixels per game pixel. `4` = standard ZX display (256×192 → 1024×768)
+- `width` — game pixels wide, default `256`
+- `height` — game pixels tall, default `192`
 
 ```ts
-window.addEventListener('keydown', () => initAudio(), { once: true })
-window.addEventListener('click',   () => initAudio(), { once: true })
+const ctx = setupCanvas(canvas, 4)            // standard 256×192
+const ctx = setupCanvas(canvas, 4, 256, 208)  // +2 extra rows for status bar
+const ctx = setupCanvas(canvas, 3)            // 768×576 CSS — smaller screen
 ```
 
-#### `resumeAudio(): void`
+### `mirrorSprite(src): Uint8Array`
+
+Flips an 8-byte sprite horizontally. Returns a new `Uint8Array` — the original is not modified. The result is cache-friendly: call once and store both orientations.
 
-Resumes a suspended `AudioContext`. Call before scheduling audio in the game loop.
+```ts
+export const PLAYER_RIGHT = new Uint8Array([0x18, 0x3C, 0x7E, 0xFF, 0xFF, 0x7E, 0x24, 0x66])
+export const PLAYER_LEFT  = mirrorSprite(PLAYER_RIGHT)
+```
 
-#### `getAudioContext(): AudioContext | null`
+### `drawSprite(ctx, sprite, x, y, ink, paper): void`
 
-Returns the current context, or `null` before `initAudio()`.
+Draws an 8×8 bitmap at game coordinates. Always paints the `paper` background first. `ink` and `paper` must be `SpectrumColor` values.
 
-#### `getMasterGain(): GainNode | null`
+```ts
+drawSprite(ctx, MINE_SPRITE, col * CELL, row * CELL, C.B_RED,   C.BLACK)
+drawSprite(ctx, GEM_SPRITE,  col * CELL, row * CELL, C.B_CYAN,  C.BLACK)
+drawSprite(ctx, DOOR_SPRITE, col * CELL, row * CELL, C.YELLOW,  C.B_BLUE)
+```
 
-Returns the master gain node. Connect custom oscillators here to respect global volume.
+### `drawChar(ctx, charCode, x, y, ink, paper?): void`
 
-#### `getMasterVolume(): number`
+Draws one ASCII character from the ROM font. Omit `paper` for a transparent background (only ink pixels are drawn).
 
-Returns the current master volume (0.0–1.0), or `0` before `initAudio()`.
+```ts
+drawChar(ctx, 127, x, y, C.B_GREEN, C.BLACK)        // solid block █
+drawChar(ctx, 'A'.charCodeAt(0), x, y, C.B_WHITE)   // transparent bg
+```
 
-#### `setMasterVolume(volume): void`
+### `drawText(ctx, text, x, y, ink, paper?): void`
 
-Sets master volume. Clamped to 0.0–1.0. No-op before `initAudio()`.
+Draws a string left-to-right, one character per `CELL`-wide slot.
 
 ```ts
-setMasterVolume(0.5)  // 50%
-setMasterVolume(0)    // mute
-setMasterVolume(1)    // full
+drawText(ctx, 'SCORE:00000', 0, statusY, C.B_WHITE, C.BLACK)
+drawText(ctx, 'PRESS ANY KEY', x, y, C.B_YELLOW)  // transparent bg
 ```
 
-#### `increaseVolume(): void` / `decreaseVolume(): void`
+### `drawTextCentered(ctx, text, y, cols, ink, paper?): void`
 
-Adjusts master volume by ±0.1, clamped at 0.0–1.0.
+Centers a string within `cols` character columns.
 
 ```ts
-// Volume keys
-if (consumeAnyKey()) increaseVolume()  // example: + key
-decreaseVolume()                        // example: - key
+// Bind the column count once to keep call sites clean
+const print = (text: string, y: number, ink: SpectrumColor) =>
+  drawTextCentered(ctx, text, y, 32, ink)
 
-// Current state
-const vol = getMasterVolume()  // e.g. 0.4 after one increaseVolume()
+print('GAME  OVER', 88,  C.B_RED)
+print('PRESS ANY KEY', 104, C.B_WHITE)
 ```
 
-#### `Note` interface
+### `flashBorder(color, times, intervalMs, resetColor?): void`
+
+Animates `document.body.style.backgroundColor`. Fire-and-forget — does not block. Each call cancels any in-flight flash (no overlapping intervals). Always resets to `resetColor` when the sequence completes.
+
+- `resetColor` defaults to `C.BLACK`
 
 ```ts
-interface Note {
-  freq: number  // Hz — use 0 for a rest (silence)
-  dur: number   // ms — duration of note or rest
-}
+flashBorder(C.B_RED,   3, 150)              // 3 red flashes → black (explosion)
+flashBorder(C.B_GREEN, 2, 200)              // level complete
+flashBorder(C.B_CYAN,  2, 120, C.B_BLUE)   // flash → reset to blue border
 ```
 
-#### `playPattern(notes, startDelay?): void`
+### `drawScanlines(ctx, width?, height?, alpha?): void`
 
-Schedules a sequence of notes. `freq: 0` = rest (advances time, no sound). `startDelay` delays the whole pattern in milliseconds.
+Draws a CRT scanline overlay. Every even row gets a semi-transparent black stripe. Pass the same `width`/`height` as `setupCanvas`, or omit to use the defaults (256×192).
 
 ```ts
-// Rising arpeggio
-playPattern([
-  { freq: 262, dur: 100 },  // C4
-  { freq: 330, dur: 100 },  // E4
-  { freq: 392, dur: 100 },  // G4
-  { freq: 523, dur: 200 },  // C5
-])
-
-// With rests and a 200ms startup delay
-playPattern([
-  { freq: 523, dur: 120 },  // C5
-  { freq: 0,   dur: 40  },  // rest
-  { freq: 784, dur: 200 },  // G5
-], 200)
+// At the end of each frame, after all game content:
+drawScanlines(ctx)              // standard 256×192, alpha=0.18
+drawScanlines(ctx, 256, 208)    // taller canvas
+drawScanlines(ctx, 256, 192, 0.25)  // darker scanlines
 ```
 
-#### `beep(freq, durationMs, startTime): void`
+### `curveDisplay(ctx, width?, height?, strength?): void`
 
-Schedules a single square-wave beep at an absolute `AudioContext.currentTime`. Use `playPattern` for sequences; use `beep` directly when you need algorithmic timing control.
+Applies a CRT barrel-distortion warp to the canvas content using a temporary off-screen canvas and a `quadraticCurveTo` warp. Gives the display a subtle CRT monitor feel.
 
 ```ts
-const audio = getAudioContext()!
-resumeAudio()
-beep(880, 80, audio.currentTime)
-beep(880, 80, audio.currentTime + 0.14)  // 140ms later
+// Last step, after drawScanlines:
+curveDisplay(ctx)               // default strength
+curveDisplay(ctx, 256, 208, 6)  // stronger warp
 ```
 
 ---
 
-### `input.ts` — Keyboard input with key-repeat
+## `audio.ts` — Beeper Audio
+
+Single-channel 1-bit square-wave audio, faithful to the ZX Spectrum beeper. Use this for simple SFX and monophonic melodies. For music with harmony, noise, and envelopes, use `ay.ts`.
 
-Handles arrow-key movement with configurable key-repeat (immediate on first press, auto-repeat on hold) plus single-consume flags for action keys.
+All audio routes through a shared `AudioContext` and master `GainNode`. **`initAudio()` must be called inside a user-gesture handler** due to browser autoplay policy.
 
-**Call `initInput()` once at startup.** Then call `tickMovement(dt)` every frame.
+### `initAudio(volume?): void`
 
-#### `Direction` type
+Creates the `AudioContext` and master gain node. Idempotent — safe to call multiple times. `volume` is clamped to 0.0–1.0 (default `0.3`).
 
 ```ts
-type Direction = 'up' | 'down' | 'left' | 'right'
+window.addEventListener('keydown', () => initAudio(), { once: true })
+window.addEventListener('click',   () => initAudio(), { once: true })
 ```
 
-#### `initInput(repeatDelay?, repeatInterval?): void`
+### `resumeAudio(): void`
 
-Attaches `keydown`/`keyup` listeners. Idempotent — timing params are always updated; listeners are only attached on the first call. Keys: arrows = movement, `F` = flag, `P` = pause, `Ctrl+Shift+B` = debug.
+Resumes a suspended `AudioContext`. Browsers suspend the context on tab hide or first load. Call before scheduling any audio in the game loop.
 
-```ts
-initInput()         // 150ms delay, 80ms repeat
-initInput(200, 60)  // custom timing; safe to call again to reconfigure
-```
+### `getAudioContext(): AudioContext | null`
+
+Returns the shared context, or `null` before `initAudio()`.
+
+### `getMasterGain(): GainNode | null`
+
+Returns the master gain node. Connect custom oscillators here to participate in the global volume level.
+
+### `getMasterVolume(): number`
+
+Returns the current master volume (0.0–1.0), or `0` before `initAudio()`.
 
-#### `tickMovement(dtMs): Direction | null`
+### `setMasterVolume(volume): void`
 
-Returns the movement direction for this frame, or `null`. Call once per frame.
+Sets master volume. Clamped to 0.0–1.0. No-op before `initAudio()`.
 
 ```ts
-const dir = tickMovement(dt)
-if (dir) movePlayer(dir)
+setMasterVolume(0.5)  // 50%
+setMasterVolume(0)    // mute
+setMasterVolume(1)    // full
 ```
 
-#### Consume flags
+### `increaseVolume() / decreaseVolume(): void`
 
-| Function | Trigger | Use case |
-|----------|---------|----------|
-| `consumeFlag()` | `F` key | Flag / unflag a cell |
-| `consumeDebug()` | `Ctrl+Shift+B` | Toggle debug mode |
-| `consumePause()` | `P` key | Pause / unpause |
-| `consumeAnyKey()` | Any key | Dismiss overlays, start game |
+Adjusts master volume by ±0.1, clamped to 0.0–1.0.
 
-Each returns `true` once per press, then resets.
+### `Note` interface
 
-#### `isHeld(key): boolean`
+```ts
+interface Note {
+  freq: number  // Hz — 0 = rest (silence, advances timeline)
+  dur:  number  // ms
+}
+```
+
+### `playPattern(notes, startDelay?): void`
 
-Returns whether a key is currently held. Argument is `KeyboardEvent.key`.
+Schedules a note sequence on the shared `AudioContext`. `freq: 0` entries produce silence for their duration. `startDelay` offsets the entire pattern in milliseconds.
 
 ```ts
-if (isHeld('ArrowUp')) { ... }
+// Rising arpeggio
+playPattern([
+  { freq: 262, dur: 80 },   // C4
+  { freq: 330, dur: 80 },   // E4
+  { freq: 392, dur: 80 },   // G4
+  { freq: 523, dur: 160 },  // C5
+])
+
+// With rest and startup delay
+playPattern([
+  { freq: 880, dur: 100 },
+  { freq: 0,   dur: 50  },  // rest
+  { freq: 880, dur: 100 },
+], 200)
 ```
 
-#### `resetInput(): void`
+### `beep(freq, durationMs, startTime): void`
 
-Clears all pending key state immediately. Call on game phase transitions to prevent stale inputs carrying over.
+Schedules a single square-wave note at an absolute `AudioContext.currentTime`. Uses a 5ms linear ramp on attack and release to avoid click artefacts. Use `playPattern` for sequences; use `beep` when you need algorithmic or sample-accurate timing.
 
 ```ts
-appPhase = 'gameover'
-resetInput()  // discard any queued keypresses from the previous phase
+const audio = getAudioContext()!
+resumeAudio()
+beep(440, 80, audio.currentTime)
+beep(880, 80, audio.currentTime + 0.15)  // 150ms later
 ```
 
 ---
 
-### `ui.ts` — ZX-style UI primitives
+## `ui.ts` — UI Widgets
 
-High-level drawing helpers and a stateful widget system for HUD elements.
-All primitives operate in game pixels and enforce the Spectrum palette via `SpectrumColor`.
+High-level drawing helpers and a stateful widget system for HUD elements. All primitives operate in game pixels and enforce the Spectrum palette.
 
-#### Types
+### Types
 
-**`BorderOptions`**
+#### `BorderOptions`
 
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
-| `enabled` | `boolean` | `true` | Set to `false` to suppress the border without removing the object |
-| `thickness` | `number` | `1` | Border thickness in pixels |
-| `color` | `SpectrumColor` | same as ink/color | Overrides the parent function's foreground color |
-| `style` | `'solid' \| 'dashed'` | `'solid'` | Solid = continuous lines; dashed = 2 px on / 2 px off |
+| `enabled` | `boolean` | `true` | Set `false` to suppress border without removing the object |
+| `thickness` | `number` | `1` | Border thickness in game pixels |
+| `color` | `SpectrumColor` | parent ink | Overrides the parent function's foreground color |
+| `style` | `'solid' \| 'dashed'` | `'solid'` | `'dashed'` = 2 px on / 2 px off |
 
-**`DrawProgressBarOptions`**
+#### `DrawProgressBarOptions`
 
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
 | `id` | `string` | `"${x},${y}"` | Stable key for managed redraws |
 | `x` | `number` | — | Left edge in game pixels |
 | `y` | `number` | — | Top edge in game pixels |
-| `width` | `number` | — | Total width in game pixels (multiples of `CELL = 8` recommended) |
+| `width` | `number` | — | Total width (multiples of `CELL = 8` recommended) |
 | `value` | `number` | — | Current value |
-| `min` | `number` | `0` | Value at the left (empty) edge |
-| `max` | `number` | `1` | Value at the right (full) edge |
+| `min` | `number` | `0` | Empty-edge value |
+| `max` | `number` | `1` | Full-edge value |
 | `ink` | `SpectrumColor` | `C.B_WHITE` | Filled-block color |
 | `paper` | `SpectrumColor` | `C.BLACK` | Empty-block background |
-| `border` | `BorderOptions` | — | Optional border around the bar |
+| `border` | `BorderOptions` | — | Optional border |
 | `visibilityLength` | `number` | `500` | Ms to stay visible after last call; `0` = permanent |
 
-#### Stateless primitives
+### Stateless primitives
 
-##### `drawBox(ctx, options): void`
+#### `drawBox(ctx, options): void`
 
 Fills a rectangle with `paper` and draws an optional border.
 
@@ -390,7 +566,7 @@ drawBox(ctx, {
 })
 ```
 
-##### `drawFrame(ctx, options): void`
+#### `drawFrame(ctx, options): void`
 
 Draws a border only — no background fill.
 
@@ -400,10 +576,9 @@ drawFrame(ctx, { x: 16, y: 16, width: 64, height: 32, color: C.B_RED,
   border: { style: 'dashed' } })
 ```
 
-##### `drawPanelTitle(ctx, options): void`
+#### `drawPanelTitle(ctx, options): void`
 
-Renders a text strip (height = `CELL + padding * 2`) with optional background fill.
-Does NOT draw the surrounding container — use `drawBox` / `drawFrame` separately.
+Renders a text strip (`CELL + padding * 2` height) with optional background fill. Does not draw a surrounding container — combine with `drawBox` or `drawFrame`.
 
 ```ts
 drawBox(ctx, { x: 8, y: 24, width: 128, height: 56, paper: C.BLACK })
@@ -414,18 +589,16 @@ drawPanelTitle(ctx, {
 })
 ```
 
-#### Stateful widget — progress bar
+### Stateful widget — Progress Bar
 
-The progress bar is a managed widget: after a `drawProgressBar` call, the bar is
-re-rendered automatically on subsequent frames by `renderUI` until `visibilityLength`
-milliseconds have elapsed. Calling `drawProgressBar` again resets the timer.
+The progress bar is a **managed widget**: after a `drawProgressBar` call, the bar is automatically re-rendered on subsequent frames by `renderUI` until `visibilityLength` milliseconds have elapsed. Calling `drawProgressBar` again resets the timer.
 
-##### `drawProgressBar(ctx, options): void`
+#### `drawProgressBar(ctx, options): void`
 
 Draws the bar immediately **and** registers it for managed redraws.
 
 ```ts
-// On value change:
+// Appears for 1.5 s after each volume change
 drawProgressBar(ctx, {
   id: 'volume', x: 88, y: 88, width: 80,
   value: getMasterVolume(),
@@ -434,7 +607,7 @@ drawProgressBar(ctx, {
   visibilityLength: 1500,
 })
 
-// Permanent HUD element:
+// Permanent HUD element (visibilityLength: 0)
 drawProgressBar(ctx, {
   id: 'health', x: 0, y: 184, width: 40,
   value: lives, min: 0, max: 3,
@@ -443,25 +616,25 @@ drawProgressBar(ctx, {
 })
 ```
 
-##### `tickUI(dtMs): void`
+#### `tickUI(dtMs): void`
 
 Advances all managed bar timers. Expired bars are removed. Call once per frame.
 
-##### `renderUI(ctx): void`
+#### `renderUI(ctx): void`
 
 Redraws all currently visible bars. Call every frame **after** the game world render.
 
-##### `resetUI(): void`
+#### `resetUI(): void`
 
-Clears all managed state. Call alongside `resetInput()` on phase transitions.
+Clears all managed widget state. Call alongside `resetInput()` on phase transitions.
 
 ```ts
-// Typical game loop:
+// Typical game loop
 renderFrame(ctx, state)
 tickUI(dt)
 renderUI(ctx)
 
-// Phase transition:
+// Phase transition
 resetInput()
 resetUI()
 appPhase = 'intro'
@@ -469,528 +642,538 @@ appPhase = 'intro'
 
 ---
 
-### `tilemap.ts` — Scrollable tile map
-
-A scrollable, queryable `TileMap` backed by an O(1) id-index. Tiles use the same 8×8 sprite format as `drawSprite`. Supports seasonal background swapping, viewport-clipped rendering, collision queries, and fast id-based lookups.
-Tile colours are palette-typed: `ink` and `paper` must be `SpectrumColor` values from `C`.
+## `input.ts` — Keyboard Input
 
-#### Types
+Handles directional movement with configurable key-repeat (immediate on first press, configurable auto-repeat delay on hold) plus single-consume flags for action keys. Call `initInput()` once at startup, then `tickMovement(dt)` every frame.
 
-**`Tile`**
+### `Direction` type
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `sprite` | `Uint8Array` | 8-byte bitmap — same format as `drawSprite()` |
-| `ink` | `SpectrumColor` | Foreground colour (`C.*` palette value) |
-| `paper` | `SpectrumColor` | Background colour (`C.*` palette value) |
-| `solid` | `boolean` | `true` = blocks movement (walls, rocks, closed doors) |
-| `id` | `string \| number` | Stable identifier for game logic and background swapping |
-| `metadata?` | `Record<string, unknown>` | Optional game-specific payload (points, next level, …) |
+```ts
+type Direction = 'up' | 'down' | 'left' | 'right'
+```
 
-**`Viewport`**
+### `initInput(repeatDelay?, repeatInterval?): void`
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `x` | `number` | First visible column (tile units) |
-| `y` | `number` | First visible row (tile units) |
-| `cols` | `number` | Number of columns to render |
-| `rows` | `number` | Number of rows to render |
+Attaches `keydown`/`keyup` listeners. Idempotent — safe to call multiple times; timing parameters are always updated but listeners are only registered once.
 
-#### `createTileMap(cols, rows): TileMap`
+Default key bindings: arrows = movement, `W A S D` = also movement, `F` = flag action, `P` = pause, `Ctrl+Shift+B` = debug toggle.
 
-Creates an empty map of `cols × rows` tiles — all cells start `null`. Returns a plain object implementing the `TileMap` interface (factory pattern, consistent with the rest of zx-kit).
+```ts
+initInput()          // default: 150ms initial delay, 80ms repeat
+initInput(200, 60)   // custom timing
+```
 
-#### Method reference
+### `tickMovement(dtMs): Direction | null`
 
-| Method | Description |
-|--------|-------------|
-| `setTile(x, y, tile)` | Store a shallow copy of `tile`. Out-of-bounds is a silent no-op. |
-| `getTile(x, y)` | Return the tile at `(x, y)`, or `null`. Never throws. |
-| `clearTile(x, y)` | Remove the tile (e.g. collect gem, break wall). Out-of-bounds is a no-op. |
-| `fill(tile)` | Fill every cell with independent shallow copies of `tile`. |
-| `fillRect(x, y, w, h, tile)` | Fill a rectangle; regions outside the map are silently clipped. |
-| `setBackground(tile)` | Register or swap the background tile (see below). |
-| `render(ctx, viewport?)` | Render the map or viewport via `drawSprite`. Empty cells are skipped. |
-| `isSolid(x, y)` | `true` when the tile is solid, or when the position is out-of-bounds. |
-| `findById(id)` | Return `{ x, y, tile }[]` for all tiles with the given `id` — O(1). |
+Returns the active movement direction for this frame, or `null`. Handles the delay/repeat state machine internally. Call exactly once per frame.
 
-#### Smart background swapping (`setBackground`)
+```ts
+const dir = tickMovement(dt)
+if (dir === 'left')  player.x -= speed * dt
+if (dir === 'right') player.x += speed * dt
+if (dir === 'up')    player.y -= speed * dt
+if (dir === 'down')  player.y += speed * dt
+```
 
-`setBackground` has two modes depending on whether a background has been registered before:
+### Consume flags
 
-- **First call** — registers the tile as the current background. The map is not modified; call `fill` or `fillRect` first to actually place the background tiles.
-- **Subsequent calls (smart swap)** — replaces every cell whose `id` still matches the previous background with a fresh copy of the new tile. Cells with any other `id` (player, gems, rocks, modified terrain) are left completely untouched.
+Each function returns `true` exactly once per key press, then resets to `false`. Designed for single-fire events — menus, flags, pause, etc.
 
-Comparison is by `id` value, so it works correctly after shallow copies.
+| Function | Default key | Typical use |
+|----------|-------------|-------------|
+| `consumeFlag()` | `F` | Flag / unflag a tile |
+| `consumePause()` | `P` | Pause / unpause |
+| `consumeDebug()` | `Ctrl+Shift+B` | Toggle debug overlay |
+| `consumeAnyKey()` | Any key | Dismiss overlays, start game |
 
 ```ts
-map.fill(TILE_GRASS)
-map.setBackground(TILE_GRASS)      // register — map unchanged
+if (consumeFlag())   toggleFlag(playerX, playerY)
+if (consumePause())  appPhase = appPhase === 'paused' ? 'game' : 'paused'
+if (consumeAnyKey()) appPhase = 'game'  // dismiss title screen
+```
 
-map.setTile(5, 3, TILE_PLAYER)     // player placed on grass
+### `isHeld(key): boolean`
 
-map.setBackground(TILE_SNOW)       // TILE_GRASS → TILE_SNOW everywhere
-                                   // TILE_PLAYER at (5, 3) — untouched
+Returns whether a key is currently held down. Argument is `KeyboardEvent.key`.
 
-map.setBackground(TILE_NIGHT)      // TILE_SNOW → TILE_NIGHT
-                                   // TILE_PLAYER — still untouched
+```ts
+if (isHeld('ArrowUp') && isHeld('ArrowRight')) moveDiagonal()
 ```
 
----
-
-#### Boulder Dash-style level
+### `resetInput(): void`
 
-A complete setup showing map construction, collision detection, item collection, and seasonal background swap — the typical usage pattern for a scrollable ZX Spectrum-style game.
+Clears all pending key state immediately — held keys, direction, all consume flags. Call on phase transitions to prevent stale inputs carrying over.
 
 ```ts
-import { createTileMap, C, CELL } from 'zx-kit'
-import type { Tile, Viewport } from 'zx-kit'
+appPhase = 'gameover'
+resetInput()   // discard any queued keypresses from gameplay
+```
 
-// ── Tile definitions ──────────────────────────────────────────────────────────
+---
 
-const TILE_DIRT: Tile = {
-  sprite: new Uint8Array([0x55, 0xAA, 0x55, 0xAA, 0x55, 0xAA, 0x55, 0xAA]),
-  ink: C.YELLOW, paper: C.BLACK,
-  solid: false, id: 'dirt',
-}
-const TILE_WALL: Tile = {
-  sprite: new Uint8Array([0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF]),
-  ink: C.WHITE, paper: C.BLACK,
-  solid: true, id: 'wall',
-}
-const TILE_ROCK: Tile = {
-  sprite: new Uint8Array([0x3C, 0x7E, 0xFF, 0xFF, 0xFF, 0xFF, 0x7E, 0x3C]),
-  ink: C.B_WHITE, paper: C.BLACK,
-  solid: true, id: 'rock',
-}
-const TILE_GEM: Tile = {
-  sprite: new Uint8Array([0x18, 0x3C, 0x7E, 0xFF, 0xFF, 0x7E, 0x3C, 0x18]),
-  ink: C.B_CYAN, paper: C.BLACK,
-  solid: false, id: 'gem',
-  metadata: { points: 10 },
-}
-const TILE_EXIT: Tile = {
-  sprite: new Uint8Array([0x3C, 0x42, 0x99, 0xA5, 0xA5, 0x99, 0x42, 0x3C]),
-  ink: C.B_YELLOW, paper: C.BLACK,
-  solid: false, id: 'exit',
-  metadata: { nextLevel: 2 },
-}
+## `sprite.ts` — Free-Roaming Sprites
 
-// ── Map setup ─────────────────────────────────────────────────────────────────
+Sprites are entities that move in continuous pixel space — not locked to the 8×8 tile grid. Use them for players, enemies, bullets, particles: anything with physics or sub-pixel movement. They integrate directly with `collision.ts` for tile-map wall resolution.
 
-const COLS = 64
-const ROWS = 32
-const map = createTileMap(COLS, ROWS)
+### `Sprite` interface
 
-// Fill with dirt and register it as the seasonal background
-map.fill(TILE_DIRT)
-map.setBackground(TILE_DIRT)
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `x` | `number` | `0` | Horizontal position in game pixels (float allowed) |
+| `y` | `number` | `0` | Vertical position in game pixels |
+| `vx` | `number` | `0` | Horizontal velocity in px/ms |
+| `vy` | `number` | `0` | Vertical velocity in px/ms |
+| `bitmap` | `Uint8Array` | — | 8-byte sprite bitmap |
+| `ink` | `SpectrumColor` | — | Foreground color |
+| `paper` | `SpectrumColor \| null` | `null` | Background color, or `null` for transparent |
+| `flipX` | `boolean` | `false` | Render mirrored horizontally (cached — no per-frame allocation) |
+| `visible` | `boolean` | `true` | When `false`, `renderSprite` skips this entity |
 
-// Perimeter walls
-map.fillRect(0, 0, COLS, 1, TILE_WALL)            // top
-map.fillRect(0, ROWS - 1, COLS, 1, TILE_WALL)     // bottom
-map.fillRect(0, 0, 1, ROWS, TILE_WALL)             // left
-map.fillRect(COLS - 1, 0, 1, ROWS, TILE_WALL)      // right
+### `createSprite(bitmap, ink, paper?): Sprite`
 
-// Objects
-map.setTile(10, 5, TILE_ROCK)
-map.setTile(20, 14, TILE_GEM)
-map.setTile(35, 10, TILE_GEM)
-map.setTile(60, 15, TILE_EXIT)
+Creates a `Sprite` at `(0, 0)` with zero velocity. `paper` defaults to `null` (transparent).
 
-// ── Seasonal swap ─────────────────────────────────────────────────────────────
+```ts
+const PLAYER_BM = new Uint8Array([0x18, 0x3C, 0x7E, 0xFF, 0xFF, 0x7E, 0x24, 0x66])
+const BULLET_BM = new Uint8Array([0x00, 0x00, 0x18, 0x3C, 0x18, 0x00, 0x00, 0x00])
 
-const TILE_SNOW: Tile = {
-  sprite: new Uint8Array([0x00, 0x18, 0x3C, 0xFF, 0x3C, 0x18, 0x00, 0x00]),
-  ink: C.B_WHITE, paper: C.BLACK,
-  solid: false, id: 'snow',
-}
+const player = createSprite(PLAYER_BM, C.B_CYAN)           // transparent bg
+const bullet = createSprite(BULLET_BM, C.B_YELLOW, C.BLACK) // opaque bg
+player.x = 16; player.y = 80
+```
 
-// Winter: only dirt tiles become snow — walls, rocks, gems, exit are untouched
-map.setBackground(TILE_SNOW)
+### `moveSprite(sprite, dt): void`
 
-// ── Game loop ─────────────────────────────────────────────────────────────────
+Advances `sprite.x` by `vx * dt` and `sprite.y` by `vy * dt`. Call once per frame, before collision resolution.
 
-const SCREEN_COLS = 32
-const SCREEN_ROWS = 24
-let playerX = 2
-let playerY = 2
-let score = 0
+### `applyGravity(sprite, gravity, dt): void`
 
-function gameLoop(ctx: CanvasRenderingContext2D) {
-  // Clamp camera so it doesn't scroll past map edges
-  const camX = Math.max(0, Math.min(playerX - Math.floor(SCREEN_COLS / 2), COLS - SCREEN_COLS))
-  const camY = Math.max(0, Math.min(playerY - Math.floor(SCREEN_ROWS / 2), ROWS - SCREEN_ROWS))
+Adds `gravity * dt` to `sprite.vy`. Call once per frame, before `moveSprite`.
 
-  map.render(ctx, { x: camX, y: camY, cols: SCREEN_COLS, rows: SCREEN_ROWS })
-}
+- `gravity` in px/ms² — typical values: `0.002`–`0.005` (platformer), `0.008` (debris)
 
-// ── Collision & interaction ───────────────────────────────────────────────────
+```ts
+applyGravity(player, 0.003, dt)
+moveSprite(player, dt)
+// then resolveX / resolveY...
+```
 
-function tryMove(dx: number, dy: number) {
-  const nx = playerX + dx
-  const ny = playerY + dy
+### `renderSprite(ctx, sprite): void`
 
-  if (map.isSolid(nx, ny)) return  // wall, rock, or map boundary
+Draws the sprite at `(Math.round(x), Math.round(y))`. Skips if `visible === false`. Respects `flipX` (uses cached mirrored bitmap) and `paper: null` (transparent — only ink pixels painted).
 
-  const target = map.getTile(nx, ny)
-  if (target?.id === 'gem') {
-    score += target.metadata!['points'] as number
-    map.clearTile(nx, ny)
-  }
+```ts
+player.flipX = player.vx < 0  // face the direction of movement
+renderSprite(ctx, player)
+```
 
-  playerX = nx
-  playerY = ny
-}
+---
 
-// ── Level completion ──────────────────────────────────────────────────────────
+## `collision.ts` — AABB Collision
 
-const exits = map.findById('exit')   // O(1) — no map scan
-if (exits.some(e => e.x === playerX && e.y === playerY)) {
-  const next = exits[0].tile.metadata!['nextLevel'] as number
-  console.log(`Loading level ${next}`)
-}
+Axis-aligned bounding box overlap tests and sprite-vs-tile-map wall resolution.
 
-// Count remaining gems
-const gemsLeft = map.findById('gem').length
-console.log(`${gemsLeft} gems remaining`)
-```
+### `Rect` interface
 
----
+```ts
+interface Rect { x: number; y: number; w: number; h: number }
+```
 
-### `sprite.ts` — Free-roaming entity system
+### `spriteRect(sprite): Rect`
 
-Sprites are entities that move freely in pixel space — not locked to the tile grid like `TileMap` cells. Use sprites for players, enemies, bullets, particles: anything that moves at sub-pixel precision or with physics.
+Returns the `CELL × CELL` bounding box of a sprite at its current position.
 
-Sprites use the same 8×8 bitmap format as `drawSprite` and the same `SpectrumColor` palette. They integrate directly with `resolveX` / `resolveY` from `collision.ts` and with `TileMap.isSolid` for platformer-style collision detection.
+### `rectsOverlap(a, b): boolean`
 
-#### `Sprite` interface
+Returns `true` when two rectangles share at least one pixel. Touching edges return `false`.
 
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `x` | `number` | `0` | Horizontal position in game pixels (float allowed — rounded on render) |
-| `y` | `number` | `0` | Vertical position in game pixels |
-| `vx` | `number` | `0` | Horizontal velocity in pixels per millisecond |
-| `vy` | `number` | `0` | Vertical velocity in pixels per millisecond |
-| `bitmap` | `Uint8Array` | — | 8-byte sprite — one byte per row, bit 7 = leftmost pixel |
-| `ink` | `SpectrumColor` | — | Foreground colour (`C.*` palette value) |
-| `paper` | `SpectrumColor \| null` | `null` | Background colour, or `null` for transparent background |
-| `flipX` | `boolean` | `false` | Render mirrored horizontally. Flipped bitmap is cached — no per-frame allocation |
-| `visible` | `boolean` | `true` | When `false`, `renderSprite` skips this entity entirely |
+```ts
+rectsOverlap(spriteRect(bullet), spriteRect(enemy))  // hit test
+```
 
-#### `createSprite(bitmap, ink, paper?): Sprite`
+### `spritesOverlap(a, b): boolean`
 
-Creates a `Sprite` at `(0, 0)` with zero velocity. `paper` defaults to `null` (transparent background).
+Shorthand: `rectsOverlap(spriteRect(a), spriteRect(b))`.
 
 ```ts
-import { createSprite, C } from 'zx-kit'
+if (spritesOverlap(player, coin)) collectCoin()
+if (enemies.some(e => spritesOverlap(player, e))) loseLife()
+```
+
+### `isSolidAt(map, px, py): boolean`
+
+Tests whether the game-pixel `(px, py)` falls inside a solid tile. Out-of-bounds pixels return `true` (implicit solid boundary).
+
+### `resolveX(sprite, map, newX): { x, hitLeft, hitRight }`
 
-const PLAYER_BM = new Uint8Array([0x18, 0x3C, 0x7E, 0xFF, 0xFF, 0x7E, 0x18, 0x3C])
-const BULLET_BM = new Uint8Array([0x00, 0x00, 0x18, 0x18, 0x18, 0x18, 0x00, 0x00])
+Resolves a proposed horizontal move against solid tiles. Returns the clamped position and directional hit flags. No collision → returns `newX` unchanged.
 
-const player = createSprite(PLAYER_BM, C.B_CYAN)          // transparent bg
-const bullet = createSprite(BULLET_BM, C.B_WHITE, C.BLACK) // opaque bg
-player.x = 16
-player.y = 80
+```ts
+const { x, hitLeft, hitRight } = resolveX(player, map, player.x)
+player.x = x
+if (hitLeft || hitRight) player.vx = 0
 ```
 
-#### `moveSprite(sprite, dt): void`
+### `resolveY(sprite, map, newY): { y, hitTop, hitBottom }`
+
+Resolves a proposed vertical move against solid tiles.
 
-Advances `sprite.x` by `vx * dt` and `sprite.y` by `vy * dt`. Call once per frame **before** collision resolution.
+- `hitBottom` — landed on a floor (use for jump ground detection)
+- `hitTop` — bumped a ceiling
 
 ```ts
-// Typical frame update order:
-applyGravity(player, 0.003, dt)
-moveSprite(player, dt)
-const rx = resolveX(player, map, player.x)
-const ry = resolveY(player, map, player.y)
-player.x = rx.x
-player.y = ry.y
-if (ry.hitBottom) player.vy = 0
+const { y, hitBottom, hitTop } = resolveY(player, map, player.y)
+player.y = y
+if (hitBottom) { player.vy = 0; onGround = true }
+if (hitTop)    { player.vy = 0 }
 ```
 
-#### `applyGravity(sprite, gravity, dt): void`
+---
+
+## `animation.ts` — Frame Timer & Tween
+
+Two small primitives for time-based animation:
 
-Adds `gravity * dt` to `sprite.vy`. Call once per frame **before** `moveSprite`.
+- **`Animation`** — counts time and reports the current frame index of an N-frame strip. Holds no bitmaps; index lookup into your sprite table is your job (so one timer can drive multi-direction sprites).
+- **`Tween`** — interpolates a 2D position from `(fromX, fromY)` to `(toX, toY)` over a duration with optional easing. Useful for sliding a sprite between cells, dropping a mine in an arc, etc.
 
-- `gravity` is in pixels per millisecond² — typical values: `0.002`–`0.005`
-- Accumulates naturally across frames so the sprite accelerates while airborne
+Both are stateful objects you mutate via tick functions — same shape as `Sprite` + `moveSprite`. Neither uses module-level state, so multiple instances coexist freely.
+
+### `Easing` type & `Easings`
 
 ```ts
-// Gentle gravity (platformer)
-applyGravity(player, 0.003, dt)
+type Easing = (t: number) => number     // 0..1 → eased value
 
-// Strong gravity (bullet hell with falling debris)
-applyGravity(debris, 0.008, dt)
+Easings.linear      // (t) => t                    — constant velocity
+Easings.easeIn      // (t) => t * t                — quadratic in (slow start)
+Easings.easeOut     // (t) => 1 - (1-t) * (1-t)    — quadratic out (slow end)
 ```
 
-#### `renderSprite(ctx, sprite): void`
-
-Draws the sprite at `(Math.round(sprite.x), Math.round(sprite.y))`.
-Skips if `sprite.visible === false`.
-Respects `flipX` (cached mirror) and `paper: null` (transparent — only ink pixels drawn).
+Pass any `(t: number) => number` to `createTween({ ease })` to roll your own.
 
-Call **after** all physics updates and collision resolution, as the last step before `drawScanlines`.
+### `Animation` interface
 
 ```ts
-// Transparent sprite over a scrolling background
-player.paper = null   // default — no background square
-renderSprite(ctx, player)
+interface Animation {
+  frameCount: number          // number of frames in cycle
+  frameMs: number             // duration of each frame
+  loop: boolean               // wrap, or stop on last frame
+  elapsed: number             // accumulated time (internal)
+  done: boolean               // true once non-looping anim reaches the end
+  onComplete?: () => void     // fired exactly once (non-looping only)
+}
+```
 
-// Opaque sprite (always paints its 8×8 cell background)
-bullet.paper = C.BLACK
-renderSprite(ctx, bullet)
+### `createAnimation(frameCount, frameMs, opts?): Animation`
 
-// Facing direction
-player.flipX = (player.vx < 0)
-renderSprite(ctx, player)
+```ts
+const walkAnim = createAnimation(2, 60)                                // 2-frame walk cycle
+const explosion = createAnimation(4, 50, {
+  loop: false,
+  onComplete: () => state.phase = 'gameover',
+})
 ```
 
-#### Full example — platformer player
+### `tickAnimation(anim, dt): number`
+
+Advances by `dt` ms, returns the current frame index (`0..frameCount-1`). For non-looping animations, fires `onComplete` exactly once when the last frame ends.
 
 ```ts
-import { createSprite, moveSprite, applyGravity, renderSprite, C, CELL } from 'zx-kit'
-import { resolveX, resolveY } from 'zx-kit'
-import { tickMovement, consumeFlag } from 'zx-kit'
+const idx = tickAnimation(walkAnim, dt)
+const sprite = PLAYER_FRAMES[playerDir][idx]   // your own lookup table
+drawSprite(ctx, sprite, x, y, C.B_WHITE, C.BLACK)
+```
 
-const PLAYER_BM = new Uint8Array([0x18, 0x3C, 0x7E, 0xFF, 0xFF, 0x7E, 0x24, 0x66])
+### `getAnimationFrame(anim): number`
 
-const player = createSprite(PLAYER_BM, C.B_CYAN)
-player.x = 2 * CELL
-player.y = 10 * CELL
+Reads the current frame index without advancing time — useful when reading inside a renderer that runs after the tick.
 
-let onGround = false
-const JUMP_VELOCITY = -0.25    // pixels/ms upward
-const WALK_VELOCITY =  0.08    // pixels/ms horizontal
-const GRAVITY       =  0.003   // pixels/ms²
+### `resetAnimation(anim): void`
 
-function updatePlayer(dt: number, map: TileMap) {
-  // Input
-  const dir = tickMovement(dt)
-  player.vx = dir === 'right' ?  WALK_VELOCITY
-            : dir === 'left'  ? -WALK_VELOCITY
-            : 0
-  if (dir === 'up' && onGround) player.vy = JUMP_VELOCITY
-
-  // Flip sprite to face movement direction
-  if (player.vx < 0) player.flipX = true
-  if (player.vx > 0) player.flipX = false
-
-  // Physics
-  applyGravity(player, GRAVITY, dt)
-  moveSprite(player, dt)
-
-  // Collision
-  const rx = resolveX(player, map, player.x)
-  player.x = rx.x
-  if (rx.hitLeft || rx.hitRight) player.vx = 0
-
-  const ry = resolveY(player, map, player.y)
-  player.y = ry.y
-  onGround = ry.hitBottom
-  if (ry.hitBottom || ry.hitTop) player.vy = 0
+Returns the animation to frame 0 and clears `done`. Use to restart a non-looping animation, or to begin a fresh loop from frame 0.
+
+### `Tween` interface
+
+```ts
+interface Tween {
+  fromX, fromY, toX, toY: number
+  durationMs: number
+  elapsed: number             // accumulated time (internal)
+  x, y: number                // current interpolated position (read after tickTween)
+  ease: Easing
+  done: boolean
+  onComplete?: () => void
 }
 ```
 
----
+### `createTween(fromX, fromY, toX, toY, durationMs, opts?): Tween`
 
-### `collision.ts` — AABB collision detection and resolution
+```ts
+// Slide player from one cell to the next over 120ms
+state.walkTween = createTween(
+  state.playerCol * 8, state.playerRow * 8,
+  newCol * 8, newRow * 8,
+  120,
+  { onComplete: () => commitMove(state) },
+)
+```
 
-Axis-aligned bounding box (AABB) helpers for sprite-vs-sprite overlap tests and sprite-vs-`TileMap` collision resolution. All coordinates are in game pixels.
+### `tickTween(tween, dt): boolean`
 
-#### `Rect` interface
+Advances by `dt` ms, updates `tween.x` / `tween.y`, returns `true` once the tween has reached its end. Fires `onComplete` exactly once. Subsequent calls after completion are no-ops.
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `x` | `number` | Left edge in game pixels |
-| `y` | `number` | Top edge in game pixels |
-| `w` | `number` | Width in game pixels |
-| `h` | `number` | Height in game pixels |
+```ts
+if (state.walkTween) {
+  tickTween(state.walkTween, dt)
+  // renderer reads state.walkTween.x / .y
+}
+```
 
-#### `spriteRect(sprite): Rect`
+### Combining Animation + Tween
 
-Returns the bounding `Rect` for a sprite — always `CELL × CELL` at the sprite's current position. Uses the raw float position (no rounding) for accurate same-frame overlap tests.
+Typical walk-between-cells pattern: a looping `Animation` cycles the foot frames while a non-looping `Tween` slides the position. They tick independently — the tween decides *where*, the animation decides *which sprite*.
 
 ```ts
-const rect = spriteRect(player)   // { x: 24.5, y: 80.0, w: 8, h: 8 }
+// On input:
+state.walkTween = createTween(/* from cell, to cell, 120ms */, {
+  onComplete: () => commitMove(state),
+})
+
+// In game loop:
+if (state.walkTween) {
+  tickAnimation(state.walkAnim, dt)
+  tickTween(state.walkTween, dt)
+}
+
+// In renderer:
+const px = state.walkTween ? state.walkTween.x : state.playerCol * CELL
+const py = state.walkTween ? state.walkTween.y : state.playerRow * CELL
+const f = getAnimationFrame(state.walkAnim)
+drawSprite(ctx, PLAYER_FRAMES[state.playerDir][f], Math.round(px), Math.round(py), ink, paper)
 ```
 
-#### `rectsOverlap(a, b): boolean`
+### `Blinker` — on/off toggle timer
 
-Returns `true` when rectangles share at least one pixel. Touching edges (zero-area overlap) returns `false`.
+A minimal boolean timer that flips its state every `intervalMs`. Use for blinking text ("PRESS ANY KEY"), flashing warnings, cursor visibility, aircraft alerts — any situation where a boolean needs to alternate on a fixed cadence.
+
+#### `Blinker` interface
 
 ```ts
-rectsOverlap(spriteRect(bullet), spriteRect(enemy))  // hit test
-rectsOverlap({ x: 0, y: 0, w: 32, h: 32 }, { x: 16, y: 16, w: 8, h: 8 })  // contained → true
+interface Blinker {
+  intervalMs: number   // toggle interval in ms
+  elapsed: number      // internal: accumulated time since last toggle
+  state: boolean       // current state — true = on, false = off
+}
 ```
 
-#### `spritesOverlap(a, b): boolean`
+#### `createBlinker(intervalMs, opts?): Blinker`
 
-Shorthand for `rectsOverlap(spriteRect(a), spriteRect(b))`.
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `opts.initialState` | `boolean` | `true` | Starting state — `true` = visible |
 
 ```ts
-if (spritesOverlap(player, coin)) collectCoin(coin)
-if (bullets.some(b => spritesOverlap(b, player))) loseLife()
+const blinker = createBlinker(500)                          // toggle every 500 ms
+const cursor  = createBlinker(400, { initialState: false }) // starts hidden
 ```
 
-#### `isSolidAt(map, px, py): boolean`
+#### `tickBlinker(blinker, dt): boolean`
 
-Tests whether the game pixel `(px, py)` falls inside a solid tile. Converts to tile coordinates via `Math.floor(px / CELL)`. Out-of-bounds pixels return `true` — the map boundary is an implicit solid wall.
+Advances the blinker by `dt` ms and returns the current state. Handles accumulated time correctly — if `dt` spans multiple intervals the state flips the appropriate number of times with the remainder carried over.
 
 ```ts
-// Is the pixel directly below the player's feet solid?
-if (isSolidAt(map, player.x, player.y + CELL)) onGround = true
+// Module-level setup (once):
+const blinker = createBlinker(BLINK_INTERVAL_MS)
 
-// Same check via resolveY — usually more convenient
+// In game loop (replaces manual timer + toggle):
+const blink = tickBlinker(blinker, dt)
+renderIntro(ctx, blink)
+state.blink = blink
 ```
 
-#### `resolveX(sprite, map, newX): { x, hitLeft, hitRight }`
+---
+
+## `tilemap.ts` — Tile Map Engine
 
-Resolves a proposed horizontal move against solid tiles. Tests the leading edge of the sprite's bounding box at `newX` and returns the clamped position plus hit flags.
+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.
 
-- `hitLeft` — the sprite hit a wall while moving left
-- `hitRight` — the sprite hit a wall while moving right
-- Always returns the original `newX` (unclamped) when no collision occurs
-- Out-of-bounds overshoot is clamped correctly — the map boundary acts as an implicit wall
+### Types
+
+#### `Tile`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `sprite` | `Uint8Array` | 8-byte bitmap |
+| `ink` | `SpectrumColor` | Foreground color |
+| `paper` | `SpectrumColor` | Background color |
+| `solid` | `boolean` | `true` = blocks movement |
+| `id` | `string \| number` | Stable identifier for logic and swap operations |
+| `metadata?` | `Record<string, unknown>` | Optional game payload (points, next level, …) |
+
+#### `Viewport`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `x` | `number` | First visible column (tile units) |
+| `y` | `number` | First visible row (tile units) |
+| `cols` | `number` | Number of columns to render |
+| `rows` | `number` | Number of rows to render |
+
+### `createTileMap(cols, rows): TileMap`
+
+Creates an empty `cols × rows` map — all cells start `null`.
+
+### Method reference
+
+| Method | Description |
+|--------|-------------|
+| `setTile(x, y, tile)` | Store a shallow copy. Out-of-bounds = silent no-op. |
+| `getTile(x, y)` | Return tile or `null`. Never throws. |
+| `clearTile(x, y)` | Remove tile (collect gem, break wall). |
+| `fill(tile)` | Fill every cell with independent shallow copies. |
+| `fillRect(x, y, w, h, tile)` | Fill rectangle; clips to map bounds. |
+| `setBackground(tile)` | Register or swap the background (see below). |
+| `render(ctx, viewport?)` | Render map or viewport via `drawSprite`. Empty cells skipped. |
+| `isSolid(x, y)` | `true` if tile is solid or position is out-of-bounds. |
+| `findById(id)` | `{ x, y, tile }[]` for all tiles with given `id` — O(1). |
+
+### Smart background swapping (`setBackground`)
+
+- **First call** — registers the tile as the current background. Map is not modified; call `fill` first to place tiles.
+- **Subsequent calls** — replaces every cell whose `id` still matches the previous background with the new tile. Cells with any other `id` (player, gems, modified terrain) are untouched.
 
 ```ts
-moveSprite(player, dt)
-const { x, hitLeft, hitRight } = resolveX(player, map, player.x)
-player.x = x
-if (hitLeft || hitRight) player.vx = 0
+map.fill(TILE_GRASS)
+map.setBackground(TILE_GRASS)   // register
+
+map.setTile(5, 3, TILE_PLAYER)  // player placed on grass
+
+map.setBackground(TILE_SNOW)    // grass → snow; player tile untouched
+map.setBackground(TILE_NIGHT)   // snow → night; player still safe
 ```
 
-#### `resolveY(sprite, map, newY): { y, hitTop, hitBottom }`
+---
+
+## `palette.ts` — Color Constants
+
+### `SCALE`
+
+Default CSS-pixel scale factor: `4`. One game pixel = 4×4 CSS pixels at standard Spectrum resolution.
 
-Resolves a proposed vertical move against solid tiles. Same contract as `resolveX`.
+### `CELL`
 
-- `hitBottom` — the sprite landed on a floor tile (use to detect "on ground" for jump logic)
-- `hitTop` — the sprite bumped its head on a ceiling tile
+Tile and character grid size: `8` game pixels. Matches the ZX Spectrum's 8×8 character cell.
+
+### `C` — Color object
+
+| Key | Hex | Key | Hex |
+|-----|-----|-----|-----|
+| `C.BLACK` | `#000000` | `C.B_BLACK` | `#000000` |
+| `C.BLUE` | `#0000CD` | `C.B_BLUE` | `#0000FF` |
+| `C.RED` | `#CD0000` | `C.B_RED` | `#FF0000` |
+| `C.MAGENTA` | `#CD00CD` | `C.B_MAGENTA` | `#FF00FF` |
+| `C.GREEN` | `#00CD00` | `C.B_GREEN` | `#00FF00` |
+| `C.CYAN` | `#00CDCD` | `C.B_CYAN` | `#00FFFF` |
+| `C.YELLOW` | `#CDCD00` | `C.B_YELLOW` | `#FFFF00` |
+| `C.WHITE` | `#CDCDCD` | `C.B_WHITE` | `#FFFFFF` |
+
+### `SpectrumColor` type
 
 ```ts
-applyGravity(player, 0.003, dt)
-moveSprite(player, dt)
-const { y, hitBottom, hitTop } = resolveY(player, map, player.y)
-player.y = y
-if (hitBottom) { player.vy = 0; onGround = true }
-if (hitTop)    { player.vy = 0 }
+type SpectrumColor = typeof C[keyof typeof C]
 ```
 
-#### Full example — bullet hell enemy swarm
+A union of all hex string values in `C`. Enforces palette compliance at compile time — any function that accepts `SpectrumColor` will reject an arbitrary `string` at the type level.
 
-```ts
-import { createSprite, moveSprite, renderSprite, spritesOverlap, C, CELL } from 'zx-kit'
-import type { Sprite } from 'zx-kit'
+---
 
-const BULLET_BM = new Uint8Array([0x00, 0x18, 0x3C, 0x3C, 0x3C, 0x3C, 0x18, 0x00])
-const ENEMY_BM  = new Uint8Array([0x3C, 0x7E, 0xFF, 0xDB, 0xFF, 0x66, 0x42, 0x81])
+## `font.ts` — ROM Bitmap Font
 
-const bullets: Sprite[] = []
-const enemies: Sprite[] = []
+96 printable ASCII characters (codes 32–127), each 8×8 pixels, byte-for-byte faithful to the original ZX Spectrum ROM. Character 127 is a solid block `█`.
 
-// Spawn a bullet traveling upward
-function fireBullet(x: number, y: number) {
-  const b = createSprite(BULLET_BM, C.B_YELLOW)
-  b.x = x; b.y = y; b.vy = -0.3  // pixels/ms upward
-  bullets.push(b)
-}
+### `FONT`
 
-// Spawn enemies in a row
-for (let i = 0; i < 8; i++) {
-  const e = createSprite(ENEMY_BM, C.B_RED, C.BLACK)
-  e.x = i * 2 * CELL + 8
-  e.y = 2 * CELL
-  e.vx = 0.03 * (i % 2 === 0 ? 1 : -1)  // alternate directions
-  enemies.push(e)
-}
+```ts
+const FONT: Uint8Array  // 768 bytes: 96 chars × 8 rows
+// Row bitmap: FONT[(charCode - 32) * 8 + row]
+// Bit layout: bit 7 = leftmost pixel
+```
 
-// Per-frame update
-function updateBulletHell(dt: number) {
-  // Move all bullets
-  for (const b of bullets) moveSprite(b, dt)
-
-  // Move all enemies
-  for (const e of enemies) moveSprite(e, dt)
-
-  // Hit tests — O(bullets × enemies), fine for dozens of sprites
-  for (const b of bullets) {
-    for (const e of enemies) {
-      if (e.visible && b.visible && spritesOverlap(b, e)) {
-        b.visible = false   // bullet disappears
-        e.visible = false   // enemy explodes
-      }
-    }
-  }
+### `getCharRow(charCode, row): number`
 
-  // Remove off-screen bullets
-  bullets.splice(0, bullets.length, ...bullets.filter(b => b.visible && b.y > -CELL))
+Returns the bitmap byte for one row of a character. `charCode` outside 32–127 returns `0`. `row` outside 0–7 returns `0`. In practice, use `drawChar`/`drawText` from `renderer.ts` — you only need `getCharRow` for custom pixel-level font rendering.
 
-  // Render
-  for (const e of enemies) if (e.visible) renderSprite(ctx, e)
-  for (const b of bullets) if (b.visible) renderSprite(ctx, b)
+```ts
+// Draw a character manually
+for (let row = 0; row < 8; row++) {
+  const byte = getCharRow('A'.charCodeAt(0), row)
+  for (let bit = 0; bit < 8; bit++) {
+    if (byte & (0x80 >> bit)) ctx.fillRect(x + bit, y + row, 1, 1)
+  }
 }
 ```
 
 ---
 
-## File structure
+## Architecture
+
+### Module structure
 
 ```
 zx-kit/
-├── package.json           # exports: { ".": "./dist/index.js" }
+├── package.json           # exports: { ".": "./dist/index.js" }, sideEffects: false
 ├── tsconfig.json          # strict, emits to dist/
 ├── README.md
-├── src/                   # TypeScript source
+├── src/
 │   ├── index.ts           # barrel — re-exports everything
 │   ├── palette.ts         # SCALE, CELL, C, SpectrumColor
 │   ├── font.ts            # FONT, getCharRow
-│   ├── renderer.ts        # setupCanvas, mirrorSprite, drawSprite, drawChar, drawText,
-│   │                      # drawTextCentered, flashBorder, drawScanlines
-│   ├── audio.ts           # initAudio, resumeAudio, beep, playPattern, Note,
+│   ├── renderer.ts        # setupCanvas, mirrorSprite, drawSprite, drawChar,
+│   │                      # drawText, drawTextCentered, flashBorder,
+│   │                      # drawScanlines, curveDisplay
+│   ├── audio.ts           # initAudio, resumeAudio, beep, playPattern,
 │   │                      # getAudioContext, getMasterGain,
 │   │                      # getMasterVolume, setMasterVolume,
-│   │                      # increaseVolume, decreaseVolume
-│   ├── input.ts           # initInput, tickMovement, consumeFlag/Debug/Pause/AnyKey,
+│   │                      # increaseVolume, decreaseVolume, Note
+│   ├── ay.ts              # createAY, playAY, AYChannel, AYNote, AYChip,
+│   │                      # AY_VOL, AY_CLOCK, AY_ENVELOPE_SHAPES
+│   ├── input.ts           # initInput, tickMovement, consumeFlag,
+│   │                      # consumePause, consumeDebug, consumeAnyKey,
 │   │                      # isHeld, resetInput, Direction
 │   ├── ui.ts              # drawBox, drawFrame, drawPanelTitle,
 │   │                      # drawProgressBar, tickUI, renderUI, resetUI,
 │   │                      # BorderOptions, DrawProgressBarOptions
 │   ├── tilemap.ts         # createTileMap, Tile, Viewport, TileMap
-│   ├── sprite.ts          # Sprite, createSprite, moveSprite, applyGravity, renderSprite
-│   └── collision.ts       # Rect, spriteRect, rectsOverlap, spritesOverlap,
-│                          # isSolidAt, resolveX, resolveY
-└── dist/                  # compiled output (generated by npm run build)
-    ├── index.js / .d.ts
+│   ├── sprite.ts          # createSprite, moveSprite, applyGravity,
+│   │                      # renderSprite, Sprite
+│   └── collision.ts       # spriteRect, rectsOverlap, spritesOverlap,
+│                          # isSolidAt, resolveX, resolveY, Rect
+└── dist/                  # compiled output (npm run build)
+    ├── index.js
+    ├── index.d.ts
     └── ...
 ```
 
----
+### Design decisions
 
-## Design principles
+**No runtime dependencies.** Every module uses only Web platform APIs — `CanvasRenderingContext2D`, `AudioContext`, `KeyboardEvent`. There is nothing to install, no transitive vulnerabilities, no version drift from third-party packages.
 
-- **Compiled distribution** — ships compiled JS + `.d.ts` in `dist/`. No bundler configuration needed in the consuming project.
-- **No runtime dependencies** — only Web platform APIs (`CanvasRenderingContext2D`, `AudioContext`, `KeyboardEvent`).
-- **Strict TypeScript** — `strict: true`, `noUnusedLocals`, `noUnusedParameters`. No `any`.
-- **Palette-typed game data** — UI colours and tile `ink` / `paper` use `SpectrumColor`, so consumers stay inside the Spectrum palette at compile time.
-- **Singleton state** — `audio.ts` and `input.ts` hold module-level state. Suitable for single-game use; not suitable for multiple independent game instances on the same page.
-- **ZX Spectrum authenticity** — palette values, cell size, and font bytes are constants, not configuration. The library is deliberately opinionated.
+**Singleton state.** `audio.ts`, `ay.ts`, and `input.ts` hold module-level state. This is intentional: a game has one audio context, one input handler. It is not suitable for multiple independent game instances on the same page.
 
----
+**Compiled distribution.** The package ships compiled JS + `.d.ts` to `dist/`. Any bundler (Vite, webpack, esbuild, Rollup) consumes it without aliases or configuration.
 
-## Local development
+**`sideEffects: false`.** All module-level initialisation is lazy — no DOM access, no event listeners, no network calls at import time. Bundlers can tree-shake any module whose exports are not used. Import only `playAY` and `createAY` and the beeper, input, and UI modules are completely excluded from your production bundle.
 
-To work against a local checkout instead of the npm version:
+**ZX Spectrum authenticity.** The palette values, cell size (`CELL = 8`), and font bytes are constants, not configuration. The `SpectrumColor` type enforces the palette at the TypeScript level — you cannot accidentally pass an arbitrary hex string where a palette color is expected.
 
-```bash
-# In your game project
-npm install ../zx-kit --prefer-online
-```
-
-> The `--prefer-online` flag ensures npm resolves from the local path without caching issues.
-> After publishing a new version to npm, switch back with `npm install zx-kit@latest`.
+**AY clock accuracy.** `AY_CLOCK = 1_773_400 Hz` and `AY_VOL[]` are measured values from the real AY-3-8912 chip. The LFSR noise buffer uses the correct 17-bit polynomial (`bit = (lfsr ^ (lfsr >> 2)) & 1`). The logarithmic amplitude table uses the real chip's ≈ √2 step factor (3 dB per level).
 
 ---
 
 ## License
 
-MIT
+MIT — see [LICENSE](LICENSE).
+
+---
+
+*zx-kit is extracted from [Minefield](https://github.com/zrebec/minefield), a ZX Spectrum-style minesweeper game.*