zx-kit 0.4.0 → 0.5.1

package/README.md

@@ -2,6 +2,8 @@
 
 Reusable ZX Spectrum primitives for browser games built with Vite + TypeScript + Canvas + Web Audio API.
 
+Current npm package: `zx-kit@0.5.1`.
+
 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.
 
 ---
@@ -469,6 +471,195 @@ appPhase = 'intro'
 
 ---
 
+### `tilemap.ts` — Scrollable tile map
+
+A scrollable, queryable `TileMap` backed by an O(1) id-index. Tiles use the same 8×8 sprite format as `drawSprite`. Supports seasonal background swapping, viewport-clipped rendering, collision queries, and fast id-based lookups.
+Tile colours are palette-typed: `ink` and `paper` must be `SpectrumColor` values from `C`.
+
+#### Types
+
+**`Tile`**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `sprite` | `Uint8Array` | 8-byte bitmap — same format as `drawSprite()` |
+| `ink` | `SpectrumColor` | Foreground colour (`C.*` palette value) |
+| `paper` | `SpectrumColor` | Background colour (`C.*` palette value) |
+| `solid` | `boolean` | `true` = blocks movement (walls, rocks, closed doors) |
+| `id` | `string \| number` | Stable identifier for game logic and background swapping |
+| `metadata?` | `Record<string, unknown>` | Optional game-specific payload (points, next level, …) |
+
+**`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
 
 ```
@@ -488,9 +679,10 @@ zx-kit/
 │   │                    # increaseVolume, decreaseVolume
 │   ├── input.ts         # initInput, tickMovement, consumeFlag/Debug/Pause/AnyKey,
 │   │                    # isHeld, resetInput, Direction
-│   └── ui.ts            # drawBox, drawFrame, drawPanelTitle,
-│                        # drawProgressBar, tickUI, renderUI, resetUI,
-│                        # BorderOptions, DrawProgressBarOptions
+│   ├── 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
     └── ...
@@ -503,6 +695,7 @@ zx-kit/
 - **Compiled distribution** — ships compiled JS + `.d.ts` in `dist/`. No bundler configuration needed in the consuming project.
 - **No runtime dependencies** — only Web platform APIs (`CanvasRenderingContext2D`, `AudioContext`, `KeyboardEvent`).
 - **Strict TypeScript** — `strict: true`, `noUnusedLocals`, `noUnusedParameters`. No `any`.
+- **Palette-typed game data** — UI colours and tile `ink` / `paper` use `SpectrumColor`, so consumers stay inside the Spectrum palette at compile time.
 - **Singleton state** — `audio.ts` and `input.ts` hold module-level state. Suitable for single-game use; not suitable for multiple independent game instances on the same page.
 - **ZX Spectrum authenticity** — palette values, cell size, and font bytes are constants, not configuration. The library is deliberately opinionated.
 

package/dist/index.d.ts

@@ -4,4 +4,5 @@ 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;AAC1B,cAAc,SAAS,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

@@ -4,4 +4,5 @@ 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;AAC1B,cAAc,SAAS,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,134 @@
+import { type SpectrumColor } from './palette.js';
+/**
+ * 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: SpectrumColor;
+    /** Background colour — a `C.*` palette value. */
+    paper: SpectrumColor;
+    /** 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":"AAAA,OAAO,EAAQ,KAAK,aAAa,EAAE,MAAM,cAAc,CAAA;AAGvD;;;GAGG;AACH,MAAM,WAAW,IAAI;IACnB,uEAAuE;IACvE,MAAM,EAAE,UAAU,CAAA;IAClB,iDAAiD;IACjD,GAAG,EAAE,aAAa,CAAA;IAClB,iDAAiD;IACjD,KAAK,EAAE,aAAa,CAAA;IACpB,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":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "zx-kit",
-  "version": "0.4.0",
-  "description": "Reusable ZX Spectrum primitives: font, palette, renderer, audio, input, ui",
+  "version": "0.5.1",
+  "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"
   }
 }