zx-kit 0.2.0 → 0.2.2

package/README.md

@@ -8,356 +8,302 @@ Extracted from [Minefield](https://github.com/zrebec/minefield) — a ZX Spectru
 
 ## Installation
 
-The package ships TypeScript source directly (no build step). Consume it via a local path in `package.json`:
-
-```json
-"dependencies": {
-  "zx-kit": "file:../zx-kit"
-}
-```
-
-Then add a Vite alias so bundler resolution works (Vite doesn't transform `node_modules` by default):
-
-```ts
-// vite.config.ts
-import { resolve } from 'path'
-
-export default defineConfig({
-  resolve: {
-    alias: { 'zx-kit': resolve(__dirname, '../zx-kit/src/index.ts') },
-  },
-})
+```bash
+npm install zx-kit
 ```
 
 Import from the barrel:
 
 ```ts
-import { C, CELL, initAudio, beep, drawSprite, initInput, tickMovement } from 'zx-kit'
+import { C, CELL, setupCanvas, initAudio, playPattern, initInput, tickMovement } from 'zx-kit'
 ```
 
+No Vite alias or path mapping required — the package ships compiled JavaScript (`dist/`).
+
 ---
 
-## Modules
+## Quick start
 
-### `palette.ts` — ZX Spectrum color constants
+```ts
+import { setupCanvas, C, CELL, drawText, initAudio, playPattern, initInput, tickMovement } from 'zx-kit'
 
-Defines the exact 15 colors of the ZX Spectrum and the 8-pixel cell size. **Never use any other hex values** — all game graphics must stay within this palette.
+// 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
 
-#### Exports
+// Input
+initInput()
 
-| Export | Type | Value | Description |
-|--------|------|-------|-------------|
-| `SCALE` | `number` | `4` | CSS pixel scale factor (1 game pixel = 4 CSS pixels) |
-| `CELL` | `number` | `8` | Sprite / character grid size in game pixels |
-| `C` | `object` | see below | All 15 Spectrum colors as `#RRGGBB` hex strings |
-| `SpectrumColor` | `type` | union of all `C` values | TypeScript type for palette-safe color values |
+// Audio (must be inside a user gesture)
+window.addEventListener('keydown', () => initAudio(), { once: true })
 
-#### Color table (`C` object)
+// Game loop
+function loop(dt: number) {
+  const dir = tickMovement(dt)
+  if (dir) movePlayer(dir)
 
-Normal brightness colors (prefix-less):
+  drawText(ctx, 'SCORE:00000', 0, 0, C.B_WHITE, C.BLACK)
+  requestAnimationFrame(t => loop(t - lastT))
+}
+```
 
-| Key | Hex | Appearance |
-|-----|-----|-----------|
-| `C.BLACK` | `#000000` | Black |
-| `C.BLUE` | `#0000CD` | Dark blue |
-| `C.RED` | `#CD0000` | Dark red |
-| `C.MAGENTA` | `#CD00CD` | Dark magenta |
-| `C.GREEN` | `#00CD00` | Dark green |
-| `C.CYAN` | `#00CDCD` | Dark cyan |
-| `C.YELLOW` | `#CDCD00` | Dark yellow |
-| `C.WHITE` | `#CDCDCD` | Light grey |
+---
 
-Bright variants (`B_` prefix):
+## Modules
+
+### `palette.ts` — ZX Spectrum color constants
 
-| Key | Hex | Appearance |
-|-----|-----|-----------|
-| `C.B_BLACK` | `#000000` | Same as `BLACK` |
-| `C.B_BLUE` | `#0000FF` | Bright blue |
-| `C.B_RED` | `#FF0000` | Bright red |
-| `C.B_MAGENTA` | `#FF00FF` | Bright magenta |
-| `C.B_GREEN` | `#00FF00` | Bright green |
-| `C.B_CYAN` | `#00FFFF` | Bright cyan |
-| `C.B_YELLOW` | `#FFFF00` | Bright yellow |
-| `C.B_WHITE` | `#FFFFFF` | Pure white |
+#### Exports
 
-#### Usage example
+| 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` |
 
-```ts
-import { C, CELL } from 'zx-kit'
+Bright variants (`B_` prefix):
 
-ctx.fillStyle = C.B_CYAN    // bright cyan
-ctx.fillRect(x, y, CELL, CELL)
-```
+| 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` |
 
 ---
 
 ### `font.ts` — ZX Spectrum ROM bitmap font
 
-Contains the exact ZX Spectrum ROM character set — 96 printable characters (ASCII 32–127), each stored as 8 bytes (one byte per row, bit 7 = leftmost pixel). Character 127 is a solid block `█`, used for things like life counters.
-
-The font data is sourced from the original Spectrum ROM and must not be altered — any change breaks Spectrum authenticity.
+96 printable characters (ASCII 32–127), each 8×8 pixels. Character 127 is a solid block █.
 
 #### Exports
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `FONT` | `Uint8Array` | Flat array: 96 chars × 8 bytes = 768 bytes total. `FONT[(charCode-32)*8 + row]` = one row bitmap. |
-| `getCharRow(charCode, row)` | `(number, number) => number` | Returns the bitmap byte for the given ASCII code and row (0–7). Returns `0` for out-of-range codes. |
+| 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). |
 
-#### Usage example
-
-```ts
-import { getCharRow } from 'zx-kit'
-
-// Draw character 'A' (65) row by row
-for (let row = 0; row < 8; row++) {
-  const byte = getCharRow(65, row)
-  for (let bit = 0; bit < 8; bit++) {
-    if (byte & (0x80 >> bit)) {
-      ctx.fillRect(x + bit, y + row, 1, 1)
-    }
-  }
-}
-```
-
-In practice you won't need this directly — use `drawChar` / `drawText` from `renderer.ts` instead.
+In practice use `drawChar` / `drawText` from `renderer.ts` — you rarely need `getCharRow` directly.
 
 ---
 
 ### `renderer.ts` — Canvas drawing primitives
 
-All drawing functions work in **game pixels** (not CSS pixels). At `SCALE=4` each game pixel maps to a 4×4 CSS pixel block. Canvas must have `imageSmoothingEnabled = false` set once at init.
+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.
 
-Every function follows the ZX Spectrum **ink / paper** model: each 8×8 cell has exactly one foreground color (ink) and one background color (paper).
+Every draw function follows the ZX Spectrum **ink / paper** model: each 8×8 cell has one foreground (ink) and one background (paper) color.
 
-#### Exports
+#### `setupCanvas(canvas, scale, width?, height?): CanvasRenderingContext2D`
 
-##### `mirrorSprite(src: Uint8Array): Uint8Array`
+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.**
 
-Flips an 8×8 sprite horizontally. Returns a new `Uint8Array`. Used to derive left-facing sprites from right-facing ones at module load time.
+- `scale` — CSS pixels per game pixel (`4` = standard ZX Spectrum display)
+- `width` — game pixels wide (default `256`)
+- `height` — game pixels tall (default `192`)
 
 ```ts
-import { mirrorSprite } from 'zx-kit'
+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
+```
+
+#### `mirrorSprite(src): Uint8Array`
 
-export const PLAYER_RIGHT = new Uint8Array([0x18, 0x3C, ...])
+Flips an 8×8 sprite horizontally. Returns a new `Uint8Array`.
+
+```ts
+export const PLAYER_RIGHT = new Uint8Array([...])
 export const PLAYER_LEFT  = mirrorSprite(PLAYER_RIGHT)
 ```
 
-##### `drawSprite(ctx, sprite, x, y, ink, paper): void`
+#### `drawSprite(ctx, sprite, x, y, ink, paper): void`
 
-Draws an 8×8 sprite at game coordinates `(x, y)`. Always fills the full 8×8 cell with `paper` first, then renders `ink` pixels from the sprite bitmap.
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `ctx` | `CanvasRenderingContext2D` | Target canvas context |
-| `sprite` | `Uint8Array` | 8-byte sprite (one byte per row) |
-| `x` | `number` | Left edge in game pixels |
-| `y` | `number` | Top edge in game pixels |
-| `ink` | `string` | Foreground color (Spectrum palette hex) |
-| `paper` | `string` | Background color (Spectrum palette hex) |
+Draws an 8×8 sprite at game coordinates. Always fills the background first.
 
 ```ts
-import { drawSprite, C } from 'zx-kit'
-
-drawSprite(ctx, MINE_SPRITE, col * 8, row * 8, C.B_RED, C.BLACK)
+drawSprite(ctx, MINE_SPRITE, col * CELL, row * CELL, C.B_RED, C.BLACK)
 ```
 
-##### `drawChar(ctx, code, x, y, ink, paper?): void`
-
-Draws a single ASCII character at game coordinates using the ROM font. If `paper` is omitted, the background is not cleared (transparent background).
+#### `drawChar(ctx, code, x, y, ink, paper?): void`
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `ctx` | `CanvasRenderingContext2D` | Target canvas context |
-| `code` | `number` | ASCII character code (32–127) |
-| `x` | `number` | Left edge in game pixels |
-| `y` | `number` | Top edge in game pixels |
-| `ink` | `string` | Foreground color |
-| `paper?` | `string` | Optional background color |
+Draws one ASCII character using the ROM font. Omit `paper` for transparent background.
 
 ```ts
-import { drawChar, C } from 'zx-kit'
-
 drawChar(ctx, 127, x, y, C.B_GREEN, C.BLACK)  // solid block █
+drawChar(ctx, 'A'.charCodeAt(0), x, y, C.B_WHITE)
 ```
 
-##### `drawText(ctx, text, x, y, ink, paper?): void`
-
-Draws a string left-to-right starting at `(x, y)`, one character per `CELL`-wide slot.
+#### `drawText(ctx, text, x, y, ink, paper?): void`
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `ctx` | `CanvasRenderingContext2D` | Target canvas context |
-| `text` | `string` | ASCII string to render |
-| `x` | `number` | Left edge in game pixels |
-| `y` | `number` | Top edge in game pixels |
-| `ink` | `string` | Foreground color |
-| `paper?` | `string` | Optional background color |
+Draws a string left-to-right, one character per `CELL`-wide slot.
 
 ```ts
-import { drawText, C } from 'zx-kit'
-
 drawText(ctx, 'SCORE:00000', 0, statusY, C.B_WHITE, C.BLACK)
 ```
 
-##### `drawTextCentered(ctx, text, y, cols, ink, paper?): void`
-
-Draws a string horizontally centered within a canvas of `cols` character columns. The `cols` parameter must match your game's grid width (e.g. 32 for a standard Spectrum layout).
+#### `drawTextCentered(ctx, text, y, cols, ink, paper?): void`
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `ctx` | `CanvasRenderingContext2D` | Target canvas context |
-| `text` | `string` | ASCII string to render |
-| `y` | `number` | Top edge in game pixels |
-| `cols` | `number` | Total character columns (canvas width ÷ CELL) |
-| `ink` | `string` | Foreground color |
-| `paper?` | `string` | Optional background color |
+Centers a string within `cols` character columns. Bind `cols` once in a helper to avoid repetition.
 
 ```ts
-import { drawTextCentered, C } from 'zx-kit'
+// Bind once:
+const centered = (ctx: CanvasRenderingContext2D, text: string, y: number, ink: string) =>
+  drawTextCentered(ctx, text, y, 32, ink)
 
-drawTextCentered(ctx, 'GAME  OVER', cy * 8, 32, C.B_RED, C.BLACK)
+centered(ctx, 'GAME  OVER', y, C.B_RED)
 ```
 
-**Tip for game code:** Bind `cols` once to avoid passing it everywhere:
+#### `flashBorder(color, times, intervalMs, resetColor?): void`
+
+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`).
 
 ```ts
-function drawCentered(ctx: CanvasRenderingContext2D, text: string, y: number, ink: string, paper?: string) {
-  drawTextCentered(ctx, text, y, COLS, ink, paper)
-}
+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
 ```
 
 ---
 
 ### `audio.ts` — Web Audio engine (ZX Spectrum style)
 
-Wraps the Web Audio API to produce authentic 1-bit square-wave sound, exactly like the ZX Spectrum's single-channel beeper. All audio goes through a shared `AudioContext` and a single `GainNode` master bus.
+Wraps the Web Audio API for authentic 1-bit square-wave sound. All audio goes through a shared `AudioContext` and a single master `GainNode`.
 
-**Important:** `AudioContext` must be created in response to a user gesture (click or keypress) due to browser autoplay policy. Call `initAudio()` from a key/click handler, then call `resumeAudio()` before playing sound in the game loop.
+**Browser autoplay policy:** `AudioContext` must be created inside a user gesture (click or keydown). Call `initAudio()` from an event handler.
 
-#### Exports
+#### `initAudio(volume?): void`
 
-##### `initAudio(volume?: number): void`
-
-Creates the `AudioContext` and master `GainNode`. Idempotent — safe to call multiple times (subsequent calls are no-ops). Default volume: `0.3`.
+Creates the `AudioContext` and master gain. Idempotent — safe to call multiple times.
 
 ```ts
-import { initAudio } from 'zx-kit'
-
-document.addEventListener('keydown', () => initAudio(), { once: true })
+window.addEventListener('keydown', () => initAudio(), { once: true })
+window.addEventListener('click',   () => initAudio(), { once: true })
 ```
 
-##### `resumeAudio(): void`
+#### `resumeAudio(): void`
 
-Resumes a suspended `AudioContext`. Browsers suspend the context when the tab is hidden or on first load. Call this before scheduling any beep in the game loop.
+Resumes a suspended `AudioContext`. Call before scheduling audio in the game loop.
 
-```ts
-import { resumeAudio, beep, getAudioContext } from 'zx-kit'
+#### `getAudioContext(): AudioContext | null`
 
-const ctx = getAudioContext()
-if (ctx) {
-  resumeAudio()
-  beep(440, 80, ctx.currentTime)
-}
-```
+Returns the current context, or `null` before `initAudio()`.
 
-##### `getAudioContext(): AudioContext | null`
+#### `getMasterGain(): GainNode | null`
 
-Returns the current `AudioContext`, or `null` if `initAudio()` has not been called yet. Use this to get `currentTime` for scheduling beeps.
+Returns the master gain node. Connect custom oscillators here to respect global volume.
 
-##### `getMasterGain(): GainNode | null`
-
-Returns the master `GainNode`. Connect your own oscillators/gains to this node to respect the global volume level. Returns `null` before `initAudio()`.
+#### `Note` interface
 
 ```ts
-const osc = ctx.createOscillator()
-const gain = ctx.createGain()
-osc.connect(gain)
-gain.connect(getMasterGain()!)
+interface Note {
+  freq: number  // Hz — use 0 for a rest (silence)
+  dur: number   // ms — duration of note or rest
+}
 ```
 
-##### `beep(freq: number, durationMs: number, startTime: number): void`
+#### `playPattern(notes, startDelay?): void`
+
+Schedules a sequence of notes. `freq: 0` = rest (advances time, no sound). `startDelay` delays the whole pattern in milliseconds.
+
+```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)
+```
 
-Schedules a single square-wave beep. Uses a 5ms linear ramp attack and release to avoid click artifacts. The beep is routed through the master gain.
+#### `beep(freq, durationMs, startTime): void`
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `freq` | `number` | Frequency in Hz |
-| `durationMs` | `number` | Duration in milliseconds |
-| `startTime` | `number` | `AudioContext.currentTime` offset to start at |
+Schedules a single square-wave beep at an absolute `AudioContext.currentTime`. Use `playPattern` for sequences; use `beep` directly when you need algorithmic timing control.
 
 ```ts
