zx-kit 0.3.0 → 0.5.0

package/README.md

@@ -344,6 +344,319 @@ resetInput()  // discard any queued keypresses from the previous phase
 
 ---
 
+### `ui.ts` — ZX-style UI primitives
+
+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`.
+
+#### Types
+
+**`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 |
+
+**`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) |
+| `value` | `number` | — | Current value |
+| `min` | `number` | `0` | Value at the left (empty) edge |
+| `max` | `number` | `1` | Value at the right (full) edge |
+| `ink` | `SpectrumColor` | `C.B_WHITE` | Filled-block color |
+| `paper` | `SpectrumColor` | `C.BLACK` | Empty-block background |
+| `border` | `BorderOptions` | — | Optional border around the bar |
+| `visibilityLength` | `number` | `500` | Ms to stay visible after last call; `0` = permanent |
+
+#### Stateless primitives
+
+##### `drawBox(ctx, options): void`
+
+Fills a rectangle with `paper` and draws an optional border.
+
+```ts
+drawBox(ctx, {
+  x: 8, y: 8, width: 112, height: 40,
+  paper: C.BLACK, ink: C.B_WHITE,
+  border: { style: 'solid', thickness: 1 },
+})
+```
+
+##### `drawFrame(ctx, options): void`
+
+Draws a border only — no background fill.
+
+```ts
+drawFrame(ctx, { x: 0, y: 0, width: 256, height: 176, color: C.B_CYAN })
+drawFrame(ctx, { x: 16, y: 16, width: 64, height: 32, color: C.B_RED,
+  border: { style: 'dashed' } })
+```
+
+##### `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.
+
+```ts
+drawBox(ctx, { x: 8, y: 24, width: 128, height: 56, paper: C.BLACK })
+drawPanelTitle(ctx, {
+  text: 'OPTIONS', x: 8, y: 24,
+  ink: C.B_YELLOW, paper: C.BLACK,
+  centered: true, width: 128,
+})
+```
+
+#### 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.
+
+##### `drawProgressBar(ctx, options): void`
+
+Draws the bar immediately **and** registers it for managed redraws.
+
+```ts
+// On value change:
+drawProgressBar(ctx, {
+  id: 'volume', x: 88, y: 88, width: 80,
+  value: getMasterVolume(),
+  ink: C.B_GREEN, paper: C.BLACK,
+  border: { style: 'solid' },
+  visibilityLength: 1500,
+})
+
+// Permanent HUD element:
+drawProgressBar(ctx, {
+  id: 'health', x: 0, y: 184, width: 40,
+  value: lives, min: 0, max: 3,
+  ink: C.B_GREEN, paper: C.BLACK,
+  visibilityLength: 0,
+})
+```
+
+##### `tickUI(dtMs): void`
+
+Advances all managed bar timers. Expired bars are removed. Call once per frame.
+
+##### `renderUI(ctx): void`
+
+Redraws all currently visible bars. Call every frame **after** the game world render.
+
+##### `resetUI(): void`
+
+Clears all managed state. Call alongside `resetInput()` on phase transitions.
+
+```ts
+// Typical game loop:
+renderFrame(ctx, state)
+tickUI(dt)
+renderUI(ctx)
+
+// Phase transition:
+resetInput()
+resetUI()
+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.
+
+#### Types
+
+**`Tile`**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `sprite` | `Uint8Array` | 8-byte bitmap — same format as `drawSprite()` |
+| `ink` | `string` | Foreground colour (`C.*` palette value) |
+| `paper` | `string` | 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, …) |
+
+**`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 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).
+
+#### Method reference
+
+| 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). |
+
+#### Smart background swapping (`setBackground`)
+
+`setBackground` has two modes depending on whether a background has been registered before:
+
+- **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.
+
+Comparison is by `id` value, so it works correctly after shallow copies.
+
+```ts
+map.fill(TILE_GRASS)
+map.setBackground(TILE_GRASS)      // register — map unchanged
+
+map.setTile(5, 3, TILE_PLAYER)     // player placed on grass
+
+map.setBackground(TILE_SNOW)       // TILE_GRASS → TILE_SNOW everywhere
+                                   // TILE_PLAYER at (5, 3) — untouched
+
+map.setBackground(TILE_NIGHT)      // TILE_SNOW → TILE_NIGHT
+                                   // TILE_PLAYER — still untouched
+```
+
+---
+
+#### Boulder Dash-style level
+
+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.
+
+```ts
+import { createTileMap, C, CELL } from 'zx-kit'
+import type { Tile, Viewport } from 'zx-kit'
+
+// ── 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 },
+}
+
+// ── Map setup ─────────────────────────────────────────────────────────────────
+
+const COLS = 64
+const ROWS = 32
+const map = createTileMap(COLS, ROWS)
+
+// Fill with dirt and register it as the seasonal background
+map.fill(TILE_DIRT)
+map.setBackground(TILE_DIRT)
+
+// 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
+
+// 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)
+
+// ── Seasonal swap ─────────────────────────────────────────────────────────────
+
+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',
+}
+
+// Winter: only dirt tiles become snow — walls, rocks, gems, exit are untouched
+map.setBackground(TILE_SNOW)
+
+// ── Game loop ─────────────────────────────────────────────────────────────────
+
+const SCREEN_COLS = 32
+const SCREEN_ROWS = 24
+let playerX = 2
+let playerY = 2
+let score = 0
+
+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))
+
+  map.render(ctx, { x: camX, y: camY, cols: SCREEN_COLS, rows: SCREEN_ROWS })
+}
+
+// ── Collision & interaction ───────────────────────────────────────────────────
+
+function tryMove(dx: number, dy: number) {
+  const nx = playerX + dx
+  const ny = playerY + dy
+
+  if (map.isSolid(nx, ny)) return  // wall, rock, or map boundary
+
+  const target = map.getTile(nx, ny)
+  if (target?.id === 'gem') {
+    score += target.metadata!['points'] as number
+    map.clearTile(nx, ny)
+  }
+
+  playerX = nx
+  playerY = ny
+}
+
+// ── Level completion ──────────────────────────────────────────────────────────
+
+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}`)
+}
+
+// Count remaining gems
+const gemsLeft = map.findById('gem').length
+console.log(`${gemsLeft} gems remaining`)
+```
+
+---
+
 ## File structure
 
 ```
