zx-kit 0.28.0 → 0.29.0

package/README.md

@@ -3,7 +3,7 @@
 > **A Speccy-flavoured fantasy toolkit for tiny TypeScript browser games.**
 > Inspired by the ZX Spectrum — not an emulator, not a hardware clone.
 
-Spectrum-palette canvas rendering. ROM bitmap font. AY-3-8912 three-channel audio. Beeper SFX. Tile maps. Free-roaming sprites. Collision detection. Saves. Camera. Scene manager. Particle pool. Dithered lighting. Zero dependencies. TypeScript-first.
+Spectrum-palette canvas rendering. ROM bitmap font. AY-3-8912 three-channel audio. Beeper SFX. Tile maps. Free-roaming sprites. Collision detection. Saves. Camera. Scene manager. Particle pool. Dithered lighting. Offscreen layer cache. Zero dependencies. TypeScript-first.
 
 [![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)
@@ -27,6 +27,7 @@ zx-kit captures that aesthetic in TypeScript. You get the Spectrum's palette, RO
 - **Authentic 15-color palette** — normal and bright variants, palette-enforced at compile time via the `SpectrumColor` type
 - **Canvas renderer** — pixel-perfect scaled rendering, sprite flipping, text drawing, CRT scanline overlay, animated border flashing
 - **Tile map engine** — scrollable maps, O(1) id-index, smart seasonal background swapping, solid-tile collision queries
+- **Offscreen layer cache** — render a static or rarely-changing layer (tile map, CRT overlay) once to an offscreen canvas and blit it each frame; `dirty`-flag invalidation turns thousands of per-pixel `fillRect`s into a single `drawImage`
 - **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 and gamepad input** — configurable key-repeat, transparent gamepad polling, single-consume action flags, instant state reset on phase transitions
@@ -589,6 +590,7 @@ requestAnimationFrame(loop)
 | [`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) |
+| [`cache.ts`](#cachets--offscreen-layer-cache) | Offscreen layer cache: render a static layer once, blit each frame, `dirty`-flag invalidation |
 | [`music.ts`](#musicts--note-name-ay-music) | Write AY music by note name (`A5`, `C#4`) and loop it for background tracks |
 
 ---
@@ -2740,6 +2742,56 @@ track.stop()
 
 ---
 
+## `cache.ts` — Offscreen Layer Cache
+
+`drawBitmap`, `drawSprite` and `drawTileMapAt` paint **one `fillRect` per lit
+pixel** — perfect for a moving sprite, but lethal for a full-screen layer redrawn
+every frame (a scrolling tile map can be thousands of `fillRect`s per frame). The
+cure is to render that layer **once** to an offscreen canvas, then blit it with a
+single `drawImage`.
+
+A `LayerCache` is an offscreen canvas plus a `dirty` flag. `refreshLayer` re-runs
+your draw callback **only while the cache is dirty**, then clears the flag; call
+`invalidateLayer` whenever the layer's contents change (a tile edited, a level
+reset) to force exactly one re-render. Headless-safe: with no `document` the
+canvas is `null`, the draw is skipped, and nothing throws.
+
+### `createLayerCache(width, height): LayerCache`
+
+Creates an offscreen cache of the given pixel size, starting `dirty`. Image
+smoothing is disabled for crisp ZX output. Create once; reuse across frames.
+Throws if `width`/`height` is not a positive number.
+
+### `invalidateLayer(layer): void`
+
+Marks the cache stale so the next `refreshLayer` re-renders it.
+
+### `refreshLayer(layer, render): HTMLCanvasElement | null`
+
+Runs `render(offscreenCtx)` only if the cache is dirty (the context is cleared
+first), then clears the flag and returns the offscreen canvas to blit (or `null`
+when headless). Blitting is yours: a `drawImage` source window for a scrolling
+camera, or `drawImage(canvas, 0, 0)` for a static overlay.
+
+```ts
+// Cache a whole tile map; blit a moving camera window each frame.
+const world = tileMapWorldSize(map)
+const tiles = createLayerCache(world.width, world.height)   // once
+
+// game loop:
+refreshLayer(tiles, (lctx) => drawTileMapAt(lctx, map, 0, 0, world.width, world.height))
+if (tiles.canvas) ctx.drawImage(tiles.canvas, camX, camY, 256, 192, 0, 0, 256, 192)
+
+// when a tile changes (a platform crumbles, the level resets):
+invalidateLayer(tiles)
+```
+
+> Pairs naturally with `tilescroll` / `tilemap`: cache the static geometry and
+> invalidate only on the rare tile change. The same primitive caches any static
+> overlay — e.g. `refreshLayer(overlay, (c) => drawScanlines(c))`.
+
+---
+
 ## Architecture
 
 ### Module structure

package/dist/cache.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @module cache
+ *
+ * **Offscreen layer cache** — render a static (or rarely-changing) layer to an
+ * offscreen canvas **once**, then blit it every frame with a single `drawImage`
+ * instead of re-rasterising it. This is the antidote to the per-pixel `fillRect`
+ * cost of {@link "renderer" | drawBitmap} / {@link "tilescroll" | drawTileMapAt}
+ * when they are used for a full-screen layer on every frame.
+ *
+ * The cache is **dirty-driven**: {@link refreshLayer} re-runs your draw callback
+ * only while the cache is `dirty`, then clears the flag. Call
+ * {@link invalidateLayer} whenever the layer's contents change (a tile edited, a
+ * palette swap, a level reset) to force exactly one re-render next frame.
+ *
+ * Headless-safe: with no `document` (Node / SSR / tests) the canvas is `null`,
+ * `refreshLayer` skips the draw and returns `null`, and nothing throws — mirrors
+ * the {@link "lighting" | lighting} module's degrade-gracefully behaviour.
+ *
+ * @example Cache a whole tile map, blit a moving camera window each frame
+ * ```ts
+ * const world = tileMapWorldSize(map)
+ * const tiles = createLayerCache(world.width, world.height)   // once
+ * // game loop:
+ * refreshLayer(tiles, (lctx) => drawTileMapAt(lctx, map, 0, 0, world.width, world.height))
+ * if (tiles.canvas) ctx.drawImage(tiles.canvas, camX, camY, viewW, viewH, 0, 0, viewW, viewH)
+ * // when a tile changes (e.g. a platform crumbles or the level resets):
+ * invalidateLayer(tiles)
+ * ```
+ *
+ * @example Cache a static overlay — drawn once, blitted forever
+ * ```ts
+ * const overlay = createLayerCache(canvas.width, canvas.height)
+ * refreshLayer(overlay, (lctx) => drawScanlines(lctx))
+ * if (overlay.canvas) ctx.drawImage(overlay.canvas, 0, 0)
+ * ```
+ */
+/** An offscreen canvas plus a dirty flag. `canvas` is `null` when headless. */
+export interface LayerCache {
+    /** Width of the cached layer in pixels. */
+    readonly width: number;
+    /** Height of the cached layer in pixels. */
+    readonly height: number;
+    /** The offscreen canvas to blit, or `null` with no `document` (headless). */
+    readonly canvas: HTMLCanvasElement | null;
+    /** When `true`, the next {@link refreshLayer} re-runs the draw callback. */
+    dirty: boolean;
+}
+/**
+ * Creates an offscreen layer cache of the given pixel size. Starts `dirty`, so
+ * the first {@link refreshLayer} renders it. Image smoothing is disabled on the
+ * offscreen context for crisp ZX output. Create once and reuse across frames.
+ *
+ * @throws if `width` or `height` is not a positive finite number.
+ */
+export declare function createLayerCache(width: number, height: number): LayerCache;
+/** Marks the cache stale so the next {@link refreshLayer} re-renders it. */
+export declare function invalidateLayer(layer: LayerCache): void;
+/**
+ * Re-renders the cache via `render` **only if it is dirty**, then clears the
+ * dirty flag. `render` receives the offscreen 2D context (already cleared) and
+ * should draw the whole layer in layer-local coordinates (top-left = `0,0`).
+ * Returns the offscreen canvas to blit (or `null` when headless).
+ *
+ * Blitting is the caller's job: use a `drawImage` source window for a scrolling
+ * camera, or `drawImage(canvas, 0, 0)` for a static overlay.
+ */
+export declare function refreshLayer(layer: LayerCache, render: (ctx: CanvasRenderingContext2D) => void): HTMLCanvasElement | null;
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,+EAA+E;AAC/E,MAAM,WAAW,UAAU;IACzB,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,4CAA4C;IAC5C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAA;IACzC,4EAA4E;IAC5E,KAAK,EAAE,OAAO,CAAA;CACf;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU,CAa1E;AAED,4EAA4E;AAC5E,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAEvD;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,CAAC,GAAG,EAAE,wBAAwB,KAAK,IAAI,GAC9C,iBAAiB,GAAG,IAAI,CAW1B"}