-import { beep, resumeAudio, getAudioContext } from 'zx-kit'
-
-const ctx = getAudioContext()
-if (ctx) {
-  resumeAudio()
-  const now = ctx.currentTime
-  // Two-pip warning: 880Hz beep twice with 60ms gap
-  beep(880, 80, now)
-  beep(880, 80, now + 0.14)
-}
+const audio = getAudioContext()!
+resumeAudio()
+beep(880, 80, audio.currentTime)
+beep(880, 80, audio.currentTime + 0.14)  // 140ms later
 ```
 
 ---
 
 ### `input.ts` — Keyboard input with key-repeat
 
-Handles arrow key movement with configurable key-repeat (first-press immediate, hold for auto-repeat), plus single-consume flags for action keys. Designed for grid-based games where one key press = one step.
-
-**Important:** Call `initInput()` once at startup (after DOM is ready) to attach `keydown`/`keyup` listeners. Then call `tickMovement(dt)` every frame.
-
-#### Exports
+Handles arrow-key movement with configurable key-repeat (immediate on first press, auto-repeat on hold) plus single-consume flags for action keys.
 
-##### `initInput(repeatDelay?: number, repeatInterval?: number): void`
+**Call `initInput()` once at startup.** Then call `tickMovement(dt)` every frame.
 
-Attaches global `keydown`/`keyup` event listeners. Default values:
-- `repeatDelay`: `150` ms — time before auto-repeat kicks in after initial press
-- `repeatInterval`: `80` ms — time between repeats while key is held
+#### `Direction` type
 
 ```ts
