zx-kit 0.25.0 → 0.26.0

package/README.md

@@ -2,7 +2,7 @@
 
 > **Build browser games that look and sound like a ZX Spectrum — without any of its limitations.**
 
-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.
+Three-channel chiptune audio. Pixel-perfect canvas rendering. Authentic 15-color palette. ROM bitmap font. Tile maps with seasonal swapping. Free-roaming sprites with velocity and gravity helpers. Collision detection. A complete retro game toolkit 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)
@@ -13,7 +13,7 @@ Three-channel chiptune audio. Pixel-perfect canvas rendering. Authentic 15-color
 
 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.
+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, free-roaming sprites with velocity and gravity helpers, 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.**
 
@@ -28,11 +28,11 @@ The goal is simple: **it should look and sound like a Spectrum, but run like a m
 - **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
 - **Three-tier collision** — AABB overlap tests, generic rect-vs-tile wall resolution (any sprite size), and pixel-precise mask overlap with O(pixels) sorted-merge intersection — no allocations per frame
-- **Keyboard input** — configurable key-repeat, single-consume action flags, instant state reset on phase transitions
+- **Keyboard and gamepad input** — configurable key-repeat, transparent gamepad polling, single-consume action flags, instant state reset on phase transitions
 - **ZX-style UI widgets** — progress bars with managed lifetime, boxes, frames, panel titles
 - **Typed save / load** — persistent saves via `localStorage` with schema versioning, migrations, slot enumeration, in-memory throttling, and discriminated Result types for every failure mode
 - **Runtime locale switching** — type-safe string-pack selection via `pickLocale()`, so a game can switch language while running — unimaginable on the original Spectrum, natural in the browser
-- **Zero dependencies** — only Web platform APIs: `Canvas`, `Web Audio`, `KeyboardEvent`
+- **Zero dependencies** — only Web platform APIs: `Canvas`, `Web Audio`, `KeyboardEvent`, `Gamepad`
 - **Tree-shakeable** — `sideEffects: false`, so unused modules are dropped from your production bundle
 - **TypeScript-first** — strict mode, full `.d.ts` declarations, no `any`
 
@@ -44,6 +44,25 @@ The goal is simple: **it should look and sound like a Spectrum, but run like a m
 
 ---
 
+## Examples
+
+The repository includes small static examples that import `../../dist/index.js`
+directly, so each one doubles as a browser-checkable API recipe:
+
+| Example | Shows |
+|---------|-------|
+| `examples/ay-music/` | AY channels A/B/C plus beeper SFX as a four-voice Spectrum-style setup |
+| `examples/pixel-collision/` | AABB false positives vs `bitmapPixelMask()` / `masksOverlap()` |
+| `examples/particles/` | Allocation-free particle pools for sparks, smoke, and explosions |
+| `examples/i18n-runtime/` | Runtime language switching with `pickLocale()` and persisted preference |
+| `examples/bitmap-attrs/` | `Bitmap`, `AttrMap`, mirroring, colour clash, and `inkOnly` rendering |
+| `examples/save-slots/` | Save profiles, auto/manual slots, latest-slot restore, throttling, and delete |
+
+Build first with `npm run build`, then serve the repository root and open any
+example path in the browser.
+
+---
+
 ## Installation
 
 ### From npm (recommended)
@@ -142,7 +161,7 @@ No prior game development experience needed. You need basic JavaScript/TypeScrip
 
 | Tool | Where to get it | Why |
 |------|----------------|-----|
