zx-kit 0.7.0 → 0.9.0

package/README.md

@@ -2,8 +2,6 @@
 
 Reusable ZX Spectrum primitives for browser games built with Vite + TypeScript + Canvas + Web Audio API.
 
-Current npm package: `zx-kit@0.6.7`.
-
 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.
 
 ---
@@ -660,30 +658,308 @@ console.log(`${gemsLeft} gems remaining`)
 
 ---
 
+### `sprite.ts` — Free-roaming entity system
+
+Sprites are entities that move freely in pixel space — not locked to the tile grid like `TileMap` cells. Use sprites for players, enemies, bullets, particles: anything that moves at sub-pixel precision or with physics.
+
+Sprites use the same 8×8 bitmap format as `drawSprite` and the same `SpectrumColor` palette. They integrate directly with `resolveX` / `resolveY` from `collision.ts` and with `TileMap.isSolid` for platformer-style collision detection.
+
+#### `Sprite` interface
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `x` | `number` | `0` | Horizontal position in game pixels (float allowed — rounded on render) |
+| `y` | `number` | `0` | Vertical position in game pixels |
+| `vx` | `number` | `0` | Horizontal velocity in pixels per millisecond |
+| `vy` | `number` | `0` | Vertical velocity in pixels per millisecond |
+| `bitmap` | `Uint8Array` | — | 8-byte sprite — one byte per row, bit 7 = leftmost pixel |
+| `ink` | `SpectrumColor` | — | Foreground colour (`C.*` palette value) |
+| `paper` | `SpectrumColor \| null` | `null` | Background colour, or `null` for transparent background |
+| `flipX` | `boolean` | `false` | Render mirrored horizontally. Flipped bitmap is cached — no per-frame allocation |
+| `visible` | `boolean` | `true` | When `false`, `renderSprite` skips this entity entirely |
+
+#### `createSprite(bitmap, ink, paper?): Sprite`
+
+Creates a `Sprite` at `(0, 0)` with zero velocity. `paper` defaults to `null` (transparent background).
+
+```ts
+import { createSprite, C } from 'zx-kit'
+
+const PLAYER_BM = new Uint8Array([0x18, 0x3C, 0x7E, 0xFF, 0xFF, 0x7E, 0x18, 0x3C])
+const BULLET_BM = new Uint8Array([0x00, 0x00, 0x18, 0x18, 0x18, 0x18, 0x00, 0x00])
+
+const player = createSprite(PLAYER_BM, C.B_CYAN)          // transparent bg
+const bullet = createSprite(BULLET_BM, C.B_WHITE, C.BLACK) // opaque bg
+player.x = 16
+player.y = 80
+```
+
+#### `moveSprite(sprite, dt): void`
+
+Advances `sprite.x` by `vx * dt` and `sprite.y` by `vy * dt`. Call once per frame **before** collision resolution.
+
+```ts
+// Typical frame update order:
+applyGravity(player, 0.003, dt)
+moveSprite(player, dt)
+const rx = resolveX(player, map, player.x)
+const ry = resolveY(player, map, player.y)
+player.x = rx.x
+player.y = ry.y
+if (ry.hitBottom) player.vy = 0
+```
+
+#### `applyGravity(sprite, gravity, dt): void`
+
+Adds `gravity * dt` to `sprite.vy`. Call once per frame **before** `moveSprite`.
+
+- `gravity` is in pixels per millisecond² — typical values: `0.002`–`0.005`
+- Accumulates naturally across frames so the sprite accelerates while airborne
+
+```ts
+// Gentle gravity (platformer)
+applyGravity(player, 0.003, dt)
+
+// Strong gravity (bullet hell with falling debris)
+applyGravity(debris, 0.008, dt)
+```
+
+#### `renderSprite(ctx, sprite): void`
+
+Draws the sprite at `(Math.round(sprite.x), Math.round(sprite.y))`.
+Skips if `sprite.visible === false`.
+Respects `flipX` (cached mirror) and `paper: null` (transparent — only ink pixels drawn).
+
+Call **after** all physics updates and collision resolution, as the last step before `drawScanlines`.
+
+```ts
+// Transparent sprite over a scrolling background
+player.paper = null   // default — no background square
+renderSprite(ctx, player)
+
+// Opaque sprite (always paints its 8×8 cell background)
+bullet.paper = C.BLACK
+renderSprite(ctx, bullet)
+
+// Facing direction
+player.flipX = (player.vx < 0)
+renderSprite(ctx, player)
+```
+
+#### Full example — platformer player
+
+```ts
+import { createSprite, moveSprite, applyGravity, renderSprite, C, CELL } from 'zx-kit'
+import { resolveX, resolveY } from 'zx-kit'
+import { tickMovement, consumeFlag } from 'zx-kit'
+
+const PLAYER_BM = new Uint8Array([0x18, 0x3C, 0x7E, 0xFF, 0xFF, 0x7E, 0x24, 0x66])
+
+const player = createSprite(PLAYER_BM, C.B_CYAN)
+player.x = 2 * CELL
+player.y = 10 * CELL
+
+let onGround = false
+const JUMP_VELOCITY = -0.25    // pixels/ms upward
+const WALK_VELOCITY =  0.08    // pixels/ms horizontal
+const GRAVITY       =  0.003   // pixels/ms²
+
+function updatePlayer(dt: number, map: TileMap) {
+  // Input
+  const dir = tickMovement(dt)
+  player.vx = dir === 'right' ?  WALK_VELOCITY
+            : dir === 'left'  ? -WALK_VELOCITY
+            : 0
+  if (dir === 'up' && onGround) player.vy = JUMP_VELOCITY
+
+  // Flip sprite to face movement direction
+  if (player.vx < 0) player.flipX = true
+  if (player.vx > 0) player.flipX = false
+
+  // Physics
+  applyGravity(player, GRAVITY, dt)
+  moveSprite(player, dt)
+
+  // Collision
+  const rx = resolveX(player, map, player.x)
+  player.x = rx.x
+  if (rx.hitLeft || rx.hitRight) player.vx = 0
+
+  const ry = resolveY(player, map, player.y)
+  player.y = ry.y
+  onGround = ry.hitBottom
+  if (ry.hitBottom || ry.hitTop) player.vy = 0
+}
+```
+
+---
+
+### `collision.ts` — AABB collision detection and resolution
+
+Axis-aligned bounding box (AABB) helpers for sprite-vs-sprite overlap tests and sprite-vs-`TileMap` collision resolution. All coordinates are in game pixels.
+
+#### `Rect` interface
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `x` | `number` | Left edge in game pixels |
+| `y` | `number` | Top edge in game pixels |
+| `w` | `number` | Width in game pixels |
+| `h` | `number` | Height in game pixels |
+
+#### `spriteRect(sprite): Rect`
+
+Returns the bounding `Rect` for a sprite — always `CELL × CELL` at the sprite's current position. Uses the raw float position (no rounding) for accurate same-frame overlap tests.
+
+```ts
+const rect = spriteRect(player)   // { x: 24.5, y: 80.0, w: 8, h: 8 }
+```
+
+#### `rectsOverlap(a, b): boolean`
+
+Returns `true` when rectangles share at least one pixel. Touching edges (zero-area overlap) returns `false`.
+
+```ts
+rectsOverlap(spriteRect(bullet), spriteRect(enemy))  // hit test
+rectsOverlap({ x: 0, y: 0, w: 32, h: 32 }, { x: 16, y: 16, w: 8, h: 8 })  // contained → true
+```
+
+#### `spritesOverlap(a, b): boolean`
+
+Shorthand for `rectsOverlap(spriteRect(a), spriteRect(b))`.
+
+```ts
+if (spritesOverlap(player, coin)) collectCoin(coin)
+if (bullets.some(b => spritesOverlap(b, player))) loseLife()
+```
+
+#### `isSolidAt(map, px, py): boolean`
+
+Tests whether the game pixel `(px, py)` falls inside a solid tile. Converts to tile coordinates via `Math.floor(px / CELL)`. Out-of-bounds pixels return `true` — the map boundary is an implicit solid wall.
+
+```ts
+// Is the pixel directly below the player's feet solid?
+if (isSolidAt(map, player.x, player.y + CELL)) onGround = true
+
+// Same check via resolveY — usually more convenient
+```
+
+#### `resolveX(sprite, map, newX): { x, hitLeft, hitRight }`
+
+Resolves a proposed horizontal move against solid tiles. Tests the leading edge of the sprite's bounding box at `newX` and returns the clamped position plus hit flags.
+
+- `hitLeft` — the sprite hit a wall while moving left
+- `hitRight` — the sprite hit a wall while moving right
+- Always returns the original `newX` (unclamped) when no collision occurs
+- Out-of-bounds overshoot is clamped correctly — the map boundary acts as an implicit wall
+
+```ts
+moveSprite(player, dt)
+const { x, hitLeft, hitRight } = resolveX(player, map, player.x)
+player.x = x
+if (hitLeft || hitRight) player.vx = 0
+```
+
+#### `resolveY(sprite, map, newY): { y, hitTop, hitBottom }`
+
+Resolves a proposed vertical move against solid tiles. Same contract as `resolveX`.
+
+- `hitBottom` — the sprite landed on a floor tile (use to detect "on ground" for jump logic)
+- `hitTop` — the sprite bumped its head on a ceiling tile
+
+```ts
+applyGravity(player, 0.003, dt)
+moveSprite(player, dt)
+const { y, hitBottom, hitTop } = resolveY(player, map, player.y)
+player.y = y
+if (hitBottom) { player.vy = 0; onGround = true }
+if (hitTop)    { player.vy = 0 }
+```
+
+#### Full example — bullet hell enemy swarm
+
+```ts
+import { createSprite, moveSprite, renderSprite, spritesOverlap, C, CELL } from 'zx-kit'
+import type { Sprite } from 'zx-kit'
+
+const BULLET_BM = new Uint8Array([0x00, 0x18, 0x3C, 0x3C, 0x3C, 0x3C, 0x18, 0x00])
+const ENEMY_BM  = new Uint8Array([0x3C, 0x7E, 0xFF, 0xDB, 0xFF, 0x66, 0x42, 0x81])
+
+const bullets: Sprite[] = []
+const enemies: Sprite[] = []
+
+// Spawn a bullet traveling upward
+function fireBullet(x: number, y: number) {
+  const b = createSprite(BULLET_BM, C.B_YELLOW)
+  b.x = x; b.y = y; b.vy = -0.3  // pixels/ms upward
+  bullets.push(b)
+}
+
+// Spawn enemies in a row
+for (let i = 0; i < 8; i++) {
+  const e = createSprite(ENEMY_BM, C.B_RED, C.BLACK)
+  e.x = i * 2 * CELL + 8
+  e.y = 2 * CELL
+  e.vx = 0.03 * (i % 2 === 0 ? 1 : -1)  // alternate directions
+  enemies.push(e)
+}
+
+// Per-frame update
+function updateBulletHell(dt: number) {
+  // Move all bullets
+  for (const b of bullets) moveSprite(b, dt)
+
+  // Move all enemies
+  for (const e of enemies) moveSprite(e, dt)
+
+  // Hit tests — O(bullets × enemies), fine for dozens of sprites
+  for (const b of bullets) {
+    for (const e of enemies) {
+      if (e.visible && b.visible && spritesOverlap(b, e)) {
+        b.visible = false   // bullet disappears
+        e.visible = false   // enemy explodes
+      }
+    }
+  }
+
+  // Remove off-screen bullets
+  bullets.splice(0, bullets.length, ...bullets.filter(b => b.visible && b.y > -CELL))
+
+  // Render
+  for (const e of enemies) if (e.visible) renderSprite(ctx, e)
+  for (const b of bullets) if (b.visible) renderSprite(ctx, b)
+}
+```
+
+---
+
 ## File structure
 
 ```
 zx-kit/
-├── package.json         # exports: { ".": "./dist/index.js" }
-├── tsconfig.json        # strict, emits to dist/
+├── package.json           # exports: { ".": "./dist/index.js" }
+├── tsconfig.json          # strict, emits to dist/
 ├── README.md
-├── src/                 # TypeScript source
-│   ├── index.ts         # barrel — re-exports everything
-│   ├── palette.ts       # SCALE, CELL, C, SpectrumColor
-│   ├── font.ts          # FONT, getCharRow
-│   ├── renderer.ts      # setupCanvas, mirrorSprite, drawSprite, drawChar, drawText,
-│   │                    # drawTextCentered, flashBorder
-│   ├── audio.ts         # initAudio, resumeAudio, beep, playPattern, Note,
-│   │                    # getAudioContext, getMasterGain,
-│   │                    # getMasterVolume, setMasterVolume,
-│   │                    # increaseVolume, decreaseVolume
-│   ├── input.ts         # initInput, tickMovement, consumeFlag/Debug/Pause/AnyKey,
-│   │                    # isHeld, resetInput, Direction
-│   ├── ui.ts            # drawBox, drawFrame, drawPanelTitle,
-│   │                    # drawProgressBar, tickUI, renderUI, resetUI,
-│   │                    # BorderOptions, DrawProgressBarOptions
-│   └── tilemap.ts       # createTileMap, Tile, Viewport, TileMap
-└── dist/                # compiled output (generated by npm run build)
+├── src/                   # TypeScript source
+│   ├── index.ts           # barrel — re-exports everything
+│   ├── palette.ts         # SCALE, CELL, C, SpectrumColor
+│   ├── font.ts            # FONT, getCharRow
+│   ├── renderer.ts        # setupCanvas, mirrorSprite, drawSprite, drawChar, drawText,
+│   │                      # drawTextCentered, flashBorder, drawScanlines
+│   ├── audio.ts           # initAudio, resumeAudio, beep, playPattern, Note,
+│   │                      # getAudioContext, getMasterGain,
+│   │                      # getMasterVolume, setMasterVolume,
+│   │                      # increaseVolume, decreaseVolume
+│   ├── input.ts           # initInput, tickMovement, consumeFlag/Debug/Pause/AnyKey,
+│   │                      # isHeld, resetInput, Direction
+│   ├── ui.ts              # drawBox, drawFrame, drawPanelTitle,
+│   │                      # drawProgressBar, tickUI, renderUI, resetUI,
+│   │                      # BorderOptions, DrawProgressBarOptions
+│   ├── tilemap.ts         # createTileMap, Tile, Viewport, TileMap
+│   ├── sprite.ts          # Sprite, createSprite, moveSprite, applyGravity, renderSprite
+│   └── collision.ts       # Rect, spriteRect, rectsOverlap, spritesOverlap,
+│                          # isSolidAt, resolveX, resolveY
+└── dist/                  # compiled output (generated by npm run build)
     ├── index.js / .d.ts
     └── ...
 ```

