zx-kit 0.20.0 → 0.22.0

package/README.md

@@ -27,7 +27,7 @@ The goal is simple: **it should look and sound like a Spectrum, but run like a m
 - **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
 - **Free-roaming sprites** — position, velocity, gravity, `flipX` caching, transparent or opaque background
-- **AABB collision resolution** — sprite vs. sprite overlap, sprite vs. tile map wall resolution with directional hit flags
+- **Three-tier collision** — AABB overlap tests, generic rect-vs-tile wall resolution (any sprite size), and pixel-precise mask overlap with O(pixels) sorted-merge intersection — no allocations per frame
 - **Keyboard input** — configurable key-repeat, single-consume action flags, instant state reset on phase transitions
 - **ZX-style UI widgets** — progress bars with managed lifetime, boxes, frames, panel titles
 - **Typed save / load** — persistent saves via `localStorage` with schema versioning, migrations, slot enumeration, in-memory throttling, and discriminated Result types for every failure mode
@@ -539,7 +539,7 @@ requestAnimationFrame(loop)
 | [`ui.ts`](#uits--ui-widgets) | Boxes, frames, panel titles, progress bars + instrumentation widgets (dotted grids, segmented bars, fluid tanks, dials, text compass) |
 | [`input.ts`](#inputts--keyboard-input) | Movement with key-repeat, action flags, state reset |
 | [`sprite.ts`](#spritets--free-roaming-sprites) | Sprites: position, velocity, gravity, flip, render |
-| [`collision.ts`](#collisionts--aabb-collision) | AABB overlap tests, tile-map wall resolution |
+| [`collision.ts`](#collisionts--collision-detection) | AABB overlap + rect-based tile resolution, pixel-precise mask overlap and tile checks |
 | [`animation.ts`](#animationts--frame-timer--tween) | Frame-timer for sprite strips, position tween between two points |
 | [`camera.ts`](#camerats--scrolling-camera) | Viewport that follows a target with lerp + deadzone, world-bounds clamping |
 | [`scene.ts`](#scenets--scene-manager) | Stack-based scene manager with onEnter/onExit/onPause/onResume hooks |
@@ -1412,9 +1412,17 @@ renderSprite(ctx, player)
 
 ---
 
-## `collision.ts` — AABB Collision
+## `collision.ts` — Collision Detection
 
-Axis-aligned bounding box overlap tests and sprite-vs-tile-map wall resolution.
+Three tiers of collision detection, from broad-phase to pixel-precise:
+
+| Tier | Functions | Use case |
+|------|-----------|----------|
+| **AABB** | `rectsOverlap`, `spritesOverlap`, `spriteRect`, `bitmapRect` | Fast broad-phase hit tests |
+| **Rect-vs-tile** | `isSolidAt`, `resolveRectX`, `resolveRectY`, `resolveX`, `resolveY` | Wall resolution for any sprite size |
+| **Pixel-precise** | `bitmapPixelMask`, `masksOverlap`, `pixelSolidCount` | Exact opaque-pixel overlap tests |
+
+Pick the tier that matches your accuracy need. AABB is O(1) and correct for most cases. Pixel-precise costs O(opaque pixels) but eliminates false positives for non-rectangular sprites.
 
 ### `Rect` interface
 
@@ -1422,19 +1430,36 @@ Axis-aligned bounding box overlap tests and sprite-vs-tile-map wall resolution.
 interface Rect { x: number; y: number; w: number; h: number }
 ```
 
-### `spriteRect(sprite): Rect`
+An axis-aligned bounding rectangle in game pixels.
+
+---
+
+### AABB overlap tests
+
+#### `spriteRect(sprite): Rect`
 
 Returns the `CELL × CELL` bounding box of a sprite at its current position.
 
-### `rectsOverlap(a, b): boolean`
+#### `bitmapRect(bitmap, x, y): Rect`
+
+Returns the bounding box for any `Bitmap` at `(x, y)`. Correct for bitmaps of any size — 16×24, 32×32, 96×128 — not just `CELL × CELL`.
+
+```ts
+const heroRect  = bitmapRect(HERO_BMP, hero.x,  hero.y)
+const enemyRect = bitmapRect(ENEMY_BMP, enemy.x, enemy.y)
+if (rectsOverlap(heroRect, enemyRect)) damage(hero)
+```
+
+#### `rectsOverlap(a, b): boolean`
 
-Returns `true` when two rectangles share at least one pixel. Touching edges return `false`.
+Returns `true` when two rectangles share at least one pixel. Touching edges (zero-area overlap) return `false`.
 
 ```ts
 rectsOverlap(spriteRect(bullet), spriteRect(enemy))  // hit test
+rectsOverlap(bitmapRect(HERO_BMP, hx, hy), bitmapRect(SWORD_BMP, sx, sy))
 ```
 
-### `spritesOverlap(a, b): boolean`
+#### `spritesOverlap(a, b): boolean`
 
 Shorthand: `rectsOverlap(spriteRect(a), spriteRect(b))`.
 
@@ -1443,13 +1468,46 @@ if (spritesOverlap(player, coin)) collectCoin()
 if (enemies.some(e => spritesOverlap(player, e))) loseLife()
 ```
 
-### `isSolidAt(map, px, py): boolean`
+---
+
+### Rect-vs-tile resolution
+
+#### `isSolidAt(map, px, py): boolean`
+
+Tests whether the game-pixel `(px, py)` falls inside a solid tile. Out-of-bounds pixels return `true` (implicit solid boundary). Converts to tile coords via `Math.floor(px / CELL)`.
 
-Tests whether the game-pixel `(px, py)` falls inside a solid tile. Out-of-bounds pixels return `true` (implicit solid boundary).
+```ts
+if (isSolidAt(map, player.x, player.y + CELL)) { player.vy = 0 } // on floor
+```
+
+#### `resolveRectX(rect, map, newX): { x, hitLeft, hitRight }`
 
-### `resolveX(sprite, map, newX): { x, hitLeft, hitRight }`
+Generic horizontal resolver for any axis-aligned rectangle. Checks every tile row the rectangle spans — so a 16×24 hero correctly detects walls in the middle rows, not just the top and bottom corners.
 
-Resolves a proposed horizontal move against solid tiles. Returns the clamped position and directional hit flags. No collision → returns `newX` unchanged.
+Returns the clamped x and collision flags. On collision, the rectangle is placed flush against the wall.
+
+```ts
+const rect = bitmapRect(HERO_BMP, hero.x, hero.y)
+const r = resolveRectX(rect, map, hero.x + dx)
+hero.x = r.x
+if (r.hitLeft || r.hitRight) hero.vx = 0
+```
+
+#### `resolveRectY(rect, map, newY): { y, hitTop, hitBottom }`
+
+Generic vertical resolver for any axis-aligned rectangle. Checks every tile column the rectangle spans — so a wide wagon detects the floor across its full footprint.
+
+```ts
+const rect = bitmapRect(HERO_BMP, hero.x, hero.y)
+const r = resolveRectY(rect, map, hero.y + dy)
+hero.y = r.y
+if (r.hitBottom) { hero.vy = 0; onGround = true }
+if (r.hitTop)    { hero.vy = 0 }
+```
+
+#### `resolveX(sprite, map, newX): { x, hitLeft, hitRight }`
+
+Resolves a proposed horizontal move for an 8×8 sprite. Thin wrapper over `resolveRectX` — preserved for the common CELL-sized sprite case.
 
 ```ts
 const { x, hitLeft, hitRight } = resolveX(player, map, player.x)
@@ -1457,9 +1515,9 @@ player.x = x
 if (hitLeft || hitRight) player.vx = 0
 ```
 
-### `resolveY(sprite, map, newY): { y, hitTop, hitBottom }`
+#### `resolveY(sprite, map, newY): { y, hitTop, hitBottom }`
 
-Resolves a proposed vertical move against solid tiles.
+Resolves a proposed vertical move for an 8×8 sprite. Thin wrapper over `resolveRectY`.
 
 - `hitBottom` — landed on a floor (use for jump ground detection)
 - `hitTop` — bumped a ceiling
@@ -1473,6 +1531,114 @@ if (hitTop)    { player.vy = 0 }
 
 ---
 
+### Pixel-precise collision
+
+AABB and rect-vs-tile use the full bounding box. This is almost always correct — but it fails for non-rectangular sprites in edge cases: a circular character standing on a ledge, a diamond-shaped projectile grazing a corner, a tall hero with narrow feet that shouldn't trigger floor detection when hanging over a gap.
+
+Pixel-precise collision solves this by working with the actual opaque pixels of a bitmap, not its enclosing rectangle.
+
+```
+AABB (16px wide):     ████████████████   → fires when any part of the box overlaps
+                                           a tile, even if the sprite itself clears it
+pixelSolidCount:      ···██····██····   → only the real foot pixels are checked —
+                                           Dizzy hanging over a platform edge doesn't
+                                           feel magically glued to empty air
+```
+
+#### `PixelMask` interface
+
+```ts
+interface PixelMask {
+  readonly width:       number
+  readonly height:      number
+  readonly rows:        readonly (readonly number[])[]   // per-row sorted opaque column indices
+  readonly totalPixels: number
+}
+```
+
+Pre-computed per-row opaque pixel data for a `Bitmap`. Build once with `bitmapPixelMask`; reuse every frame. Each `rows[r]` is a sorted array of column indices where that row has a set bit. Empty rows have zero-length arrays — never `undefined`.
+
+```
+// Example: 16×16 circular sprite
+mask.rows[0]  → [6, 7, 8, 9]        // narrow top
+mask.rows[7]  → [0, 1, 2, ..., 15]  // full-width middle
+mask.rows[11] → [3, 4, 10, 11]      // only feet
+mask.rows[14] → []                   // below feet, empty
+```
+
+The immutability guarantee matters: the mask is derived from immutable `Bitmap` data. Pre-compute once and store alongside the bitmap definition.
+
+#### `bitmapPixelMask(bitmap): PixelMask`
+
+Extracts a pixel mask from a `Bitmap`. Reads each row's bit data (bit 7 = leftmost pixel) and collects column indices of set (opaque) pixels into sorted arrays. Counts `totalPixels` for overlap severity calculations.
+
+```ts
+// Pre-compute at module load time — not inside the game loop
+const HERO_MASK   = bitmapPixelMask(HERO_BMP)
+const ENEMY_MASK  = bitmapPixelMask(ENEMY_BMP)
+const BULLET_MASK = bitmapPixelMask(BULLET_BMP)
+```
+
+**Bitmap width must be a multiple of 8.** Bitmaps with width `w` require `w * height / 8` bytes of data — standard `createBitmap` enforces this.
+
+#### `masksOverlap(a, ax, ay, b, bx, by): number`
+
+Counts opaque pixels of mask `a` at `(ax, ay)` that overlap with opaque pixels of mask `b` at `(bx, by)`.
+
+Returns **0** when there is no pixel-level overlap. Any value **> 0** is a pixel-perfect collision. The count itself carries semantic meaning: use it for overlap severity — damage scaling, knock-back strength, or as a threshold to ignore grazing touches.
+
+Uses sorted-merge intersection per row: O(opaque pixels), no allocations per call. Safe to call every frame for multiple pairs.
+
+```ts
+// Simple hit test
+if (masksOverlap(BULLET_MASK, bullet.x, bullet.y, ENEMY_MASK, enemy.x, enemy.y) > 0) {
+  destroyEnemy()
+}
+
+// Severity — require a real overlap, not just a 1-pixel graze
+const overlap = masksOverlap(SWORD_MASK, sx, sy, HERO_MASK, hx, hy)
+if (overlap >= 3) {
+  takeDamage(Math.round(overlap / SWORD_MASK.totalPixels * 10))
+}
+```
+
+Masks of different sizes work without any special handling — the overlap window is clipped to the intersection region automatically.
+
+#### `pixelSolidCount(mask, mx, my, map): number`
+
+Counts opaque pixels of a mask at `(mx, my)` that sit on solid tiles in a `TileMap`. Pixel-precise replacement for AABB-based ground / wall checks.
+
+Solves the "character standing on a platform edge" problem: a round sprite with narrow feet can hang over the edge — only the real foot pixels are checked against the tile map, not the full bounding box.
+
+```ts
+const HERO_MASK = bitmapPixelMask(HERO_BMP)
+
+// Check if standing — test 1 px below current foot position
+const standing = pixelSolidCount(HERO_MASK, hero.x, hero.y + 1, map) > 0
+
+// Check wall to the right — test 1 px past right edge
+const wallRight = pixelSolidCount(HERO_MASK, hero.x + 1, hero.y, map) > 0
+
+// How many foot pixels are actually on solid ground? Use as grip factor
+const groundContact = pixelSolidCount(HERO_MASK, hero.x, hero.y + 1, map)
+```
+
+When `groundContact` is 0, a circle-shaped hero hanging over a tile edge won't trigger `hitBottom` in `resolveRectY` — the pixel-check and AABB-check intentionally disagree, and you pick which one to trust for each gameplay mechanic.
+
+---
+
+### Choosing the right tier
+
+| Situation | Recommended tier |
+|-----------|-----------------|
+| Player touches any part of a coin | `spritesOverlap` — AABB is exact when both sprites are `CELL × CELL` |
+| Large hero (16×24) walks into a wall | `resolveRectX` / `resolveRectY` — checks all tile rows the sprite spans |
+| Round sprite on a platform edge | `pixelSolidCount` — only real foot pixels count |
+| Bullet vs. irregular boss sprite | `masksOverlap` — pixel-precise, returns overlap count for damage |
+| Off-road detection for a truck with a bumpy silhouette | `pixelSolidCount` / custom mask loop — checks each opaque pixel against road boundary |
+
+---
+
 ## `animation.ts` — Frame Timer & Tween
 
 Two small primitives for time-based animation:
@@ -2057,8 +2223,10 @@ zx-kit/
 │   ├── tilemap.ts         # createTileMap, Tile, Viewport, TileMap
 │   ├── sprite.ts          # createSprite, moveSprite, applyGravity,
 │   │                      # renderSprite, Sprite
-│   └── collision.ts       # spriteRect, rectsOverlap, spritesOverlap,
-│                          # isSolidAt, resolveX, resolveY, Rect
+│   └── collision.ts       # spriteRect, bitmapRect, rectsOverlap, spritesOverlap,
+│                          # isSolidAt, resolveRectX, resolveRectY, resolveX, resolveY,
+│                          # bitmapPixelMask, masksOverlap, pixelSolidCount,
+│                          # Rect, PixelMask
 └── dist/                  # compiled output (npm run build)
     ├── index.js
     ├── index.d.ts

package/dist/collision.d.ts

@@ -85,6 +85,88 @@ export declare function resolveRectY(rect: Rect, map: TileMap, newY: number): {
     hitTop: boolean;
     hitBottom: boolean;
 };
+/**
+ * Pre-computed per-row opaque pixel data for a {@link Bitmap}.
+ * Build once with {@link bitmapPixelMask}, reuse every frame.
+ *
+ * Each row is a sorted array of column indices where the bitmap has a set bit.
+ * Empty rows have zero-length arrays — never `undefined`.
+ *
+ * @example
+ * ```
+ * // 16×16 circular sprite:
+ * mask.rows[0]  → [6, 7, 8, 9]              // narrow top
+ * mask.rows[7]  → [0, 1, 2, ..., 15]        // full-width middle
+ * mask.rows[11] → [3, 4, 10, 11]            // only feet
+ * mask.rows[14] → []                         // below feet, empty
+ * ```
+ */
+export interface PixelMask {
+    readonly width: number;
+    readonly height: number;
+    readonly rows: readonly (readonly number[])[];
+    readonly totalPixels: number;
+}
+/**
+ * Extract a pixel mask from a {@link Bitmap}.
+ * Reads each row's bit data (bit 7 = leftmost pixel) and collects column
+ * indices of set (opaque) pixels into sorted arrays.
+ *
+ * Pre-compute once per sprite definition — the result is immutable and
+ * derived from immutable bitmap data.
+ *
+ * @example
+ * ```ts
+ * const HERO_MASK = bitmapPixelMask(HERO_BMP)
+ * // Now use with masksOverlap() or pixelSolidCount()
+ * ```
+ */
+export declare function bitmapPixelMask(bitmap: Bitmap): PixelMask;
+/**
+ * Count opaque pixels of mask `a` at `(ax, ay)` that overlap with
+ * opaque pixels of mask `b` at `(bx, by)`.
+ *
+ * Returns 0 when no overlap. Any value > 0 means pixel-perfect collision.
+ * The count itself is useful for overlap severity — e.g. damage scaling.
+ *
+ * Uses sorted-merge intersection per row — O(pixels) total, no allocations.
+ *
+ * @example
+ * ```ts
+ * const BULLET = bitmapPixelMask(BULLET_BMP)
+ * const ENEMY  = bitmapPixelMask(ENEMY_BMP)
+ *
+ * if (masksOverlap(BULLET, bx, by, ENEMY, ex, ey) > 0) {
+ *   destroyEnemy()
+ * }
+ * ```
+ */
+export declare function masksOverlap(a: PixelMask, ax: number, ay: number, b: PixelMask, bx: number, by: number): number;
+/**
+ * Count opaque pixels of a mask at `(mx, my)` that sit on solid tiles
+ * in a {@link TileMap}. Pixel-precise replacement for AABB-based checks.
+ *
+ * Solves the "character standing on a platform edge" problem: a round
+ * sprite with narrow feet can hang over the edge — only real foot pixels
+ * are checked, not the full bounding box.
+ *
+ * ```
+ * AABB (16px wide):    ████████████████  → full-width overlap check
+ * pixelSolidCount:     ···██····██····  → only feet matter
+ * ```
+ *
+ * @example
+ * ```ts
+ * const HERO_MASK = bitmapPixelMask(HERO_BMP)
+ *
+ * // Check if standing: test 1px below current position
+ * const standing = pixelSolidCount(HERO_MASK, hero.x, hero.y + 1, map) > 0
+ *
+ * // Check wall to the right
+ * const wallRight = pixelSolidCount(HERO_MASK, hero.x + 1, hero.y, map) > 0
+ * ```
+ */
+export declare function pixelSolidCount(mask: PixelMask, mx: number, my: number, map: TileMap): number;
 /**
  * Resolves a proposed horizontal movement for an 8×8 sprite against solid tiles.
  * Thin wrapper over {@link resolveRectX} preserved for backward compatibility.

package/dist/collision.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"collision.d.ts","sourceRoot":"","sources":["../src/collision.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAC3C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAE3C;;GAEG;AACH,MAAM,WAAW,IAAI;IACnB,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;CACV;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAE/C;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,GAAG,OAAO,CAKtD;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAE5D;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAErE;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAEvE;AAwBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,IAAI,EACV,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,MAAM,GACX;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAuBpD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,IAAI,EACV,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,MAAM,GACX;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAuBpD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CACtB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,MAAM,GACX;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAEpD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CACtB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,MAAM,GACX;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAEpD"}
+{"version":3,"file":"collision.d.ts","sourceRoot":"","sources":["../src/collision.ts"],"names":[],"mappings":"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"}

package/dist/collision.js

@@ -144,6 +144,123 @@ export function resolveRectY(rect, map, newY) {
     }
     return { y, hitTop, hitBottom };
 }
+/**
+ * Extract a pixel mask from a {@link Bitmap}.
+ * Reads each row's bit data (bit 7 = leftmost pixel) and collects column
+ * indices of set (opaque) pixels into sorted arrays.
+ *
+ * Pre-compute once per sprite definition — the result is immutable and
+ * derived from immutable bitmap data.
+ *
+ * @example
+ * ```ts
+ * const HERO_MASK = bitmapPixelMask(HERO_BMP)
+ * // Now use with masksOverlap() or pixelSolidCount()
+ * ```
+ */
+export function bitmapPixelMask(bitmap) {
+    const bytesPerRow = bitmap.width / 8;
+    const rows = [];
+    let total = 0;
+    for (let row = 0; row < bitmap.height; row++) {
+        const cols = [];
+        for (let col = 0; col < bitmap.width; col++) {
+            const byteIdx = row * bytesPerRow + Math.floor(col / 8);
+            const bitIdx = 7 - (col % 8);
+            if (bitmap.data[byteIdx] & (1 << bitIdx))
+                cols.push(col);
+        }
+        rows.push(cols);
+        total += cols.length;
+    }
+    return { width: bitmap.width, height: bitmap.height, rows, totalPixels: total };
+}
+/**
+ * Count opaque pixels of mask `a` at `(ax, ay)` that overlap with
+ * opaque pixels of mask `b` at `(bx, by)`.
+ *
+ * Returns 0 when no overlap. Any value > 0 means pixel-perfect collision.
+ * The count itself is useful for overlap severity — e.g. damage scaling.
+ *
+ * Uses sorted-merge intersection per row — O(pixels) total, no allocations.
+ *
+ * @example
+ * ```ts
+ * const BULLET = bitmapPixelMask(BULLET_BMP)
+ * const ENEMY  = bitmapPixelMask(ENEMY_BMP)
+ *
+ * if (masksOverlap(BULLET, bx, by, ENEMY, ex, ey) > 0) {
+ *   destroyEnemy()
+ * }
+ * ```
+ */
+export function masksOverlap(a, ax, ay, b, bx, by) {
+    const top = Math.max(ay, by);
+    const bot = Math.min(ay + a.height, by + b.height);
+    if (top >= bot)
+        return 0;
+    if (ax >= bx + b.width || ax + a.width <= bx)
+        return 0;
+    let count = 0;
+    for (let y = top; y < bot; y++) {
+        const rowA = a.rows[y - ay];
+        const rowB = b.rows[y - by];
+        if (rowA.length === 0 || rowB.length === 0)
+            continue;
+        let i = 0, j = 0;
+        while (i < rowA.length && j < rowB.length) {
+            const ca = rowA[i] + ax;
+            const cb = rowB[j] + bx;
+            if (ca === cb) {
+                count++;
+                i++;
+                j++;
+            }
+            else if (ca < cb)
+                i++;
+            else
+                j++;
+        }
+    }
+    return count;
+}
+/**
+ * Count opaque pixels of a mask at `(mx, my)` that sit on solid tiles
+ * in a {@link TileMap}. Pixel-precise replacement for AABB-based checks.
+ *
+ * Solves the "character standing on a platform edge" problem: a round
+ * sprite with narrow feet can hang over the edge — only real foot pixels
+ * are checked, not the full bounding box.
+ *
+ * ```
+ * AABB (16px wide):    ████████████████  → full-width overlap check
+ * pixelSolidCount:     ···██····██····  → only feet matter
+ * ```
+ *
+ * @example
+ * ```ts
+ * const HERO_MASK = bitmapPixelMask(HERO_BMP)
+ *
+ * // Check if standing: test 1px below current position
+ * const standing = pixelSolidCount(HERO_MASK, hero.x, hero.y + 1, map) > 0
+ *
+ * // Check wall to the right
+ * const wallRight = pixelSolidCount(HERO_MASK, hero.x + 1, hero.y, map) > 0
+ * ```
+ */
+export function pixelSolidCount(mask, mx, my, map) {
+    let count = 0;
+    for (let row = 0; row < mask.height; row++) {
+        const worldY = my + row;
+        const tileY = Math.floor(worldY / CELL);
+        for (const col of mask.rows[row]) {
+            if (map.isSolid(Math.floor((mx + col) / CELL), tileY))
+                count++;
+        }
+    }
+    return count;
+}
+// ─── AABB sprite wrappers (backward-compatible) ─────────────────────────────
 /**
  * Resolves a proposed horizontal movement for an 8×8 sprite against solid tiles.
  * Thin wrapper over {@link resolveRectX} preserved for backward compatibility.

package/dist/collision.js.map

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

package/dist/i18n.d.ts

@@ -0,0 +1,43 @@
+/**
+ * i18n.ts — locale selection helper.
+ *
+ * A tiny, dependency-free utility for picking a string pack at runtime
+ * based on a language code. Designed so any zx-kit game can ship with
+ * multiple translations and switch them via a single config flag.
+ *
+ * USAGE
+ * ─────
+ * Each locale exports the same shape — usually as named string constants
+ * and template functions (e.g. `STR_DEPTH = (m) => \`D:${m}M\``).
+ * Import each locale module as a namespace and hand them to `pickLocale`:
+ *
+ *   import * as en from './strings.ts'        // default English
+ *   import * as sk from './strings.sk.ts'     // Slovak
+ *   import * as ru from './strings.ru.ts'     // Russian
+ *   import { LANGUAGE_CODE } from './config.ts'
+ *
+ *   export const L = pickLocale(en, { sk, ru }, LANGUAGE_CODE)
+ *
+ * Consumers then read `L.STR_DEPTH(120)` etc. — same name, swapped values.
+ *
+ * SELECTION RULES
+ * ───────────────
+ * - `code` null / undefined / empty       → returns `defaultLocale`
+ * - `code` matches a key in `locales`     → returns that locale
+ *   (case-insensitive: 'SK' === 'sk')
+ * - `code` doesn't match anything         → returns `defaultLocale`
+ *
+ * The default key (typically 'en') doesn't need to live in the `locales`
+ * map — passing 'en' simply falls through to `defaultLocale`. This keeps
+ * the English source-of-truth file at the conventional `strings.ts` path
+ * without forcing a `strings.en.ts` rename.
+ */
+/**
+ * Pick a locale object from a map by code, with fallback to a default.
+ *
+ * Generic over `T` so every entry in `locales` is type-checked against the
+ * shape of `defaultLocale` — adding a new translation that misses a key
+ * (or has a wrong signature) becomes a compile error.
+ */
+export declare function pickLocale<T>(defaultLocale: T, locales: Record<string, T>, code: string | null | undefined): T;
+//# sourceMappingURL=i18n.d.ts.map

package/dist/i18n.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i18n.d.ts","sourceRoot":"","sources":["../src/i18n.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAC1B,aAAa,EAAE,CAAC,EAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,EAC1B,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC9B,CAAC,CAIH"}

package/dist/i18n.js

@@ -0,0 +1,48 @@
+/**
+ * i18n.ts — locale selection helper.
+ *
+ * A tiny, dependency-free utility for picking a string pack at runtime
+ * based on a language code. Designed so any zx-kit game can ship with
+ * multiple translations and switch them via a single config flag.
+ *
+ * USAGE
+ * ─────
+ * Each locale exports the same shape — usually as named string constants
+ * and template functions (e.g. `STR_DEPTH = (m) => \`D:${m}M\``).
+ * Import each locale module as a namespace and hand them to `pickLocale`:
+ *
+ *   import * as en from './strings.ts'        // default English
+ *   import * as sk from './strings.sk.ts'     // Slovak
+ *   import * as ru from './strings.ru.ts'     // Russian
+ *   import { LANGUAGE_CODE } from './config.ts'
+ *
+ *   export const L = pickLocale(en, { sk, ru }, LANGUAGE_CODE)
+ *
+ * Consumers then read `L.STR_DEPTH(120)` etc. — same name, swapped values.
+ *
+ * SELECTION RULES
+ * ───────────────
+ * - `code` null / undefined / empty       → returns `defaultLocale`
+ * - `code` matches a key in `locales`     → returns that locale
+ *   (case-insensitive: 'SK' === 'sk')
+ * - `code` doesn't match anything         → returns `defaultLocale`
+ *
+ * The default key (typically 'en') doesn't need to live in the `locales`
+ * map — passing 'en' simply falls through to `defaultLocale`. This keeps
+ * the English source-of-truth file at the conventional `strings.ts` path
+ * without forcing a `strings.en.ts` rename.
+ */
+/**
+ * Pick a locale object from a map by code, with fallback to a default.
+ *
+ * Generic over `T` so every entry in `locales` is type-checked against the
+ * shape of `defaultLocale` — adding a new translation that misses a key
+ * (or has a wrong signature) becomes a compile error.
+ */
+export function pickLocale(defaultLocale, locales, code) {
+    if (!code)
+        return defaultLocale;
+    const normalised = code.toLowerCase();
+    return locales[normalised] ?? defaultLocale;
+}
+//# sourceMappingURL=i18n.js.map

package/dist/i18n.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"i18n.js","sourceRoot":"","sources":["../src/i18n.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CACxB,aAAgB,EAChB,OAA0B,EAC1B,IAA+B;IAE/B,IAAI,CAAC,IAAI;QAAE,OAAO,aAAa,CAAA;IAC/B,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,EAAE,CAAA;IACrC,OAAO,OAAO,CAAC,UAAU,CAAC,IAAI,aAAa,CAAA;AAC7C,CAAC"}

package/dist/index.d.ts

@@ -12,4 +12,5 @@ export * from './animation.js';
 export * from './camera.js';
 export * from './scene.js';
 export * from './save.js';
+export * from './i18n.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,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA;AAC5B,cAAc,SAAS,CAAA;AACvB,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,SAAS,CAAA;AACvB,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA"}

package/dist/index.js

@@ -12,4 +12,5 @@ export * from './animation.js';
 export * from './camera.js';
 export * from './scene.js';
 export * from './save.js';
+export * from './i18n.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,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA;AAC5B,cAAc,SAAS,CAAA;AACvB,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,SAAS,CAAA;AACvB,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA"}

package/package.json

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