zx-kit 0.12.0 → 0.13.0

package/README.md

@@ -140,6 +140,8 @@ requestAnimationFrame(loop)
 | [`sprite.ts`](#spritets--free-roaming-sprites) | Sprites: position, velocity, gravity, flip, render |
 | [`collision.ts`](#collisionts--aabb-collision) | AABB overlap tests, tile-map wall resolution |
 | [`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 |
 | [`tilemap.ts`](#tilemapts--tile-map-engine) | Scrollable maps, solid tiles, O(1) id-index, background swap |
 | [`palette.ts`](#palettets--color-constants) | 15 Spectrum colors, `SpectrumColor` type, `CELL`, `SCALE` |
 | [`font.ts`](#fontts--rom-bitmap-font) | 96-character ROM font, raw bitmap access |
@@ -993,6 +995,145 @@ state.blink = blink
 
 ---
 
+## `camera.ts` — Scrolling Camera
+
+A 2D viewport that maps a window of world space onto the screen. The camera follows a target point (typically the player) with frame-rate-independent smoothing and an optional deadzone, and clamps to world bounds so the viewport never sees outside the map.
+
+```ts
+import { createCamera, setCameraTarget, tickCamera, worldToScreen, isInView } from 'zx-kit'
+
+const cam = createCamera({
+  viewW: 256, viewH: 192,        // game canvas size
+  worldW: 2048, worldH: 192,     // a long horizontal level
+  lerp: 0.15,                    // smooth follow (15% of remaining distance per 16.67 ms)
+  deadzoneW: 64, deadzoneH: 0,   // ±32 px horizontal slack before the camera scrolls
+})
+
+// In your game loop:
+setCameraTarget(cam, player.x, player.y)
+tickCamera(cam, dt)
+
+// Render anything via worldToScreen — sprites stay aligned to the camera:
+for (const e of enemies) {
+  if (!isInView(cam, e.x, e.y, 8, 8)) continue   // cull off-screen
+  const s = worldToScreen(cam, e.x, e.y)
+  drawSprite(ctx, ENEMY, s.x, s.y, C.B_RED, C.BLACK)
+}
+```
+
+### `Camera` interface
+
+| Field | Description |
+|-------|-------------|
+| `x`, `y` | Current viewport top-left in world pixels (mutated by `tickCamera`) |
+| `viewW`, `viewH` | Viewport size in pixels |
+| `worldW`, `worldH` | World size in pixels — camera clamps so `x ∈ [0, worldW-viewW]` |
+| `lerp` | `(0..1]` — fraction of remaining distance covered per 60 fps frame. `1` = snap. |
+| `deadzoneW`, `deadzoneH` | Deadzone size — target may move ±`deadzoneW/2` from centre before scrolling |
+| `targetX`, `targetY` | Current follow target (set via `setCameraTarget`) |
+
+### `createCamera(opts): Camera`
+
+Creates a camera at world origin `(0, 0)`. `lerp` defaults to `1` (snap), deadzones default to `0`.
+
+### `setCameraTarget(cam, x, y): void`
+
+Sets the world-space follow target. Does not move the camera — `tickCamera` does that.
+
+### `tickCamera(cam, dt): void`
+
+Advances the camera one frame:
+1. Computes the desired viewport position from the target, honouring the deadzone
+2. Eases `cam.x` / `cam.y` toward the desired position using `lerp` (frame-rate-corrected by `dt`)
+3. Clamps to world bounds so the viewport never sees outside the world
+
+The lerp is dt-independent: one `tickCamera(cam, 33.34)` call produces (within floating-point precision) the same result as two `tickCamera(cam, 16.67)` calls. If the world is smaller than the viewport the camera pins to `(0, 0)`.
+
+### `worldToScreen(cam, wx, wy): { x, y }`
+
+Converts a world coordinate to a screen (viewport-relative) coordinate. Subtracts `cam.x` / `cam.y`.
+
+### `isInView(cam, wx, wy, w?, h?): boolean`
+
+Returns `true` when a world rectangle of size `w × h` (default `0 × 0` for a point test) overlaps the camera viewport. Use to cull off-screen sprites before drawing.
+
+---
+
+## `scene.ts` — Scene Manager
+
+A stack-based scene manager with full lifecycle hooks. Replaces ad-hoc phase enums (`'intro' | 'playing' | 'gameover'`) with a clean push / pop / replace API. Only the **top** scene receives `update`, so pushing a pause overlay freezes everything beneath; **all** scenes receive `render` bottom-up, so the paused scene stays visible.
+
+```ts
+import { createSceneManager, pushScene, popScene, updateScenes, renderScenes, type Scene } from 'zx-kit'
+
+const gameplay: Scene = {
+  name: 'gameplay',
+  update(dt) { /* tick game */ },
+  render(ctx) { /* draw game */ },
+  onPause() { stopAmbientSound() },
+  onResume() { startAmbientSound() },
+}
+
+const pauseOverlay: Scene = {
+  name: 'pause',
+  update(_dt) { if (keys.pressed('P')) popScene(mgr) },
+  render(ctx) { drawTextCentered(ctx, '** PAUSED **', ROWS/2 * CELL, C.B_WHITE, C.BLACK) },
+}
+
+const mgr = createSceneManager()
+pushScene(mgr, gameplay)        // gameplay.onEnter(null)
+// later, player presses P:
+pushScene(mgr, pauseOverlay)    // gameplay.onPause() → pauseOverlay.onEnter(gameplay)
+
+// Game loop:
+updateScenes(mgr, dt)           // only top scene ticks
+renderScenes(mgr, ctx)          // bottom-up: gameplay first, then pause overlay
+```
+
+### `Scene` interface
+
+| Field | Description |
+|-------|-------------|
+| `name` | Human-readable identifier (for logging / debugging) |
+| `update(dt)` | Called once per frame on the **top** scene only |
+| `render(ctx)` | Called once per frame on **all** scenes, bottom-up |
+| `onEnter?(prev)` | Fired when this scene becomes top (push / replace / initial). `prev` is the previously-top scene or `null`. |
+| `onExit?(next)` | Fired when this scene is removed (pop / replace). `next` is what becomes top, or `null`. |
+| `onPause?()` | Fired when another scene is pushed on top of this one. |
+| `onResume?()` | Fired when the scene above this one is popped. |
+
+### `createSceneManager(): SceneManager`
+
+Creates a manager with an empty stack.
+
+### `pushScene(mgr, scene): void`
+
+Pushes a scene onto the stack. Lifecycle order: `prev.onPause()` → `scene.onEnter(prev)`. Use for modal overlays, dialogs, pause screens.
+
+### `popScene(mgr): Scene | null`
+
+Pops the top scene and returns it (or `null` if the stack was empty). Lifecycle order: `top.onExit(below)` → `below.onResume()`.
+
+### `replaceScene(mgr, scene): void`
+
+Swaps the top scene without affecting scenes beneath. Lifecycle order: `outgoing.onExit(scene)` → `scene.onEnter(outgoing)`. Does **not** fire `onPause` / `onResume` on the scene below — it was never paused by this call. Use for state transitions like `gameplay → gameOver` while keeping `intro` on the bottom.
+
+On an empty manager `replaceScene` behaves like `pushScene` (outgoing is `null`).
+
+### `currentScene(mgr): Scene | null`
+
+Returns the top scene, or `null` if the stack is empty.
+
+### `updateScenes(mgr, dt): void`
+
+Updates the top scene only. No-op on an empty manager. Scenes beneath the top stay frozen — this is what makes pause overlays work.
+
+### `renderScenes(mgr, ctx): void`
+
+Renders every scene from bottom to top. No-op on an empty manager.
+
+---
+
 ## `tilemap.ts` — Tile Map Engine
 
 A scrollable, queryable tile map backed by an O(1) id-index. Tiles use the same 8×8 sprite format as `drawSprite`. Supports solid-tile collision queries, viewport-clipped rendering, and smart seasonal background swapping.

package/dist/camera.d.ts

@@ -0,0 +1,117 @@
+/**
+ * A 2D camera that maps a window of world space onto the screen viewport.
+ *
+ * The camera's position (`x`, `y`) is the world-pixel coordinate of the viewport's
+ * top-left corner. Use `worldToScreen` to convert sprite positions for rendering,
+ * or `tickCamera` each frame to follow a moving target with smoothing.
+ *
+ * **Coordinate model:**
+ * - World extends from `(0,0)` to `(worldW, worldH)`
+ * - Viewport is a `viewW × viewH` window into the world
+ * - Camera clamps so the viewport never sees outside world bounds
+ *
+ * **Smoothing:**
+ * - `lerp = 1` → snaps to target each tick
+ * - `lerp < 1` → eases toward target; lower = slower follow
+ * - The lerp factor is **frame-rate independent** — internally adjusted by `dt`
+ *
+ * **Deadzone:**
+ * - Rectangle centred on the camera's centre point
+ * - While the target stays inside the deadzone, the camera does not move
+ * - Once the target exits, the camera shifts just enough to put the target back on the deadzone edge
+ */
+export interface Camera {
+    /** Current viewport top-left X in world pixels. */
+    x: number;
+    /** Current viewport top-left Y in world pixels. */
+    y: number;
+    /** Viewport width in pixels (typically the game's canvas width). */
+    viewW: number;
+    /** Viewport height in pixels. */
+    viewH: number;
+    /** World width in pixels — camera clamps so `x` stays in `[0, worldW - viewW]`. */
+    worldW: number;
+    /** World height in pixels. */
+    worldH: number;
+    /**
+     * Lerp factor in `(0..1]` — fraction of remaining distance covered per 60 fps frame.
+     * `1` = instant snap, `0.1` = covers 10 % of distance per 16.67 ms.
+     * Frame-rate corrected: `tickCamera(cam, 33.34)` ≈ two `tickCamera(cam, 16.67)` calls.
+     */
+    lerp: number;
+    /** Deadzone width — target may move ±`deadzoneW/2` from viewport centre without scrolling. */
+    deadzoneW: number;
+    /** Deadzone height. */
+    deadzoneH: number;
+    /** Current target X in world pixels (set via `setCameraTarget`). */
+    targetX: number;
+    /** Current target Y in world pixels. */
+    targetY: number;
+}
+/**
+ * Options passed to `createCamera`. See {@link Camera} for full semantics.
+ */
+export interface CameraOptions {
+    viewW: number;
+    viewH: number;
+    worldW: number;
+    worldH: number;
+    /** Default `1` (instant snap). */
+    lerp?: number;
+    /** Default `0`. */
+    deadzoneW?: number;
+    /** Default `0`. */
+    deadzoneH?: number;
+}
+/**
+ * Creates a Camera at world origin `(0, 0)`.
+ *
+ * @example
+ * const cam = createCamera({
+ *   viewW: 256, viewH: 192,            // game canvas size
+ *   worldW: 2048, worldH: 192,         // long horizontal level
+ *   lerp: 0.15, deadzoneW: 64,         // smooth follow with a centre deadzone
+ * })
+ */
+export declare function createCamera(opts: CameraOptions): Camera;
+/**
+ * Sets the world-space point the camera should track.
+ * Call each frame with the player (or other follow target) position.
+ * Does not move the camera itself — call `tickCamera` for that.
+ */
+export declare function setCameraTarget(cam: Camera, x: number, y: number): void;
+/**
+ * Advances the camera one frame:
+ * 1. Computes the desired viewport position from `targetX/Y`, respecting the deadzone
+ * 2. Eases `cam.x/y` toward the desired position by `lerp` (frame-rate-corrected by `dt`)
+ * 3. Clamps to world bounds so the viewport never sees outside the world
+ *
+ * Call once per frame after `setCameraTarget`.
+ */
+export declare function tickCamera(cam: Camera, dt: number): void;
+/**
+ * Converts a world coordinate to a screen (viewport-relative) coordinate.
+ * Useful when drawing sprites: `drawSprite(ctx, bmp, screen.x, screen.y, ink, paper)`.
+ *
+ * @example
+ * const s = worldToScreen(cam, enemy.x, enemy.y)
+ * drawSprite(ctx, ENEMY, s.x, s.y, C.B_RED, C.BLACK)
+ */
+export declare function worldToScreen(cam: Camera, wx: number, wy: number): {
+    x: number;
+    y: number;
+};
+/**
+ * Returns `true` when a world-space rectangle overlaps the camera viewport.
+ * Use to cull off-screen sprites before drawing.
+ *
+ * `w` and `h` default to `0` (point test). For an 8×8 sprite pass `8, 8`.
+ *
+ * @example
+ * for (const e of enemies) {
+ *   if (!isInView(cam, e.x, e.y, 8, 8)) continue
+ *   // draw e
+ * }
+ */
+export declare function isInView(cam: Camera, wx: number, wy: number, w?: number, h?: number): boolean;
+//# sourceMappingURL=camera.d.ts.map

package/dist/camera.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"camera.d.ts","sourceRoot":"","sources":["../src/camera.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,MAAM;IACrB,mDAAmD;IACnD,CAAC,EAAE,MAAM,CAAA;IACT,mDAAmD;IACnD,CAAC,EAAE,MAAM,CAAA;IACT,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAA;IACb,iCAAiC;IACjC,KAAK,EAAE,MAAM,CAAA;IACb,mFAAmF;IACnF,MAAM,EAAE,MAAM,CAAA;IACd,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ,8FAA8F;IAC9F,SAAS,EAAE,MAAM,CAAA;IACjB,uBAAuB;IACvB,SAAS,EAAE,MAAM,CAAA;IACjB,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAA;IACf,wCAAwC;IACxC,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,kCAAkC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,mBAAmB;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,mBAAmB;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAcxD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAGvE;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAwCxD;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAE3F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,SAAI,EAAE,CAAC,SAAI,GAAG,OAAO,CAKnF"}

package/dist/camera.js

@@ -0,0 +1,114 @@
+// ── Camera: viewport that follows a target across a larger world ────────────
+/**
+ * Creates a Camera at world origin `(0, 0)`.
+ *
+ * @example
+ * const cam = createCamera({
+ *   viewW: 256, viewH: 192,            // game canvas size
+ *   worldW: 2048, worldH: 192,         // long horizontal level
+ *   lerp: 0.15, deadzoneW: 64,         // smooth follow with a centre deadzone
+ * })
+ */
+export function createCamera(opts) {
+    return {
+        x: 0,
+        y: 0,
+        viewW: opts.viewW,
+        viewH: opts.viewH,
+        worldW: opts.worldW,
+        worldH: opts.worldH,
+        lerp: opts.lerp ?? 1,
+        deadzoneW: opts.deadzoneW ?? 0,
+        deadzoneH: opts.deadzoneH ?? 0,
+        targetX: 0,
+        targetY: 0,
+    };
+}
+/**
+ * Sets the world-space point the camera should track.
+ * Call each frame with the player (or other follow target) position.
+ * Does not move the camera itself — call `tickCamera` for that.
+ */
+export function setCameraTarget(cam, x, y) {
+    cam.targetX = x;
+    cam.targetY = y;
+}
+/**
+ * Advances the camera one frame:
+ * 1. Computes the desired viewport position from `targetX/Y`, respecting the deadzone
+ * 2. Eases `cam.x/y` toward the desired position by `lerp` (frame-rate-corrected by `dt`)
+ * 3. Clamps to world bounds so the viewport never sees outside the world
+ *
+ * Call once per frame after `setCameraTarget`.
+ */
+export function tickCamera(cam, dt) {
+    // Desired viewport position that puts target on the relevant deadzone edge.
+    const halfW = cam.viewW / 2;
+    const halfH = cam.viewH / 2;
+    const dzL = cam.deadzoneW / 2;
+    const dzT = cam.deadzoneH / 2;
+    const centerX = cam.x + halfW;
+    const centerY = cam.y + halfH;
+    let desiredX = cam.x;
+    let desiredY = cam.y;
+    if (cam.targetX > centerX + dzL) {
+        desiredX = cam.targetX - halfW - dzL;
+    }
+    else if (cam.targetX < centerX - dzL) {
+        desiredX = cam.targetX - halfW + dzL;
+    }
+    if (cam.targetY > centerY + dzT) {
+        desiredY = cam.targetY - halfH - dzT;
+    }
+    else if (cam.targetY < centerY - dzT) {
+        desiredY = cam.targetY - halfH + dzT;
+    }
+    // Frame-rate-corrected lerp: t = 1 - (1 - lerp)^(dt/16.67)
+    const FRAME_MS = 16.67;
+    const t = cam.lerp >= 1
+        ? (dt > 0 ? 1 : 0)
+        : (dt > 0 ? 1 - Math.pow(1 - cam.lerp, dt / FRAME_MS) : 0);
+    cam.x += (desiredX - cam.x) * t;
+    cam.y += (desiredY - cam.y) * t;
+    // Clamp to world bounds; if world is smaller than viewport, pin to 0.
+    const maxX = Math.max(0, cam.worldW - cam.viewW);
+    const maxY = Math.max(0, cam.worldH - cam.viewH);
+    if (cam.x < 0)
+        cam.x = 0;
+    else if (cam.x > maxX)
+        cam.x = maxX;
+    if (cam.y < 0)
+        cam.y = 0;
+    else if (cam.y > maxY)
+        cam.y = maxY;
+}
+/**
+ * Converts a world coordinate to a screen (viewport-relative) coordinate.
+ * Useful when drawing sprites: `drawSprite(ctx, bmp, screen.x, screen.y, ink, paper)`.
+ *
+ * @example
+ * const s = worldToScreen(cam, enemy.x, enemy.y)
+ * drawSprite(ctx, ENEMY, s.x, s.y, C.B_RED, C.BLACK)
+ */
+export function worldToScreen(cam, wx, wy) {
+    return { x: wx - cam.x, y: wy - cam.y };
+}
+/**
+ * Returns `true` when a world-space rectangle overlaps the camera viewport.
+ * Use to cull off-screen sprites before drawing.
+ *
+ * `w` and `h` default to `0` (point test). For an 8×8 sprite pass `8, 8`.
+ *
+ * @example
+ * for (const e of enemies) {
+ *   if (!isInView(cam, e.x, e.y, 8, 8)) continue
+ *   // draw e
+ * }
+ */
+export function isInView(cam, wx, wy, w = 0, h = 0) {
+    return wx + w > cam.x
+        && wx < cam.x + cam.viewW
+        && wy + h > cam.y
+        && wy < cam.y + cam.viewH;
+}
+//# sourceMappingURL=camera.js.map

package/dist/camera.js.map

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

package/dist/index.d.ts

@@ -9,4 +9,6 @@ export * from './tilemap.js';
 export * from './sprite.js';
 export * from './collision.js';
 export * from './animation.js';
+export * from './camera.js';
+export * from './scene.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"}
+{"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"}

package/dist/index.js

@@ -9,4 +9,6 @@ export * from './tilemap.js';
 export * from './sprite.js';
 export * from './collision.js';
 export * from './animation.js';
+export * from './camera.js';
+export * from './scene.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"}
+{"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"}

package/dist/scene.d.ts

@@ -0,0 +1,90 @@
+/**
+ * A single screen / game state — intro, gameplay, pause overlay, game over, etc.
+ *
+ * `update` is called on the **top** scene only (so pushing a pause scene freezes
+ * everything beneath). `render` is called on **all** scenes bottom-up, so a paused
+ * underlying scene remains visible behind a translucent overlay.
+ *
+ * **Lifecycle hooks (all optional):**
+ * - `onEnter(prev)` — the scene becomes top of the stack (push / replace / initial)
+ * - `onExit(next)`  — the scene is removed (pop / replace); `next` is what becomes top
+ * - `onPause()`     — another scene is pushed on top of this one
+ * - `onResume()`    — the scene above this one is popped, this becomes top again
+ *
+ * Manage scenes via {@link createSceneManager}, {@link pushScene}, {@link popScene}, {@link replaceScene}.
+ */
+export interface Scene {
+    /** Human-readable identifier, useful for logging and debugging. */
+    name: string;
+    /** Called once per frame on the top scene only. */
+    update(dt: number): void;
+    /** Called once per frame on all scenes, bottom-up. */
+    render(ctx: CanvasRenderingContext2D): void;
+    /** Optional: fired when this scene becomes the top of the stack. `prev` is the previously-top scene, or `null` if the stack was empty. */
+    onEnter?(prev: Scene | null): void;
+    /** Optional: fired when this scene is removed. `next` is the scene that becomes top (or `null` if the stack becomes empty). */
+    onExit?(next: Scene | null): void;
+    /** Optional: fired when another scene is pushed on top of this one. */
+    onPause?(): void;
+    /** Optional: fired when the scene above this one is popped, restoring this scene to top. */
+    onResume?(): void;
+}
+/**
+ * Holds the scene stack. Mutated by `pushScene`, `popScene`, `replaceScene`.
+ * Create via {@link createSceneManager}.
+ */
+export interface SceneManager {
+    /** Bottom-up scene stack. `stack[stack.length - 1]` is the current top. */
+    stack: Scene[];
+}
+/**
+ * Creates an empty SceneManager.
+ *
+ * @example
+ * const mgr = createSceneManager()
+ * pushScene(mgr, introScene)
+ *
+ * // In game loop:
+ * updateScenes(mgr, dt)
+ * renderScenes(mgr, ctx)
+ */
+export declare function createSceneManager(): SceneManager;
+/**
+ * Returns the top scene, or `null` if the stack is empty.
+ */
+export declare function currentScene(mgr: SceneManager): Scene | null;
+/**
+ * Pushes a scene onto the stack. Fires `onPause` on the previous top (if any),
+ * then `onEnter(prev)` on the new scene.
+ *
+ * @example
+ * pushScene(mgr, pauseOverlayScene)   // freezes underlying game, draws on top
+ */
+export declare function pushScene(mgr: SceneManager, scene: Scene): void;
+/**
+ * Pops the top scene and returns it (or `null` if the stack was empty).
+ * Fires `onExit(below)` on the popped scene, then `onResume` on the uncovered scene below (if any).
+ */
+export declare function popScene(mgr: SceneManager): Scene | null;
+/**
+ * Replaces the top scene with a new one without affecting scenes beneath.
+ * Fires `onExit(incoming)` on the outgoing top, then `onEnter(outgoing)` on the incoming scene.
+ * **Does not** fire `onPause` / `onResume` on any scene below — they were never paused by this call.
+ *
+ * On an empty manager, behaves like `pushScene` (outgoing is `null`).
+ *
+ * @example
+ * replaceScene(mgr, gameOverScene)   // swap gameplay → game over, leave intro on bottom
+ */
+export declare function replaceScene(mgr: SceneManager, scene: Scene): void;
+/**
+ * Updates the top scene only. No-op on an empty manager.
+ * Scenes beneath the top remain frozen — this is what makes pause overlays work.
+ */
+export declare function updateScenes(mgr: SceneManager, dt: number): void;
+/**
+ * Renders every scene from bottom to top. No-op on an empty manager.
+ * Bottom-up order means a paused scene stays visible behind a translucent overlay.
+ */
+export declare function renderScenes(mgr: SceneManager, ctx: CanvasRenderingContext2D): void;
+//# sourceMappingURL=scene.d.ts.map

package/dist/scene.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scene.d.ts","sourceRoot":"","sources":["../src/scene.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,KAAK;IACpB,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAA;IACZ,mDAAmD;IACnD,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,sDAAsD;IACtD,MAAM,CAAC,GAAG,EAAE,wBAAwB,GAAG,IAAI,CAAA;IAC3C,0IAA0I;IAC1I,OAAO,CAAC,CAAC,IAAI,EAAE,KAAK,GAAG,IAAI,GAAG,IAAI,CAAA;IAClC,+HAA+H;IAC/H,MAAM,CAAC,CAAC,IAAI,EAAE,KAAK,GAAG,IAAI,GAAG,IAAI,CAAA;IACjC,uEAAuE;IACvE,OAAO,CAAC,IAAI,IAAI,CAAA;IAChB,4FAA4F;IAC5F,QAAQ,CAAC,IAAI,IAAI,CAAA;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,2EAA2E;IAC3E,KAAK,EAAE,KAAK,EAAE,CAAA;CACf;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,IAAI,YAAY,CAEjD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,YAAY,GAAG,KAAK,GAAG,IAAI,CAE5D;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,YAAY,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CAK/D;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,YAAY,GAAG,KAAK,GAAG,IAAI,CAOxD;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,YAAY,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CAKlE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,YAAY,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAGhE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,YAAY,EAAE,GAAG,EAAE,wBAAwB,GAAG,IAAI,CAEnF"}

package/dist/scene.js

@@ -0,0 +1,83 @@
+// ── Scene: stack-based scene manager with onEnter/onExit/onPause/onResume ───
+/**
+ * Creates an empty SceneManager.
+ *
+ * @example
+ * const mgr = createSceneManager()
+ * pushScene(mgr, introScene)
+ *
+ * // In game loop:
+ * updateScenes(mgr, dt)
+ * renderScenes(mgr, ctx)
+ */
+export function createSceneManager() {
+    return { stack: [] };
+}
+/**
+ * Returns the top scene, or `null` if the stack is empty.
+ */
+export function currentScene(mgr) {
+    return mgr.stack.length === 0 ? null : mgr.stack[mgr.stack.length - 1];
+}
+/**
+ * Pushes a scene onto the stack. Fires `onPause` on the previous top (if any),
+ * then `onEnter(prev)` on the new scene.
+ *
+ * @example
+ * pushScene(mgr, pauseOverlayScene)   // freezes underlying game, draws on top
+ */
+export function pushScene(mgr, scene) {
+    const prev = currentScene(mgr);
+    if (prev)
+        prev.onPause?.();
+    mgr.stack.push(scene);
+    scene.onEnter?.(prev);
+}
+/**
+ * Pops the top scene and returns it (or `null` if the stack was empty).
+ * Fires `onExit(below)` on the popped scene, then `onResume` on the uncovered scene below (if any).
+ */
+export function popScene(mgr) {
+    if (mgr.stack.length === 0)
+        return null;
+    const top = mgr.stack.pop();
+    const below = currentScene(mgr);
+    top.onExit?.(below);
+    if (below)
+        below.onResume?.();
+    return top;
+}
+/**
+ * Replaces the top scene with a new one without affecting scenes beneath.
+ * Fires `onExit(incoming)` on the outgoing top, then `onEnter(outgoing)` on the incoming scene.
+ * **Does not** fire `onPause` / `onResume` on any scene below — they were never paused by this call.
+ *
+ * On an empty manager, behaves like `pushScene` (outgoing is `null`).
+ *
+ * @example
+ * replaceScene(mgr, gameOverScene)   // swap gameplay → game over, leave intro on bottom
+ */
+export function replaceScene(mgr, scene) {
+    const outgoing = mgr.stack.length > 0 ? mgr.stack.pop() : null;
+    outgoing?.onExit?.(scene);
+    mgr.stack.push(scene);
+    scene.onEnter?.(outgoing);
+}
+/**
+ * Updates the top scene only. No-op on an empty manager.
+ * Scenes beneath the top remain frozen — this is what makes pause overlays work.
+ */
+export function updateScenes(mgr, dt) {
+    const top = currentScene(mgr);
+    if (top)
+        top.update(dt);
+}
+/**
+ * Renders every scene from bottom to top. No-op on an empty manager.
+ * Bottom-up order means a paused scene stays visible behind a translucent overlay.
+ */
+export function renderScenes(mgr, ctx) {
+    for (const scene of mgr.stack)
+        scene.render(ctx);
+}
+//# sourceMappingURL=scene.js.map

package/dist/scene.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scene.js","sourceRoot":"","sources":["../src/scene.ts"],"names":[],"mappings":"AAAA,+EAA+E;AA2C/E;;;;;;;;;;GAUG;AACH,MAAM,UAAU,kBAAkB;IAChC,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,CAAA;AACtB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,GAAiB;IAC5C,OAAO,GAAG,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;AACxE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,GAAiB,EAAE,KAAY;IACvD,MAAM,IAAI,GAAG,YAAY,CAAC,GAAG,CAAC,CAAA;IAC9B,IAAI,IAAI;QAAE,IAAI,CAAC,OAAO,EAAE,EAAE,CAAA;IAC1B,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IACrB,KAAK,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,CAAA;AACvB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAiB;IACxC,IAAI,GAAG,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IACvC,MAAM,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,EAAG,CAAA;IAC5B,MAAM,KAAK,GAAG,YAAY,CAAC,GAAG,CAAC,CAAA;IAC/B,GAAG,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,CAAA;IACnB,IAAI,KAAK;QAAE,KAAK,CAAC,QAAQ,EAAE,EAAE,CAAA;IAC7B,OAAO,GAAG,CAAA;AACZ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAAC,GAAiB,EAAE,KAAY;IAC1D,MAAM,QAAQ,GAAG,GAAG,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,EAAG,CAAC,CAAC,CAAC,IAAI,CAAA;IAC/D,QAAQ,EAAE,MAAM,EAAE,CAAC,KAAK,CAAC,CAAA;IACzB,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IACrB,KAAK,CAAC,OAAO,EAAE,CAAC,QAAQ,CAAC,CAAA;AAC3B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,GAAiB,EAAE,EAAU;IACxD,MAAM,GAAG,GAAG,YAAY,CAAC,GAAG,CAAC,CAAA;IAC7B,IAAI,GAAG;QAAE,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;AACzB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,GAAiB,EAAE,GAA6B;IAC3E,KAAK,MAAM,KAAK,IAAI,GAAG,CAAC,KAAK;QAAE,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;AAClD,CAAC"}

package/package.json

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