zx-kit 0.1.0

package/README.md

@@ -0,0 +1,414 @@
+# zx-kit
+
+Reusable ZX Spectrum primitives for browser games built with Vite + TypeScript + Canvas + Web Audio API.
+
+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.
+
+---
+
+## 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') },
+  },
+})
+```
+
+Import from the barrel:
+
+```ts
+import { C, CELL, initAudio, beep, drawSprite, initInput, tickMovement } from 'zx-kit'
+```
+
+---
+
+## Modules
+
+### `palette.ts` — ZX Spectrum color constants
+
+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.
+
+#### Exports
+
+| 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 |
+
+#### Color table (`C` object)
+
+Normal brightness colors (prefix-less):
+
+| 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):
+
+| 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 |
+
+#### Usage example
+
+```ts
+import { C, CELL } from 'zx-kit'
+
+ctx.fillStyle = C.B_CYAN    // bright cyan
+ctx.fillRect(x, y, CELL, CELL)
+```
+
+---
+
+### `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.
+
+#### 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. |
+
+#### 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.
+
+---
+
+### `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.
+
+Every function follows the ZX Spectrum **ink / paper** model: each 8×8 cell has exactly one foreground color (ink) and one background color (paper).
+
+#### Exports
+
+##### `mirrorSprite(src: Uint8Array): Uint8Array`
+
+Flips an 8×8 sprite horizontally. Returns a new `Uint8Array`. Used to derive left-facing sprites from right-facing ones at module load time.
+
+```ts
+import { mirrorSprite } from 'zx-kit'
+
+export const PLAYER_RIGHT = new Uint8Array([0x18, 0x3C, ...])
+export const PLAYER_LEFT  = mirrorSprite(PLAYER_RIGHT)
+```
+
+##### `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) |
+
+```ts
+import { drawSprite, C } from 'zx-kit'
+
+drawSprite(ctx, MINE_SPRITE, col * 8, row * 8, 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).
+
+| 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 |
+
+```ts
+import { drawChar, C } from 'zx-kit'
+
+drawChar(ctx, 127, x, y, C.B_GREEN, C.BLACK)  // solid block █
+```
+
+##### `drawText(ctx, text, x, y, ink, paper?): void`
+
+Draws a string left-to-right starting at `(x, y)`, one character per `CELL`-wide slot.
+
+| 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 |
+
+```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).
+
+| 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 |
+
+```ts
+import { drawTextCentered, C } from 'zx-kit'
+
+drawTextCentered(ctx, 'GAME  OVER', cy * 8, 32, C.B_RED, C.BLACK)
+```
+
+**Tip for game code:** Bind `cols` once to avoid passing it everywhere:
+
+```ts
+function drawCentered(ctx: CanvasRenderingContext2D, text: string, y: number, ink: string, paper?: string) {
+  drawTextCentered(ctx, text, y, COLS, ink, paper)
+}
+```
+
+---
+
+### `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.
+
+**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.
+
+#### Exports
+
+##### `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`.
+
+```ts
+import { initAudio } from 'zx-kit'
+
+document.addEventListener('keydown', () => initAudio(), { once: true })
+```
+
+##### `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.
+
+```ts
+import { resumeAudio, beep, getAudioContext } from 'zx-kit'
+
+const ctx = getAudioContext()
+if (ctx) {
+  resumeAudio()
+  beep(440, 80, ctx.currentTime)
+}
+```
+
+##### `getAudioContext(): AudioContext | null`
+
+Returns the current `AudioContext`, or `null` if `initAudio()` has not been called yet. Use this to get `currentTime` for scheduling beeps.
+
+##### `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()`.
+
+```ts
+const osc = ctx.createOscillator()
+const gain = ctx.createGain()
+osc.connect(gain)
+gain.connect(getMasterGain()!)
+```
+
+##### `beep(freq: number, durationMs: number, startTime: number): void`
+
+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.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `freq` | `number` | Frequency in Hz |
+| `durationMs` | `number` | Duration in milliseconds |
+| `startTime` | `number` | `AudioContext.currentTime` offset to start at |
+
+```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)
+}
+```
+
+---
+
+### `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
+
+##### `initInput(repeatDelay?: number, repeatInterval?: number): void`
+
+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
+
+```ts
+import { initInput } from 'zx-kit'
+
+initInput(150, 80)
+```
+
+##### `tickMovement(dtMs: number): Direction | null`
+
+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`).
+
+```ts
+import { tickMovement } from 'zx-kit'
+
+function gameLoop(dtMs: number) {
+  const dir = tickMovement(dtMs)
+  if (dir) movePlayer(dir)
+}
+```
+
+##### `consumeFlag(): boolean`
+
+Returns `true` once if `F` key was pressed since the last call, then resets. Designed for the flag-placement action (mark suspected mine cell).
+
+##### `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.
+
+##### `consumeAnyKey(): boolean`
+
+Returns `true` once if any key was pressed. Used to dismiss intro screens or game-over overlays.
+
+##### `isHeld(key: string): boolean`
+
+Returns whether a key is currently held. Argument is the `KeyboardEvent.key` string (e.g. `'ArrowUp'`, `' '`).
+
+##### `Direction` type
+
+```ts
+export type Direction = 'up' | 'down' | 'left' | 'right'
+```
+
+---
+
+## File structure
+
+```
+zx-kit/
+├── package.json         # { "exports": { ".": "./src/index.ts" } }
+├── tsconfig.json        # strict, bundler moduleResolution, noEmit
+├── 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
+```
+
+---
+
+## Design principles
+
+- **No build step in the library** — exports raw TypeScript source. Consuming project's bundler (Vite, esbuild) handles transpilation.
+- **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.
+
+---
+
+## 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()` |
+
+---
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "zx-kit",
+  "version": "0.1.0",
+  "description": "Reusable ZX Spectrum primitives: font, palette, renderer, audio, input",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "keywords": ["zx-spectrum", "retro", "game", "canvas"],
+  "license": "MIT"
+}