-import { initInput } from 'zx-kit'
-
-initInput(150, 80)
+type Direction = 'up' | 'down' | 'left' | 'right'
 ```
 
-##### `tickMovement(dtMs: number): Direction | null`
+#### `initInput(repeatDelay?, repeatInterval?): void`
 
-Call once per frame with the frame delta in milliseconds. Returns the direction to move this frame, or `null` if no movement. On the first frame a key is pressed, returns immediately. While held, returns a direction every `repeatInterval` ms (after initial `repeatDelay`).
+Attaches `keydown`/`keyup` listeners. Keys: arrows = movement, `F` = flag, `P` = pause, `Ctrl+Shift+B` = debug.
 
 ```ts
-import { tickMovement } from 'zx-kit'
-
-function gameLoop(dtMs: number) {
-  const dir = tickMovement(dtMs)
-  if (dir) movePlayer(dir)
-}
+initInput()         // 150ms delay, 80ms repeat
+initInput(200, 60)  // custom timing
 ```
 
-##### `consumeFlag(): boolean`
+#### `tickMovement(dtMs): Direction | null`
 
-Returns `true` once if `F` key was pressed since the last call, then resets. Designed for the flag-placement action (mark suspected mine cell).
+Returns the movement direction for this frame, or `null`. Call once per frame.
 
-##### `consumeDebug(): boolean`
-
-Returns `true` once if `Ctrl+Shift+B` was pressed. Used to toggle debug mode (reveal all mines). Calls `e.preventDefault()` to suppress browser shortcuts.
-
-##### `consumePause(): boolean`
-
-Returns `true` once if `P` key was pressed.
+```ts
+const dir = tickMovement(dt)
+if (dir) movePlayer(dir)
+```
 
-##### `consumeAnyKey(): boolean`
+#### Consume flags
 
-Returns `true` once if any key was pressed. Used to dismiss intro screens or game-over overlays.
+| 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 |
 
-##### `isHeld(key: string): boolean`
+Each returns `true` once per press, then resets.
 
-Returns whether a key is currently held. Argument is the `KeyboardEvent.key` string (e.g. `'ArrowUp'`, `' '`).
+#### `isHeld(key): boolean`
 
-##### `Direction` type
+Returns whether a key is currently held. Argument is `KeyboardEvent.key`.
 
 ```ts