package/dist/collision.d.ts

@@ -0,0 +1,87 @@
+import type { Sprite } from './sprite.js';
+import type { TileMap } from './tilemap.js';
+/**
+ * Axis-aligned bounding rectangle in game pixels.
+ */
+export interface Rect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/**
+ * Returns the bounding `Rect` for a sprite (always `CELL × CELL`).
+ * Position is taken from `sprite.x / sprite.y` without rounding —
+ * use this for precise overlap tests during the same frame the sprite moved.
+ */
+export declare function spriteRect(sprite: Sprite): Rect;
+/**
+ * Returns `true` when rectangles `a` and `b` overlap (share at least one pixel).
+ * Touching edges (shared border, zero overlap area) returns `false`.
+ *
+ * @example
+ * if (rectsOverlap(spriteRect(bullet), spriteRect(enemy))) { hitEnemy() }
+ */
+export declare function rectsOverlap(a: Rect, b: Rect): boolean;
+/**
+ * Shorthand for `rectsOverlap(spriteRect(a), spriteRect(b))`.
+ *
+ * @example
+ * if (spritesOverlap(player, coin)) collectCoin()
+ */
+export declare function spritesOverlap(a: Sprite, b: Sprite): boolean;
+/**
+ * Returns `true` when the game pixel at `(px, py)` falls inside a solid tile.
+ * Converts pixel coords to tile coords via integer division by `CELL`.
+ * Out-of-bounds pixels are treated as solid (map boundary is an implicit wall).
+ *
+ * @example
+ * if (isSolidAt(map, player.x, player.y + CELL)) { player.vy = 0 } // on floor
+ */
+export declare function isSolidAt(map: TileMap, px: number, py: number): boolean;
+/**
+ * Resolves a proposed horizontal movement for a sprite against solid tiles.
+ * Tests the leading edge of the sprite's bounding box at the target x position.
+ * Returns the clamped x coordinate and collision flags.
+ *
+ * Call BEFORE `resolveY` so each axis is resolved independently.
+ *
+ * @param sprite - Sprite being moved (uses current `sprite.y` for vertical extent)
+ * @param map    - Tile map to test solidity against
+ * @param newX   - Proposed new x position (after `moveSprite`)
+ *
+ * @example
+ * moveSprite(player, dt)
+ * const rx = resolveX(player, map, player.x)
+ * player.x = rx.x
+ * if (rx.hitLeft || rx.hitRight) player.vx = 0
+ */
+export declare function resolveX(sprite: Sprite, map: TileMap, newX: number): {
+    x: number;
+    hitLeft: boolean;
+    hitRight: boolean;
+};
+/**
+ * Resolves a proposed vertical movement for a sprite against solid tiles.
+ * Tests the leading edge of the sprite's bounding box at the target y position.
+ * Returns the clamped y coordinate and collision flags.
+ *
+ * Typical platformer pattern: `hitBottom` means the sprite landed on a floor.
+ * Zero out `vy` on `hitBottom` and `hitTop` to prevent tunnelling.
+ *
+ * @param sprite - Sprite being moved (uses current `sprite.x` for horizontal extent)
+ * @param map    - Tile map to test solidity against
+ * @param newY   - Proposed new y position (after `moveSprite`)
+ *
+ * @example
+ * const ry = resolveY(player, map, player.y)
+ * player.y = ry.y
+ * if (ry.hitBottom) { player.vy = 0; onGround = true }
+ * if (ry.hitTop)    { player.vy = 0 }
+ */
+export declare function resolveY(sprite: Sprite, map: TileMap, newY: number): {
+    y: number;
+    hitTop: boolean;
+    hitBottom: boolean;
+};
+//# sourceMappingURL=collision.d.ts.map

