zx-kit 0.7.0 → 0.8.0

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/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.8.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/zrebec/zx-kit.git"