@@ -361,8 +674,12 @@ zx-kit/
 │   │                    # getAudioContext, getMasterGain,
 │   │                    # getMasterVolume, setMasterVolume,
 │   │                    # increaseVolume, decreaseVolume
-│   └── input.ts         # initInput, tickMovement, consumeFlag/Debug/Pause/AnyKey,
-│                        # isHeld, resetInput, Direction
+│   ├── input.ts         # initInput, tickMovement, consumeFlag/Debug/Pause/AnyKey,
+│   │                    # isHeld, resetInput, Direction
+│   ├── ui.ts            # drawBox, drawFrame, drawPanelTitle,
+│   │                    # drawProgressBar, tickUI, renderUI, resetUI,
+│   │                    # BorderOptions, DrawProgressBarOptions
+│   └── tilemap.ts       # createTileMap, Tile, Viewport, TileMap
 └── dist/                # compiled output (generated by npm run build)
     ├── index.js / .d.ts
     └── ...

package/dist/index.d.ts

@@ -3,4 +3,6 @@ export * from './font.js';
 export * from './renderer.js';
 export * from './audio.js';
 export * from './input.js';
+export * from './ui.js';
+export * from './tilemap.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,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA;AAC5B,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,SAAS,CAAA;AACvB,cAAc,cAAc,CAAA"}

package/dist/index.js

@@ -3,4 +3,6 @@ export * from './font.js';
 export * from './renderer.js';
 export * from './audio.js';
 export * from './input.js';
+export * from './ui.js';
+export * from './tilemap.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,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA;AAC5B,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,SAAS,CAAA;AACvB,cAAc,cAAc,CAAA"}

package/dist/tilemap.d.ts

@@ -0,0 +1,133 @@
+/**
+ * A single 8×8 tile placed in a `TileMap`.
+ * Sprite format is identical to `drawSprite()` — one byte per row, bit 7 = leftmost pixel.
+ */
+export interface Tile {
+    /** 8-byte sprite bitmap (one byte per row, bit 7 = leftmost pixel). */
+    sprite: Uint8Array;
+    /** Foreground colour — a `C.*` palette value. */
+    ink: string;
+    /** Background colour — a `C.*` palette value. */
+    paper: string;
+    /** When `true` the tile blocks movement (walls, solid objects, map boundary). */
+    solid: boolean;
+    /** Stable identifier used for game logic and smart background swapping. */
+    id: string | number;
+    /** Arbitrary game-specific data attached to this tile instance. */
+    metadata?: Record<string, unknown>;
+}
+/** Defines the visible region of a map to render. All values are in tile units, not pixels. */
+export interface Viewport {
+    /** First visible column (tile units). */
+    x: number;
+    /** First visible row (tile units). */
+    y: number;
+    /** Number of tile columns to render. */
+    cols: number;
+    /** Number of tile rows to render. */
+    rows: number;
+}
+/**
+ * A scrollable, queryable tile map with O(1) id-based lookup.
+ * Obtain an instance via `createTileMap(cols, rows)`.
+ *
+ * All mutating methods store **shallow copies** of tile objects — the caller
+ * may safely reuse or mutate tile definitions without affecting placed tiles.
+ */
+export interface TileMap {
+    /** Map width in tile columns. */
+    readonly cols: number;
+    /** Map height in tile rows. */
+    readonly rows: number;
+    /**
+     * Registers or swaps the background tile.
+     *
+     * - **First call:** stores `tile` as the current background; the map is left unchanged.
+     * - **Subsequent calls (smart swap):** every cell whose `id` still matches the previously
+     *   registered background is replaced with a shallow copy of the new tile. Cells with
+     *   any other `id` (player, objects, modified terrain) are not touched.
+     *
+     * Comparison is by `id` value, so it works correctly after shallow copies.
+     *
+     * @example
+     * map.fill(TILE_GRASS)
+     * map.setBackground(TILE_GRASS)       // registers background; map unchanged
+     * map.setTile(3, 5, TILE_PLAYER)
+     * map.setBackground(TILE_SNOW)        // grass → snow; TILE_PLAYER untouched
+     */
+    setBackground(tile: Tile): void;
+    /**
+     * Stores a shallow copy of `tile` at `(x, y)`.
+     * Out-of-bounds coordinates are silently ignored.
+     */
+    setTile(x: number, y: number, tile: Tile): void;
+    /**
+     * Returns the tile at `(x, y)`, or `null` if the cell is empty or out of bounds.
+     * Never throws.
+     */
+    getTile(x: number, y: number): Tile | null;
+    /**
+     * Removes the tile at `(x, y)`, making the cell empty.
+     * Out-of-bounds coordinates are silently ignored.
+     */
+    clearTile(x: number, y: number): void;
+    /** Fills every cell in the map with a separate shallow copy of `tile`. */
+    fill(tile: Tile): void;
+    /**
+     * Fills the rectangle `(x, y) – (x+w, y+h)` with shallow copies of `tile`.
+     * Areas outside the map boundary are silently clipped.
+     */
+    fillRect(x: number, y: number, w: number, h: number, tile: Tile): void;
+    /**
+     * Renders the map (or the given `viewport`) to `ctx` via `drawSprite`.
+     * Empty cells are skipped. Tiles partially outside the viewport are not drawn.
+     * Canvas pixel position: `canvasX = (tileX - viewport.x) * CELL`.
+     *
+     * When `viewport` is omitted the entire map is rendered starting at canvas origin.
+     */
+    render(ctx: CanvasRenderingContext2D, viewport?: Viewport): void;
+    /**
+     * Returns `true` when the tile at `(x, y)` has `solid === true`.
+     * Out-of-bounds coordinates return `true` — the map boundary is implicitly solid.
+     */
+    isSolid(x: number, y: number): boolean;
+    /**
+     * Returns every cell whose tile has the given `id`.
+     * Uses an internal index — O(1) lookup, does not iterate the full map.
+     * Returns an empty array when no matching tile exists.
+     */
+    findById(id: string | number): {
+        x: number;
+        y: number;
+        tile: Tile;
+    }[];
+}
+/**
+ * Creates a `TileMap` of `cols × rows` tiles. All cells start empty.
+ * Use `fill` / `fillRect` / `setTile` to populate terrain, and `setBackground`
+ * to register a background tile for later smart swapping.
+ *
+ * @param cols - Map width in tiles
+ * @param rows - Map height in tiles
+ *
+ * @example
+ * import { createTileMap, C } from 'zx-kit'
+ *
+ * const map = createTileMap(64, 32)
+ * map.fill(TILE_GRASS)
+ * map.setBackground(TILE_GRASS)
+ * map.fillRect(0, 0, 64, 1, TILE_WALL)        // ceiling
+ * map.fillRect(0, 31, 64, 1, TILE_WALL)       // floor
+ * map.setTile(60, 15, TILE_EXIT)
+ *
+ * // In game loop — camera follows the player
+ * map.render(ctx, { x: camX - 16, y: camY - 12, cols: 32, rows: 24 })
+ *
+ * // Collision
+ * if (!map.isSolid(playerX, playerY + 1)) playerY++
+ *
+ * // Season swap — player, gems, modified cells are untouched
+ * map.setBackground(TILE_SNOW)
+ */
+export declare function createTileMap(cols: number, rows: number): TileMap;
+//# sourceMappingURL=tilemap.d.ts.map