-export type Direction = 'up' | 'down' | 'left' | 'right'
+if (isHeld('ArrowUp')) { ... }
 ```
 
 ---
@@ -366,46 +312,47 @@ export type Direction = 'up' | 'down' | 'left' | 'right'
 
 ```
 zx-kit/
-├── package.json         # { "exports": { ".": "./src/index.ts" } }
-├── tsconfig.json        # strict, bundler moduleResolution, noEmit
+├── package.json         # exports: { ".": "./dist/index.js" }
+├── tsconfig.json        # strict, emits to dist/
 ├── README.md
-└── src/
-    ├── index.ts         # barrel — re-exports everything
-    ├── palette.ts       # SCALE, CELL, C color constants, SpectrumColor type
-    ├── font.ts          # ROM font Uint8Array + getCharRow()
-    ├── renderer.ts      # mirrorSprite, drawSprite, drawChar, drawText, drawTextCentered
-    ├── audio.ts         # initAudio, resumeAudio, beep, getAudioContext, getMasterGain
-    └── input.ts         # initInput, tickMovement, consumeFlag/Debug/Pause/AnyKey, isHeld
+├── src/                 # TypeScript source
+│   ├── 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
+│   ├── audio.ts         # initAudio, resumeAudio, beep, playPattern, Note,
+│   │                    # getAudioContext, getMasterGain
+│   └── input.ts         # initInput, tickMovement, consumeFlag/Debug/Pause/AnyKey,
+│                        # isHeld, Direction
+└── dist/                # compiled output (generated by npm run build)
+    ├── index.js / .d.ts
+    └── ...
 ```
 
 ---
 
 ## Design principles
 
-- **No build step in the library** — exports raw TypeScript source. Consuming project's bundler (Vite, esbuild) handles transpilation.
+- **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`.
-- **Singleton state** — `audio.ts` and `input.ts` hold module-level state. Suitable for single-game use; not suitable for running multiple independent game instances in the same page.
-- **ZX Spectrum constraint enforcement** — palette, cell size, and font data are constants, not configuration. The library is deliberately opinionated.
+- **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.
 
 ---
 