-| **Node.js 18+** | [nodejs.org](https://nodejs.org) | Runs npm — the package manager we use to install zx-kit |
+| **Node.js 22+** | [nodejs.org](https://nodejs.org) | Runs npm — the package manager we use to install zx-kit |
 | **A code editor** | [code.visualstudio.com](https://code.visualstudio.com) (free) | Edits your source files |
 | **A terminal** | Built into macOS/Linux; use PowerShell on Windows | Runs commands |
 
@@ -188,7 +207,7 @@ Open `package.json` and replace it with the following. The two key additions are
     "build": "vite build"
   },
   "dependencies": {
-    "zx-kit": "^0.15.0"
+    "zx-kit": "^0.25.0"
   },
   "devDependencies": {
     "vite": "^6.0.0"
@@ -535,10 +554,10 @@ requestAnimationFrame(loop)
 | 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 |
+| [`renderer.ts`](#rendererts--canvas-renderer) | Canvas setup, 8x8 sprites, arbitrary-size bitmaps, attribute maps, text, scanlines, border flash |
 | [`audio.ts`](#audiots--beeper-audio) | 1-bit beeper: square-wave notes, patterns, volume control |
 | [`ui.ts`](#uits--ui-widgets) | Boxes, frames, panel titles, progress bars + instrumentation widgets (dotted grids, segmented bars, fluid tanks, dials, text compass) |
-| [`input.ts`](#inputts--keyboard-input) | Movement with key-repeat, action flags, state reset |
+| [`input.ts`](#inputts--keyboard--gamepad-input) | Keyboard/gamepad movement, key-repeat, action flags, state reset |
 | [`sprite.ts`](#spritets--free-roaming-sprites) | Sprites: position, velocity, gravity, flip, render |
 | [`collision.ts`](#collisionts--collision-detection) | AABB overlap + rect-based tile resolution, pixel-precise mask overlap and tile checks |
 | [`animation.ts`](#animationts--frame-timer--tween) | Frame-timer for sprite strips, position tween between two points |
@@ -552,6 +571,7 @@ requestAnimationFrame(loop)
 | [`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 |
 | [`i18n.ts`](#i18nts--runtime-locale-selection) | Type-safe runtime locale selection for translated string packs |
+| [`lighting.ts`](#lightingts--dithered-cave-darkness) | Dithered cave darkness: pre-baked level tiles + dirty-cell buffer, one blit/frame (no per-frame putImageData) |
 
 ---
 
@@ -907,6 +927,37 @@ curveDisplay(ctx)               // default strength
 curveDisplay(ctx, 256, 208, 6)  // stronger warp
 ```
 
+### `Bitmap` interface
+
+An arbitrary-size monochrome bitmap. Width must be a positive multiple of 8 so
+each row is byte-aligned. `data` is row-major; bit 7 is the leftmost pixel in
+each byte.
+
+```ts
+interface Bitmap {
+  data: Uint8Array
+  width: number
+  height: number
+}
+```
+
+Use `Bitmap` for 16x16 enemies, 16x24 heroes, 32x32 bosses, tall objects, and
+anything that outgrows the classic 8x8 `drawSprite()` format.
+
+### `createBitmap(data, width, height): Bitmap`
+
+Builds a `Bitmap` from packed bytes and validates the dimensions and byte
+count immediately. Throws if width is not byte-aligned, height is invalid, or
+the data length does not match `(width / 8) * height`.
+
+```ts
+const HERO = createBitmap(new Uint8Array([
+  0x03, 0xC0,
+  0x07, 0xE0,
+  // ...22 more 16px-wide rows
+]), 16, 24)
+```
+
 ### `createBitmapFromRows(rows): Bitmap`
 
 Builds an arbitrary-size `Bitmap` from readable pixel-art rows instead of
@@ -949,6 +1000,49 @@ Draws an arbitrary-size `Bitmap`. The colour model has three modes, ordered by h
 
 `inkOnly` (last parameter, default `false`) **suppresses the paper rectangle even when a `paper` colour is supplied.** For `drawBitmap` this is functionally identical to omitting `paper` — its value is ergonomic: keep a sprite's configured `paper` and toggle the opaque box on or off with a boolean, instead of conditionally choosing whether to pass the argument at the call site.
 
+### `mirrorBitmap(src): Bitmap`
+
+Returns a horizontally flipped copy of a `Bitmap`. The original is not
+modified. Use it at module load time to derive left-facing sprites from one
+right-facing definition.
+
+```ts
+const HERO_RIGHT = createBitmapFromRows([...])
+const HERO_LEFT = mirrorBitmap(HERO_RIGHT)
+```
+
+### `AttrMap` interface
+
+Per-8x8-cell ink and paper colours for a `Bitmap`, mirroring the ZX Spectrum
+attribute buffer. `cols` must match `bitmap.width / 8`; `rows` must match
+`bitmap.height / 8`.
+
+```ts
+interface AttrMap {
+  readonly cols: number
+  readonly rows: number
+  readonly inks: readonly SpectrumColor[]
+  readonly papers?: readonly SpectrumColor[]
+}
+```
+
+Omit `papers` for transparent per-cell ink rendering, or provide papers for
+the authentic colour-clash look.
+
+### `createAttrMap(cols, rows, inks, papers?): AttrMap`
+
+Builds an `AttrMap` with validation. `inks` must contain `cols * rows` colours.
+`papers` can be omitted, supplied as a matching per-cell array, or supplied as
+one colour to fill every cell.
+
+```ts
+const HERO_ATTRS = createAttrMap(2, 3, [
+  C.B_YELLOW, C.B_YELLOW,
+  C.B_RED,    C.B_MAGENTA,
+  C.B_CYAN,   C.B_GREEN,
+], C.BLACK)
+```
+
 ### `drawBitmapAttrs(ctx, bitmap, attrs, x, y, inkOnly?): void`
 
 Renders a `Bitmap` with a per-cell `AttrMap` — each 8×8 cell carries its own `(ink, paper)`, the authentic Spectrum attribute model. Here `inkOnly` is **not** redundant: it keeps every per-cell *ink* colour but skips all per-cell *paper* fills. One fully-coloured `AttrMap` (with `papers` for the boxed look on a plain background) then renders two ways — flip `inkOnly` per frame, with no second paper-less map to build and keep in sync. Dimension validation still throws under `inkOnly`: the flag changes what is painted, never the contract.
@@ -960,6 +1054,17 @@ drawBitmapAttrs(ctx, BUNNY, BUNNY_ATTRS, x, y, true)
 //    the cave behind it. The rabbit reads by its own silhouette.
 ```
 
+### `mirrorAttrMap(attrs): AttrMap`
+
+Returns a horizontally flipped copy of an `AttrMap`, reversing each attribute
+row. Pair it with `mirrorBitmap()` so a mirrored sprite keeps its colours on
+the matching 8x8 cells.
+
+```ts
+const HERO_LEFT = mirrorBitmap(HERO_RIGHT)
+const HERO_LEFT_ATTRS = mirrorAttrMap(HERO_RIGHT_ATTRS)
+```
+
 ### Why does `inkOnly` exist? (and why is it, honestly, a little bit of debt?)
 
 This is the kind of decision worth writing down, because the "obvious" answer is the wrong one.
@@ -1148,6 +1253,8 @@ Five stateless primitives for HUDs, dashboards and tactical displays — gauges,
 
 #### `drawDottedGrid(ctx, options): void`
 
+Options type: `DrawDottedGridOptions`.
+
 Regularly-spaced dot pattern. Useful for radar / sonar screens, tactical scanner overlays, debug grids, stippled backgrounds, alien-invasion detection grids.
 
 ```ts
@@ -1174,6 +1281,8 @@ drawDottedGrid(ctx, {
 
 #### `drawSegmentedBar(ctx, options): void`
 
+Options type: `DrawSegmentedBarOptions`.
+
 Discrete segmented bar — health, ammo, shield, fuel, stamina, mana, battery, damage. Computes `round(value/max * segments)` filled segments.
 
 Two colouring strategies, mutually exclusive:
@@ -1217,6 +1326,8 @@ drawSegmentedBar(ctx, {
 
 #### `drawTank(ctx, options): void`
 
+Options type: `DrawTankOptions`.
+
 Fluid container — ballast tanks, fuel gauges, water reservoirs, lava levels, oil drums, chemical canisters. Liquid fills from the bottom up.
 
 ```ts
@@ -1250,6 +1361,8 @@ drawTank(ctx, {
 
 #### `drawDial(ctx, options): void`
 
+Options type: `DrawDialOptions`.
+
 Circular analog gauge with movable needle — RPM, speedometer, fuel, temperature, volume knob. Decorations (face fill, rim outline, tick marks) are optional; the needle alone is the minimum visible output.
 
 ```ts
@@ -1288,6 +1401,8 @@ Angles use canvas convention: `0` = right, `π/2` = down, `π` = left, `3π/2` =
 
 #### `drawCompassText(ctx, options): void`
 
+Options type: `DrawCompassTextOptions`.
+
 Text-based heading indicator in the classic 80s tactical-display style `[W [NW] N [NE] E]` — current direction in the centre, highlighted, with two neighbouring directions on each side. Heading rounds to the nearest 45° step.
 
 ```ts
@@ -1365,9 +1480,11 @@ appPhase = 'intro'
 
 ---
 
-## `input.ts` — Keyboard Input
+## `input.ts` — Keyboard & Gamepad Input
 
-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.
+Handles directional movement with configurable keyboard repeat, transparent
+gamepad polling, and single-consume flags for action buttons. Call
+`initInput()` once at startup, then `tickMovement(dt)` every frame.
 
 ### `Direction` type
 
@@ -1381,6 +1498,11 @@ Attaches `keydown`/`keyup` listeners. Idempotent — safe to call multiple times
 
 Default key bindings: arrows = movement, `W A S D` = also movement, `F` = flag action, `P` = pause, `Ctrl+Shift+B` = debug toggle.
 
+Gamepad support is automatic. `tickMovement()` polls the first connected
+gamepad via the browser Gamepad API: D-pad / left stick move, button 0 maps to
+`consumeFlag()`, button 9 maps to `consumePause()`, button 3 maps to
+`consumeDebug()`, and any button triggers `consumeAnyKey()`.
+
 ```ts
 initInput()          // default: 150ms initial delay, 80ms repeat
 initInput(200, 60)   // custom timing
@@ -1388,7 +1510,9 @@ initInput(200, 60)   // custom timing
 
 ### `tickMovement(dtMs): Direction | null`
 
-Returns the active movement direction for this frame, or `null`. Handles the delay/repeat state machine internally. Call exactly once per frame.
+Returns the active movement direction for this frame, or `null`. Handles the
+keyboard delay/repeat state machine and gamepad polling internally. Call
+exactly once per frame.
 
 ```ts
 const dir = tickMovement(dt)
@@ -1404,10 +1528,10 @@ Each function returns `true` exactly once per key press, then resets to `false`.
 
 | 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 |
+| `consumeFlag()` | `F` / gamepad button 0 | Flag / unflag a tile |
+| `consumePause()` | `P` / gamepad button 9 | Pause / unpause |
+| `consumeDebug()` | `Ctrl+Shift+B` / gamepad button 3 | Toggle debug overlay |
+| `consumeAnyKey()` | Any key / any gamepad button | Dismiss overlays, start game |
 
 ```ts
 if (consumeFlag())   toggleFlag(playerX, playerY)
@@ -1921,6 +2045,23 @@ for (const e of enemies) {
 | `deadzoneW`, `deadzoneH` | Deadzone size — target may move ±`deadzoneW/2` from centre before scrolling |
 | `targetX`, `targetY` | Current follow target (set via `setCameraTarget`) |
 
+### `CameraOptions` interface
+
+Options passed to `createCamera()`. `viewW`, `viewH`, `worldW`, and `worldH`
+are required; `lerp`, `deadzoneW`, and `deadzoneH` are optional.
+
+```ts
+interface CameraOptions {
+  viewW: number
+  viewH: number
+  worldW: number
+  worldH: number
+  lerp?: number
+  deadzoneW?: number
+  deadzoneH?: number
+}
+```
+
 ### `createCamera(opts): Camera`
 
 Creates a camera at world origin `(0, 0)`. `lerp` defaults to `1` (snap), deadzones default to `0`.
@@ -2377,13 +2518,23 @@ interface ParticleSystem {
 }
 ```
 
+### `Ranged` type
+
+Several emitter options accept either a fixed value or a `[min, max]` range.
+
+```ts
+type Ranged = number | readonly [number, number]
+```
+
 ### `createParticleSystem(capacity): ParticleSystem`
 
 Creates a pool of `capacity` particles, all inactive. Throws when `capacity` is not a positive integer.
 
 ### `emitParticles(ps, opts): number`
 
-Emits up to `opts.count` particles and returns the number actually emitted (fewer when the pool is full). Throws when `count` is negative or non-integer.
+Emits up to `opts.count` particles and returns the number actually emitted
+(fewer when the pool is full). Throws when `count` is negative or non-integer.
+The options object is exported as `EmitOptions`.
 
 | Option | Type | Default | Meaning |
 |--------|------|---------|---------|
@@ -2469,6 +2620,55 @@ Hashes a string to an unsigned 32-bit integer (FNV-1a). Deterministic; exported
 
 ---
 
+## `lighting.ts` — Dithered Cave Darkness
+
+The ZX way to fake light: hard 8×8 light pools with an ordered (Bayer) **dither** edge — no alpha gradients. The look of *Knight Lore* / *Head over Heels*, not modern soft shadows.
+
+Done the naive way (recompute a full-screen `ImageData` and `putImageData` it every frame) this is a real CPU/upload hog — it measured ~27% of a frame in an actual game. This module instead **pre-renders the dither for each darkness level to a tiny tile, darkens the view cell-by-cell into a persistent buffer (repainting only cells whose level changed), and blits the buffer with one `drawImage`** — no per-frame `putImageData`.
+
+You own the *policy* (where it's dark) via a per-cell callback; the module owns the fast *rendering*.
+
+### `Light` interface
+
+```ts
+interface Light { x: number; y: number; radius: number; intensity: number } // intensity 0..1
+```
+
+### `brightnessAt(px, py, lights): number`
+
+Brightest attenuated light at a point — `max((1 - dist/radius) * intensity)` over all lights, clamped to `0..1`. Turn it into darkness with `1 - brightnessAt(...)`. Pure.
+
+### `ditherBlack(px, py, amount): boolean`
+
+The ordered-dither rule used to bake the tiles: is pixel `(px, py)` black at darkness `amount` (0..1)? Pure and deterministic — handy for tests or custom effects.
+
+### `createDarknessLayer(width, height, levels?): DarknessLayer`
+
+Builds a view-sized overlay: pre-bakes `levels` dither tiles (default **8** — more = smoother), a persistent buffer, and a per-cell level cache. Call **once**; reuse across frames. Throws if `levels < 2`.
+
+### `renderDarkness(layer, ctx, darknessAt): void`
+
+Darkens `ctx` for this frame. `darknessAt(col, row)` returns the darkness of each 8×8 cell — **0 = lit, 1 = pitch black** (clamped, then quantised to the layer's levels). Only cells whose level changed since the last call are repainted; then the buffer is blitted once.
+
+```ts
+import { createDarknessLayer, renderDarkness, brightnessAt, CELL } from 'zx-kit'
+
+const dark = createDarknessLayer(256, 192)           // once
+
+// each frame, after drawing the scene, before the HUD:
+const lights = [{ x: playerX, y: playerY, radius: 72, intensity: 1 }]
+renderDarkness(dark, ctx, (col, row) => {
+  const b = brightnessAt(col * CELL + 4, row * CELL + 4, lights)
+  return 1 - b                                        // 0 = lit … 1 = dark
+})
+```
+
+The `darknessAt` callback is where you add **depth gradients** (darker the deeper you are), fog, flashing — anything; the renderer stays fast because it only repaints cells whose quantised level actually changed.
+
+> Lights are in **screen** pixels (apply the camera yourself). Rendering needs a real canvas; in a headless test environment the layer degrades to a no-op blit while the level math still runs.
+
+---
+
 ## Architecture
 
 ### Module structure

package/dist/index.d.ts

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

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -16,4 +16,5 @@ export * from './camera.js';
 export * from './scene.js';
 export * from './save.js';
 export * from './i18n.js';
+export * from './lighting.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/lighting.d.ts

@@ -0,0 +1,45 @@
+/** A point light: position (screen px), reach `radius` (px) and `intensity` 0..1. */
+export interface Light {
+    x: number;
+    y: number;
+    radius: number;
+    intensity: number;
+}
+/**
+ * The ordered-dither rule: is pixel `(px, py)` black at darkness `amount` (0..1)?
+ * Pure and deterministic — used to bake the level tiles, and handy to test.
+ */
+export declare function ditherBlack(px: number, py: number, amount: number): boolean;
+/**
+ * Brightest attenuated light at a point: `max((1 - dist/radius) * intensity)`
+ * over all lights, clamped to 0..1. Turn it into darkness with `1 - brightnessAt(...)`.
+ */
+export declare function brightnessAt(px: number, py: number, lights: readonly Light[]): number;
+/** A view-sized darkness overlay with pre-baked dither tiles + a cached buffer. */
+export interface DarknessLayer {
+    readonly width: number;
+    readonly height: number;
+    readonly levels: number;
+    readonly cols: number;
+    readonly rows: number;
+    /** Pre-rendered 8×8 dither tiles, index 0 (lit, `null`) … levels-1 (darkest). */
+    readonly tiles: ReadonlyArray<HTMLCanvasElement | null>;
+    /** Persistent darkness buffer (view-sized), blitted each frame. */
+    readonly buffer: HTMLCanvasElement | null;
+    /** Last level drawn per cell, row-major; -1 = never drawn (forces a repaint). */
+    readonly cellLevel: Int16Array;
+}
+/**
+ * Creates a darkness layer sized to the view. `levels` is the number of darkness
+ * steps (default 8) — more is a smoother dither for a little more memory. Call
+ * once; reuse across frames.
+ */
+export declare function createDarknessLayer(width: number, height: number, levels?: number): DarknessLayer;
+/**
+ * Renders dithered darkness onto `ctx`. `darknessAt(col, row)` returns the
+ * darkness of each 8×8 cell: **0 = lit**, **1 = pitch black** (values are clamped
+ * and quantised to the layer's `levels`). Only cells whose level changed since the
+ * last call are repainted on the cached buffer; the buffer is then blitted once.
+ */
+export declare function renderDarkness(layer: DarknessLayer, ctx: CanvasRenderingContext2D, darknessAt: (col: number, row: number) => number): void;
+//# sourceMappingURL=lighting.d.ts.map

package/dist/lighting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lighting.d.ts","sourceRoot":"","sources":["../src/lighting.ts"],"names":[],"mappings":"AAkCA,qFAAqF;AACrF,MAAM,WAAW,KAAK;IACpB,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;CAClB;AAMD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAE3E;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,KAAK,EAAE,GAAG,MAAM,CAarF;AAED,mFAAmF;AACnF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,iFAAiF;IACjF,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAA;IACvD,mEAAmE;IACnE,QAAQ,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAA;IACzC,iFAAiF;IACjF,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAA;CAC/B;AAmBD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,SAAI,GAAG,aAAa,CAkB5F;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,aAAa,EACpB,GAAG,EAAE,wBAAwB,EAC7B,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,MAAM,GAC/C,IAAI,CAwBN"}

package/dist/lighting.js

@@ -0,0 +1,138 @@
+/**
+ * @module lighting
+ *
+ * **Dithered cave darkness** — the ZX way to fake light: hard 8×8 light pools
+ * with an ordered (Bayer) dither edge, no alpha gradients. Think *Knight Lore*,
+ * not modern soft shadows.
+ *
+ * Built for speed. The naive way (recompute a full-screen `ImageData` and
+ * `putImageData` it every frame) is a CPU/upload hog — it was ~27% of a frame in
+ * a real game. Instead:
+ *
+ *  1. The dither for each darkness **level** is pre-rendered once to a tiny 8×8
+ *     tile ({@link createDarknessLayer}).
+ *  2. The view is darkened **cell by cell** into a persistent buffer, and only
+ *     cells whose level **changed** since the last frame are repainted.
+ *  3. The whole buffer is blitted with **one `drawImage`** — no per-frame
+ *     `putImageData`.
+ *
+ * The game supplies a per-cell darkness via a callback, so it owns the *policy*
+ * (lights, depth gradients, fog…) while this module owns the fast *rendering*.
+ * {@link brightnessAt} is a ready helper for the common "pools of light" case.
+ *
+ * @example
+ * ```ts
+ * const dark = createDarknessLayer(256, 192)        // once, view-sized
+ * // each frame, after drawing the scene:
+ * renderDarkness(dark, ctx, (col, row) => {
+ *   const b = brightnessAt(col * CELL + 4, row * CELL + 4, lights)
+ *   return 1 - b                                    // 0 = lit, 1 = pitch black
+ * })
+ * ```
+ */
+import { CELL } from './palette.js';
+// Dispersed 4×4 Bayer matrix (values 0..15), row-major — drives the stipple.
+// 8×8 cells are a multiple of 4, so tiles dither seamlessly across cell borders.
+const BAYER4 = [0, 8, 2, 10, 12, 4, 14, 6, 3, 11, 1, 9, 15, 7, 13, 5];
+/**
+ * The ordered-dither rule: is pixel `(px, py)` black at darkness `amount` (0..1)?
+ * Pure and deterministic — used to bake the level tiles, and handy to test.
+ */
+export function ditherBlack(px, py, amount) {
+    return (BAYER4[((py & 3) << 2) | (px & 3)] + 0.5) / 16 < amount;
+}
+/**
+ * Brightest attenuated light at a point: `max((1 - dist/radius) * intensity)`
+ * over all lights, clamped to 0..1. Turn it into darkness with `1 - brightnessAt(...)`.
+ */
+export function brightnessAt(px, py, lights) {
+    let b = 0;
+    for (const l of lights) {
+        if (l.radius <= 0)
+            continue;
+        const dx = px - l.x;
+        const dy = py - l.y;
+        const d = Math.sqrt(dx * dx + dy * dy);
+        if (d < l.radius) {
+            const c = (1 - d / l.radius) * l.intensity;
+            if (c > b)
+                b = c;
+        }
+    }
+    return b > 1 ? 1 : b < 0 ? 0 : b;
+}
+/** Bakes one 8×8 dither tile for darkness `amount`, or `null` when fully lit. */
+function makeTile(amount) {
+    if (amount <= 0 || typeof document === 'undefined')
+        return null;
+    const c = document.createElement('canvas');
+    c.width = CELL;
+    c.height = CELL;
+    const ctx = c.getContext('2d');
+    if (!ctx)
+        return null;
+    ctx.fillStyle = '#000';
+    for (let y = 0; y < CELL; y++) {
+        for (let x = 0; x < CELL; x++) {
+            if (ditherBlack(x, y, amount))
+                ctx.fillRect(x, y, 1, 1);
+        }
+    }
+    return c;
+}
+/**
+ * Creates a darkness layer sized to the view. `levels` is the number of darkness
+ * steps (default 8) — more is a smoother dither for a little more memory. Call
+ * once; reuse across frames.
+ */
+export function createDarknessLayer(width, height, levels = 8) {
+    if (!Number.isInteger(levels) || levels < 2) {
+        throw new Error(`createDarknessLayer: levels must be an integer >= 2, got ${levels}`);
+    }
+    const cols = Math.ceil(width / CELL);
+    const rows = Math.ceil(height / CELL);
+    const tiles = [];
+    for (let i = 0; i < levels; i++)
+        tiles.push(makeTile(i / (levels - 1)));
+    let buffer = null;
+    if (typeof document !== 'undefined') {
+        buffer = document.createElement('canvas');
+        buffer.width = width;
+        buffer.height = height;
+    }
+    const cellLevel = new Int16Array(cols * rows).fill(-1);
+    return { width, height, levels, cols, rows, tiles, buffer, cellLevel };
+}
+/**
+ * Renders dithered darkness onto `ctx`. `darknessAt(col, row)` returns the
+ * darkness of each 8×8 cell: **0 = lit**, **1 = pitch black** (values are clamped
+ * and quantised to the layer's `levels`). Only cells whose level changed since the
+ * last call are repainted on the cached buffer; the buffer is then blitted once.
+ */
+export function renderDarkness(layer, ctx, darknessAt) {
+    const { buffer, tiles, levels, cols, rows, cellLevel } = layer;
+    const bctx = buffer ? buffer.getContext('2d') : null;
+    const maxLevel = levels - 1;
+    for (let row = 0; row < rows; row++) {
+        for (let col = 0; col < cols; col++) {
+            let a = darknessAt(col, row);
+            a = a < 0 ? 0 : a > 1 ? 1 : a;
+            const level = Math.round(a * maxLevel);
+            const idx = row * cols + col;
+            if (cellLevel[idx] === level)
+                continue; // unchanged → skip the repaint
+            cellLevel[idx] = level;
+            if (bctx) {
+                const x = col * CELL;
+                const y = row * CELL;
+                bctx.clearRect(x, y, CELL, CELL);
+                const tile = tiles[level];
+                if (tile)
+                    bctx.drawImage(tile, x, y);
+            }
+        }
+    }
+    if (buffer)
+        ctx.drawImage(buffer, 0, 0);
+}
+//# sourceMappingURL=lighting.js.map

package/dist/lighting.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zx-kit",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/zrebec/zx-kit.git"