package/dist/tilemap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tilemap.d.ts","sourceRoot":"","sources":["../src/tilemap.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,MAAM,WAAW,IAAI;IACnB,uEAAuE;IACvE,MAAM,EAAE,UAAU,CAAA;IAClB,iDAAiD;IACjD,GAAG,EAAE,MAAM,CAAA;IACX,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAA;IACb,iFAAiF;IACjF,KAAK,EAAE,OAAO,CAAA;IACd,2EAA2E;IAC3E,EAAE,EAAE,MAAM,GAAG,MAAM,CAAA;IACnB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC;AAED,+FAA+F;AAC/F,MAAM,WAAW,QAAQ;IACvB,yCAAyC;IACzC,CAAC,EAAE,MAAM,CAAA;IACT,sCAAsC;IACtC,CAAC,EAAE,MAAM,CAAA;IACT,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAA;IACZ,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAA;CACb;AAED;;;;;;GAMG;AACH,MAAM,WAAW,OAAO;IACtB,iCAAiC;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB;;;;;;;;;;;;;;;OAeG;IACH,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAAA;IAE/B;;;OAGG;IACH,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI,CAAA;IAE/C;;;OAGG;IACH,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAA;IAE1C;;;OAGG;IACH,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAErC,0EAA0E;IAC1E,IAAI,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAAA;IAEtB;;;OAGG;IACH,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI,CAAA;IAEtE;;;;;;OAMG;IACH,MAAM,CAAC,GAAG,EAAE,wBAAwB,EAAE,QAAQ,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAA;IAEhE;;;OAGG;IACH,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IAEtC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,IAAI,CAAA;KAAE,EAAE,CAAA;CACtE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAyIjE"}

package/dist/tilemap.js