package/dist/collision.d.ts.map

@@ -0,0 +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;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;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAEvE;AAED;;;;;;;;;;;;;;;;GAgBG;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,CAyBpD;AAED;;;;;;;;;;;;;;;;;GAiBG;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,CAwBpD"}

package/dist/collision.js

@@ -0,0 +1,127 @@
+import { CELL } from './palette.js';
+/**
+ * Returns the bounding `Rect` for a sprite (always `CELL × CELL`).
+ * Position is taken from `sprite.x / sprite.y` without rounding —
+ * use this for precise overlap tests during the same frame the sprite moved.
+ */
+export function spriteRect(sprite) {
+    return { x: sprite.x, y: sprite.y, w: CELL, h: CELL };
+}
+/**
+ * Returns `true` when rectangles `a` and `b` overlap (share at least one pixel).
+ * Touching edges (shared border, zero overlap area) returns `false`.
+ *
+ * @example
+ * if (rectsOverlap(spriteRect(bullet), spriteRect(enemy))) { hitEnemy() }
+ */
+export function rectsOverlap(a, b) {
+    return a.x < b.x + b.w &&
+        a.x + a.w > b.x &&
+        a.y < b.y + b.h &&
+        a.y + a.h > b.y;
+}
+/**
+ * Shorthand for `rectsOverlap(spriteRect(a), spriteRect(b))`.
+ *
+ * @example
+ * if (spritesOverlap(player, coin)) collectCoin()
+ */
+export function spritesOverlap(a, b) {
+    return rectsOverlap(spriteRect(a), spriteRect(b));
+}
+/**
+ * Returns `true` when the game pixel at `(px, py)` falls inside a solid tile.
+ * Converts pixel coords to tile coords via integer division by `CELL`.
+ * Out-of-bounds pixels are treated as solid (map boundary is an implicit wall).
+ *
+ * @example
+ * if (isSolidAt(map, player.x, player.y + CELL)) { player.vy = 0 } // on floor
+ */
+export function isSolidAt(map, px, py) {
+    return map.isSolid(Math.floor(px / CELL), Math.floor(py / CELL));
+}
+/**
+ * Resolves a proposed horizontal movement for a sprite against solid tiles.
+ * Tests the leading edge of the sprite's bounding box at the target x position.
+ * Returns the clamped x coordinate and collision flags.
+ *
+ * Call BEFORE `resolveY` so each axis is resolved independently.
+ *
+ * @param sprite - Sprite being moved (uses current `sprite.y` for vertical extent)
+ * @param map    - Tile map to test solidity against
+ * @param newX   - Proposed new x position (after `moveSprite`)
+ *
+ * @example
+ * moveSprite(player, dt)
+ * const rx = resolveX(player, map, player.x)
+ * player.x = rx.x
+ * if (rx.hitLeft || rx.hitRight) player.vx = 0
+ */
+export function resolveX(sprite, map, newX) {
+    const y0 = sprite.y;
+    const y1 = sprite.y + CELL - 1;
+    let x = newX;
+    let hitLeft = false;
+    let hitRight = false;
+    if (newX < sprite.x) {
+        // Moving left — check left edge
+        if (isSolidAt(map, newX, y0) || isSolidAt(map, newX, y1)) {
+            // Clamp to in-bounds before computing tile column (avoids negative col from OOB overshoot)
+            const safeX = Math.max(0, newX);
+            x = (Math.floor(safeX / CELL) + 1) * CELL;
+            hitLeft = true;
+        }
+    }
+    else if (newX > sprite.x) {
+        // Moving right — check right edge
+        if (isSolidAt(map, newX + CELL - 1, y0) || isSolidAt(map, newX + CELL - 1, y1)) {
+            const safeEdge = Math.min(map.cols * CELL - 1, newX + CELL - 1);
+            x = Math.floor(safeEdge / CELL) * CELL - CELL;
+            hitRight = true;
+        }
+    }
+    return { x, hitLeft, hitRight };
+}
+/**
+ * Resolves a proposed vertical movement for a sprite against solid tiles.
+ * Tests the leading edge of the sprite's bounding box at the target y position.
+ * Returns the clamped y coordinate and collision flags.
+ *
+ * Typical platformer pattern: `hitBottom` means the sprite landed on a floor.
+ * Zero out `vy` on `hitBottom` and `hitTop` to prevent tunnelling.
+ *
+ * @param sprite - Sprite being moved (uses current `sprite.x` for horizontal extent)
+ * @param map    - Tile map to test solidity against
+ * @param newY   - Proposed new y position (after `moveSprite`)
+ *
+ * @example
+ * const ry = resolveY(player, map, player.y)
+ * player.y = ry.y
+ * if (ry.hitBottom) { player.vy = 0; onGround = true }
+ * if (ry.hitTop)    { player.vy = 0 }
+ */
+export function resolveY(sprite, map, newY) {
+    const x0 = sprite.x;
+    const x1 = sprite.x + CELL - 1;
+    let y = newY;
+    let hitTop = false;
+    let hitBottom = false;
+    if (newY < sprite.y) {
+        // Moving up — check top edge
+        if (isSolidAt(map, x0, newY) || isSolidAt(map, x1, newY)) {
+            const safeY = Math.max(0, newY);
+            y = (Math.floor(safeY / CELL) + 1) * CELL;
+            hitTop = true;
+        }
+    }
+    else if (newY > sprite.y) {
+        // Moving down — check bottom edge
+        if (isSolidAt(map, x0, newY + CELL - 1) || isSolidAt(map, x1, newY + CELL - 1)) {
+            const safeEdge = Math.min(map.rows * CELL - 1, newY + CELL - 1);
+            y = Math.floor(safeEdge / CELL) * CELL - CELL;
+            hitBottom = true;
+        }
+    }
+    return { y, hitTop, hitBottom };
+}
+//# sourceMappingURL=collision.js.map

