minimojs 1.0.0-alpha.1

package/dist/minimo.d.ts

@@ -0,0 +1,941 @@
+/**
+ * @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.
+ */
+/**
+ * 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 declare class Sprite {
+    /**
+     * The emoji character used to render this sprite.
+     * Must be a single emoji. Change this at runtime to animate between frames.
+     * @example "🔥", "⭐", "🐢"
+     */
+    sprite: string;
+    /**
+     * 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.
+     */
+    x: number;
+    /**
+     * 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.
+     */
+    y: number;
+    /**
+     * Width and height of the sprite's bounding square, in pixels.
+     * Used for both canvas rendering (font size) and AABB collision detection.
+     */
+    size: number;
+    /**
+     * 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.
+     */
+    rotation: number;
+    /**
+     * Horizontal visual flip.
+     * When `true`, the sprite is mirrored left-right during rendering.
+     * This is visual-only and does NOT affect collision detection.
+     */
+    flipX: boolean;
+    /**
+     * Vertical visual flip.
+     * When `true`, the sprite is mirrored top-bottom during rendering.
+     * This is visual-only and does NOT affect collision detection.
+     */
+    flipY: boolean;
+    /**
+     * 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.
+     */
+    ignoreScroll: boolean;
+    /**
+     * Opacity of the sprite. Must be in range `[0, 1]`.
+     * `0` = fully transparent, `1` = fully opaque.
+     * Clamped to `[0, 1]` at render time.
+     */
+    alpha: number;
+    /**
+     * 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.
+     */
+    visible: boolean;
+    /**
+     * 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.
+     */
+    layer: number;
+    /**
+     * Horizontal velocity in pixels per second.
+     * Applied each frame: `x += vx * dt`.
+     * Gravity also modifies this: `vx += gravityX * gravityScale * dt`.
+     */
+    vx: number;
+    /**
+     * Vertical velocity in pixels per second.
+     * Applied each frame: `y += vy * dt`.
+     * Gravity also modifies this: `vy += gravityY * gravityScale * dt`.
+     */
+    vy: number;
+    /**
+     * 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.
+     */
+    gravityScale: number;
+    /**
+     * 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: string, x?: number, y?: number);
+}
+/**
+ * # 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 declare class Game {
+    /**
+     * 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
+     * ```
+     */
+    gravityX: number;
+    /**
+     * 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
+     * ```
+     */
+    gravityY: number;
+    /**
+     * 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
+     * ```
+     */
+    scrollX: number;
+    /**
+     * 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}.
+     */
+    scrollY: number;
+    /**
+     * 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";
+     * ```
+     */
+    background: string | 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" };
+     * ```
+     */
+    backgroundGradient: {
+        from: string;
+        to: string;
+    } | 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";
+     * ```
+     */
+    pageBackground: string | 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);
+     * };
+     * ```
+     */
+    onCreate: (() => void) | 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;
+     * };
+     * ```
+     */
+    onUpdate: ((dt: number) => void) | null;
+    /**
+     * 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?: number, height?: number);
+    /**
+     * The width of the canvas in pixels. Read-only — set via constructor.
+     */
+    get width(): number;
+    /**
+     * The height of the canvas in pixels. Read-only — set via constructor.
+     */
+    get height(): number;
+    /**
+     * 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(): number;
+    /**
+     * 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(): number;
+    /**
+     * 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: Sprite): 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: Sprite): void;
+    /**
+     * 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(): readonly Sprite[];
+    /**
+     * 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: Sprite, b: Sprite): boolean;
+    /**
+     * 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: Sprite[], listB: Sprite[]): [Sprite, Sprite] | null;
+    /**
+     * 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: string): boolean;
+    /**
+     * 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: string): boolean;
+    /**
+     * 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(): boolean;
+    /**
+     * 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(): boolean;
+    /**
+     * 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(): boolean;
+    /**
+     * 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: number, durationMs: number): void;
+    /**
+     * 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: Sprite, to: number, durationMs: number, onComplete?: () => void): void;
+    /**
+     * 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: Sprite, to: number, durationMs: number, onComplete?: () => void): void;
+    /**
+     * 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: number, repeat: boolean, callback: () => void): number;
+    /**
+     * 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: number): void;
+    /**
+     * 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: string, x: number, y: number, fontSize: number, color?: string, centered?: boolean): void;
+    /**
+     * 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(): number;
+    /**
+     * 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(): void;
+    /**
+     * 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(): void;
+    /**
+     * Stops the game loop. The canvas retains its last rendered frame.
+     * Call {@link Game.start} to resume.
+     */
+    stop(): void;
+}