@@ -0,0 +1,166 @@
+import { CELL } from './palette.js';
+import { drawSprite } from './renderer.js';
+/**
+ * Creates a `TileMap` of `cols × rows` tiles. All cells start empty.
+ * Use `fill` / `fillRect` / `setTile` to populate terrain, and `setBackground`
+ * to register a background tile for later smart swapping.
+ *
+ * @param cols - Map width in tiles
+ * @param rows - Map height in tiles
+ *
+ * @example
+ * import { createTileMap, C } from 'zx-kit'
+ *
+ * const map = createTileMap(64, 32)
+ * map.fill(TILE_GRASS)
+ * map.setBackground(TILE_GRASS)
+ * map.fillRect(0, 0, 64, 1, TILE_WALL)        // ceiling
+ * map.fillRect(0, 31, 64, 1, TILE_WALL)       // floor
+ * map.setTile(60, 15, TILE_EXIT)
+ *
+ * // In game loop — camera follows the player
+ * map.render(ctx, { x: camX - 16, y: camY - 12, cols: 32, rows: 24 })
+ *
+ * // Collision
+ * if (!map.isSolid(playerX, playerY + 1)) playerY++
+ *
+ * // Season swap — player, gems, modified cells are untouched
+ * map.setBackground(TILE_SNOW)
+ */
+export function createTileMap(cols, rows) {
+    const cells = new Array(cols * rows).fill(null);
+    const idIndex = new Map();
+    let currentBackground = null;
+    function inBounds(x, y) {
+        return x >= 0 && y >= 0 && x < cols && y < rows;
+    }
+    function cellKey(x, y) {
+        return `${x},${y}`;
+    }
+    function indexRemove(x, y) {
+        const existing = cells[y * cols + x];
+        if (existing === null)
+            return;
+        const set = idIndex.get(existing.id);
+        if (!set)
+            return;
+        set.delete(cellKey(x, y));
+        if (set.size === 0)
+            idIndex.delete(existing.id);
+    }
+    function indexAdd(x, y, tile) {
+        let set = idIndex.get(tile.id);
+        if (!set) {
+            set = new Set();
+            idIndex.set(tile.id, set);
+        }
+        set.add(cellKey(x, y));
+    }
+    return {
+        get cols() { return cols; },
+        get rows() { return rows; },
+        setBackground(tile) {
+            if (currentBackground === null) {
+                currentBackground = { ...tile };
+                return;
+            }
+            const oldId = currentBackground.id;
+            for (let y = 0; y < rows; y++) {
+                for (let x = 0; x < cols; x++) {
+                    const cell = cells[y * cols + x];
+                    if (cell !== null && cell.id === oldId) {
+                        indexRemove(x, y);
+                        const copy = { ...tile };
+                        cells[y * cols + x] = copy;
+                        indexAdd(x, y, copy);
+                    }
+                }
+            }
+            currentBackground = { ...tile };
+        },
+        setTile(x, y, tile) {
+            if (!inBounds(x, y))
+                return;
+            indexRemove(x, y);
+            const copy = { ...tile };
+            cells[y * cols + x] = copy;
+            indexAdd(x, y, copy);
+        },
+        getTile(x, y) {
+            if (!inBounds(x, y))
+                return null;
+            return cells[y * cols + x];
+        },
+        clearTile(x, y) {
+            if (!inBounds(x, y))
+                return;
+            indexRemove(x, y);
+            cells[y * cols + x] = null;
+        },
+        fill(tile) {
+            idIndex.clear();
+            for (let y = 0; y < rows; y++) {
+                for (let x = 0; x < cols; x++) {
+                    const copy = { ...tile };
+                    cells[y * cols + x] = copy;
+                    indexAdd(x, y, copy);
+                }
+            }
+        },
+        fillRect(x, y, w, h, tile) {
+            const x0 = Math.max(0, x);
+            const y0 = Math.max(0, y);
+            const x1 = Math.min(cols, x + w);
+            const y1 = Math.min(rows, y + h);
+            for (let ty = y0; ty < y1; ty++) {
+                for (let tx = x0; tx < x1; tx++) {
+                    indexRemove(tx, ty);
+                    const copy = { ...tile };
+                    cells[ty * cols + tx] = copy;
+                    indexAdd(tx, ty, copy);
+                }
+            }
+        },
+        render(ctx, viewport) {
+            const vx = viewport?.x ?? 0;
+            const vy = viewport?.y ?? 0;
+            const vcols = viewport?.cols ?? cols;
+            const vrows = viewport?.rows ?? rows;
+            for (let row = 0; row < vrows; row++) {
+                const ty = vy + row;
+                if (ty < 0 || ty >= rows)
+                    continue;
+                for (let col = 0; col < vcols; col++) {
+                    const tx = vx + col;
+                    if (tx < 0 || tx >= cols)
+                        continue;
+                    const tile = cells[ty * cols + tx];
+                    if (tile === null)
+                        continue;
+                    drawSprite(ctx, tile.sprite, col * CELL, row * CELL, tile.ink, tile.paper);
+                }
+            }
+        },
+        isSolid(x, y) {
+            if (!inBounds(x, y))
+                return true;
+            return cells[y * cols + x]?.solid ?? false;
+        },
+        findById(id) {
+            const set = idIndex.get(id);
+            if (!set)
+                return [];
+            const result = [];
+            for (const k of set) {
+                const comma = k.indexOf(',');
+                const tx = parseInt(k.slice(0, comma), 10);
+                const ty = parseInt(k.slice(comma + 1), 10);
+                const tile = cells[ty * cols + tx];
+                if (tile !== null)
+                    result.push({ x: tx, y: ty, tile });
+            }
+            return result;
+        },
+    };
+}
+//# sourceMappingURL=tilemap.js.map