package/dist/collision.js.map

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

package/dist/index.d.ts

@@ -5,4 +5,6 @@ export * from './audio.js';
 export * from './input.js';
 export * from './ui.js';
 export * from './tilemap.js';
+export * from './sprite.js';
+export * from './collision.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;AACvB,cAAc,cAAc,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;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA"}

package/dist/index.js

@@ -5,4 +5,6 @@ export * from './audio.js';
 export * from './input.js';
 export * from './ui.js';
 export * from './tilemap.js';
+export * from './sprite.js';
+export * from './collision.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;AACvB,cAAc,cAAc,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;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA"}

package/dist/renderer.d.ts

@@ -17,6 +17,26 @@ import { type SpectrumColor } from './palette.js';
  * const ctx = setupCanvas(canvas, 4, 256, 208) // taller canvas for status rows
  */
 export declare function setupCanvas(canvas: HTMLCanvasElement, scale: number, width?: number, height?: number): CanvasRenderingContext2D;
+/**
+ * Applies a CRT monitor curvature effect to the canvas element via CSS.
+ *
+ * Current implementation: rounded corners (`border-radius`), inset edge shadow,
+ * and a subtle perspective tilt. This is a deliberate abstraction — the CSS
+ * internals may be replaced by WebGL barrel distortion in a future version
+ * without changing this API signature.
+ *
+ * Call once after `setupCanvas`. Call again with `intensity = 0` to remove.
+ *
+ * @param canvas    - The `<canvas>` element to apply the effect to
+ * @param intensity - Strength 0–1 (default `1`; `0` removes all effect)
+ *
+ * @example
+ * const ctx = setupCanvas(canvas, 4)
+ * curveDisplay(canvas)        // default full intensity
+ * curveDisplay(canvas, 0.5)   // subtle effect
+ * curveDisplay(canvas, 0)     // remove effect
+ */
+export declare function curveDisplay(canvas: HTMLCanvasElement, intensity?: number): void;
 /**
  * Flips an 8×8 sprite horizontally. Returns a new `Uint8Array`.
  * Use to derive left-facing sprites from right-facing definitions at module load time.

package/dist/renderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../src/renderer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,aAAa,EAAE,MAAM,cAAc,CAAA;AAiB1D;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,iBAAiB,EACzB,KAAK,EAAE,MAAM,EACb,KAAK,SAAM,EACX,MAAM,SAAM,GACX,wBAAwB,CAS1B;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,UAAU,GAAG,UAAU,CAUxD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CACxB,GAAG,EAAE,wBAAwB,EAC7B,MAAM,EAAE,UAAU,EAClB,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EACpB,GAAG,EAAE,aAAa,EAAE,KAAK,EAAE,aAAa,GACvC,IAAI,CAKN;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,QAAQ,CACtB,GAAG,EAAE,wBAAwB,EAC7B,IAAI,EAAE,MAAM,EACZ,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EACpB,GAAG,EAAE,aAAa,EAAE,KAAK,CAAC,EAAE,aAAa,GACxC,IAAI,CAON;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CACtB,GAAG,EAAE,wBAAwB,EAC7B,IAAI,EAAE,MAAM,EACZ,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EACpB,GAAG,EAAE,aAAa,EAAE,KAAK,CAAC,EAAE,aAAa,GACxC,IAAI,CAIN;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,wBAAwB,EAC7B,IAAI,EAAE,MAAM,EACZ,CAAC,EAAE,MAAM,EACT,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,aAAa,EAAE,KAAK,CAAC,EAAE,aAAa,GACxC,IAAI,CAGN;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,wBAAwB,EAC7B,KAAK,SAAO,GACX,IAAI,CASN;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,aAAa,EACpB,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,EAClB,UAAU,GAAE,aAAuB,GAClC,IAAI,CAWN"}
+{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../src/renderer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,aAAa,EAAE,MAAM,cAAc,CAAA;AAiB1D;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,iBAAiB,EACzB,KAAK,EAAE,MAAM,EACb,KAAK,SAAM,EACX,MAAM,SAAM,GACX,wBAAwB,CAS1B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,iBAAiB,EAAE,SAAS,SAAI,GAAG,IAAI,CAW3E;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,UAAU,GAAG,UAAU,CAUxD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CACxB,GAAG,EAAE,wBAAwB,EAC7B,MAAM,EAAE,UAAU,EAClB,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EACpB,GAAG,EAAE,aAAa,EAAE,KAAK,EAAE,aAAa,GACvC,IAAI,CAKN;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,QAAQ,CACtB,GAAG,EAAE,wBAAwB,EAC7B,IAAI,EAAE,MAAM,EACZ,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EACpB,GAAG,EAAE,aAAa,EAAE,KAAK,CAAC,EAAE,aAAa,GACxC,IAAI,CAON;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CACtB,GAAG,EAAE,wBAAwB,EAC7B,IAAI,EAAE,MAAM,EACZ,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EACpB,GAAG,EAAE,aAAa,EAAE,KAAK,CAAC,EAAE,aAAa,GACxC,IAAI,CAIN;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,wBAAwB,EAC7B,IAAI,EAAE,MAAM,EACZ,CAAC,EAAE,MAAM,EACT,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,aAAa,EAAE,KAAK,CAAC,EAAE,aAAa,GACxC,IAAI,CAGN;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,wBAAwB,EAC7B,KAAK,SAAO,GACX,IAAI,CASN;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,aAAa,EACpB,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,EAClB,UAAU,GAAE,aAAuB,GAClC,IAAI,CAWN"}

package/dist/renderer.js

@@ -36,6 +36,37 @@ export function setupCanvas(canvas, scale, width = 256, height = 192) {
     ctx.scale(scale, scale);
     return ctx;
 }
+/**
+ * Applies a CRT monitor curvature effect to the canvas element via CSS.
+ *
+ * Current implementation: rounded corners (`border-radius`), inset edge shadow,
+ * and a subtle perspective tilt. This is a deliberate abstraction — the CSS
+ * internals may be replaced by WebGL barrel distortion in a future version
+ * without changing this API signature.
+ *
+ * Call once after `setupCanvas`. Call again with `intensity = 0` to remove.
+ *
+ * @param canvas    - The `<canvas>` element to apply the effect to
+ * @param intensity - Strength 0–1 (default `1`; `0` removes all effect)
+ *
+ * @example
+ * const ctx = setupCanvas(canvas, 4)
+ * curveDisplay(canvas)        // default full intensity
+ * curveDisplay(canvas, 0.5)   // subtle effect
+ * curveDisplay(canvas, 0)     // remove effect
+ */
+export function curveDisplay(canvas, intensity = 1) {
+    const i = Math.max(0, Math.min(1, intensity));
+    if (i === 0) {
+        canvas.style.borderRadius = '';
+        canvas.style.boxShadow = '';
+        canvas.style.transform = '';
+        return;
+    }
+    canvas.style.borderRadius = `${Math.round(18 * i)}px`;
+    canvas.style.boxShadow = `inset 0 0 ${Math.round(60 * i)}px rgba(0,0,0,${(0.45 * i).toFixed(2)})`;
+    canvas.style.transform = `perspective(${Math.round(800 - 400 * i)}px) rotateX(${(2.5 * i).toFixed(1)}deg)`;
+}
 /**
  * Flips an 8×8 sprite horizontally. Returns a new `Uint8Array`.
  * Use to derive left-facing sprites from right-facing definitions at module load time.

package/dist/renderer.js.map

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

package/dist/sprite.d.ts

@@ -0,0 +1,81 @@
+import { type SpectrumColor } from './palette.js';
+/**
+ * A game entity with position, velocity, and an 8×8 bitmap.
+ * Use `createSprite` to create, `moveSprite` / `applyGravity` to update each frame,
+ * and `renderSprite` to draw.
+ */
+export interface Sprite {
+    /** Horizontal position in game pixels (float allowed — rounded on render). */
+    x: number;
+    /** Vertical position in game pixels (float allowed — rounded on render). */
+    y: number;
+    /** Horizontal velocity in pixels per millisecond. */
+    vx: number;
+    /** Vertical velocity in pixels per millisecond. */
+    vy: number;
+    /** 8-byte sprite bitmap — one byte per row, bit 7 = leftmost pixel. */
+    bitmap: Uint8Array;
+    /** Foreground colour (`C.*` palette value). */
+    ink: SpectrumColor;
+    /**
+     * Background colour, or `null` for a transparent background.
+     * Transparent sprites draw only ink pixels — useful over scrolling backgrounds.
+     */
+    paper: SpectrumColor | null;
+    /** When `true` the sprite is rendered mirrored horizontally. Bitmap is cached. */
+    flipX: boolean;
+    /** When `false` `renderSprite` skips this sprite entirely. */
+    visible: boolean;
+}
+/**
+ * Creates a `Sprite` at position (0, 0) with zero velocity.
+ *
+ * @param bitmap - 8-byte sprite definition
+ * @param ink    - Foreground colour
+ * @param paper  - Background colour, or `null` for transparent (default `null`)
+ *
+ * @example
+ * const player = createSprite(PLAYER_BITMAP, C.B_CYAN)
+ * const bullet = createSprite(BULLET_BITMAP, C.B_WHITE, C.BLACK)
+ */
+export declare function createSprite(bitmap: Uint8Array, ink: SpectrumColor, paper?: SpectrumColor | null): Sprite;
+/**
+ * Advances the sprite position by `vx * dt` and `vy * dt`.
+ * Call once per frame before collision resolution.
+ *
+ * @param sprite - Sprite to update
+ * @param dt     - Elapsed time in milliseconds since last frame
+ *
+ * @example
+ * // Game loop
+ * moveSprite(player, dt)
+ * const { x, hitBottom } = resolveY(player, map, player.y)
+ * player.y = y
+ * if (hitBottom) player.vy = 0
+ */
+export declare function moveSprite(sprite: Sprite, dt: number): void;
+/**
+ * Adds `gravity * dt` to the sprite's vertical velocity.
+ * Call once per frame before `moveSprite`.
+ *
+ * @param sprite  - Sprite to affect
+ * @param gravity - Acceleration in pixels per millisecond² (e.g. `0.003` for gentle gravity)
+ * @param dt      - Elapsed time in milliseconds
+ *
+ * @example
+ * applyGravity(player, 0.003, dt)
+ * moveSprite(player, dt)
+ */
+export declare function applyGravity(sprite: Sprite, gravity: number, dt: number): void;
+/**
+ * Draws the sprite at its current position (rounded to nearest pixel).
+ * Does nothing when `sprite.visible === false`.
+ * Respects `sprite.paper` (transparent when `null`) and `sprite.flipX`.
+ *
+ * Must be called after all position updates and collision resolution for the frame.
+ *
+ * @param ctx    - Canvas 2D context (same one used for the rest of the frame)
+ * @param sprite - Sprite to render
+ */
+export declare function renderSprite(ctx: CanvasRenderingContext2D, sprite: Sprite): void;
+//# sourceMappingURL=sprite.d.ts.map