-## Migrating from inline code
-
-When extracting from a game that previously had these utilities inline:
-
-| What was inline | Now in zx-kit | Change required in game |
-|-----------------|---------------|------------------------|
-| `drawSprite`, `drawChar`, `drawText` | `renderer.ts` | Import from `'zx-kit'`; remove duplicate bodies |
-| `drawTextCentered` | `renderer.ts` (takes `cols` param) | Wrap with a local helper that binds your game's `COLS` |
-| `mirrorSprite` | `renderer.ts` | Import from `'zx-kit'`; keep sprite data in game's `sprites.ts` |
-| `C` color object | `palette.ts` | Re-export from game's `constants.ts` via `export { C } from 'zx-kit'` |
-| `SCALE`, `CELL` | `palette.ts` | Same as above |
-| `FONT`, `getCharRow` | `font.ts` | Re-export from game's `font.ts` |
-| `AudioContext` + `GainNode` init | `audio.ts` | Replace with `initAudio()` / `getAudioContext()` / `getMasterGain()` |
-| `beep()` helper | `audio.ts` | Import directly; remove inline version |
-| Arrow-key repeat logic | `input.ts` | Replace with `initInput()` + `tickMovement(dt)` |
-| Flag / debug / pause key flags | `input.ts` | Use `consumeFlag()`, `consumeDebug()`, `consumePause()` |
+## Local development
+
+To work against a local checkout instead of the npm version:
+
+```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`.
 
 ---