package/dist/tilemap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tilemap.js","sourceRoot":"","sources":["../src/tilemap.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAA;AACnC,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAkH1C;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY,EAAE,IAAY;IACtD,MAAM,KAAK,GAAoB,IAAI,KAAK,CAAc,IAAI,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAC7E,MAAM,OAAO,GAAG,IAAI,GAAG,EAAgC,CAAA;IACvD,IAAI,iBAAiB,GAAgB,IAAI,CAAA;IAEzC,SAAS,QAAQ,CAAC,CAAS,EAAE,CAAS;QACpC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,IAAI,CAAA;IACjD,CAAC;IAED,SAAS,OAAO,CAAC,CAAS,EAAE,CAAS;QACnC,OAAO,GAAG,CAAC,IAAI,CAAC,EAAE,CAAA;IACpB,CAAC;IAED,SAAS,WAAW,CAAC,CAAS,EAAE,CAAS;QACvC,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAA;QACpC,IAAI,QAAQ,KAAK,IAAI;YAAE,OAAM;QAC7B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAA;QACpC,IAAI,CAAC,GAAG;YAAE,OAAM;QAChB,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;QACzB,IAAI,GAAG,CAAC,IAAI,KAAK,CAAC;YAAE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAA;IACjD,CAAC;IAED,SAAS,QAAQ,CAAC,CAAS,EAAE,CAAS,EAAE,IAAU;QAChD,IAAI,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;QAC9B,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,GAAG,GAAG,IAAI,GAAG,EAAU,CAAA;YACvB,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,GAAG,CAAC,CAAA;QAC3B,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;IACxB,CAAC;IAED,OAAO;QACL,IAAI,IAAI,KAAK,OAAO,IAAI,CAAA,CAAC,CAAC;QAC1B,IAAI,IAAI,KAAK,OAAO,IAAI,CAAA,CAAC,CAAC;QAE1B,aAAa,CAAC,IAAU;YACtB,IAAI,iBAAiB,KAAK,IAAI,EAAE,CAAC;gBAC/B,iBAAiB,GAAG,EAAE,GAAG,IAAI,EAAE,CAAA;gBAC/B,OAAM;YACR,CAAC;YACD,MAAM,KAAK,GAAG,iBAAiB,CAAC,EAAE,CAAA;YAClC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC9B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC;oBAC9B,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAA;oBAChC,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,CAAC,EAAE,KAAK,KAAK,EAAE,CAAC;wBACvC,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;wBACjB,MAAM,IAAI,GAAG,EAAE,GAAG,IAAI,EAAE,CAAA;wBACxB,KAAK,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,CAAA;wBAC1B,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,CAAA;oBACtB,CAAC;gBACH,CAAC;YACH,CAAC;YACD,iBAAiB,GAAG,EAAE,GAAG,IAAI,EAAE,CAAA;QACjC,CAAC;QAED,OAAO,CAAC,CAAS,EAAE,CAAS,EAAE,IAAU;YACtC,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC;gBAAE,OAAM;YAC3B,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;YACjB,MAAM,IAAI,GAAG,EAAE,GAAG,IAAI,EAAE,CAAA;YACxB,KAAK,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,CAAA;YAC1B,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,CAAA;QACtB,CAAC;QAED,OAAO,CAAC,CAAS,EAAE,CAAS;YAC1B,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC;gBAAE,OAAO,IAAI,CAAA;YAChC,OAAO,KAAK,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAA;QAC5B,CAAC;QAED,SAAS,CAAC,CAAS,EAAE,CAAS;YAC5B,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC;gBAAE,OAAM;YAC3B,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;YACjB,KAAK,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,CAAA;QAC5B,CAAC;QAED,IAAI,CAAC,IAAU;YACb,OAAO,CAAC,KAAK,EAAE,CAAA;YACf,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC9B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC;oBAC9B,MAAM,IAAI,GAAG,EAAE,GAAG,IAAI,EAAE,CAAA;oBACxB,KAAK,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,CAAA;oBAC1B,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,CAAA;gBACtB,CAAC;YACH,CAAC;QACH,CAAC;QAED,QAAQ,CAAC,CAAS,EAAE,CAAS,EAAE,CAAS,EAAE,CAAS,EAAE,IAAU;YAC7D,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;YACzB,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;YACzB,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAA;YAChC,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAA;YAChC,KAAK,IAAI,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC;gBAChC,KAAK,IAAI,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC;oBAChC,WAAW,CAAC,EAAE,EAAE,EAAE,CAAC,CAAA;oBACnB,MAAM,IAAI,GAAG,EAAE,GAAG,IAAI,EAAE,CAAA;oBACxB,KAAK,CAAC,EAAE,GAAG,IAAI,GAAG,EAAE,CAAC,GAAG,IAAI,CAAA;oBAC5B,QAAQ,CAAC,EAAE,EAAE,EAAE,EAAE,IAAI,CAAC,CAAA;gBACxB,CAAC;YACH,CAAC;QACH,CAAC;QAED,MAAM,CAAC,GAA6B,EAAE,QAAmB;YACvD,MAAM,EAAE,GAAG,QAAQ,EAAE,CAAC,IAAI,CAAC,CAAA;YAC3B,MAAM,EAAE,GAAG,QAAQ,EAAE,CAAC,IAAI,CAAC,CAAA;YAC3B,MAAM,KAAK,GAAG,QAAQ,EAAE,IAAI,IAAI,IAAI,CAAA;YACpC,MAAM,KAAK,GAAG,QAAQ,EAAE,IAAI,IAAI,IAAI,CAAA;YACpC,KAAK,IAAI,GAAG,GAAG,CAAC,EAAE,GAAG,GAAG,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC;gBACrC,MAAM,EAAE,GAAG,EAAE,GAAG,GAAG,CAAA;gBACnB,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,IAAI,IAAI;oBAAE,SAAQ;gBAClC,KAAK,IAAI,GAAG,GAAG,CAAC,EAAE,GAAG,GAAG,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC;oBACrC,MAAM,EAAE,GAAG,EAAE,GAAG,GAAG,CAAA;oBACnB,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,IAAI,IAAI;wBAAE,SAAQ;oBAClC,MAAM,IAAI,GAAG,KAAK,CAAC,EAAE,GAAG,IAAI,GAAG,EAAE,CAAC,CAAA;oBAClC,IAAI,IAAI,KAAK,IAAI;wBAAE,SAAQ;oBAC3B,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,EAAE,GAAG,GAAG,IAAI,EAAE,GAAG,GAAG,IAAI,EAAE,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,CAAA;gBAC5E,CAAC;YACH,CAAC;QACH,CAAC;QAED,OAAO,CAAC,CAAS,EAAE,CAAS;YAC1B,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC;gBAAE,OAAO,IAAI,CAAA;YAChC,OAAO,KAAK,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,EAAE,KAAK,IAAI,KAAK,CAAA;QAC5C,CAAC;QAED,QAAQ,CAAC,EAAmB;YAC1B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;YAC3B,IAAI,CAAC,GAAG;gBAAE,OAAO,EAAE,CAAA;YACnB,MAAM,MAAM,GAA2C,EAAE,CAAA;YACzD,KAAK,MAAM,CAAC,IAAI,GAAG,EAAE,CAAC;gBACpB,MAAM,KAAK,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;gBAC5B,MAAM,EAAE,GAAG,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAA;gBAC1C,MAAM,EAAE,GAAG,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;gBAC3C,MAAM,IAAI,GAAG,KAAK,CAAC,EAAE,GAAG,IAAI,GAAG,EAAE,CAAC,CAAA;gBAClC,IAAI,IAAI,KAAK,IAAI;oBAAE,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAA;YACxD,CAAC;YACD,OAAO,MAAM,CAAA;QACf,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/ui.d.ts