package/dist/sprite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sprite.d.ts","sourceRoot":"","sources":["../src/sprite.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,cAAc,CAAA;AAGjD;;;;GAIG;AACH,MAAM,WAAW,MAAM;IACrB,8EAA8E;IAC9E,CAAC,EAAE,MAAM,CAAA;IACT,4EAA4E;IAC5E,CAAC,EAAE,MAAM,CAAA;IACT,qDAAqD;IACrD,EAAE,EAAE,MAAM,CAAA;IACV,mDAAmD;IACnD,EAAE,EAAE,MAAM,CAAA;IACV,uEAAuE;IACvE,MAAM,EAAE,UAAU,CAAA;IAClB,+CAA+C;IAC/C,GAAG,EAAE,aAAa,CAAA;IAClB;;;OAGG;IACH,KAAK,EAAE,aAAa,GAAG,IAAI,CAAA;IAC3B,kFAAkF;IAClF,KAAK,EAAE,OAAO,CAAA;IACd,8DAA8D;IAC9D,OAAO,EAAE,OAAO,CAAA;CACjB;AAcD;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,UAAU,EAClB,GAAG,EAAE,aAAa,EAClB,KAAK,GAAE,aAAa,GAAG,IAAW,GACjC,MAAM,CAER;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAG3D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAE9E;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,wBAAwB,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAiBhF"}

