minimojs 1.0.0-alpha.1

package/dist/minimo.js

@@ -0,0 +1,1381 @@
+/**
+ * @module minimojs
+ *
+ * MinimoJS v1 — Ultra-minimal 2D web game engine for TypeScript.
+ *
+ * ALL TIME VALUES ARE IN MILLISECONDS.
+ * ALL ROTATIONS ARE IN DEGREES.
+ * THE ENGINE LOOP USES requestAnimationFrame ONLY.
+ */
+// ---------------------------------------------------------------------------
+// Sprite
+// ---------------------------------------------------------------------------
+/**
+ * A 2D game object rendered as an emoji on the canvas.
+ *
+ * Instantiate directly or extend to create custom sprite types.
+ * Register with the engine by passing the instance to {@link Game.add}.
+ *
+ * **Coordinate system:** center-based world space. `(x, y)` is the center of
+ * the sprite. Positive X = right, positive Y = down.
+ *
+ * **Lifecycle:** A sprite exists until {@link Game.destroySprite} is called or
+ * {@link Game.reset} is invoked. After destruction, do not read or write its fields.
+ *
+ * @example
+ * ```ts
+ * // Direct instantiation
+ * const coin = new Sprite("🪙");
+ * coin.x = 300;
+ * coin.y = 200;
+ * coin.size = 32;
+ * game.add(coin);
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Subclassing for custom game objects
+ * class Player extends Sprite {
+ *   health = 3;
+ *
+ *   constructor(x: number, y: number) {
+ *     super("🐢");
+ *     this.x = x;
+ *     this.y = y;
+ *     this.size = 48;
+ *     this.gravityScale = 1;
+ *   }
+ * }
+ *
+ * const player = new Player(400, 300);
+ * game.add(player);
+ * ```
+ */
+export class Sprite {
+    /**
+     * Creates a new Sprite with the given emoji and optional position.
+     * All other properties use their defaults and can be set after construction.
+     *
+     * @param sprite - The emoji character to render. Must be a single emoji.
+     *   Image sprites are NOT supported — emoji only.
+     *   @example "🔥", "⭐", "🐢", "💣", "👾"
+     * @param x - Initial X position in world space (center), in pixels. Default: `0`.
+     * @param y - Initial Y position in world space (center), in pixels. Default: `0`.
+     *
+     * @example
+     * ```ts
+     * const enemy = new Sprite("👾", 200, 100);
+     * enemy.size = 40;
+     * game.add(enemy);
+     * ```
+     */
+    constructor(sprite, x = 0, y = 0) {
+        /**
+         * X position in world space (horizontal center of the sprite), in pixels.
+         * Positive X points right. Updated each frame by: `x += vx * dt`.
+         * May be set directly to teleport the sprite.
+         */
+        this.x = 0;
+        /**
+         * Y position in world space (vertical center of the sprite), in pixels.
+         * Positive Y points down. Updated each frame by: `y += vy * dt`.
+         * May be set directly to teleport the sprite.
+         */
+        this.y = 0;
+        /**
+         * Width and height of the sprite's bounding square, in pixels.
+         * Used for both canvas rendering (font size) and AABB collision detection.
+         */
+        this.size = 32;
+        /**
+         * Visual rotation of the sprite in degrees.
+         * `0` = upright. Positive values rotate clockwise.
+         * **Note:** rotation does NOT affect the AABB collision box — it remains axis-aligned.
+         */
+        this.rotation = 0;
+        /**
+         * Horizontal visual flip.
+         * When `true`, the sprite is mirrored left-right during rendering.
+         * This is visual-only and does NOT affect collision detection.
+         */
+        this.flipX = false;
+        /**
+         * Vertical visual flip.
+         * When `true`, the sprite is mirrored top-bottom during rendering.
+         * This is visual-only and does NOT affect collision detection.
+         */
+        this.flipY = false;
+        /**
+         * Camera scroll toggle for this sprite.
+         * When `false` (default), the sprite is rendered in world space and is affected
+         * by {@link Game.scrollX} and {@link Game.scrollY}.
+         * When `true`, the sprite is rendered in canvas/screen space and ignores camera
+         * scrolling. Useful for HUD-like sprites that should stay fixed on screen.
+         */
+        this.ignoreScroll = false;
+        /**
+         * Opacity of the sprite. Must be in range `[0, 1]`.
+         * `0` = fully transparent, `1` = fully opaque.
+         * Clamped to `[0, 1]` at render time.
+         */
+        this.alpha = 1;
+        /**
+         * Controls whether this sprite is drawn each frame.
+         * When `false`, the sprite still receives physics updates (gravity, velocity)
+         * but is not rendered. Use {@link Game.destroySprite} to fully remove a sprite.
+         */
+        this.visible = true;
+        /**
+         * Render layer order. Sprites with higher `layer` values are drawn on top.
+         * Sprites on the same layer render in creation order (first created = bottom).
+         * Changing this at runtime takes effect on the next frame.
+         */
+        this.layer = 0;
+        /**
+         * Horizontal velocity in pixels per second.
+         * Applied each frame: `x += vx * dt`.
+         * Gravity also modifies this: `vx += gravityX * gravityScale * dt`.
+         */
+        this.vx = 0;
+        /**
+         * Vertical velocity in pixels per second.
+         * Applied each frame: `y += vy * dt`.
+         * Gravity also modifies this: `vy += gravityY * gravityScale * dt`.
+         */
+        this.vy = 0;
+        /**
+         * Gravity multiplier for this sprite.
+         * Each frame: `vx += game.gravityX * gravityScale * dt`
+         *             `vy += game.gravityY * gravityScale * dt`.
+         * `0` = immune to gravity (default). `1` = full gravity.
+         * Values > 1 amplify gravity; negative values invert it.
+         */
+        this.gravityScale = 0;
+        this.sprite = sprite;
+        this.x = x;
+        this.y = y;
+    }
+}
+// ---------------------------------------------------------------------------
+// Game
+// ---------------------------------------------------------------------------
+/**
+ * # MinimoJS v1 — AI Agent Integration Guide
+ *
+ * `Game` is the single entry point to the entire engine.
+ * Every feature — sprites, input, physics, sound, timers, text — is accessed
+ * directly on the `game` object. There are no sub-systems or nested namespaces.
+ *
+ * ---
+ *
+ * ## Quick Start
+ *
+ * ```ts
+ * import { Game, Sprite } from "minimojs";
+ *
+ * const game = new Game(800, 600);
+ *
+ * const player = new Sprite("🐢");
+ * player.x = 400;
+ * player.y = 500;
+ * player.size = 48;
+ * game.add(player);
+ *
+ * game.onUpdate = (dt) => {
+ *   if (game.isKeyDown("ArrowLeft"))  player.vx = -200;
+ *   else if (game.isKeyDown("ArrowRight")) player.vx = 200;
+ *   else player.vx = 0;
+ *
+ *   game.drawText(`x: ${Math.round(player.x)}`, 10, 10, 16);
+ * };
+ *
+ * game.start();
+ * ```
+ *
+ * ---
+ *
+ * ## Engine Philosophy
+ *
+ * MinimoJS is **flat, deterministic, and ultra-minimal**. It is intentionally
+ * designed to be easy for AI agents to reason about. The full API fits in a
+ * single file. There are no plugins, no registries, no event buses.
+ *
+ * ---
+ *
+ * ## Flat API
+ *
+ * ALL engine functionality is on the `game` object.
+ * Do not look for sub-objects like `game.physics`, `game.input`, etc. They do not exist.
+ *
+ * ---
+ *
+ * ## Responsive Canvas
+ *
+ * The engine auto-centers the canvas on the page and responsively scales it
+ * to use as much viewport space as possible while preserving aspect ratio.
+ *
+ * ---
+ *
+ * ## Emoji-Only Sprites
+ *
+ * Every sprite MUST use a single emoji character as its visual representation.
+ * PNG, SVG, spritesheet, and image sprites are NOT supported.
+ * Use Unicode emoji: `"🔥"`, `"⭐"`, `"💣"`, `"🐢"`, `"👾"`, `"🧱"`, etc.
+ * AI agents can also use text-like emojis (regional indicators, symbols, letters)
+ * to build fun title art, HUD labels, and expressive in-game text.
+ *
+ * ---
+ *
+ * ## Degrees-Only Rotation
+ *
+ * ALL rotations are in **degrees**. Never use radians.
+ * `0` = upright, `90` = 90° clockwise, `-90` = 90° counter-clockwise.
+ * This applies to {@link Sprite.rotation} and {@link Game.animateRotation}.
+ *
+ * ---
+ *
+ * ## Milliseconds-Only Timing
+ *
+ * ALL time parameters to engine methods are in **milliseconds (ms)**.
+ * This includes: {@link Game.addTimer}, {@link Game.animateAlpha},
+ * {@link Game.animateRotation}, and {@link Game.sound}.
+ *
+ * The `dt` parameter in {@link Game.onUpdate} is an exception — it is in
+ * **seconds** for convenient velocity math (`position += velocity * dt`).
+ *
+ * ---
+ *
+ * ## rAF-Only Loop
+ *
+ * The engine loop runs exclusively on `requestAnimationFrame`.
+ * There are **no** `setTimeout` or `setInterval` calls anywhere.
+ * All timers, animations, and physics are driven by the rAF loop.
+ * Delta time is automatically capped at 100ms to prevent spiral-of-death.
+ *
+ * ---
+ *
+ * ## Gravity Model
+ *
+ * Gravity is a constant per-frame acceleration in pixels/second².
+ * Set {@link Game.gravityX} and {@link Game.gravityY} to define the direction.
+ * For standard downward gravity: `game.gravityY = 980`.
+ *
+ * Per-sprite effect is controlled by {@link Sprite.gravityScale}:
+ * - `gravityScale = 0` (default): sprite is unaffected by gravity.
+ * - `gravityScale = 1`: full gravity applied.
+ * - `gravityScale = 0.5`: half gravity.
+ *
+ * Each frame: `vx += gravityX * gravityScale * dt`, same for Y.
+ *
+ * ---
+ *
+ * ## Timer System
+ *
+ * Timers are rAF-driven countdown callbacks — NOT `setTimeout`.
+ * They accumulate elapsed time each frame and fire when the delay is reached.
+ *
+ * - {@link Game.addTimer}`(delayMs, repeat, callback)` — schedule a callback.
+ * - {@link Game.clearTimer}`(id)` — cancel a scheduled timer.
+ * - ALL timers are cleared on {@link Game.reset}.
+ *
+ * ```ts
+ * // Fire once after 2 seconds
+ * game.addTimer(2000, false, () => { player.sprite = "💥"; });
+ *
+ * // Repeat every 1 second
+ * const id = game.addTimer(1000, true, () => { spawnEnemy(); });
+ * // Later:
+ * game.clearTimer(id);
+ * ```
+ *
+ * ---
+ *
+ * ## Scene Initialization with `onCreate`
+ *
+ * MinimoJS has NO scene system. Use {@link Game.onCreate} to build a scene.
+ * The engine calls `onCreate`:
+ * - Once before the first frame (when {@link Game.start} is called).
+ * - Again after each {@link Game.reset}.
+ *
+ * `reset()` clears:
+ * - All sprites
+ * - All timers
+ * - All running animations
+ * - All text overlays
+ * - Scroll position (scrollX and scrollY reset to 0)
+ * - Per-frame input state (pressed keys/pointer)
+ *
+ * After clearing, `reset()` calls `onCreate()` so your callback can rebuild the
+ * new scene immediately. Simply re-add sprites and re-register timers.
+ *
+ * ```ts
+ * game.onCreate = () => {
+ *   // scene init: add sprites, setup timers
+ *   const skull = new Sprite("💀");
+ *   skull.x = 400; skull.y = 300; skull.size = 96;
+ *   game.add(skull);
+ * };
+ *
+ * game.onUpdate = (dt) => {
+ *   // normal per-frame update
+ * };
+ *
+ * game.start(); // calls onCreate() once before first frame
+ * // later:
+ * game.reset(); // clears + calls onCreate() again
+ * ```
+ *
+ * ---
+ *
+ * ## Sprite Lifecycle Ownership
+ *
+ * The `Game` instance owns all sprites.
+ * - Create sprites with {@link Game.add}.
+ * - Destroy sprites with {@link Game.destroySprite}.
+ * - Read the live sprite list with {@link Game.getSprites} (returns a read-only snapshot).
+ * - Do NOT hold references to destroyed sprites.
+ * - All sprites are destroyed on {@link Game.reset}.
+ *
+ * ---
+ *
+ * ## Forbidden Features
+ *
+ * The following do NOT exist in MinimoJS v1. Do NOT attempt to use them:
+ * - Scene system or scene manager
+ * - Entity Component System (ECS)
+ * - Physics engine (no Box2D, Matter.js, etc.)
+ * - Camera zoom or scale
+ * - Nested APIs or namespaces
+ * - Text input / HTML form elements
+ * - Parallax layers
+ * - Multiple cameras
+ * - Collision resolution (only detection is supported)
+ * - Image sprites (PNG, SVG, canvas, etc.)
+ * - `setTimeout` or `setInterval`
+ */
+export class Game {
+    // -------------------------------------------------------------------------
+    // Constructor
+    // -------------------------------------------------------------------------
+    /**
+     * Creates a new MinimoJS game instance.
+     *
+     * The engine creates its own `<canvas>`, sets its dimensions, and appends it
+     * to `document.body`. The canvas is automatically centered and responsively
+     * scaled to use the maximum available viewport space while preserving aspect ratio.
+     *
+     * @param width - Canvas width in pixels. Default: `800`.
+     * @param height - Canvas height in pixels. Default: `600`.
+     *
+     * @throws Error if a 2D context cannot be obtained.
+     *
+     * @example
+     * ```ts
+     * const game = new Game(800, 600);
+     * ```
+     */
+    constructor(width = 800, height = 600) {
+        /** @internal */ this._sprites = [];
+        /** @internal */ this._timers = [];
+        /** @internal */ this._animations = [];
+        /** @internal */ this._textOverlays = [];
+        /** @internal */ this._timerIdCounter = 0;
+        /** @internal */ this._keysDown = new Set();
+        /** @internal */ this._keysPressed = new Set();
+        /** @internal */ this._pointerDown = false;
+        /** @internal */ this._pointerPressed = false;
+        /** @internal */ this._pointerX = 0;
+        /** @internal */ this._pointerY = 0;
+        /** @internal */ this._rafId = null;
+        /** @internal */ this._lastTimestamp = null;
+        /** @internal */ this._running = false;
+        /** @internal */ this._hasCreated = false;
+        /** @internal */ this._onResize = () => this._applyResponsiveCanvasLayout();
+        /** @internal */ this._audioCtx = null;
+        /** @internal */ this._lastAppliedPageBackground = undefined;
+        // -------------------------------------------------------------------------
+        // Public state
+        // -------------------------------------------------------------------------
+        /**
+         * Horizontal gravity acceleration in pixels per second².
+         * Applied to every sprite whose {@link Sprite.gravityScale} is non-zero.
+         * Positive = accelerates right. Typical value for sideways wind: `200`.
+         * Default: `0`.
+         *
+         * @example
+         * ```ts
+         * game.gravityX = 0;   // no horizontal gravity
+         * ```
+         */
+        this.gravityX = 0;
+        /**
+         * Vertical gravity acceleration in pixels per second².
+         * Applied to every sprite whose {@link Sprite.gravityScale} is non-zero.
+         * Positive = accelerates downward (canvas Y-axis points down).
+         * Typical value for platformers: `980` (approximately Earth gravity in px/s²).
+         * Default: `0`.
+         *
+         * @example
+         * ```ts
+         * game.gravityY = 980; // standard downward gravity
+         * ```
+         */
+        this.gravityY = 0;
+        /**
+         * Horizontal scroll offset of the world camera, in pixels.
+         * The canvas viewport is shifted left by `scrollX` — sprites with higher `x`
+         * values are revealed as `scrollX` increases.
+         * Default: `0`. Reset to `0` by {@link Game.reset}.
+         *
+         * @example
+         * ```ts
+         * game.scrollX = player.x - game.width / 2; // center camera on player
+         * ```
+         */
+        this.scrollX = 0;
+        /**
+         * Vertical scroll offset of the world camera, in pixels.
+         * The canvas viewport is shifted up by `scrollY` — sprites with higher `y`
+         * values are revealed as `scrollY` increases.
+         * Default: `0`. Reset to `0` by {@link Game.reset}.
+         */
+        this.scrollY = 0;
+        /**
+         * Solid background color for the full canvas.
+         * Set to any valid CSS color string (e.g. `"#000"`, `"skyblue"`, `"rgba(0,0,0,0.5)"`).
+         * Default: `null` (transparent canvas background).
+         *
+         * If {@link Game.backgroundGradient} is set, the gradient takes priority over
+         * this solid color.
+         *
+         * @example
+         * ```ts
+         * game.background = "#101820";
+         * ```
+         */
+        this.background = null;
+        /**
+         * Vertical gradient background for the full canvas.
+         * `from` is the top color and `to` is the bottom color.
+         * Set to `null` to disable gradient mode.
+         *
+         * @example
+         * ```ts
+         * game.backgroundGradient = { from: "#92d7ff", to: "#5ca44f" };
+         * ```
+         */
+        this.backgroundGradient = null;
+        /**
+         * Background color for the full web page (`document.body`).
+         * Set to any valid CSS color string. Default: `null` (engine leaves page background unchanged).
+         *
+         * This is independent from {@link Game.background}, which affects the canvas only.
+         *
+         * @example
+         * ```ts
+         * game.pageBackground = "#f4e4bc";
+         * ```
+         */
+        this.pageBackground = null;
+        /**
+         * Scene creation callback.
+         *
+         * Called once before the first frame on {@link Game.start}, and again after
+         * each {@link Game.reset}. Use this to create sprites and timers for a scene.
+         *
+         * @example
+         * ```ts
+         * game.onCreate = () => {
+         *   const player = new Sprite("🐢");
+         *   player.x = 200;
+         *   player.y = 300;
+         *   game.add(player);
+         * };
+         * ```
+         */
+        this.onCreate = null;
+        /**
+         * Callback invoked once per frame after physics and timer updates.
+         *
+         * @param dt - Delta time in **seconds** since the last frame.
+         *   Use this for velocity-based movement: `sprite.x += speed * dt`.
+         *   Capped at `0.1` seconds (100ms) to prevent spiral-of-death.
+         *
+         * @example
+         * ```ts
+         * game.onUpdate = (dt) => {
+         *   if (game.isKeyDown("ArrowRight")) player.vx = 200;
+         *   else player.vx = 0;
+         * };
+         * ```
+         */
+        this.onUpdate = null;
+        this._canvas = document.createElement("canvas");
+        this._canvas.width = width;
+        this._canvas.height = height;
+        this._canvas.style.display = "block";
+        this._canvas.style.touchAction = "none";
+        this._canvas.style.width = `${width}px`;
+        this._canvas.style.height = `${height}px`;
+        const mountCanvas = () => {
+            if (document.body && !this._canvas.isConnected) {
+                document.body.appendChild(this._canvas);
+            }
+            this._applyResponsiveCanvasLayout();
+        };
+        if (document.body) {
+            mountCanvas();
+        }
+        else {
+            window.addEventListener("DOMContentLoaded", mountCanvas, { once: true });
+        }
+        window.addEventListener("resize", this._onResize);
+        const ctx = this._canvas.getContext("2d");
+        if (!ctx) {
+            throw new Error("MinimoJS: Could not acquire a 2D rendering context.");
+        }
+        this._ctx = ctx;
+        this._bindInputEvents();
+    }
+    // -------------------------------------------------------------------------
+    // Canvas dimensions (read-only)
+    // -------------------------------------------------------------------------
+    /**
+     * The width of the canvas in pixels. Read-only — set via constructor.
+     */
+    get width() {
+        return this._canvas.width;
+    }
+    /**
+     * The height of the canvas in pixels. Read-only — set via constructor.
+     */
+    get height() {
+        return this._canvas.height;
+    }
+    /**
+     * Current pointer (mouse or touch) X position in **canvas/screen space**,
+     * in pixels. Updated every `mousemove` / `touchmove` event.
+     * `(0, 0)` is the top-left corner of the canvas.
+     * To convert to world space: `worldX = game.pointerX + game.scrollX`.
+     */
+    get pointerX() {
+        return this._pointerX;
+    }
+    /**
+     * Current pointer (mouse or touch) Y position in **canvas/screen space**,
+     * in pixels. Updated every `mousemove` / `touchmove` event.
+     * `(0, 0)` is the top-left corner of the canvas.
+     * To convert to world space: `worldY = game.pointerY + game.scrollY`.
+     */
+    get pointerY() {
+        return this._pointerY;
+    }
+    // -------------------------------------------------------------------------
+    // Sprite management
+    // -------------------------------------------------------------------------
+    /**
+     * Registers a {@link Sprite} (or subclass instance) with the engine.
+     * After calling `add`, the sprite is rendered and receives physics updates
+     * every frame until {@link Game.destroySprite} or {@link Game.reset} is called.
+     *
+     * **Ownership:** The game instance takes ownership of the sprite from this
+     * point forward. It will appear in {@link Game.getSprites} on the same frame.
+     *
+     * **Subclasses:** Any class that extends {@link Sprite} can be passed here.
+     * The engine stores and processes it as a `Sprite`; your custom properties
+     * are preserved on the instance.
+     *
+     * @param sprite - A {@link Sprite} instance (or subclass) to add.
+     * @returns The same sprite instance, for chaining or inline assignment.
+     *
+     * @example
+     * ```ts
+     * // Plain sprite
+     * const coin = new Sprite("🪙");
+     * coin.x = 300; coin.y = 200; coin.size = 32;
+     * game.add(coin);
+     *
+     * // Custom subclass
+     * class Enemy extends Sprite {
+     *   speed = 150;
+     *   constructor(x: number, y: number) {
+     *     super("👾");
+     *     this.x = x; this.y = y; this.size = 40;
+     *   }
+     * }
+     * const enemy = game.add(new Enemy(600, 100));
+     * ```
+     */
+    add(sprite) {
+        this._sprites.push(sprite);
+        return sprite;
+    }
+    /**
+     * Removes a sprite from the engine, stopping its rendering and physics updates.
+     * Also cancels any running animations targeting this sprite.
+     *
+     * **Side effects:** The sprite is removed immediately. Accessing the sprite's
+     * fields after destruction has no effect on the engine, but reading them
+     * returns stale values. Do not keep references to destroyed sprites.
+     *
+     * If `sprite` is not found (already destroyed or never added), this is a no-op.
+     *
+     * @param sprite - The sprite instance to destroy, as passed to {@link Game.add}.
+     *
+     * @example
+     * ```ts
+     * game.destroySprite(enemy); // remove enemy from game
+     * ```
+     */
+    destroySprite(sprite) {
+        const idx = this._sprites.indexOf(sprite);
+        if (idx !== -1)
+            this._sprites.splice(idx, 1);
+        this._animations = this._animations.filter((a) => a.sprite !== sprite);
+    }
+    /**
+     * Returns a **read-only snapshot** of all currently active sprites.
+     * The array is a shallow copy — mutating it has no effect on the engine.
+     * Individual sprite objects in the array are the live instances.
+     *
+     * **Deterministic guarantee:** Sprites appear in creation order within each
+     * layer. The order matches the render order (lower layer = earlier in array).
+     *
+     * @returns A read-only array of active {@link Sprite} instances.
+     *
+     * @example
+     * ```ts
+     * const enemies = game.getSprites().filter(s => s.sprite === "👾");
+     * ```
+     */
+    getSprites() {
+        return [...this._sprites];
+    }
+    // -------------------------------------------------------------------------
+    // Collision
+    // -------------------------------------------------------------------------
+    /**
+     * Tests whether two sprites overlap using **Axis-Aligned Bounding Box (AABB)**
+     * collision detection.
+     *
+     * Each sprite's bounding box is a square centered at `(x, y)` with side
+     * length `size`. Rotation is **ignored** — the box is always axis-aligned.
+     *
+     * **No collision resolution is performed.** This method is detection-only.
+     * If you need bounce or push-apart behavior, implement it in `onUpdate`.
+     *
+     * @param a - First sprite.
+     * @param b - Second sprite.
+     * @returns `true` if the bounding boxes overlap; `false` otherwise.
+     *
+     * @example
+     * ```ts
+     * if (game.overlap(player, enemy)) {
+     *   game.reset(); // restart on collision
+     * }
+     * ```
+     */
+    overlap(a, b) {
+        const halfA = a.size / 2;
+        const halfB = b.size / 2;
+        return (Math.abs(a.x - b.x) < halfA + halfB &&
+            Math.abs(a.y - b.y) < halfA + halfB);
+    }
+    /**
+     * Tests for any overlap between two groups of sprites.
+     * Performs an O(n × m) AABB check for every pair `(a, b)` where `a ∈ listA`
+     * and `b ∈ listB`. Returns the **first** overlapping pair found.
+     *
+     * Internally uses {@link Game.overlap} — same AABB rules apply.
+     * No collision resolution is performed.
+     *
+     * @param listA - First group of sprites.
+     * @param listB - Second group of sprites. May share sprites with `listA`.
+     * @returns A `[Sprite, Sprite]` tuple of the first overlapping pair,
+     *   or `null` if no pair overlaps.
+     *
+     * @example
+     * ```ts
+     * const hit = game.overlapAny(bullets, enemies);
+     * if (hit) {
+     *   const [bullet, enemy] = hit;
+     *   game.destroySprite(bullet);
+     *   game.destroySprite(enemy);
+     * }
+     * ```
+     */
+    overlapAny(listA, listB) {
+        for (const a of listA) {
+            for (const b of listB) {
+                if (this.overlap(a, b))
+                    return [a, b];
+            }
+        }
+        return null;
+    }
+    // -------------------------------------------------------------------------
+    // Input — Keyboard
+    // -------------------------------------------------------------------------
+    /**
+     * Returns `true` while the specified key is held down (every frame it is held).
+     * Use this for continuous actions like movement.
+     *
+     * Uses the `KeyboardEvent.key` string (e.g. `"ArrowLeft"`, `"a"`, `" "`, `"Enter"`).
+     * Key names are case-sensitive.
+     *
+     * **Hold behavior:** returns `true` on the first frame the key is pressed AND
+     * every subsequent frame until the key is released.
+     *
+     * @param key - The `KeyboardEvent.key` value to check.
+     * @returns `true` if the key is currently held down.
+     *
+     * @example
+     * ```ts
+     * if (game.isKeyDown("ArrowRight")) player.vx = 200;
+     * ```
+     */
+    isKeyDown(key) {
+        return this._keysDown.has(key);
+    }
+    /**
+     * Returns `true` only on the **single frame** the key was first pressed.
+     * Use this for one-shot actions like jumping or firing.
+     *
+     * **Edge behavior:** returns `true` exactly once per press, on the frame the
+     * key transitions from up → down. Subsequent frames while held return `false`.
+     *
+     * @param key - The `KeyboardEvent.key` value to check.
+     * @returns `true` only on the first frame of the key press.
+     *
+     * @example
+     * ```ts
+     * if (game.isKeyPressed(" ")) player.vy = -500; // jump on spacebar press
+     * ```
+     */
+    isKeyPressed(key) {
+        return this._keysPressed.has(key);
+    }
+    // -------------------------------------------------------------------------
+    // Input — Pointer (mouse / touch)
+    // -------------------------------------------------------------------------
+    /**
+     * Returns `true` while the pointer (mouse button or touch) is held down.
+     * Use this for continuous pointer actions.
+     *
+     * **Hold behavior:** returns `true` every frame from press until release.
+     *
+     * @returns `true` if the pointer is currently pressed.
+     *
+     * @example
+     * ```ts
+     * if (game.isPointerDown()) fireContinuously();
+     * ```
+     */
+    isPointerDown() {
+        return this._pointerDown;
+    }
+    /**
+     * Returns `true` only on the **single frame** the pointer was first pressed.
+     * Use this for tap/click one-shot actions.
+     *
+     * **Edge behavior:** returns `true` exactly once per press, on the frame the
+     * pointer transitions from up → down. Subsequent frames while held return `false`.
+     *
+     * @returns `true` only on the first frame of the pointer press.
+     *
+     * @example
+     * ```ts
+     * if (game.isPointerPressed()) spawnAt(game.pointerX, game.pointerY);
+     * ```
+     */
+    isPointerPressed() {
+        return this._pointerPressed;
+    }
+    /**
+     * Returns `true` when the current device appears to be mobile/touch-first.
+     *
+     * This is a heuristic helper intended for gameplay UI decisions (for example,
+     * showing on-screen touch controls). It checks user-agent/platform hints and
+     * coarse-pointer/touch capabilities.
+     *
+     * @returns `true` if the runtime likely corresponds to a mobile device.
+     *
+     * @example
+     * ```ts
+     * if (game.isMobileDevice()) {
+     *   // Show touch buttons
+     * } else {
+     *   // Show keyboard hints
+     * }
+     * ```
+     */
+    isMobileDevice() {
+        if (typeof navigator === "undefined")
+            return false;
+        const ua = navigator.userAgent ?? "";
+        const mobileUA = /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini|Mobile/i.test(ua);
+        const iPadOS = navigator.platform === "MacIntel" && navigator.maxTouchPoints > 1;
+        const coarsePointer = typeof window !== "undefined" &&
+            typeof window.matchMedia === "function" &&
+            window.matchMedia("(pointer: coarse)").matches;
+        return mobileUA || iPadOS || coarsePointer;
+    }
+    // -------------------------------------------------------------------------
+    // Sound
+    // -------------------------------------------------------------------------
+    /**
+     * Plays a square-wave beep using the Web Audio API.
+     *
+     * **Square wave only.** MinimoJS does not support audio files, samples,
+     * or other waveforms. Only procedural square-wave tones.
+     *
+     * The AudioContext is created lazily on first call. Browsers require a user
+     * gesture (click, keypress) before audio can play — always call `sound()` in
+     * response to user input or a game event triggered by input.
+     *
+     * The tone fades out exponentially over `durationMs` to avoid clicks.
+     *
+     * @param freq - Frequency in Hz. Middle C = 261.6. Typical range: 100–4000 Hz.
+     * @param durationMs - Duration of the sound in **milliseconds**.
+     *
+     * @example
+     * ```ts
+     * game.sound(440, 100);   // 440 Hz beep for 100ms
+     * game.sound(261, 500);   // middle C for 500ms
+     * game.sound(880, 50);    // high beep for 50ms (jump sound)
+     * ```
+     */
+    sound(freq, durationMs) {
+        if (!this._audioCtx) {
+            this._audioCtx = new AudioContext();
+        }
+        const ctx = this._audioCtx;
+        if (ctx.state === "suspended") {
+            ctx.resume();
+        }
+        const oscillator = ctx.createOscillator();
+        const gain = ctx.createGain();
+        oscillator.type = "square";
+        oscillator.frequency.setValueAtTime(freq, ctx.currentTime);
+        gain.gain.setValueAtTime(0.08, ctx.currentTime);
+        gain.gain.exponentialRampToValueAtTime(0.001, ctx.currentTime + durationMs / 1000);
+        oscillator.connect(gain);
+        gain.connect(ctx.destination);
+        oscillator.start(ctx.currentTime);
+        oscillator.stop(ctx.currentTime + durationMs / 1000);
+    }
+    // -------------------------------------------------------------------------
+    // Animations
+    // -------------------------------------------------------------------------
+    /**
+     * Animates a sprite's {@link Sprite.alpha} from its current value to `to`
+     * over `durationMs` milliseconds using **linear interpolation**.
+     *
+     * If an alpha animation is already running on this sprite, it is replaced
+     * by the new one immediately (no queuing).
+     *
+     * **Timing:** driven by the rAF loop, not `setTimeout`. Duration is in ms.
+     *
+     * @param sprite - The sprite to animate.
+     * @param to - Target alpha value (0 = transparent, 1 = opaque).
+     * @param durationMs - Duration of the animation in **milliseconds**.
+     * @param onComplete - Optional callback invoked when the animation finishes.
+     *
+     * @example
+     * ```ts
+     * // Fade out a sprite over 1 second, then destroy it
+     * game.animateAlpha(coin, 0, 1000, () => game.destroySprite(coin));
+     * ```
+     */
+    animateAlpha(sprite, to, durationMs, onComplete) {
+        this._animations = this._animations.filter((a) => !(a.sprite === sprite && a.property === "alpha"));
+        this._animations.push({
+            sprite,
+            property: "alpha",
+            from: sprite.alpha,
+            to,
+            durationMs,
+            elapsed: 0,
+            onComplete,
+        });
+    }
+    /**
+     * Animates a sprite's {@link Sprite.rotation} from its current value to `to`
+     * (in degrees) over `durationMs` milliseconds using **linear interpolation**.
+     *
+     * If a rotation animation is already running on this sprite, it is replaced
+     * immediately (no queuing).
+     *
+     * **Timing:** driven by the rAF loop, not `setTimeout`. Duration is in ms.
+     * **Units:** `to` is in **degrees**.
+     *
+     * @param sprite - The sprite to animate.
+     * @param to - Target rotation in **degrees**.
+     * @param durationMs - Duration of the animation in **milliseconds**.
+     * @param onComplete - Optional callback invoked when the animation finishes.
+     *
+     * @example
+     * ```ts
+     * // Spin a sprite 360° over 2 seconds
+     * game.animateRotation(star, 360, 2000);
+     *
+     * // Tilt on hit, then straighten
+     * game.animateRotation(player, 45, 200, () => {
+     *   game.animateRotation(player, 0, 200);
+     * });
+     * ```
+     */
+    animateRotation(sprite, to, durationMs, onComplete) {
+        this._animations = this._animations.filter((a) => !(a.sprite === sprite && a.property === "rotation"));
+        this._animations.push({
+            sprite,
+            property: "rotation",
+            from: sprite.rotation,
+            to,
+            durationMs,
+            elapsed: 0,
+            onComplete,
+        });
+    }
+    // -------------------------------------------------------------------------
+    // Timers
+    // -------------------------------------------------------------------------
+    /**
+     * Schedules a callback to fire after `delayMs` milliseconds, driven by the
+     * rAF loop (not `setTimeout`). Timers accumulate elapsed time each frame and
+     * fire once the threshold is reached.
+     *
+     * **Repeat behavior:**
+     * - `repeat = false`: fires once, then auto-removes.
+     * - `repeat = true`: fires every `delayMs` ms until cleared with {@link Game.clearTimer}.
+     *   The elapsed time wraps (excess time carries over), so repeat timers are
+     *   accurate over long durations.
+     *
+     * **Reset behavior:** ALL timers are cleared on {@link Game.reset}.
+     *
+     * @param delayMs - Delay (and period for repeating timers) in **milliseconds**.
+     * @param repeat - If `true`, the timer fires repeatedly every `delayMs` ms.
+     * @param callback - Function to call when the timer fires.
+     * @returns A numeric timer ID for use with {@link Game.clearTimer}.
+     *
+     * @example
+     * ```ts
+     * // One-shot: explode after 3 seconds
+     * game.addTimer(3000, false, () => { bomb.sprite = "💥"; });
+     *
+     * // Repeating: spawn enemy every 2 seconds
+     * const spawnId = game.addTimer(2000, true, spawnEnemy);
+     * // Stop spawning:
+     * game.clearTimer(spawnId);
+     * ```
+     */
+    addTimer(delayMs, repeat, callback) {
+        const id = ++this._timerIdCounter;
+        this._timers.push({ id, delayMs, elapsed: 0, repeat, callback });
+        return id;
+    }
+    /**
+     * Cancels a timer previously created with {@link Game.addTimer}.
+     * If the ID does not exist (already fired and removed, or never created),
+     * this is a safe no-op.
+     *
+     * @param id - The timer ID returned by {@link Game.addTimer}.
+     *
+     * @example
+     * ```ts
+     * const id = game.addTimer(5000, true, spawnEnemy);
+     * // Stop spawning when player reaches the end:
+     * game.clearTimer(id);
+     * ```
+     */
+    clearTimer(id) {
+        this._timers = this._timers.filter((t) => t.id !== id);
+    }
+    // -------------------------------------------------------------------------
+    // Text
+    // -------------------------------------------------------------------------
+    /**
+     * Draws text on screen as a **screen-space overlay** this frame.
+     *
+     * **Overlay behavior:** Text is drawn in canvas/screen space — it ignores
+     * `scrollX` / `scrollY`. Position `(0, 0)` is always the top-left of the canvas.
+     * Use this for HUD elements: score, lives, timer, debug info.
+     *
+     * **Per-frame:** `drawText` must be called every frame to keep text visible.
+     * The text overlay list is cleared after each render. Call this inside `onUpdate`.
+     *
+     * **Layer:** Text is always drawn on top of all sprites.
+     * **Font:** Text always uses a fixed `monospace` font family.
+     * Font family cannot be customized in MinimoJS v1.
+     *
+     * @param text - The string to render. Supports emoji and Unicode.
+     * @param x - X position in **screen space** (pixels from canvas left edge).
+     * @param y - Y position in **screen space** (pixels from canvas top edge).
+     *   Text baseline is at the top of the text.
+     * @param fontSize - Font size in pixels (e.g. `16`, `24`, `32`).
+     * @param color - CSS color string. Default: `"#ffffff"` (white).
+     * @param centered - If `true`, text is centered on `(x, y)` (both axes).
+     *   If `false`, `(x, y)` is the top-left anchor. Default: `false`.
+     *
+     * @example
+     * ```ts
+     * game.onUpdate = (dt) => {
+     *   game.drawText(`Score: ${score}`, 10, 10, 20, "#ffff00");
+     *   game.drawText(`Lives: ${"❤️".repeat(lives)}`, 10, 40, 20);
+     *   game.drawText("PAUSED", game.width / 2, game.height / 2, 28, "#ffffff", true);
+     * };
+     * ```
+     */
+    drawText(text, x, y, fontSize, color = "#ffffff", centered = false) {
+        this._textOverlays.push({ text, x, y, fontSize, color, centered });
+    }
+    // -------------------------------------------------------------------------
+    // Misc
+    // -------------------------------------------------------------------------
+    /**
+     * Returns a pseudo-random floating-point number in the range `[0, 1)`.
+     * Delegates to `Math.random()`.
+     *
+     * **Determinism note:** This method is NOT seeded and NOT deterministic across
+     * runs. The output changes every invocation. If you need reproducible randomness,
+     * implement a seeded PRNG (e.g. a simple LCG) in your game code.
+     *
+     * @returns A random number in `[0, 1)`.
+     *
+     * @example
+     * ```ts
+     * const x = game.random() * game.width;
+     * const emoji = ["⭐", "🔥", "💎"][Math.floor(game.random() * 3)];
+     * ```
+     */
+    random() {
+        return Math.random();
+    }
+    /**
+     * Performs a full engine state reset to enable scene switching.
+     *
+     * **Cleared by reset:**
+     * - All sprites (equivalent to calling {@link Game.destroySprite} on every sprite)
+     * - All timers (regardless of repeat state)
+     * - All running animations
+     * - All pending text overlays
+     * - Scroll position (`scrollX = 0`, `scrollY = 0`)
+     * - Per-frame input state (pressed keys, pressed pointer)
+     *
+     * **NOT cleared by reset:**
+     * - `gravityX` / `gravityY` (global engine setting)
+     * - `background` / `backgroundGradient` / `pageBackground`
+     * - `onCreate` callback (your handler stays registered)
+     * - `onUpdate` callback (your handler stays registered)
+     * - Canvas dimensions
+     * - AudioContext
+     *
+     * After clearing, `reset()` immediately calls `onCreate()` so your callback
+     * can rebuild the new scene synchronously.
+     *
+     * @example
+     * ```ts
+     * // Switch from gameplay to game-over screen
+     * function gameOver() {
+     *   game.reset(); // onCreate() is called here, rebuild inside it
+     * }
+     *
+     * game.onCreate = () => {
+     *   // Scene init
+     *   const skull = new Sprite("💀");
+     *   skull.x = 400; skull.y = 300; skull.size = 96;
+     *   game.add(skull);
+     *   game.addTimer(3000, false, () => game.reset()); // auto-restart
+     * };
+     * ```
+     */
+    reset() {
+        this._sprites = [];
+        this._timers = [];
+        this._animations = [];
+        this._textOverlays = [];
+        this._keysPressed.clear();
+        this._pointerPressed = false;
+        this.scrollX = 0;
+        this.scrollY = 0;
+        this._invokeCreate();
+    }
+    // -------------------------------------------------------------------------
+    // Loop control
+    // -------------------------------------------------------------------------
+    /**
+     * Starts the `requestAnimationFrame` game loop.
+     * Safe to call multiple times — does nothing if already running.
+     * If this is the first start (or after a reset), `onCreate()` is called
+     * before the first frame.
+     *
+     * The loop calls `onUpdate` once per frame, then renders all sprites and
+     * text overlays. Order per frame:
+     * 1. Accumulate timer elapsed time; fire ready callbacks.
+     * 2. Advance animations (linear interpolation).
+     * 3. Apply gravity to sprite velocities.
+     * 4. Apply velocities to sprite positions.
+     * 5. Call `onUpdate(dt)`.
+     * 6. Render sprites (sorted by layer) with scroll offset.
+     * 7. Render text overlays (screen space, on top of sprites).
+     * 8. Clear per-frame input state.
+     *
+     * @example
+     * ```ts
+     * game.onUpdate = (dt) => { ... };
+     * game.start();
+     * ```
+     */
+    start() {
+        if (this._running)
+            return;
+        if (!this._hasCreated)
+            this._invokeCreate();
+        this._running = true;
+        this._lastTimestamp = null;
+        this._rafId = requestAnimationFrame(this._loop.bind(this));
+    }
+    /**
+     * Stops the game loop. The canvas retains its last rendered frame.
+     * Call {@link Game.start} to resume.
+     */
+    stop() {
+        this._running = false;
+        if (this._rafId !== null) {
+            cancelAnimationFrame(this._rafId);
+            this._rafId = null;
+        }
+        this._lastTimestamp = null;
+    }
+    // -------------------------------------------------------------------------
+    // Private — input binding
+    // -------------------------------------------------------------------------
+    /** @internal */
+    _bindInputEvents() {
+        window.addEventListener("keydown", (e) => {
+            if (!this._keysDown.has(e.key)) {
+                this._keysPressed.add(e.key);
+            }
+            this._keysDown.add(e.key);
+        });
+        window.addEventListener("keyup", (e) => {
+            this._keysDown.delete(e.key);
+        });
+        const getCanvasPoint = (e) => {
+            const rect = this._canvas.getBoundingClientRect();
+            const scaleX = this._canvas.width / rect.width;
+            const scaleY = this._canvas.height / rect.height;
+            let clientX;
+            let clientY;
+            if (e instanceof MouseEvent) {
+                clientX = e.clientX;
+                clientY = e.clientY;
+            }
+            else {
+                clientX = e.touches[0]?.clientX ?? this._pointerX;
+                clientY = e.touches[0]?.clientY ?? this._pointerY;
+            }
+            return {
+                x: (clientX - rect.left) * scaleX,
+                y: (clientY - rect.top) * scaleY,
+            };
+        };
+        this._canvas.addEventListener("mousedown", (e) => {
+            const p = getCanvasPoint(e);
+            this._pointerX = p.x;
+            this._pointerY = p.y;
+            this._pointerDown = true;
+            this._pointerPressed = true;
+        });
+        this._canvas.addEventListener("mouseup", () => {
+            this._pointerDown = false;
+        });
+        this._canvas.addEventListener("mousemove", (e) => {
+            const p = getCanvasPoint(e);
+            this._pointerX = p.x;
+            this._pointerY = p.y;
+        });
+        this._canvas.addEventListener("touchstart", (e) => {
+            const p = getCanvasPoint(e);
+            this._pointerX = p.x;
+            this._pointerY = p.y;
+            this._pointerDown = true;
+            this._pointerPressed = true;
+            e.preventDefault();
+        }, { passive: false });
+        this._canvas.addEventListener("touchend", () => {
+            this._pointerDown = false;
+        });
+        this._canvas.addEventListener("touchmove", (e) => {
+            const p = getCanvasPoint(e);
+            this._pointerX = p.x;
+            this._pointerY = p.y;
+            e.preventDefault();
+        }, { passive: false });
+    }
+    // -------------------------------------------------------------------------
+    // Private — rAF loop
+    // -------------------------------------------------------------------------
+    /** @internal */
+    _loop(timestamp) {
+        if (!this._running)
+            return;
+        if (this._lastTimestamp === null) {
+            this._lastTimestamp = timestamp;
+        }
+        let dt = (timestamp - this._lastTimestamp) / 1000;
+        this._lastTimestamp = timestamp;
+        if (dt > 0.1)
+            dt = 0.1;
+        const dtMs = dt * 1000;
+        this._updateTimers(dtMs);
+        this._updateAnimations(dtMs);
+        this._updatePhysics(dt);
+        if (this.onUpdate)
+            this.onUpdate(dt);
+        this._render();
+        this._keysPressed.clear();
+        this._pointerPressed = false;
+        this._textOverlays = [];
+        this._rafId = requestAnimationFrame(this._loop.bind(this));
+    }
+    /** @internal */
+    _updateTimers(dtMs) {
+        const toRemove = [];
+        const toFire = [];
+        for (const timer of this._timers) {
+            timer.elapsed += dtMs;
+            if (timer.elapsed >= timer.delayMs) {
+                toFire.push(timer);
+                if (timer.repeat) {
+                    timer.elapsed -= timer.delayMs;
+                }
+                else {
+                    toRemove.push(timer.id);
+                }
+            }
+        }
+        if (toRemove.length > 0) {
+            this._timers = this._timers.filter((t) => !toRemove.includes(t.id));
+        }
+        for (const timer of toFire) {
+            timer.callback();
+        }
+    }
+    /** @internal */
+    _updateAnimations(dtMs) {
+        const toRemove = [];
+        for (let i = 0; i < this._animations.length; i++) {
+            const anim = this._animations[i];
+            anim.elapsed += dtMs;
+            const t = Math.min(anim.elapsed / anim.durationMs, 1);
+            anim.sprite[anim.property] = anim.from + (anim.to - anim.from) * t;
+            if (t >= 1) {
+                toRemove.push(i);
+                anim.onComplete?.();
+            }
+        }
+        for (let i = toRemove.length - 1; i >= 0; i--) {
+            this._animations.splice(toRemove[i], 1);
+        }
+    }
+    /** @internal */
+    _updatePhysics(dt) {
+        for (const sprite of this._sprites) {
+            if (sprite.gravityScale !== 0) {
+                sprite.vx += this.gravityX * sprite.gravityScale * dt;
+                sprite.vy += this.gravityY * sprite.gravityScale * dt;
+            }
+            sprite.x += sprite.vx * dt;
+            sprite.y += sprite.vy * dt;
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Private — rendering
+    // -------------------------------------------------------------------------
+    /** @internal */
+    _render() {
+        const ctx = this._ctx;
+        const W = this._canvas.width;
+        const H = this._canvas.height;
+        this._applyPageBackground();
+        ctx.clearRect(0, 0, W, H);
+        if (this.backgroundGradient !== null) {
+            const gradient = ctx.createLinearGradient(0, 0, 0, H);
+            gradient.addColorStop(0, this.backgroundGradient.from);
+            gradient.addColorStop(1, this.backgroundGradient.to);
+            ctx.fillStyle = gradient;
+            ctx.fillRect(0, 0, W, H);
+        }
+        else if (this.background !== null) {
+            ctx.fillStyle = this.background;
+            ctx.fillRect(0, 0, W, H);
+        }
+        const sorted = [...this._sprites].sort((a, b) => a.layer - b.layer);
+        for (const sprite of sorted) {
+            if (!sprite.visible)
+                continue;
+            ctx.save();
+            ctx.globalAlpha = Math.max(0, Math.min(1, sprite.alpha));
+            const drawX = sprite.ignoreScroll ? sprite.x : sprite.x - this.scrollX;
+            const drawY = sprite.ignoreScroll ? sprite.y : sprite.y - this.scrollY;
+            ctx.translate(drawX, drawY);
+            if (sprite.rotation !== 0) {
+                ctx.rotate((sprite.rotation * Math.PI) / 180);
+            }
+            if (sprite.flipX || sprite.flipY) {
+                ctx.scale(sprite.flipX ? -1 : 1, sprite.flipY ? -1 : 1);
+            }
+            ctx.font = `${sprite.size}px serif`;
+            ctx.textAlign = "center";
+            ctx.textBaseline = "middle";
+            ctx.fillText(sprite.sprite, 0, 0);
+            ctx.restore();
+        }
+        for (const entry of this._textOverlays) {
+            ctx.save();
+            ctx.font = `${entry.fontSize}px monospace`;
+            ctx.fillStyle = entry.color;
+            ctx.textAlign = entry.centered ? "center" : "left";
+            ctx.textBaseline = entry.centered ? "middle" : "top";
+            ctx.fillText(entry.text, entry.x, entry.y);
+            ctx.restore();
+        }
+    }
+    /** @internal */
+    _applyPageBackground() {
+        if (!document.body)
+            return;
+        if (this._lastAppliedPageBackground === this.pageBackground)
+            return;
+        if (this.pageBackground === null) {
+            document.body.style.removeProperty("background");
+        }
+        else {
+            document.body.style.background = this.pageBackground;
+        }
+        this._lastAppliedPageBackground = this.pageBackground;
+    }
+    /** @internal */
+    _applyResponsiveCanvasLayout() {
+        if (!document.body)
+            return;
+        document.body.style.margin = "0";
+        document.body.style.minHeight = "100vh";
+        document.body.style.display = "grid";
+        document.body.style.placeItems = "center";
+        document.body.style.touchAction = "manipulation";
+        const viewportW = Math.max(1, window.innerWidth);
+        const viewportH = Math.max(1, window.innerHeight);
+        const scale = Math.min(viewportW / this._canvas.width, viewportH / this._canvas.height);
+        const safeScale = Number.isFinite(scale) && scale > 0 ? scale : 1;
+        this._canvas.style.width = `${Math.floor(this._canvas.width * safeScale)}px`;
+        this._canvas.style.height = `${Math.floor(this._canvas.height * safeScale)}px`;
+    }
+    /** @internal */
+    _invokeCreate() {
+        this._hasCreated = true;
+        if (this.onCreate)
+            this.onCreate();
+    }
+}