package/src/audio.ts

@@ -0,0 +1,39 @@
+let ctx: AudioContext | null = null
+let masterGain: GainNode | null = null
+
+export function initAudio(volume = 0.3): void {
+  if (ctx) return
+  ctx = new AudioContext()
+  masterGain = ctx.createGain()
+  masterGain.gain.value = volume
+  masterGain.connect(ctx.destination)
+}
+
+export function resumeAudio(): void {
+  if (ctx && ctx.state === 'suspended') void ctx.resume()
+}
+
+export function getAudioContext(): AudioContext | null {
+  return ctx
+}
+
+export function getMasterGain(): GainNode | null {
+  return masterGain
+}
+
+// Core primitive — schedule a square-wave beep on the shared AudioContext
+export function beep(freq: number, durationMs: number, startTime: number): void {
+  if (!ctx || !masterGain) return
+  const osc = ctx.createOscillator()
+  const gain = ctx.createGain()
+  osc.type = 'square'
+  osc.frequency.value = freq
+  gain.gain.setValueAtTime(0, startTime)
+  gain.gain.linearRampToValueAtTime(0.8, startTime + 0.005)
+  gain.gain.setValueAtTime(0.8, startTime + durationMs / 1000 - 0.005)
+  gain.gain.linearRampToValueAtTime(0, startTime + durationMs / 1000)
+  osc.connect(gain)
+  gain.connect(masterGain)
+  osc.start(startTime)
+  osc.stop(startTime + durationMs / 1000 + 0.01)
+}

package/src/font.ts