package/dist/sprite.js

@@ -0,0 +1,91 @@
+import {} from './palette.js';
+import { mirrorSprite, drawSprite as _drawSprite } from './renderer.js';
+// Lazy cache: avoids creating a new mirrored Uint8Array every frame
+const _flipCache = new WeakMap();
+function getFlipped(bm) {
+    let flipped = _flipCache.get(bm);
+    if (!flipped) {
+        flipped = mirrorSprite(bm);
+        _flipCache.set(bm, flipped);
+    }
+    return flipped;
+}
+/**
+ * Creates a `Sprite` at position (0, 0) with zero velocity.
+ *
+ * @param bitmap - 8-byte sprite definition
+ * @param ink    - Foreground colour
+ * @param paper  - Background colour, or `null` for transparent (default `null`)
+ *
+ * @example
+ * const player = createSprite(PLAYER_BITMAP, C.B_CYAN)
+ * const bullet = createSprite(BULLET_BITMAP, C.B_WHITE, C.BLACK)
+ */
+export function createSprite(bitmap, ink, paper = null) {
+    return { x: 0, y: 0, vx: 0, vy: 0, bitmap, ink, paper, flipX: false, visible: true };
+}
+/**
+ * Advances the sprite position by `vx * dt` and `vy * dt`.
+ * Call once per frame before collision resolution.
+ *
+ * @param sprite - Sprite to update
+ * @param dt     - Elapsed time in milliseconds since last frame
+ *
+ * @example
+ * // Game loop
+ * moveSprite(player, dt)
+ * const { x, hitBottom } = resolveY(player, map, player.y)
+ * player.y = y
+ * if (hitBottom) player.vy = 0
+ */
+export function moveSprite(sprite, dt) {
+    sprite.x += sprite.vx * dt;
+    sprite.y += sprite.vy * dt;
+}
+/**
+ * Adds `gravity * dt` to the sprite's vertical velocity.
+ * Call once per frame before `moveSprite`.
+ *
+ * @param sprite  - Sprite to affect
+ * @param gravity - Acceleration in pixels per millisecond² (e.g. `0.003` for gentle gravity)
+ * @param dt      - Elapsed time in milliseconds
+ *
+ * @example
+ * applyGravity(player, 0.003, dt)
+ * moveSprite(player, dt)
+ */
+export function applyGravity(sprite, gravity, dt) {
+    sprite.vy += gravity * dt;
+}
+/**
+ * Draws the sprite at its current position (rounded to nearest pixel).
+ * Does nothing when `sprite.visible === false`.
+ * Respects `sprite.paper` (transparent when `null`) and `sprite.flipX`.
+ *
+ * Must be called after all position updates and collision resolution for the frame.
+ *
+ * @param ctx    - Canvas 2D context (same one used for the rest of the frame)
+ * @param sprite - Sprite to render
+ */
+export function renderSprite(ctx, sprite) {
+    if (!sprite.visible)
+        return;
+    const x = Math.round(sprite.x);
+    const y = Math.round(sprite.y);
+    const bm = sprite.flipX ? getFlipped(sprite.bitmap) : sprite.bitmap;
+    if (sprite.paper !== null) {
+        _drawSprite(ctx, bm, x, y, sprite.ink, sprite.paper);
+    }
+    else {
+        // Transparent background — draw only ink pixels
+        ctx.fillStyle = sprite.ink;
+        for (let row = 0; row < 8; row++) {
+            const byte = bm[row];
+            for (let bit = 0; bit < 8; bit++) {
+                if (byte & (0x80 >> bit))
+                    ctx.fillRect(x + bit, y + row, 1, 1);
+            }
+        }
+    }
+}
+//# sourceMappingURL=sprite.js.map