@@ -0,0 +1,231 @@
+import type { SpectrumColor } from './palette.js';
+/**
+ * Border configuration for UI primitives.
+ * When the `border` object is present on a parent option, a border is rendered.
+ * `enabled` defaults to `true` — set it to `false` to suppress the border
+ * while keeping the object in place for future toggling.
+ */
+export type BorderOptions = {
+    /** Enable/disable border rendering. Default: `true` */
+    enabled?: boolean;
+    /** Border thickness in pixels. Default: `1` */
+    thickness?: number;
+    /**
+     * Border color. Default: same as the primary `ink` / `color` of the parent function.
+     * Accepts any {@link SpectrumColor} value.
+     */
+    color?: SpectrumColor;
+    /**
+     * Border style.
+     * - `'solid'`  — continuous lines (default)
+     * - `'dashed'` — alternating 2 px on / 2 px off segments
+     */
+    style?: 'solid' | 'dashed';
+};
+/**
+ * Options for {@link drawProgressBar}.
+ */
+export type DrawProgressBarOptions = {
+    /**
+     * Stable key for managed-visibility mode.
+     * The bar's last-drawn state is registered under this key so `renderUI` can
+     * redraw it on subsequent frames. Defaults to `"${x},${y}"` when omitted.
+     */
+    id?: string;
+    /** Left edge of the bar in game pixels. */
+    x: number;
+    /** Top edge of the bar in game pixels. */
+    y: number;
+    /**
+     * Total width of the bar in game pixels.
+     * Should be a multiple of `CELL` (8) — any remainder is left blank.
+     */
+    width: number;
+    /** Current value to represent. */
+    value: number;
+    /** Minimum value (left edge = empty). Default: `0` */
+    min?: number;
+    /** Maximum value (right edge = full). Default: `1` */
+    max?: number;
+    /** Filled-block foreground color. Default: `C.B_WHITE` */
+    ink?: SpectrumColor;
+    /** Empty-block background color. Default: `C.BLACK` */
+    paper?: SpectrumColor;
+    /** Optional border around the entire bar. */
+    border?: BorderOptions;
+    /**
+     * How long the bar stays visible after the last `drawProgressBar` call (ms).
+     * - `> 0` — auto-hides after this many milliseconds.
+     * - `0`   — permanent; only cleared by `resetUI()`.
+     * Default: `500`
+     */
+    visibilityLength?: number;
+};
+/**
+ * Draws a filled rectangular box using ZX-style rendering.
+ *
+ * Renders a solid background (`paper`) and an optional border.
+ * Coordinates are in game pixels (already scaled by `setupCanvas`).
+ * Does NOT render text — use `drawPanelTitle` for labelled panels.
+ *
+ * @example
+ * drawBox(ctx, {
+ *   x: 8, y: 8, width: 112, height: 40,
+ *   paper: C.BLACK, ink: C.B_WHITE,
+ *   border: { style: 'solid', thickness: 1 },
+ * })
+ */
+export declare function drawBox(ctx: CanvasRenderingContext2D, options: {
+    /** Left edge in game pixels */
+    x: number;
+    /** Top edge in game pixels */
+    y: number;
+    /** Width in game pixels */
+    width: number;
+    /** Height in game pixels */
+    height: number;
+    /** Background fill color */
+    paper: SpectrumColor;
+    /** Foreground color — used as default border color when `border.color` is omitted */
+    ink?: SpectrumColor;
+    /** Optional border */
+    border?: BorderOptions;
+}): void;
+/**
+ * Draws a rectangular frame — border only, no background fill.
+ *
+ * Unlike `drawBox`, the inside area is left untouched.
+ * Useful for selection highlights, overlays, and ZX-style panels
+ * where the background is already painted.
+ *
+ * @example
+ * drawFrame(ctx, { x: 0, y: 0, width: 256, height: 176, color: C.B_CYAN })
+ * drawFrame(ctx, { x: 16, y: 16, width: 64, height: 32, color: C.B_RED,
+ *   border: { style: 'dashed', thickness: 1 } })
+ */
+export declare function drawFrame(ctx: CanvasRenderingContext2D, options: {
+    /** Left edge in game pixels */
+    x: number;
+    /** Top edge in game pixels */
+    y: number;
+    /** Width in game pixels */
+    width: number;
+    /** Height in game pixels */
+    height: number;
+    /** Frame color */
+    color: SpectrumColor;
+    /** Border configuration — `color` here overrides the top-level `color` */
+    border?: BorderOptions;
+}): void;
+/**
+ * Draws a ZX-style panel title — a text strip with an optional background fill.
+ *
+ * Does NOT draw the surrounding container (`drawBox` / `drawFrame` are separate).
+ * The strip height is always `CELL + padding * 2` pixels.
+ *
+ * @example
+ * // Labelled panel:
+ * drawBox(ctx,   { x: 8, y: 24, width: 128, height: 56, paper: C.BLACK })
+ * drawPanelTitle(ctx, { text: 'OPTIONS', x: 8, y: 24, ink: C.B_YELLOW,
+ *   paper: C.BLACK, centered: true, width: 128 })
+ *
+ * // No background — ink only:
+ * drawPanelTitle(ctx, { text: 'DEBUG', x: 0, y: 0, ink: C.B_CYAN })
+ */
+export declare function drawPanelTitle(ctx: CanvasRenderingContext2D, options: {
+    /** Title text (ASCII — rendered via ZX ROM font) */
+    text: string;
+    /** Left edge in game pixels */
+    x: number;
+    /** Top edge of the title strip in game pixels */
+    y: number;
+    /** Text color */
+    ink: SpectrumColor;
+    /** Background behind the title strip. Omit for transparent (ink-only rendering) */
+    paper?: SpectrumColor;
+    /** Padding inside the strip in pixels. Default: `2` */
+    padding?: number;
+    /**
+     * Center the title horizontally within `width`.
+     * Requires `width` to be provided; ignored otherwise.
+     */
+    centered?: boolean;
+    /** Width used for centering (game pixels). Required when `centered: true`. */
+    width?: number;
+}): void;
+/**
+ * Draws a ZX-style progress / value bar and registers it for managed redraws.
+ *
+ * The bar is drawn **immediately** on every call. Additionally, the options are
+ * stored internally so `renderUI` can repaint the bar each frame for
+ * `visibilityLength` ms without requiring the caller to supply the state again.
+ *
+ * Calling `drawProgressBar` again with the same `id` **resets the timer** — use
+ * this to refresh the display when the value changes.
+ *
+ * **Typical pattern:**
+ * ```ts
+ * // On value change only:
+ * if (consumeVolUp()) {
+ *   increaseVolume()
+ *   drawProgressBar(ctx, { id: 'volume', x: 88, y: 88, width: 80,
+ *     value: getMasterVolume(), visibilityLength: 1500 })
+ * }
+ *
+ * // Every frame (after game world render):
+ * tickUI(dt)
+ * renderUI(ctx)
+ * ```
+ *
+ * @example
+ * // Permanent HUD health bar:
+ * drawProgressBar(ctx, {
+ *   id: 'health', x: 0, y: 184, width: 40, value: lives, min: 0, max: 3,
+ *   ink: C.B_GREEN, paper: C.BLACK, visibilityLength: 0,
+ * })
+ *
+ * // Temporary volume indicator (auto-hides after 1.5 s):
+ * drawProgressBar(ctx, {
+ *   id: 'volume', x: 88, y: 88, width: 80, value: getMasterVolume(),
+ *   ink: C.B_GREEN, paper: C.BLACK,
+ *   border: { style: 'solid' },
+ *   visibilityLength: 1500,
+ * })
+ */
+export declare function drawProgressBar(ctx: CanvasRenderingContext2D, options: DrawProgressBarOptions): void;
+/**
+ * Advances all managed bar timers by `dtMs` milliseconds.
+ * Bars whose timer reaches zero are removed and will no longer appear in `renderUI`.
+ * Call once per frame, typically just before `renderUI`.
+ *
+ * @param dtMs - Frame delta in milliseconds
+ *
+ * @example
+ * // End of game loop:
+ * tickUI(dt)
+ * renderUI(ctx)
+ */
+export declare function tickUI(dtMs: number): void;
+/**
+ * Redraws all currently visible managed bars (timer > 0 or permanent).
+ * Call every frame **after** the game world has been rendered so bars appear on top.
+ *
+ * @param ctx - Canvas 2D rendering context
+ *
+ * @example
+ * renderFrame(ctx, state)
+ * tickUI(dt)
+ * renderUI(ctx)
+ */
+export declare function renderUI(ctx: CanvasRenderingContext2D): void;
+/**
+ * Clears all managed UI state — removes every active bar timer and its stored options.
+ * Call alongside `resetInput()` when transitioning between major game phases.
+ *
+ * @example
+ * resetInput()
+ * resetUI()
+ * appPhase = 'intro'
+ */
+export declare function resetUI(): void;
+//# sourceMappingURL=ui.d.ts.map