@@ -0,0 +1,203 @@
+// ZX Spectrum ROM font — characters 32–127, 8 bytes per char (row-major, bit7=leftmost pixel)
+const RAW: readonly number[] = [
+  // 32 space
+  0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,
+  // 33 !
+  0x00,0x10,0x10,0x10,0x10,0x00,0x10,0x00,
+  // 34 "
+  0x00,0x28,0x28,0x00,0x00,0x00,0x00,0x00,
+  // 35 #
+  0x00,0x28,0x7C,0x28,0x28,0x7C,0x28,0x00,
+  // 36 $
+  0x00,0x10,0x3C,0x50,0x3C,0x14,0x7C,0x10,
+  // 37 %
+  0x00,0x62,0x64,0x08,0x10,0x26,0x46,0x00,
+  // 38 &
+  0x00,0x10,0x28,0x10,0x2A,0x44,0x3A,0x00,
+  // 39 '
+  0x00,0x08,0x08,0x00,0x00,0x00,0x00,0x00,
+  // 40 (
+  0x00,0x04,0x08,0x08,0x08,0x08,0x04,0x00,
+  // 41 )
+  0x00,0x20,0x10,0x10,0x10,0x10,0x20,0x00,
+  // 42 *
+  0x00,0x00,0x14,0x08,0x3E,0x08,0x14,0x00,
+  // 43 +
+  0x00,0x00,0x08,0x08,0x3E,0x08,0x08,0x00,
+  // 44 ,
+  0x00,0x00,0x00,0x00,0x00,0x08,0x08,0x10,
+  // 45 -
+  0x00,0x00,0x00,0x00,0x3E,0x00,0x00,0x00,
+  // 46 .
+  0x00,0x00,0x00,0x00,0x00,0x00,0x10,0x00,
+  // 47 /
+  0x00,0x02,0x04,0x08,0x10,0x20,0x40,0x00,
+  // 48 0
+  0x00,0x3C,0x46,0x4A,0x52,0x62,0x3C,0x00,
+  // 49 1
+  0x00,0x08,0x18,0x08,0x08,0x08,0x1C,0x00,
+  // 50 2
+  0x00,0x3C,0x42,0x04,0x18,0x20,0x7E,0x00,
+  // 51 3
+  0x00,0x3C,0x42,0x0C,0x02,0x42,0x3C,0x00,
+  // 52 4
+  0x00,0x08,0x18,0x28,0x48,0x7E,0x08,0x00,
+  // 53 5
+  0x00,0x7E,0x40,0x7C,0x02,0x42,0x3C,0x00,
+  // 54 6
+  0x00,0x3C,0x40,0x7C,0x42,0x42,0x3C,0x00,
+  // 55 7
+  0x00,0x7E,0x02,0x04,0x08,0x10,0x10,0x00,
+  // 56 8
+  0x00,0x3C,0x42,0x3C,0x42,0x42,0x3C,0x00,
+  // 57 9
+  0x00,0x3C,0x42,0x42,0x3E,0x02,0x3C,0x00,
+  // 58 :
+  0x00,0x00,0x10,0x00,0x00,0x10,0x00,0x00,
+  // 59 ;
+  0x00,0x00,0x10,0x00,0x00,0x10,0x10,0x20,
+  // 60 <
+  0x00,0x04,0x08,0x10,0x08,0x04,0x00,0x00,
+  // 61 =
+  0x00,0x00,0x00,0x7C,0x00,0x7C,0x00,0x00,
+  // 62 >
+  0x00,0x20,0x10,0x08,0x10,0x20,0x00,0x00,
+  // 63 ?
+  0x00,0x3C,0x42,0x04,0x08,0x00,0x08,0x00,
+  // 64 @
+  0x00,0x3C,0x4A,0x56,0x5C,0x40,0x3C,0x00,
+  // 65 A
+  0x00,0x18,0x24,0x42,0x7E,0x42,0x42,0x00,
+  // 66 B
+  0x00,0x7C,0x42,0x7C,0x42,0x42,0x7C,0x00,
+  // 67 C
+  0x00,0x3C,0x42,0x40,0x40,0x42,0x3C,0x00,
+  // 68 D
+  0x00,0x78,0x44,0x42,0x42,0x44,0x78,0x00,
+  // 69 E
+  0x00,0x7E,0x40,0x7C,0x40,0x40,0x7E,0x00,
+  // 70 F
+  0x00,0x7E,0x40,0x7C,0x40,0x40,0x40,0x00,
+  // 71 G
+  0x00,0x3C,0x42,0x40,0x4E,0x42,0x3C,0x00,
+  // 72 H
+  0x00,0x42,0x42,0x7E,0x42,0x42,0x42,0x00,
+  // 73 I
+  0x00,0x3E,0x08,0x08,0x08,0x08,0x3E,0x00,
+  // 74 J
+  0x00,0x02,0x02,0x02,0x02,0x42,0x3C,0x00,
+  // 75 K
+  0x00,0x44,0x48,0x70,0x48,0x44,0x42,0x00,
+  // 76 L
+  0x00,0x40,0x40,0x40,0x40,0x40,0x7E,0x00,
+  // 77 M
+  0x00,0x42,0x66,0x5A,0x42,0x42,0x42,0x00,
+  // 78 N
+  0x00,0x42,0x62,0x52,0x4A,0x46,0x42,0x00,
+  // 79 O
+  0x00,0x3C,0x42,0x42,0x42,0x42,0x3C,0x00,
+  // 80 P
+  0x00,0x7C,0x42,0x42,0x7C,0x40,0x40,0x00,
+  // 81 Q
+  0x00,0x3C,0x42,0x42,0x4A,0x44,0x3A,0x00,
+  // 82 R
+  0x00,0x7C,0x42,0x42,0x7C,0x48,0x44,0x00,
+  // 83 S
+  0x00,0x3C,0x40,0x3C,0x02,0x42,0x3C,0x00,
+  // 84 T
+  0x00,0x7E,0x08,0x08,0x08,0x08,0x08,0x00,
+  // 85 U
+  0x00,0x42,0x42,0x42,0x42,0x42,0x3C,0x00,
+  // 86 V
+  0x00,0x42,0x42,0x42,0x42,0x24,0x18,0x00,
+  // 87 W
+  0x00,0x42,0x42,0x42,0x5A,0x66,0x42,0x00,
+  // 88 X
+  0x00,0x42,0x24,0x18,0x18,0x24,0x42,0x00,
+  // 89 Y
+  0x00,0x42,0x42,0x24,0x18,0x08,0x08,0x00,
+  // 90 Z
+  0x00,0x7E,0x04,0x08,0x10,0x20,0x7E,0x00,
+  // 91 [
+  0x00,0x1C,0x10,0x10,0x10,0x10,0x1C,0x00,
+  // 92 backslash
+  0x00,0x40,0x20,0x10,0x08,0x04,0x02,0x00,
+  // 93 ]
+  0x00,0x38,0x08,0x08,0x08,0x08,0x38,0x00,
+  // 94 ^
+  0x00,0x08,0x14,0x22,0x00,0x00,0x00,0x00,
+  // 95 _
+  0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x7E,
+  // 96 `
+  0x00,0x10,0x08,0x00,0x00,0x00,0x00,0x00,
+  // 97 a
+  0x00,0x00,0x3C,0x02,0x3E,0x42,0x3E,0x00,
+  // 98 b
+  0x00,0x20,0x20,0x3E,0x22,0x22,0x3E,0x00,
+  // 99 c
+  0x00,0x00,0x1E,0x20,0x20,0x20,0x1E,0x00,
+  // 100 d
+  0x00,0x02,0x02,0x3E,0x42,0x42,0x3E,0x00,
+  // 101 e
+  0x00,0x00,0x3C,0x42,0x7E,0x40,0x3C,0x00,
+  // 102 f
+  0x00,0x0C,0x10,0x3C,0x10,0x10,0x10,0x00,
+  // 103 g
+  0x00,0x00,0x3E,0x42,0x42,0x3E,0x02,0x3C,
+  // 104 h
+  0x00,0x20,0x20,0x2C,0x32,0x22,0x22,0x00,
+  // 105 i
+  0x00,0x08,0x00,0x18,0x08,0x08,0x1C,0x00,
+  // 106 j
+  0x00,0x04,0x00,0x0C,0x04,0x04,0x44,0x38,
+  // 107 k
+  0x00,0x20,0x28,0x30,0x28,0x24,0x22,0x00,
+  // 108 l
+  0x00,0x18,0x08,0x08,0x08,0x08,0x1C,0x00,
+  // 109 m
+  0x00,0x00,0x76,0x49,0x49,0x49,0x49,0x00,
+  // 110 n
+  0x00,0x00,0x2C,0x32,0x22,0x22,0x22,0x00,
+  // 111 o
+  0x00,0x00,0x3C,0x42,0x42,0x42,0x3C,0x00,
+  // 112 p
+  0x00,0x00,0x3C,0x22,0x22,0x3C,0x20,0x20,
+  // 113 q
+  0x00,0x00,0x1E,0x22,0x22,0x1E,0x02,0x02,
+  // 114 r
+  0x00,0x00,0x2C,0x30,0x20,0x20,0x20,0x00,
+  // 115 s
+  0x00,0x00,0x1E,0x20,0x1C,0x02,0x3C,0x00,
+  // 116 t
+  0x00,0x10,0x7C,0x10,0x10,0x12,0x0C,0x00,
+  // 117 u
+  0x00,0x00,0x22,0x22,0x22,0x26,0x1A,0x00,
+  // 118 v
+  0x00,0x00,0x42,0x42,0x42,0x24,0x18,0x00,
+  // 119 w
+  0x00,0x00,0x42,0x42,0x49,0x55,0x22,0x00,
+  // 120 x
+  0x00,0x00,0x42,0x24,0x18,0x24,0x42,0x00,
+  // 121 y
+  0x00,0x00,0x44,0x44,0x44,0x3C,0x04,0x38,
+  // 122 z
+  0x00,0x00,0x7E,0x04,0x18,0x20,0x7E,0x00,
+  // 123 {
+  0x00,0x0C,0x10,0x60,0x10,0x10,0x0C,0x00,
+  // 124 |
+  0x00,0x08,0x08,0x08,0x08,0x08,0x08,0x00,
+  // 125 }
+  0x00,0x30,0x08,0x06,0x08,0x08,0x30,0x00,
+  // 126 ~
+  0x00,0x00,0x32,0x4C,0x00,0x00,0x00,0x00,
+  // 127 solid block (used for lives / filled blocks)
+  0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,
+]
+
+export const FONT = new Uint8Array(RAW)
+
+export function getCharRow(charCode: number, row: number): number {
+  const idx = charCode - 32
+  if (idx < 0 || idx >= 96) return 0
+  return FONT[idx * 8 + row]
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './palette.ts'
+export * from './font.ts'
+export * from './renderer.ts'
+export * from './audio.ts'
+export * from './input.ts'

package/src/input.ts

@@ -0,0 +1,77 @@
+export type Direction = 'up' | 'down' | 'left' | 'right'
+
+const DIR_KEYS: Record<string, Direction> = {
+  ArrowUp: 'up', ArrowDown: 'down', ArrowLeft: 'left', ArrowRight: 'right',
+}
+
+const held = new Set<string>()
+let pendingFlag = false
+let pendingDebug = false
+let pendingPause = false
+let pendingAnyKey = false
+
+let repeatDir: Direction | null = null
+let repeatTimer = 0
+let repeatPhase: 'delay' | 'repeat' | 'idle' = 'idle'
+let pendingImmediate: Direction | null = null
+let _repeatDelay = 150
+let _repeatInterval = 80
+
+export function initInput(repeatDelay = 150, repeatInterval = 80): void {
+  _repeatDelay = repeatDelay
+  _repeatInterval = repeatInterval
+
+  window.addEventListener('keydown', (e: KeyboardEvent) => {
+    if (e.repeat) return
+    pendingAnyKey = true
+    held.add(e.key)
+
+    const dir = DIR_KEYS[e.key]
+    if (dir) {
+      repeatDir = dir
+      repeatPhase = 'delay'
+      repeatTimer = _repeatDelay
+      pendingImmediate = dir
+    }
+
+    if (e.key === 'f' || e.key === 'F') pendingFlag = true
+    if (e.key === 'p' || e.key === 'P') pendingPause = true
+
+    if (e.ctrlKey && e.shiftKey && (e.key === 'b' || e.key === 'B')) {
+      pendingDebug = true
+      e.preventDefault()
+    }
+  })
+
+  window.addEventListener('keyup', (e: KeyboardEvent) => {
+    held.delete(e.key)
+    const dir = DIR_KEYS[e.key]
+    if (dir && repeatDir === dir) {
+      repeatDir = null
+      repeatPhase = 'idle'
+    }
+  })
+}
+
+export function tickMovement(dtMs: number): Direction | null {
+  if (pendingImmediate !== null) {
+    const d = pendingImmediate
+    pendingImmediate = null
+    return d
+  }
+  if (repeatDir !== null && repeatPhase !== 'idle') {
+    repeatTimer -= dtMs
+    if (repeatTimer <= 0) {
+      repeatTimer += _repeatInterval
+      if (repeatPhase === 'delay') repeatPhase = 'repeat'
+      return repeatDir
+    }
+  }
+  return null
+}
+
+export function consumeFlag(): boolean   { const v = pendingFlag;   pendingFlag   = false; return v }
+export function consumeDebug(): boolean  { const v = pendingDebug;  pendingDebug  = false; return v }
+export function consumePause(): boolean  { const v = pendingPause;  pendingPause  = false; return v }
+export function consumeAnyKey(): boolean { const v = pendingAnyKey; pendingAnyKey = false; return v }
+export function isHeld(key: string): boolean { return held.has(key) }

package/src/palette.ts

@@ -0,0 +1,24 @@
+export const SCALE = 4
+export const CELL = 8
+
+// ZX Spectrum palette — exactly 15 colours, EXCLUSIVELY these hex values
+export const C = {
+  BLACK:     '#000000',
+  BLUE:      '#0000CD',
+  RED:       '#CD0000',
+  MAGENTA:   '#CD00CD',
+  GREEN:     '#00CD00',
+  CYAN:      '#00CDCD',
+  YELLOW:    '#CDCD00',
+  WHITE:     '#CDCDCD',
+  B_BLACK:   '#000000',
+  B_BLUE:    '#0000FF',
+  B_RED:     '#FF0000',
+  B_MAGENTA: '#FF00FF',
+  B_GREEN:   '#00FF00',
+  B_CYAN:    '#00FFFF',
+  B_YELLOW:  '#FFFF00',
+  B_WHITE:   '#FFFFFF',
+} as const
+
+export type SpectrumColor = typeof C[keyof typeof C]

package/src/renderer.ts

@@ -0,0 +1,74 @@
+import { CELL } from './palette.ts'
+import { getCharRow } from './font.ts'
+
+// Flip an 8×8 sprite horizontally
+export function mirrorSprite(src: Uint8Array): Uint8Array {
+  const out = new Uint8Array(8)
+  for (let r = 0; r < 8; r++) {
+    let b = src[r], m = 0
+    for (let i = 0; i < 8; i++) {
+      if (b & (1 << i)) m |= (1 << (7 - i))
+    }
+    out[r] = m
+  }
+  return out
+}
+
+export function drawSprite(
+  ctx: CanvasRenderingContext2D,
+  sprite: Uint8Array,
+  x: number, y: number,
+  ink: string, paper: string,
+): void {
+  ctx.fillStyle = paper
+  ctx.fillRect(x, y, CELL, CELL)
+  ctx.fillStyle = ink
+  for (let row = 0; row < 8; row++) {
+    const byte = sprite[row]
+    for (let bit = 0; bit < 8; bit++) {
+      if (byte & (0x80 >> bit)) ctx.fillRect(x + bit, y + row, 1, 1)
+    }
+  }
+}
+
+export function drawChar(
+  ctx: CanvasRenderingContext2D,
+  code: number,
+  x: number, y: number,
+  ink: string, paper?: string,
+): void {
+  if (paper !== undefined) {
+    ctx.fillStyle = paper
+    ctx.fillRect(x, y, CELL, CELL)
+  }
+  ctx.fillStyle = ink
+  for (let row = 0; row < 8; row++) {
+    const byte = getCharRow(code, row)
+    for (let bit = 0; bit < 8; bit++) {
+      if (byte & (0x80 >> bit)) ctx.fillRect(x + bit, y + row, 1, 1)
+    }
+  }
+}
+
+export function drawText(
+  ctx: CanvasRenderingContext2D,
+  text: string,
+  x: number, y: number,
+  ink: string, paper?: string,
+): void {
+  for (let i = 0; i < text.length; i++) {
+    drawChar(ctx, text.charCodeAt(i), x + i * CELL, y, ink, paper)
+  }
+}
+
+// cols = total character columns of the canvas (e.g. 32 for standard Spectrum)
+export function drawTextCentered(
+  ctx: CanvasRenderingContext2D,
+  text: string,
+  y: number,
+  cols: number,
+  ink: string, paper?: string,
+): void {
+  const x = Math.floor((cols - text.length) / 2) * CELL
+  drawText(ctx, text, x, y, ink, paper)
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "es2023",
+    "module": "esnext",
+    "lib": ["ES2023", "DOM"],
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true
+  },
+  "include": ["src"]
+}