package/dist/sprite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sprite.js","sourceRoot":"","sources":["../src/sprite.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,MAAM,cAAc,CAAA;AACjD,OAAO,EAAE,YAAY,EAAE,UAAU,IAAI,WAAW,EAAE,MAAM,eAAe,CAAA;AA+BvE,oEAAoE;AACpE,MAAM,UAAU,GAAG,IAAI,OAAO,EAA0B,CAAA;AAExD,SAAS,UAAU,CAAC,EAAc;IAChC,IAAI,OAAO,GAAG,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;IAChC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,GAAG,YAAY,CAAC,EAAE,CAAC,CAAA;QAC1B,UAAU,CAAC,GAAG,CAAC,EAAE,EAAE,OAAO,CAAC,CAAA;IAC7B,CAAC;IACD,OAAO,OAAO,CAAA;AAChB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,YAAY,CAC1B,MAAkB,EAClB,GAAkB,EAClB,QAA8B,IAAI;IAElC,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,CAAA;AACtF,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,UAAU,CAAC,MAAc,EAAE,EAAU;IACnD,MAAM,CAAC,CAAC,IAAI,MAAM,CAAC,EAAE,GAAG,EAAE,CAAA;IAC1B,MAAM,CAAC,CAAC,IAAI,MAAM,CAAC,EAAE,GAAG,EAAE,CAAA;AAC5B,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,YAAY,CAAC,MAAc,EAAE,OAAe,EAAE,EAAU;IACtE,MAAM,CAAC,EAAE,IAAI,OAAO,GAAG,EAAE,CAAA;AAC3B,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAAC,GAA6B,EAAE,MAAc;IACxE,IAAI,CAAC,MAAM,CAAC,OAAO;QAAE,OAAM;IAC3B,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAA;IAC9B,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAA;IAC9B,MAAM,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAA;IACnE,IAAI,MAAM,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;QAC1B,WAAW,CAAC,GAAG,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,CAAA;IACtD,CAAC;SAAM,CAAC;QACN,gDAAgD;QAChD,GAAG,CAAC,SAAS,GAAG,MAAM,CAAC,GAAG,CAAA;QAC1B,KAAK,IAAI,GAAG,GAAG,CAAC,EAAE,GAAG,GAAG,CAAC,EAAE,GAAG,EAAE,EAAE,CAAC;YACjC,MAAM,IAAI,GAAG,EAAE,CAAC,GAAG,CAAC,CAAA;YACpB,KAAK,IAAI,GAAG,GAAG,CAAC,EAAE,GAAG,GAAG,CAAC,EAAE,GAAG,EAAE,EAAE,CAAC;gBACjC,IAAI,IAAI,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC;oBAAE,GAAG,CAAC,QAAQ,CAAC,CAAC,GAAG,GAAG,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;YAChE,CAAC;QACH,CAAC;IACH,CAAC;AACH,CAAC"}

package/package.json

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