package/dist/ui.d.ts.map

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

package/dist/ui.js

@@ -0,0 +1,210 @@
+import { C, CELL } from './palette.js';
+import { drawChar, drawText } from './renderer.js';
+const _bars = new Map();
+// ─── Private helpers ──────────────────────────────────────────────────────────
+function _drawBorder(ctx, x, y, width, height, border, fallbackColor) {
+    if (border.enabled === false)
+        return;
+    const color = border.color ?? fallbackColor;
+    const t = border.thickness ?? 1;
+    ctx.fillStyle = color;
+    if (border.style !== 'dashed') {
+        ctx.fillRect(x, y, width, t); // top
+        ctx.fillRect(x, y + height - t, width, t); // bottom
+        ctx.fillRect(x, y, t, height); // left
+        ctx.fillRect(x + width - t, y, t, height); // right
+    }
+    else {
+        const d = 2; // dash length in pixels
+        for (let i = 0; i < width; i += d * 2) {
+            ctx.fillRect(x + i, y, Math.min(d, width - i), t); // top
+            ctx.fillRect(x + i, y + height - t, Math.min(d, width - i), t); // bottom
+        }
+        for (let i = 0; i < height; i += d * 2) {
+            ctx.fillRect(x, y + i, t, Math.min(d, height - i)); // left
+            ctx.fillRect(x + width - t, y + i, t, Math.min(d, height - i)); // right
+        }
+    }
+}
+function _renderBar(ctx, o) {
+    const min = o.min ?? 0;
+    const max = o.max ?? 1;
+    const ink = o.ink ?? C.B_WHITE;
+    const paper = o.paper ?? C.BLACK;
+    const chars = Math.floor(o.width / CELL);
+    const ratio = Math.max(0, Math.min(1, (o.value - min) / (max - min)));
+    const filled = Math.round(ratio * chars);
+    ctx.fillStyle = paper;
+    ctx.fillRect(o.x, o.y, chars * CELL, CELL);
+    for (let i = 0; i < filled; i++) {
+        drawChar(ctx, 127, o.x + i * CELL, o.y, ink, paper); // 127 = solid block █
+    }
+    if (o.border)
+        _drawBorder(ctx, o.x, o.y, chars * CELL, CELL, o.border, ink);
+}
+// ─── Public API — stateless primitives ───────────────────────────────────────
+/**
+ * Draws a filled rectangular box using ZX-style rendering.
+ *
+ * Renders a solid background (`paper`) and an optional border.
+ * Coordinates are in game pixels (already scaled by `setupCanvas`).
+ * Does NOT render text — use `drawPanelTitle` for labelled panels.
+ *
+ * @example
+ * drawBox(ctx, {
+ *   x: 8, y: 8, width: 112, height: 40,
+ *   paper: C.BLACK, ink: C.B_WHITE,
+ *   border: { style: 'solid', thickness: 1 },
+ * })
+ */
+export function drawBox(ctx, options) {
+    const { x, y, width, height, paper, ink, border } = options;
+    ctx.fillStyle = paper;
+    ctx.fillRect(x, y, width, height);
+    if (border)
+        _drawBorder(ctx, x, y, width, height, border, ink ?? paper);
+}
+/**
+ * Draws a rectangular frame — border only, no background fill.
+ *
+ * Unlike `drawBox`, the inside area is left untouched.
+ * Useful for selection highlights, overlays, and ZX-style panels
+ * where the background is already painted.
+ *
+ * @example
+ * drawFrame(ctx, { x: 0, y: 0, width: 256, height: 176, color: C.B_CYAN })
+ * drawFrame(ctx, { x: 16, y: 16, width: 64, height: 32, color: C.B_RED,
+ *   border: { style: 'dashed', thickness: 1 } })
+ */
+export function drawFrame(ctx, options) {
+    const { x, y, width, height, color, border = {} } = options;
+    _drawBorder(ctx, x, y, width, height, { ...border, color }, color);
+}
+/**
+ * Draws a ZX-style panel title — a text strip with an optional background fill.
+ *
+ * Does NOT draw the surrounding container (`drawBox` / `drawFrame` are separate).
+ * The strip height is always `CELL + padding * 2` pixels.
+ *
+ * @example
+ * // Labelled panel:
+ * drawBox(ctx,   { x: 8, y: 24, width: 128, height: 56, paper: C.BLACK })
+ * drawPanelTitle(ctx, { text: 'OPTIONS', x: 8, y: 24, ink: C.B_YELLOW,
+ *   paper: C.BLACK, centered: true, width: 128 })
+ *
+ * // No background — ink only:
+ * drawPanelTitle(ctx, { text: 'DEBUG', x: 0, y: 0, ink: C.B_CYAN })
+ */
+export function drawPanelTitle(ctx, options) {
+    const { text, x, y, ink, paper, padding = 2, centered, width } = options;
+    const textW = text.length * CELL;
+    const stripW = centered && width !== undefined ? width : textW + padding * 2;
+    if (paper !== undefined) {
+        ctx.fillStyle = paper;
+        ctx.fillRect(x, y, stripW, CELL + padding * 2);
+    }
+    const tx = centered && width !== undefined
+        ? x + Math.floor((width - textW) / 2)
+        : x + padding;
+    drawText(ctx, text, tx, y + padding, ink, paper);
+}
+// ─── Public API — stateful widget ────────────────────────────────────────────
+/**
+ * Draws a ZX-style progress / value bar and registers it for managed redraws.
+ *
+ * The bar is drawn **immediately** on every call. Additionally, the options are
+ * stored internally so `renderUI` can repaint the bar each frame for
+ * `visibilityLength` ms without requiring the caller to supply the state again.
+ *
+ * Calling `drawProgressBar` again with the same `id` **resets the timer** — use
+ * this to refresh the display when the value changes.
+ *
+ * **Typical pattern:**
+ * ```ts
+ * // On value change only:
+ * if (consumeVolUp()) {
+ *   increaseVolume()
+ *   drawProgressBar(ctx, { id: 'volume', x: 88, y: 88, width: 80,
+ *     value: getMasterVolume(), visibilityLength: 1500 })
+ * }
+ *
+ * // Every frame (after game world render):
+ * tickUI(dt)
+ * renderUI(ctx)
+ * ```
+ *
+ * @example
+ * // Permanent HUD health bar:
+ * drawProgressBar(ctx, {
+ *   id: 'health', x: 0, y: 184, width: 40, value: lives, min: 0, max: 3,
+ *   ink: C.B_GREEN, paper: C.BLACK, visibilityLength: 0,
+ * })
+ *
+ * // Temporary volume indicator (auto-hides after 1.5 s):
+ * drawProgressBar(ctx, {
+ *   id: 'volume', x: 88, y: 88, width: 80, value: getMasterVolume(),
+ *   ink: C.B_GREEN, paper: C.BLACK,
+ *   border: { style: 'solid' },
+ *   visibilityLength: 1500,
+ * })
+ */
+export function drawProgressBar(ctx, options) {
+    _renderBar(ctx, options);
+    const id = options.id ?? `${options.x},${options.y}`;
+    const visibilityLength = options.visibilityLength ?? 500;
+    _bars.set(id, {
+        options,
+        timer: visibilityLength,
+        permanent: visibilityLength === 0,
+    });
+}
+/**
+ * Advances all managed bar timers by `dtMs` milliseconds.
+ * Bars whose timer reaches zero are removed and will no longer appear in `renderUI`.
+ * Call once per frame, typically just before `renderUI`.
+ *
+ * @param dtMs - Frame delta in milliseconds
+ *
+ * @example
+ * // End of game loop:
+ * tickUI(dt)
+ * renderUI(ctx)
+ */
+export function tickUI(dtMs) {
+    for (const [id, bar] of _bars) {
+        if (bar.permanent)
+            continue;
+        bar.timer -= dtMs;
+        if (bar.timer <= 0)
+            _bars.delete(id);
+    }
+}
+/**
+ * Redraws all currently visible managed bars (timer > 0 or permanent).
+ * Call every frame **after** the game world has been rendered so bars appear on top.
+ *
+ * @param ctx - Canvas 2D rendering context
+ *
+ * @example
+ * renderFrame(ctx, state)
+ * tickUI(dt)
+ * renderUI(ctx)
+ */
+export function renderUI(ctx) {
+    for (const bar of _bars.values()) {
+        _renderBar(ctx, bar.options);
+    }
+}
+/**
+ * Clears all managed UI state — removes every active bar timer and its stored options.
+ * Call alongside `resetInput()` when transitioning between major game phases.
+ *
+ * @example
+ * resetInput()
+ * resetUI()
+ * appPhase = 'intro'
+ */
+export function resetUI() {
+    _bars.clear();
+}
+//# sourceMappingURL=ui.js.map

package/dist/ui.js.map

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "zx-kit",
-  "version": "0.3.0",
-  "description": "Reusable ZX Spectrum primitives: font, palette, renderer, audio, input",
+  "version": "0.5.0",
+  "description": "Reusable ZX Spectrum primitives: font, palette, renderer, audio, input, ui, tilemap",
   "type": "module",
   "exports": {
     ".": {
@@ -18,7 +18,8 @@
   ],
   "scripts": {
     "build": "tsc",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "test": "vitest run"
   },
   "keywords": [
     "zx-spectrum",
@@ -28,6 +29,8 @@
   ],
   "license": "MIT",
   "devDependencies": {
-    "typescript": "^6.0.3"
+    "jsdom": "^29.1.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
   }
 }