zx-kit 0.29.0 → 0.31.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. Offscreen layer cache. 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. Authentic attribute clash. Monochrome playfield. 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)
@@ -28,6 +28,8 @@ zx-kit captures that aesthetic in TypeScript. You get the Spectrum's palette, RO
 - **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`
+- **Authentic attribute clash (opt-in)** — a 32×24 cell ink/paper screen that reproduces the real Spectrum colour bleed when a sprite and the background share an 8×8 cell; resolved to one `putImageData`/frame. Off by default, on when you want it
+- **Monochrome playfield (opt-in)** — the classic anti-clash trick: render the action area in a single ink + paper at its own size, keep the colour in the HUD around it. Everything inside becomes a clean two-colour silhouette — no clash, ever
 - **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
@@ -591,6 +593,8 @@ requestAnimationFrame(loop)
 | [`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 |
+| [`attrscreen.ts`](#attrscreents--attribute-clash-opt-in) | Opt-in authentic ZX colour clash: 1-bit pixels + 32×24 per-cell ink/paper, one `putImageData`/frame |
+| [`monoscreen.ts`](#monoscreents--monochrome-playfield) | Opt-in monochrome playfield (own size): 1-bit mask + one ink/paper, blitted at an offset — clash-proof |
 | [`music.ts`](#musicts--note-name-ay-music) | Write AY music by note name (`A5`, `C#4`) and loop it for background tracks |
 
 ---
@@ -2792,6 +2796,123 @@ invalidateLayer(tiles)
 
 ---
 
+## `attrscreen.ts` — Attribute Clash (opt-in)
+
+The real Spectrum stored the screen as **two planes**: a 1-bit pixel bitmap and a
+32×24 grid where each 8×8 cell holds exactly *one* ink + *one* paper. Drawing into a
+cell rewrote that single attribute, so the sprite and the background sharing the
+cell snapped to the same two colours — the famous **colour clash**.
+
+zx-kit composites in full colour by default (no clash — see *Spectrum-inspired, not
+hardware-accurate*). `attrscreen.ts` is the opt-in way to get the authentic bleed,
+the same shape as `drawScanlines` / `renderDarkness`: route a frame through an
+`AttrScreen`, then `flushAttrScreen` once.
+
+`stampMono` writes a monochrome bitmap's *shape* into the pixel plane and
+re-attributes every cell a lit pixel lands in — and it **never clears** other
+pixels, so whatever was already in a touched cell renders in the new colour. That
+is the clash. The flush resolves both planes into one reused `ImageData` and uploads
+it with a single `putImageData` + `drawImage` — never per-pixel `fillRect`.
+
+> Not hardware-exact by choice: ink and paper may be any two of the 15 colours (the
+> real machine forced both to share the BRIGHT bit), and FLASH is not modelled (yet).
+> Assumes a little-endian platform (every browser). Headless-safe.
+
+### `createAttrScreen(cols = 32, rows = 24): AttrScreen`
+
+Allocates a screen-space attribute plane (default 32×24 cells = 256×192). Create
+once; reuse across frames. Throws on a non-positive size.
+
+### `clearAttrScreen(scr, paper, ink?)`
+
+Resets for a new frame: clears all pixels to paper and fills every cell's
+attributes (`ink` defaults to `paper`). Call before stamping.
+
+### `stampMono(scr, bitmap, x, y, ink, paper, policy?)`
+
+Stamps a monochrome `Bitmap` at screen pixel `(x, y)` (rounded; may be sub-cell,
+negative, or off-screen — clipped). `policy` controls how touched cells recolour:
+`'both'` (default — ink **and** paper, the most authentic bleed), `'ink-only'`
+(keep the existing paper), `'paper-only'`.
+
+### `flushAttrScreen(ctx, scr)`
+
+Resolves the two planes into RGBA and uploads with one `putImageData` + `drawImage`
+at `(0, 0)` under the current transform (so `setupCanvas`'s `×scale` fills the
+canvas). Headless: fills `scr.rgba` and skips the blit.
+
+```ts
+const scr = createAttrScreen()                              // once
+// each frame, in screen space:
+clearAttrScreen(scr, C.BLACK)
+stampMono(scr, caveBitmap,   0,  0, C.B_BLUE,  C.BLACK)     // background
+stampMono(scr, rabbitBitmap, rx, ry, C.B_WHITE, C.BLACK)    // sprite → its cells clash to white
+flushAttrScreen(ctx, scr)
+```
+
+> A cell clashes only when a lit pixel lands in it (silhouette clash), so a sprite
+> recolours exactly the cells it visibly occupies.
+
+---
+
+## `monoscreen.ts` — Monochrome Playfield
+
+The surest cure for attribute clash is to not have it: render the action area in a
+**single ink + paper** and keep the colour in a separate HUD/border. Light Force,
+Bobby Bearing, Highway Encounter and Head Over Heels all did exactly this.
+
+A `MonoScreen` is a **1-bit foreground mask of its own size** (smaller than the
+canvas) plus two colours. Everything drawn into it collapses to ink (lit pixels)
+or paper — a white sprite, a green tile and a cyan hero all become the same ink, so
+they can never clash. Draw the colourful HUD normally *outside* the region;
+`flushMonoScreen` blits the playfield at an offset.
+
+Versus `attrscreen` (authentic *per-cell* clash): mono is one ink/paper for the
+**whole** region — simpler, cheaper, and the right tool for a clean retro look
+rather than the colour-bleed artefact. Flush is one `putImageData` + `drawImage`.
+Little-endian; headless-safe.
+
+### `createMonoScreen(width, height, ink, paper): MonoScreen`
+
+Creates a playfield of its own pixel size (not the canvas). `ink`/`paper` are
+mutable — recolour the whole playfield any time (e.g. per biome). Throws on a
+non-positive size.
+
+### `clearMonoScreen(scr)`
+
+Resets the mask to all-paper. Call at the start of each frame.
+
+### `drawMonoBitmap(scr, bitmap, x, y)`
+
+Draws a monochrome `Bitmap`'s lit pixels as foreground (clipped). Clear pixels are
+left untouched, so paper and earlier draws show through.
+
+### `fillMono(scr, x, y, w, h)`
+
+Sets a filled foreground rectangle (clipped) — a 1px-wide rect is a thread, rail or
+laser; a block is a platform.
+
+### `flushMonoScreen(ctx, scr, dx?, dy?)`
+
+Resolves the mask (ink where lit, paper elsewhere) and blits the region at canvas
+offset `(dx, dy)` under the current transform. Headless: fills `scr.rgba`, skips
+the blit.
+
+```ts
+const play = createMonoScreen(256, 160, C.BLACK, C.B_CYAN)   // playfield, once
+// each frame, in playfield space:
+clearMonoScreen(play)
+drawMonoBitmap(play, tileBmp, tx, ty)
+drawMonoBitmap(play, heroBmp, hx, hy)
+fillMono(play, threadX, threadY, 1, len)
+flushMonoScreen(ctx, play, 0, 16)            // playfield below a 16px colour HUD
+```
+
+> Tip: it carries its own `ink`/`paper`, so a one-line swap reskins the whole
+> playfield — a cheap "biome" tint or a damage flash.
+
+---
+
 ## Architecture
 
 ### Module structure

package/dist/attrscreen.d.ts

@@ -0,0 +1,96 @@
+/**
+ * @module attrscreen
+ *
+ * **Authentic ZX attribute clash — opt-in.** The real Spectrum stored the screen
+ * as two separate planes: a 1-bit **pixel** bitmap (256×192) and a 32×24
+ * **attribute** grid where each 8×8 cell holds exactly *one* ink + *one* paper.
+ * Drawing a sprite into a cell rewrote that cell's attribute, so everything in
+ * the cell — sprite *and* background — snapped to the same two colours. That bleed
+ * is the famous *colour clash*.
+ *
+ * zx-kit normally composites in full colour (no clash — by design, see the README).
+ * This module is the opt-in way to get the real thing, the same shape as the other
+ * effects ({@link "renderer" | drawScanlines}, {@link "lighting" | renderDarkness}):
+ * a game that wants clash routes its drawing through an {@link AttrScreen} and
+ * calls {@link flushAttrScreen} once per frame.
+ *
+ * **The dual plane:** {@link stampMono} writes a monochrome bitmap's *shape* into
+ * the pixel plane and re-attributes every cell it touches (per {@link AttrPolicy}).
+ * Crucially it does **not** clear other pixels — so a leaf already drawn in a cell
+ * keeps its pixels but now renders in the *new* cell colour. That is the clash.
+ *
+ * **Fast flush:** the two planes are resolved into one RGBA buffer and uploaded
+ * with a single `putImageData` + `drawImage` — never per-pixel `fillRect`. Assumes
+ * a little-endian platform (every browser; common Node).
+ *
+ * Headless-safe: with no `document` the offscreen canvas is `null`, the resolve
+ * still runs (so the logic is testable) and the blit is skipped — nothing throws.
+ *
+ * @example
+ * ```ts
+ * const scr = createAttrScreen()                       // 32×24 cells = 256×192, once
+ * // each frame, in screen space:
+ * clearAttrScreen(scr, C.BLACK)                        // blank paper
+ * stampMono(scr, caveBitmap,   0,  0, C.B_BLUE,  C.BLACK)   // background
+ * stampMono(scr, rabbitBitmap, rx, ry, C.B_WHITE, C.BLACK)  // sprite → its cells clash to white
+ * flushAttrScreen(ctx, scr)                            // one putImageData + drawImage
+ * ```
+ */
+import { type SpectrumColor } from './palette.js';
+import type { Bitmap } from './renderer.js';
+/**
+ * How a {@link stampMono} re-colours each cell it touches:
+ * - `'both'` — set ink **and** paper (last writer owns the whole cell — the most
+ *   authentic clash: the background paper changes too).
+ * - `'ink-only'` — set ink, keep the existing paper (gentler bleed).
+ * - `'paper-only'` — set paper, keep the existing ink.
+ */
+export type AttrPolicy = 'both' | 'ink-only' | 'paper-only';
+/** A screen-space dual plane: 1-bit pixels + per-cell ink/paper attributes. */
+export interface AttrScreen {
+    readonly cols: number;
+    readonly rows: number;
+    readonly width: number;
+    readonly height: number;
+    /** One byte per pixel — `1` = ink, `0` = paper. Row-major, `width*height`. */
+    readonly pixels: Uint8Array;
+    /** Packed RGBA (little-endian) ink colour per cell, `cols*rows`. */
+    readonly cellInk: Uint32Array;
+    /** Packed RGBA paper colour per cell, `cols*rows`. */
+    readonly cellPaper: Uint32Array;
+    /** Resolved RGBA frame buffer (`width*height*4`), filled by {@link flushAttrScreen}. */
+    readonly rgba: Uint8ClampedArray;
+    /** Reusable `ImageData` backing {@link rgba} (`null` when headless). */
+    readonly image: ImageData | null;
+    /** Offscreen canvas the resolved buffer is uploaded to (`null` when headless). */
+    readonly canvas: HTMLCanvasElement | null;
+}
+/**
+ * Creates a screen-space attribute plane of `cols`×`rows` 8×8 cells (default
+ * 32×24 = 256×192). Allocate once; reuse across frames. Throws on a non-positive
+ * size.
+ */
+export declare function createAttrScreen(cols?: number, rows?: number): AttrScreen;
+/**
+ * Resets the screen for a new frame: clears all pixels to paper and fills every
+ * cell's attributes. `ink` defaults to `paper`, so untouched cells are a flat
+ * paper colour. Call at the start of each frame, before stamping.
+ */
+export declare function clearAttrScreen(scr: AttrScreen, paper: SpectrumColor, ink?: SpectrumColor): void;
+/**
+ * Stamps a monochrome {@link Bitmap} at screen pixel `(x, y)` (rounded; may be
+ * sub-cell, negative, or off-screen — clipped). Sets the bitmap's lit pixels in
+ * the pixel plane and re-attributes every cell that receives a lit pixel, per
+ * `policy` (default `'both'`). Lit-pixel-only: existing pixels are never cleared,
+ * so other sprites/background in a touched cell bleed to the new colour.
+ */
+export declare function stampMono(scr: AttrScreen, bitmap: Bitmap, x: number, y: number, ink: SpectrumColor, paper: SpectrumColor, policy?: AttrPolicy): void;
+/**
+ * Resolves the two planes into RGBA (each pixel takes its cell's ink or paper)
+ * and uploads the result with one `putImageData` + `drawImage`. The image is
+ * drawn at `(0, 0)` under the current transform, so the usual `setupCanvas`
+ * `×scale` makes it fill the canvas. Headless: fills {@link AttrScreen.rgba} and
+ * skips the blit.
+ */
+export declare function flushAttrScreen(ctx: CanvasRenderingContext2D, scr: AttrScreen): void;
+//# sourceMappingURL=attrscreen.d.ts.map

package/dist/attrscreen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attrscreen.d.ts","sourceRoot":"","sources":["../src/attrscreen.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,OAAO,EAAQ,KAAK,aAAa,EAAE,MAAM,cAAc,CAAA;AACvD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAE3C;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,UAAU,GAAG,YAAY,CAAA;AAE3D,+EAA+E;AAC/E,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;IAC3B,oEAAoE;IACpE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAA;IAC7B,sDAAsD;IACtD,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAA;IAC/B,wFAAwF;IACxF,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAA;IAChC,wEAAwE;IACxE,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAAA;IAChC,kFAAkF;IAClF,QAAQ,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAA;CAC1C;AAUD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,SAAK,EAAE,IAAI,SAAK,GAAG,UAAU,CAiCjE;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,aAAa,EAAE,GAAG,GAAE,aAAqB,GAAG,IAAI,CAIvG;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CACvB,GAAG,EAAE,UAAU,EACf,MAAM,EAAE,MAAM,EACd,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,GAAG,EAAE,aAAa,EAClB,KAAK,EAAE,aAAa,EACpB,MAAM,GAAE,UAAmB,GAC1B,IAAI,CA+BN;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,wBAAwB,EAAE,GAAG,EAAE,UAAU,GAAG,IAAI,CAoBpF"}

package/dist/attrscreen.js

@@ -0,0 +1,167 @@
+/**
+ * @module attrscreen
+ *
+ * **Authentic ZX attribute clash — opt-in.** The real Spectrum stored the screen
+ * as two separate planes: a 1-bit **pixel** bitmap (256×192) and a 32×24
+ * **attribute** grid where each 8×8 cell holds exactly *one* ink + *one* paper.
+ * Drawing a sprite into a cell rewrote that cell's attribute, so everything in
+ * the cell — sprite *and* background — snapped to the same two colours. That bleed
+ * is the famous *colour clash*.
+ *
+ * zx-kit normally composites in full colour (no clash — by design, see the README).
+ * This module is the opt-in way to get the real thing, the same shape as the other
+ * effects ({@link "renderer" | drawScanlines}, {@link "lighting" | renderDarkness}):
+ * a game that wants clash routes its drawing through an {@link AttrScreen} and
+ * calls {@link flushAttrScreen} once per frame.
+ *
+ * **The dual plane:** {@link stampMono} writes a monochrome bitmap's *shape* into
+ * the pixel plane and re-attributes every cell it touches (per {@link AttrPolicy}).
+ * Crucially it does **not** clear other pixels — so a leaf already drawn in a cell
+ * keeps its pixels but now renders in the *new* cell colour. That is the clash.
+ *
+ * **Fast flush:** the two planes are resolved into one RGBA buffer and uploaded
+ * with a single `putImageData` + `drawImage` — never per-pixel `fillRect`. Assumes
+ * a little-endian platform (every browser; common Node).
+ *
+ * Headless-safe: with no `document` the offscreen canvas is `null`, the resolve
+ * still runs (so the logic is testable) and the blit is skipped — nothing throws.
+ *
+ * @example
+ * ```ts
+ * const scr = createAttrScreen()                       // 32×24 cells = 256×192, once
+ * // each frame, in screen space:
+ * clearAttrScreen(scr, C.BLACK)                        // blank paper
+ * stampMono(scr, caveBitmap,   0,  0, C.B_BLUE,  C.BLACK)   // background
+ * stampMono(scr, rabbitBitmap, rx, ry, C.B_WHITE, C.BLACK)  // sprite → its cells clash to white
+ * flushAttrScreen(ctx, scr)                            // one putImageData + drawImage
+ * ```
+ */
+import { CELL } from './palette.js';
+/** Packs a `#RRGGBB` Spectrum colour into a little-endian RGBA word (opaque). */
+function hexToU32(hex) {
+    const r = parseInt(hex.slice(1, 3), 16);
+    const g = parseInt(hex.slice(3, 5), 16);
+    const b = parseInt(hex.slice(5, 7), 16);
+    return ((255 << 24) | (b << 16) | (g << 8) | r) >>> 0;
+}
+/**
+ * Creates a screen-space attribute plane of `cols`×`rows` 8×8 cells (default
+ * 32×24 = 256×192). Allocate once; reuse across frames. Throws on a non-positive
+ * size.
+ */
+export function createAttrScreen(cols = 32, rows = 24) {
+    if (!Number.isInteger(cols) || cols <= 0 || !Number.isInteger(rows) || rows <= 0) {
+        throw new Error(`createAttrScreen: cols and rows must be positive integers, got ${cols}×${rows}`);
+    }
+    const width = cols * CELL;
+    const height = rows * CELL;
+    let canvas = null;
+    let image = 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;
+            image = ctx.createImageData(width, height);
+        }
+    }
+    // In the browser the resolved buffer IS the ImageData's data (no per-frame copy,
+    // no constructor); headless it's a standalone buffer so the resolve stays testable.
+    const rgba = image ? image.data : new Uint8ClampedArray(width * height * 4);
+    return {
+        cols,
+        rows,
+        width,
+        height,
+        pixels: new Uint8Array(width * height),
+        cellInk: new Uint32Array(cols * rows),
+        cellPaper: new Uint32Array(cols * rows),
+        rgba,
+        image,
+        canvas,
+    };
+}
+/**
+ * Resets the screen for a new frame: clears all pixels to paper and fills every
+ * cell's attributes. `ink` defaults to `paper`, so untouched cells are a flat
+ * paper colour. Call at the start of each frame, before stamping.
+ */
+export function clearAttrScreen(scr, paper, ink = paper) {
+    scr.pixels.fill(0);
+    scr.cellPaper.fill(hexToU32(paper));
+    scr.cellInk.fill(hexToU32(ink));
+}
+/**
+ * Stamps a monochrome {@link Bitmap} at screen pixel `(x, y)` (rounded; may be
+ * sub-cell, negative, or off-screen — clipped). Sets the bitmap's lit pixels in
+ * the pixel plane and re-attributes every cell that receives a lit pixel, per
+ * `policy` (default `'both'`). Lit-pixel-only: existing pixels are never cleared,
+ * so other sprites/background in a touched cell bleed to the new colour.
+ */
+export function stampMono(scr, bitmap, x, y, ink, paper, policy = 'both') {
+    const inkU32 = hexToU32(ink);
+    const paperU32 = hexToU32(paper);
+    const setInk = policy !== 'paper-only';
+    const setPaper = policy !== 'ink-only';
+    const { data, width: bw, height: bh } = bitmap;
+    const bytesPerRow = bw >> 3;
+    const ox = Math.round(x);
+    const oy = Math.round(y);
+    for (let row = 0; row < bh; row++) {
+        const py = oy + row;
+        if (py < 0 || py >= scr.height)
+            continue;
+        const rowByteBase = row * bytesPerRow;
+        const rowPixBase = py * scr.width;
+        const cellRowBase = (py >> 3) * scr.cols;
+        for (let byteIdx = 0; byteIdx < bytesPerRow; byteIdx++) {
+            const byte = data[rowByteBase + byteIdx];
+            if (!byte)
+                continue;
+            const colBase = byteIdx << 3;
+            for (let bit = 0; bit < 8; bit++) {
+                if (!(byte & (0x80 >> bit)))
+                    continue;
+                const px = ox + colBase + bit;
+                if (px < 0 || px >= scr.width)
+                    continue;
+                scr.pixels[rowPixBase + px] = 1;
+                const cell = cellRowBase + (px >> 3);
+                if (setInk)
+                    scr.cellInk[cell] = inkU32;
+                if (setPaper)
+                    scr.cellPaper[cell] = paperU32;
+            }
+        }
+    }
+}
+/**
+ * Resolves the two planes into RGBA (each pixel takes its cell's ink or paper)
+ * and uploads the result with one `putImageData` + `drawImage`. The image is
+ * drawn at `(0, 0)` under the current transform, so the usual `setupCanvas`
+ * `×scale` makes it fill the canvas. Headless: fills {@link AttrScreen.rgba} and
+ * skips the blit.
+ */
+export function flushAttrScreen(ctx, scr) {
+    const { pixels, cellInk, cellPaper, width, height, cols } = scr;
+    const out = new Uint32Array(scr.rgba.buffer);
+    let p = 0;
+    for (let yy = 0; yy < height; yy++) {
+        const cellRow = (yy >> 3) * cols;
+        for (let xx = 0; xx < width; xx++) {
+            const cell = cellRow + (xx >> 3);
+            out[p] = pixels[p] ? cellInk[cell] : cellPaper[cell];
+            p++;
+        }
+    }
+    if (scr.canvas && scr.image) {
+        const offctx = scr.canvas.getContext('2d');
+        if (offctx) {
+            offctx.putImageData(scr.image, 0, 0);
+            ctx.drawImage(scr.canvas, 0, 0);
+        }
+    }
+}
+//# sourceMappingURL=attrscreen.js.map

package/dist/attrscreen.js.map

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

package/dist/index.d.ts

@@ -18,5 +18,7 @@ export * from './save.js';
 export * from './i18n.js';
 export * from './lighting.js';
 export * from './cache.js';
+export * from './attrscreen.js';
+export * from './monoscreen.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;AAC1B,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,iBAAiB,CAAA;AAC/B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,YAAY,CAAA"}

package/dist/index.js

@@ -18,5 +18,7 @@ export * from './save.js';
 export * from './i18n.js';
 export * from './lighting.js';
 export * from './cache.js';
+export * from './attrscreen.js';
+export * from './monoscreen.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;AAC1B,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,iBAAiB,CAAA;AAC/B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,YAAY,CAAA"}

package/dist/monoscreen.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @module monoscreen
+ *
+ * **Monochrome playfield — the classic ZX anti-clash trick.** The surest way to
+ * avoid attribute clash is to have no clash at all: render the action area in a
+ * single ink + paper, and keep the colour in a separate HUD/border around it.
+ * Light Force, Bobby Bearing, Highway Encounter and Head Over Heels all did this.
+ *
+ * A {@link MonoScreen} is a **1-bit foreground mask of any size** (its own,
+ * smaller than the canvas) plus two colours. Everything drawn into it is reduced
+ * to ink (lit pixels) or paper (everything else) — a white sprite, a green tile
+ * and a cyan rabbit all become the same ink, so they can never clash. Draw your
+ * colourful HUD normally *outside* the region; {@link flushMonoScreen} blits the
+ * playfield at a given offset.
+ *
+ * Unlike {@link "attrscreen" | attrscreen} (authentic *per-cell* clash), this is
+ * one ink/paper for the **whole** region — simpler, cheaper, and the right tool
+ * when you want a clean retro look rather than the colour-bleed artefact.
+ *
+ * Fast flush: the mask is resolved into one reused `ImageData` and uploaded with
+ * a single `putImageData` + `drawImage` — never per-pixel `fillRect`. Little-endian
+ * (every browser). Headless-safe: the resolve runs, the blit is skipped.
+ *
+ * @example
+ * ```ts
+ * const play = createMonoScreen(256, 160, C.BLACK, C.B_CYAN)   // playfield, once
+ * // each frame, in playfield space:
+ * clearMonoScreen(play)
+ * drawMonoBitmap(play, tileBmp,   tx, ty)     // tiles  → ink
+ * drawMonoBitmap(play, rabbitBmp, rx, ry)     // sprite → ink (silhouette)
+ * fillMono(play, threadX, threadY, 1, len)    // a thin line (e.g. a spider thread)
+ * flushMonoScreen(ctx, play, 0, 16)           // blit the playfield below a 16px HUD
+ * // …draw the colourful HUD normally, outside the region…
+ * ```
+ */
+import type { SpectrumColor } from './palette.js';
+import type { Bitmap } from './renderer.js';
+/** A monochrome region: a 1-bit foreground mask plus an ink/paper colour pair. */
+export interface MonoScreen {
+    readonly width: number;
+    readonly height: number;
+    /** Foreground colour (lit pixels). Mutable — recolour the playfield any time. */
+    ink: SpectrumColor;
+    /** Background colour (everything else). Mutable. */
+    paper: SpectrumColor;
+    /** One byte per pixel — `1` = ink/foreground, `0` = paper. Row-major, `width*height`. */
+    readonly pixels: Uint8Array;
+    /** Resolved RGBA buffer (`width*height*4`), filled by {@link flushMonoScreen}. */
+    readonly rgba: Uint8ClampedArray;
+    /** Reusable `ImageData` backing {@link rgba} (`null` when headless). */
+    readonly image: ImageData | null;
+    /** Offscreen canvas the resolved buffer is uploaded to (`null` when headless). */
+    readonly canvas: HTMLCanvasElement | null;
+}
+/**
+ * Creates a monochrome playfield of the given pixel size — **its own size, not
+ * the canvas**. Pick a region smaller than the canvas and keep the HUD colourful
+ * around it. `ink`/`paper` are mutable. Create once; reuse across frames. Throws
+ * on a non-positive size.
+ */
+export declare function createMonoScreen(width: number, height: number, ink: SpectrumColor, paper: SpectrumColor): MonoScreen;
+/** Resets the playfield to all-paper for a new frame. Call before drawing. */
+export declare function clearMonoScreen(scr: MonoScreen): void;
+/**
+ * Draws a monochrome {@link Bitmap}'s lit pixels as foreground (ink) at `(x, y)`
+ * (rounded; may be off-screen — clipped). Clear pixels are left untouched, so the
+ * paper (and anything drawn earlier) shows through.
+ */
+export declare function drawMonoBitmap(scr: MonoScreen, bitmap: Bitmap, x: number, y: number): void;
+/**
+ * Sets a filled foreground rectangle (clipped) — handy for thin lines (a 1px-wide
+ * rect is a spider thread, a ladder rail, a laser) or solid blocks.
+ */
+export declare function fillMono(scr: MonoScreen, x: number, y: number, w: number, h: number): void;
+/**
+ * Resolves the mask into RGBA (ink where lit, paper elsewhere) and blits the
+ * region at canvas offset `(dx, dy)` with one `putImageData` + `drawImage` — under
+ * the current transform, so `setupCanvas`'s `×scale` is honoured. Headless: fills
+ * {@link MonoScreen.rgba} and skips the blit.
+ */
+export declare function flushMonoScreen(ctx: CanvasRenderingContext2D, scr: MonoScreen, dx?: number, dy?: number): void;
+//# sourceMappingURL=monoscreen.d.ts.map

package/dist/monoscreen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"monoscreen.d.ts","sourceRoot":"","sources":["../src/monoscreen.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AACjD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAE3C,kFAAkF;AAClF,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,iFAAiF;IACjF,GAAG,EAAE,aAAa,CAAA;IAClB,oDAAoD;IACpD,KAAK,EAAE,aAAa,CAAA;IACpB,yFAAyF;IACzF,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;IAC3B,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAA;IAChC,wEAAwE;IACxE,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAAA;IAChC,kFAAkF;IAClF,QAAQ,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAA;CAC1C;AAUD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,aAAa,EAClB,KAAK,EAAE,aAAa,GACnB,UAAU,CAkBZ;AAED,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,GAAG,EAAE,UAAU,GAAG,IAAI,CAErD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAsB1F;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAS1F;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,wBAAwB,EAAE,GAAG,EAAE,UAAU,EAAE,EAAE,SAAI,EAAE,EAAE,SAAI,GAAG,IAAI,CAcpG"}

package/dist/monoscreen.js

@@ -0,0 +1,105 @@
+/** Packs a `#RRGGBB` colour into a little-endian RGBA word (opaque). */
+function hexToU32(hex) {
+    const r = parseInt(hex.slice(1, 3), 16);
+    const g = parseInt(hex.slice(3, 5), 16);
+    const b = parseInt(hex.slice(5, 7), 16);
+    return ((255 << 24) | (b << 16) | (g << 8) | r) >>> 0;
+}
+/**
+ * Creates a monochrome playfield of the given pixel size — **its own size, not
+ * the canvas**. Pick a region smaller than the canvas and keep the HUD colourful
+ * around it. `ink`/`paper` are mutable. Create once; reuse across frames. Throws
+ * on a non-positive size.
+ */
+export function createMonoScreen(width, height, ink, paper) {
+    if (!Number.isFinite(width) || width <= 0 || !Number.isFinite(height) || height <= 0) {
+        throw new Error(`createMonoScreen: width and height must be positive, got ${width}×${height}`);
+    }
+    let canvas = null;
+    let image = 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;
+            image = ctx.createImageData(width, height);
+        }
+    }
+    const rgba = image ? image.data : new Uint8ClampedArray(width * height * 4);
+    return { width, height, ink, paper, pixels: new Uint8Array(width * height), rgba, image, canvas };
+}
+/** Resets the playfield to all-paper for a new frame. Call before drawing. */
+export function clearMonoScreen(scr) {
+    scr.pixels.fill(0);
+}
+/**
+ * Draws a monochrome {@link Bitmap}'s lit pixels as foreground (ink) at `(x, y)`
+ * (rounded; may be off-screen — clipped). Clear pixels are left untouched, so the
+ * paper (and anything drawn earlier) shows through.
+ */
+export function drawMonoBitmap(scr, bitmap, x, y) {
+    const { data, width: bw, height: bh } = bitmap;
+    const bytesPerRow = bw >> 3;
+    const ox = Math.round(x);
+    const oy = Math.round(y);
+    for (let row = 0; row < bh; row++) {
+        const py = oy + row;
+        if (py < 0 || py >= scr.height)
+            continue;
+        const rowByteBase = row * bytesPerRow;
+        const rowPixBase = py * scr.width;
+        for (let byteIdx = 0; byteIdx < bytesPerRow; byteIdx++) {
+            const byte = data[rowByteBase + byteIdx];
+            if (!byte)
+                continue;
+            const colBase = byteIdx << 3;
+            for (let bit = 0; bit < 8; bit++) {
+                if (!(byte & (0x80 >> bit)))
+                    continue;
+                const px = ox + colBase + bit;
+                if (px < 0 || px >= scr.width)
+                    continue;
+                scr.pixels[rowPixBase + px] = 1;
+            }
+        }
+    }
+}
+/**
+ * Sets a filled foreground rectangle (clipped) — handy for thin lines (a 1px-wide
+ * rect is a spider thread, a ladder rail, a laser) or solid blocks.
+ */
+export function fillMono(scr, x, y, w, h) {
+    const x0 = Math.max(0, Math.round(x));
+    const y0 = Math.max(0, Math.round(y));
+    const x1 = Math.min(scr.width, Math.round(x) + w);
+    const y1 = Math.min(scr.height, Math.round(y) + h);
+    for (let yy = y0; yy < y1; yy++) {
+        const base = yy * scr.width;
+        for (let xx = x0; xx < x1; xx++)
+            scr.pixels[base + xx] = 1;
+    }
+}
+/**
+ * Resolves the mask into RGBA (ink where lit, paper elsewhere) and blits the
+ * region at canvas offset `(dx, dy)` with one `putImageData` + `drawImage` — under
+ * the current transform, so `setupCanvas`'s `×scale` is honoured. Headless: fills
+ * {@link MonoScreen.rgba} and skips the blit.
+ */
+export function flushMonoScreen(ctx, scr, dx = 0, dy = 0) {
+    const inkU32 = hexToU32(scr.ink);
+    const paperU32 = hexToU32(scr.paper);
+    const out = new Uint32Array(scr.rgba.buffer);
+    const px = scr.pixels;
+    for (let i = 0; i < px.length; i++)
+        out[i] = px[i] ? inkU32 : paperU32;
+    if (scr.canvas && scr.image) {
+        const offctx = scr.canvas.getContext('2d');
+        if (offctx) {
+            offctx.putImageData(scr.image, 0, 0);
+            ctx.drawImage(scr.canvas, dx, dy);
+        }
+    }
+}
+//# sourceMappingURL=monoscreen.js.map

package/dist/monoscreen.js.map

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

package/package.json

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