package/dist/cache.js

@@ -0,0 +1,84 @@
+/**
+ * @module cache
+ *
+ * **Offscreen layer cache** — render a static (or rarely-changing) layer to an
+ * offscreen canvas **once**, then blit it every frame with a single `drawImage`
+ * instead of re-rasterising it. This is the antidote to the per-pixel `fillRect`
+ * cost of {@link "renderer" | drawBitmap} / {@link "tilescroll" | drawTileMapAt}
+ * when they are used for a full-screen layer on every frame.
+ *
+ * The cache is **dirty-driven**: {@link refreshLayer} re-runs your draw callback
+ * only while the cache is `dirty`, then clears the flag. Call
+ * {@link invalidateLayer} whenever the layer's contents change (a tile edited, a
+ * palette swap, a level reset) to force exactly one re-render next frame.
+ *
+ * Headless-safe: with no `document` (Node / SSR / tests) the canvas is `null`,
+ * `refreshLayer` skips the draw and returns `null`, and nothing throws — mirrors
+ * the {@link "lighting" | lighting} module's degrade-gracefully behaviour.
+ *
+ * @example Cache a whole tile map, blit a moving camera window each frame
+ * ```ts
+ * const world = tileMapWorldSize(map)
+ * const tiles = createLayerCache(world.width, world.height)   // once
+ * // game loop:
+ * refreshLayer(tiles, (lctx) => drawTileMapAt(lctx, map, 0, 0, world.width, world.height))
+ * if (tiles.canvas) ctx.drawImage(tiles.canvas, camX, camY, viewW, viewH, 0, 0, viewW, viewH)
+ * // when a tile changes (e.g. a platform crumbles or the level resets):
+ * invalidateLayer(tiles)
+ * ```
+ *
+ * @example Cache a static overlay — drawn once, blitted forever
+ * ```ts
+ * const overlay = createLayerCache(canvas.width, canvas.height)
+ * refreshLayer(overlay, (lctx) => drawScanlines(lctx))
+ * if (overlay.canvas) ctx.drawImage(overlay.canvas, 0, 0)
+ * ```
+ */
+/**
+ * Creates an offscreen layer cache of the given pixel size. Starts `dirty`, so
+ * the first {@link refreshLayer} renders it. Image smoothing is disabled on the
+ * offscreen context for crisp ZX output. Create once and reuse across frames.
+ *
+ * @throws if `width` or `height` is not a positive finite number.
+ */
+export function createLayerCache(width, height) {
+    if (!Number.isFinite(width) || width <= 0 || !Number.isFinite(height) || height <= 0) {
+        throw new Error(`createLayerCache: width and height must be positive, got ${width}×${height}`);
+    }
+    let canvas = null;
+    if (typeof document !== 'undefined') {
+        canvas = document.createElement('canvas');
+        canvas.width = width;
+        canvas.height = height;
+        const ctx = canvas.getContext('2d');
+        if (ctx)
+            ctx.imageSmoothingEnabled = false;
+    }
+    return { width, height, canvas, dirty: true };
+}
+/** Marks the cache stale so the next {@link refreshLayer} re-renders it. */
+export function invalidateLayer(layer) {
+    layer.dirty = true;
+}
+/**
+ * Re-renders the cache via `render` **only if it is dirty**, then clears the
+ * dirty flag. `render` receives the offscreen 2D context (already cleared) and
+ * should draw the whole layer in layer-local coordinates (top-left = `0,0`).
+ * Returns the offscreen canvas to blit (or `null` when headless).
+ *
+ * Blitting is the caller's job: use a `drawImage` source window for a scrolling
+ * camera, or `drawImage(canvas, 0, 0)` for a static overlay.
+ */
+export function refreshLayer(layer, render) {
+    if (layer.dirty) {
+        layer.dirty = false;
+        const ctx = layer.canvas ? layer.canvas.getContext('2d') : null;
+        if (ctx) {
+            ctx.clearRect(0, 0, layer.width, layer.height);
+            ctx.imageSmoothingEnabled = false;
+            render(ctx);
+        }
+    }
+    return layer.canvas;
+}
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAcH;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAa,EAAE,MAAc;IAC5D,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,CAAC,EAAE,CAAC;QACrF,MAAM,IAAI,KAAK,CAAC,4DAA4D,KAAK,IAAI,MAAM,EAAE,CAAC,CAAA;IAChG,CAAC;IACD,IAAI,MAAM,GAA6B,IAAI,CAAA;IAC3C,IAAI,OAAO,QAAQ,KAAK,WAAW,EAAE,CAAC;QACpC,MAAM,GAAG,QAAQ,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAA;QACzC,MAAM,CAAC,KAAK,GAAG,KAAK,CAAA;QACpB,MAAM,CAAC,MAAM,GAAG,MAAM,CAAA;QACtB,MAAM,GAAG,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,CAAA;QACnC,IAAI,GAAG;YAAE,GAAG,CAAC,qBAAqB,GAAG,KAAK,CAAA;IAC5C,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;AAC/C,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,eAAe,CAAC,KAAiB;IAC/C,KAAK,CAAC,KAAK,GAAG,IAAI,CAAA;AACpB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAC1B,KAAiB,EACjB,MAA+C;IAE/C,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;QAChB,KAAK,CAAC,KAAK,GAAG,KAAK,CAAA;QACnB,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;QAC/D,IAAI,GAAG,EAAE,CAAC;YACR,GAAG,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;YAC9C,GAAG,CAAC,qBAAqB,GAAG,KAAK,CAAA;YACjC,MAAM,CAAC,GAAG,CAAC,CAAA;QACb,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC,MAAM,CAAA;AACrB,CAAC"}

package/dist/index.d.ts

@@ -17,5 +17,6 @@ export * from './scene.js';
 export * from './save.js';
 export * from './i18n.js';
 export * from './lighting.js';
+export * from './cache.js';
 export * from './music.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;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,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;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA"}

package/dist/index.js

@@ -17,5 +17,6 @@ export * from './scene.js';
 export * from './save.js';
 export * from './i18n.js';
 export * from './lighting.js';
+export * from './cache.js';
 export * from './music.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;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,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;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA"}

package/package.json

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