minimojs 1.0.0-alpha.4 → 1.0.0-alpha.41

package/dist/minimo.js

@@ -7,81 +7,40 @@
  * ALL ROTATIONS ARE IN DEGREES.
  * THE ENGINE LOOP USES requestAnimationFrame ONLY.
  */
+import { AnimationSystem } from "./internal/AnimationSystem.js";
+import { AssetSystem } from "./internal/AssetSystem.js";
+import { BackgroundSystem } from "./internal/BackgroundSystem.js";
+import { CanvasSystem } from "./internal/CanvasSystem.js";
+import { ExplosionSystem } from "./internal/ExplosionSystem.js";
+import { InputSystem } from "./internal/InputSystem.js";
+import { LoopSystem } from "./internal/LoopSystem.js";
+import { PhysicsSystem } from "./internal/PhysicsSystem.js";
+import { RenderSystem } from "./internal/RenderSystem.js";
+import { SoundSystem } from "./internal/SoundSystem.js";
+import { SpriteSystem } from "./internal/SpriteSystem.js";
+import { TextSystem } from "./internal/TextSystem.js";
+import { TrailSystem } from "./internal/TrailSystem.js";
+import { TransitionSystem } from "./internal/TransitionSystem.js";
+import { TimerSystem } from "./internal/TimerSystem.js";
+import { Design, designModules, findFirst, parseAssetFile, parseDesignObject } from "./minimo-format.js";
+export { Design, parseAssetFile } from "./minimo-format.js";
+export { SoundPlayback } from "./internal/SoundSystem.js";
+/** How long a scene may load before it dims and its progress ring appears, so a fast load shows neither. */
+const SCENE_LOADING_INDICATOR_DELAY_MS = 250;
+/** How long the dimming and the ring take to fade in once they appear. */
+const SCENE_LOADING_FADE_MS = 200;
 // ---------------------------------------------------------------------------
-// Sprite
+// EmojiSprite
 // ---------------------------------------------------------------------------
 /**
- * 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("🪙", 300, 200, 32);
- * game.add(coin);
- * ```
+ * Base class for all renderable MinimoJS actors.
  *
- * @example
- * ```ts
- * // Subclassing for custom game objects
- * class Player extends Sprite {
- *   health = 3;
- *
- *   constructor(x: number, y: number) {
- *     super("🐢", x, y, 48);
- *     this.gravityScale = 1;
- *   }
- * }
- *
- * const player = new Player(400, 300);
- * game.add(player);
- * ```
+ * Concrete subclasses provide their own visual content while inheriting the
+ * shared transform, visibility, physics, and animation state required by the
+ * engine.
  */
 export class Sprite {
-    /**
-     * Base width and height of this sprite in pixels.
-     *
-     * This value is read-only after construction and defines the glyph-cache
-     * render size. The visible and collision size during gameplay is exposed by
-     * {@link Sprite.displaySize}.
-     */
-    get size() {
-        return this._size;
-    }
-    /**
-     * Effective rendered/collision size in pixels.
-     * Computed as `size * scale` with non-negative clamping.
-     */
-    get displaySize() {
-        const safeScale = Number.isFinite(this.scale) ? this.scale : 1;
-        return this._size * Math.max(0, safeScale);
-    }
-    /**
-     * Creates a new Sprite with the given emoji, optional position, and base size.
-     * 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`.
-     * @param size - Base sprite size in pixels. Default: `32`.
-     *
-     * @example
-     * ```ts
-     * const enemy = new Sprite("👾", 200, 100, 40);
-     * game.add(enemy);
-     * ```
-     */
-    constructor(sprite, x = 0, y = 0, size = 32) {
+    constructor(game = null) {
         /**
          * X position in world space (horizontal center of the sprite), in pixels.
          * Positive X points right. Updated each frame by: `x += vx * dt`.
@@ -95,13 +54,42 @@ export class Sprite {
          */
         this.y = 0;
         /**
-         * Visual scale multiplier applied to {@link Sprite.size}.
+         * Visual scale multiplier applied to this sprite's logical width/height.
          * Default: `1`.
-         *
-         * Set this at runtime to resize a sprite without changing its base cached
-         * glyph size.
          */
         this.scale = 1;
+        /** @internal */
+        this._renderData = null;
+        /**
+         * Optional logical body width used by physics helpers and collision checks.
+         *
+         * When `null` (default), MinimoJS uses the sprite's visual {@link Sprite.width}.
+         * When set, this value is scaled by {@link Sprite.scale} the same way as the
+         * visual sprite size.
+         */
+        this.bodyWidth = null;
+        /**
+         * Optional logical body height used by physics helpers and collision checks.
+         *
+         * When `null` (default), MinimoJS uses the sprite's visual {@link Sprite.height}.
+         * When set, this value is scaled by {@link Sprite.scale} the same way as the
+         * visual sprite size.
+         */
+        this.bodyHeight = null;
+        /**
+         * Horizontal body offset, in local sprite pixels before scale is applied.
+         *
+         * Positive values move the collision body to the right of the sprite's rendered center.
+         * Negative values move it to the left.
+         */
+        this.bodyOffsetX = 0;
+        /**
+         * Vertical body offset, in local sprite pixels before scale is applied.
+         *
+         * Positive values move the collision body downward relative to the sprite's
+         * rendered center. Negative values move it upward.
+         */
+        this.bodyOffsetY = 0;
         /**
          * CSS text color used when rendering this sprite.
          *
@@ -187,14 +175,784 @@ export class Sprite {
          * Values > 1 amplify gravity; negative values invert it.
          */
         this.gravityScale = 0;
+        /**
+         * Optional name, so code can ask an object what it is. Names may repeat,
+         * like a `name` attribute in the DOM. The engine never reads it.
+         * A sprite created from a design file takes the object's `name`.
+         *
+         * @example
+         * ```ts
+         * if (other.name === "door") openDoor();
+         * ```
+         */
+        this.name = undefined;
+        /**
+         * Tags for grouping, like CSS classes in the DOM. Empty by default. The
+         * engine never reads them. A sprite created from a design file takes the
+         * object's `tags`, which {@link Game.registerBuilderByTag} also matches.
+         *
+         * @example
+         * ```ts
+         * if (other.tags.includes("coin")) collect(other);
+         * ```
+         */
+        this.tags = [];
+        /**
+         * The game's own values for this object, such as a button's action or an
+         * enemy's speed. An empty object by default, so `sprite.data.hp = 3` needs
+         * no check. The engine never reads it. A sprite created from a design file
+         * takes a copy of the object's `data`.
+         */
+        this.data = {};
+        // `abstract` and `protected` are erased by the TypeScript compiler, and games
+        // are written in JavaScript, so nothing but this check stops old code from
+        // calling `new Sprite(glyph, x, y, size)`. Without it the glyph would be
+        // stored as this sprite's game reference, the position and size would be
+        // discarded, and the failure would surface one call later inside `Game.add`
+        // as an unrelated "attached to multiple Game instances" error.
+        if (new.target === Sprite) {
+            throw new Error("MinimoJS: Sprite is an abstract type and cannot be constructed directly. " +
+                "Use EmojiSprite for an emoji, ImageSprite for a preloaded image, " +
+                "TextSprite for text, or DrawSprite for procedural drawing.");
+        }
+        this._game = game;
+    }
+    /**
+     * Game instance associated with this sprite, if any.
+     */
+    get game() {
+        return this._game;
+    }
+    /** @internal */
+    _setGame(game) {
+        if (this._game !== null && this._game !== game) {
+            throw new Error("MinimoJS: A sprite cannot be attached to multiple Game instances.");
+        }
+        this._game = game;
+    }
+    /**
+     * Resolved center X used internally by rendering, hit testing, and collisions.
+     */
+    get renderX() {
+        return this.x + this.getAnchorOffsetX();
+    }
+    /**
+     * Resolved center Y used internally by rendering, hit testing, and collisions.
+     */
+    get renderY() {
+        return this.y + this.getAnchorOffsetY();
+    }
+    /**
+     * Effective rendered/collision width in pixels.
+     */
+    get displayWidth() {
+        const safeScale = Number.isFinite(this.scale) ? this.scale : 1;
+        return this.width * Math.max(0, safeScale);
+    }
+    /**
+     * Effective rendered/collision height in pixels.
+     */
+    get displayHeight() {
+        const safeScale = Number.isFinite(this.scale) ? this.scale : 1;
+        return this.height * Math.max(0, safeScale);
+    }
+    /**
+     * Effective collision-body width in pixels after applying {@link Sprite.scale}.
+     */
+    get bodyDisplayWidth() {
+        const safeScale = Number.isFinite(this.scale) ? this.scale : 1;
+        const baseWidth = typeof this.bodyWidth === "number" &&
+            Number.isFinite(this.bodyWidth) &&
+            this.bodyWidth > 0
+            ? this.bodyWidth
+            : this.width;
+        return baseWidth * Math.max(0, safeScale);
+    }
+    /**
+     * Effective collision-body height in pixels after applying {@link Sprite.scale}.
+     */
+    get bodyDisplayHeight() {
+        const safeScale = Number.isFinite(this.scale) ? this.scale : 1;
+        const baseHeight = typeof this.bodyHeight === "number" &&
+            Number.isFinite(this.bodyHeight) &&
+            this.bodyHeight > 0
+            ? this.bodyHeight
+            : this.height;
+        return baseHeight * Math.max(0, safeScale);
+    }
+    /**
+     * Resolved body center X used internally by physics helpers and collision checks.
+     */
+    get bodyCenterX() {
+        const safeScale = Number.isFinite(this.scale) ? this.scale : 1;
+        return this.renderX + this.bodyOffsetX * Math.max(0, safeScale);
+    }
+    /**
+     * Resolved body center Y used internally by physics helpers and collision checks.
+     */
+    get bodyCenterY() {
+        const safeScale = Number.isFinite(this.scale) ? this.scale : 1;
+        return this.renderY + this.bodyOffsetY * Math.max(0, safeScale);
+    }
+    /**
+     * The box, in world space, that a design editor selects and aligns this
+     * sprite by, when it is not the sprite's own: a module's object whose
+     * surface is larger than what the player sees, such as a flame with room
+     * for its glow, reports the visible part. `null` uses the sprite's bounds.
+     *
+     * @internal
+     */
+    _editorBox() {
+        return null;
+    }
+    getAnchorOffsetX() {
+        return 0;
+    }
+    getAnchorOffsetY() {
+        return 0;
+    }
+}
+/**
+ * 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
+ * const coin = new EmojiSprite("🪙", 300, 200, 32);
+ * game.add(coin);
+ * ```
+ */
+export class EmojiSprite extends Sprite {
+    get size() {
+        return this._size;
+    }
+    get width() {
+        return this._size;
+    }
+    get height() {
+        return this._size;
+    }
+    get displaySize() {
+        return this.displayWidth;
+    }
+    /**
+     * Creates a new EmojiSprite with the given emoji, optional position, and base size.
+     * All other properties use their defaults and can be set after construction.
+     *
+     * @param sprite - The emoji character to render. Must be a single emoji.
+     *   Use {@link ImageSprite} for preloaded bitmap textures.
+     *   @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`.
+     * @param size - Base sprite size in pixels. Default: `32`.
+     *
+     * @example
+     * ```ts
+     * const enemy = new EmojiSprite("👾", 200, 100, 40);
+     * game.add(enemy);
+     * ```
+     */
+    constructor(sprite, x = 0, y = 0, size = 32) {
+        super();
         this.sprite = sprite;
         this.x = x;
         this.y = y;
         const safeSize = Number.isFinite(size) ? size : 32;
         this._size = Math.max(1, safeSize);
     }
+    getRenderCacheKey() {
+        return `emoji:${this.sprite}|size:${this._size}|color:${this.color}`;
+    }
+}
+/**
+ * A renderable sprite backed by a preloaded image asset.
+ *
+ * Width and height are always resolved from the current texture. To resize the
+ * sprite visually, use {@link Sprite.scale}.
+ */
+export class ImageSprite extends Sprite {
+    get imageKey() {
+        return this._imageKey;
+    }
+    get width() {
+        const image = this.getResolvedImage();
+        return image instanceof HTMLImageElement
+            ? image.naturalWidth || image.width
+            : image.width;
+    }
+    get height() {
+        const image = this.getResolvedImage();
+        return image instanceof HTMLImageElement
+            ? image.naturalHeight || image.height
+            : image.height;
+    }
+    /**
+     * Creates a new image-backed sprite.
+     *
+     * @param game - Game instance used to resolve the texture key.
+     * @param imageKey - Texture key previously registered with {@link Game.loadImage} or {@link Game.createTexture}.
+     * @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`.
+     */
+    constructor(game, imageKey, x = 0, y = 0) {
+        super(game);
+        this._imageKey = imageKey;
+        this.x = x;
+        this.y = y;
+    }
+    /**
+     * Replaces the current texture with another preloaded image.
+     *
+     * @param imageKey - New texture key to render.
+     */
+    setTexture(imageKey) {
+        if (imageKey === this._imageKey)
+            return;
+        this.assertTextureAvailable(imageKey);
+        this._imageKey = imageKey;
+    }
+    getRenderCacheKey() {
+        const image = this.getResolvedImage();
+        const width = image instanceof HTMLImageElement ? image.naturalWidth || image.width : image.width;
+        const height = image instanceof HTMLImageElement ? image.naturalHeight || image.height : image.height;
+        return [
+            "image",
+            this._imageKey,
+            this.game?.getImageVersion(this._imageKey) ?? 0,
+            width,
+            height,
+        ].join("|");
+    }
+    /** @internal */
+    getResolvedImage() {
+        this.assertTextureAvailable(this._imageKey);
+        const image = this.game?.getImage(this._imageKey);
+        if (!image) {
+            throw new Error(`MinimoJS: Image '${this._imageKey}' is not loaded.`);
+        }
+        return image;
+    }
+    /** @internal */
+    assertTextureAvailable(imageKey) {
+        if (!this.game) {
+            throw new Error("MinimoJS: ImageSprite requires an associated Game instance.");
+        }
+        if (!this.game.hasImage(imageKey)) {
+            throw new Error(`MinimoJS: Image '${imageKey}' is not loaded.`);
+        }
+    }
+}
+/**
+ * A renderable sprite backed by a per-instance canvas that is repainted on demand.
+ *
+ * `DrawSprite` is useful for procedural shapes, gauges, charts, minimaps, and
+ * HUD widgets whose appearance changes often and is easier to express with
+ * Canvas 2D drawing commands than with emoji, text, or image swaps.
+ *
+ * Treat `DrawSprite` as a specialized tool, not the default sprite type.
+ * Because it may execute custom Canvas 2D drawing code repeatedly, overusing it
+ * can affect game performance much more than regular {@link EmojiSprite},
+ * {@link ImageSprite}, or {@link TextSprite} instances.
+ *
+ * Prefer the other sprite types whenever they can express the same result more
+ * simply. Reach for `DrawSprite` only when you truly need procedural drawing or
+ * custom per-sprite canvas rendering that the built-in sprite types cannot
+ * provide cleanly.
+ *
+ * MinimoJS creates and owns an internal canvas for each `DrawSprite` instance.
+ * Before every engine render that needs this sprite's surface, the engine:
+ *
+ * 1. Resolves the sprite's internal canvas size
+ * 2. Optionally clears and repaints that internal canvas
+ * 3. Draws the resulting canvas like any other sprite surface
+ *
+ * By default, `DrawSprite` is live-rendered: the engine clears the internal
+ * canvas and calls {@link DrawSprite.redraw} every frame.
+ *
+ * Set {@link DrawSprite.frozen} to `true` if you want to keep and reuse the
+ * last rendered canvas contents without repainting on each frame. This is
+ * useful for shapes or procedural art that you only want to draw once.
+ *
+ * While `frozen` is `true`, MinimoJS reuses the existing surface exactly as-is:
+ * it does not clear the canvas and does not call {@link DrawSprite.redraw}
+ * again, unless the surface does not exist yet or its size had to be rebuilt.
+ *
+ * This means freezing is a rendering optimization and content-preservation
+ * flag, not a separate caching system. You can switch `frozen` on or off at
+ * runtime whenever it makes sense for your sprite.
+ *
+ * The local drawing coordinate system uses the sprite surface itself:
+ * - `(0, 0)` is the top-left corner of the internal canvas
+ * - `width` / `height` match the sprite's logical size before `scale`
+ * - draw centered content yourself if you want the visual origin in the middle
+ *
+ * Override {@link DrawSprite.redraw} in a subclass, or assign your own method
+ * on an instance if you prefer an inline style in JavaScript.
+ */
+export class DrawSprite extends Sprite {
+    get width() {
+        return this._width;
+    }
+    get height() {
+        return this._height;
+    }
+    /**
+     * Creates a new dynamic canvas-backed sprite.
+     *
+     * @param width - Internal canvas width in pixels. Minimum `1`.
+     * @param height - Internal canvas height in pixels. Minimum `1`.
+     * @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`.
+     */
+    constructor(width, height, x = 0, y = 0) {
+        super();
+        /** @internal */
+        this._surface = null;
+        /** @internal */
+        this._surfaceCtx = null;
+        /** @internal */
+        this._lastRedrawPassId = -1;
+        /**
+         * When `false` (default), MinimoJS clears this sprite's internal canvas and
+         * calls {@link DrawSprite.redraw} on every render pass.
+         *
+         * When `true`, MinimoJS keeps and reuses the existing canvas contents without
+         * clearing or repainting them again, unless the internal surface does not yet
+         * exist or had to be resized.
+         *
+         * Use this when your procedural drawing becomes static after its first paint,
+         * or when you want explicit manual control over when the sprite is redrawn by
+         * toggling `frozen` at runtime.
+         */
+        this.frozen = false;
+        this._surfaceId = DrawSprite._nextSurfaceId++;
+        this._width = Math.max(1, Math.round(Number.isFinite(width) ? width : 1));
+        this._height = Math.max(1, Math.round(Number.isFinite(height) ? height : 1));
+        this.x = x;
+        this.y = y;
+    }
+    /**
+     * Called by the engine whenever the sprite's internal surface must be repainted.
+     *
+     * The provided context is already cleared and reset to the default 2D canvas
+     * state for the current surface size. MinimoJS repaints each `DrawSprite` at
+     * most once per render pass while it is not {@link DrawSprite.frozen}, so
+     * repeated snapshot reads during the same frame reuse the already-redrawn
+     * surface.
+     *
+     * @param ctx - The sprite's internal 2D drawing context.
+     */
+    redraw(_ctx) { }
+    getRenderCacheKey() {
+        return `draw:${this._surfaceId}`;
+    }
+}
+/** @internal */
+DrawSprite._nextSurfaceId = 1;
+/**
+ * A renderable text actor that participates in the same animation/effects
+ * pipeline as regular sprites.
+ *
+ * Use `TextSprite` when the content is primarily text, or when you need text
+ * layout features such as wrapping, fixed button sizes, background/border, or
+ * text stroke.
+ *
+ * For controls that are only a single emoji, prefer {@link EmojiSprite}. Emoji-only
+ * buttons usually behave better as sprites because they do not need text
+ * padding/layout and their bounds match the rendered emoji more directly.
+ */
+export class TextSprite extends Sprite {
+    get width() {
+        this.ensureMeasured();
+        return this._measuredWidth;
+    }
+    get height() {
+        this.ensureMeasured();
+        return this._measuredHeight;
+    }
+    constructor(text, x = 0, y = 0, fontSizeOrConfig = 16, config = {}) {
+        super();
+        this.anchorX = "center";
+        this.anchorY = "middle";
+        /**
+         * CSS font family. Default: `monospace`, which needs no download. Name a web
+         * font here, and register it with {@link Game.requireFont}, to use one.
+         */
+        this.fontFamily = "monospace";
+        this.fontWeight = "400";
+        this.lineHeight = 1.2;
+        this.maxWidth = 0;
+        this.fixedWidth = 0;
+        this.fixedHeight = 0;
+        this.paddingX = 2;
+        this.paddingY = 2;
+        this.backgroundColor = null;
+        this.borderColor = null;
+        this.borderWidth = 0;
+        this.cornerRadius = 0;
+        this.strokeColor = null;
+        this.strokeWidth = 0;
+        this.textAlign = "center";
+        /** @internal */
+        this._measuredWidth = 1;
+        /** @internal */
+        this._measuredHeight = 1;
+        /** @internal */
+        this._measurementCacheKey = "";
+        this.text = text;
+        this.x = x;
+        this.y = y;
+        this.fontSize =
+            typeof fontSizeOrConfig === "number" ? fontSizeOrConfig : 16;
+        this.color = "#ffffff";
+        if (typeof fontSizeOrConfig === "number") {
+            this.applyConfig(config);
+        }
+        else {
+            this.applyConfig(fontSizeOrConfig);
+        }
+    }
+    getRenderCacheKey() {
+        return [
+            "text",
+            this.text,
+            this.anchorX,
+            this.anchorY,
+            this.fontFamily,
+            this.fontSize,
+            this.fontWeight,
+            this.lineHeight,
+            this.maxWidth,
+            this.fixedWidth,
+            this.fixedHeight,
+            this.color,
+            this.textAlign,
+            this.paddingX,
+            this.paddingY,
+            this.backgroundColor ?? "",
+            this.borderColor ?? "",
+            this.borderWidth,
+            this.cornerRadius,
+            this.strokeColor ?? "",
+            this.strokeWidth,
+        ].join("|");
+    }
+    get align() {
+        return this.textAlign;
+    }
+    set align(value) {
+        this.textAlign = value;
+    }
+    getAnchorOffsetX() {
+        if (this.anchorX === "left") {
+            return this.displayWidth / 2;
+        }
+        if (this.anchorX === "right") {
+            return -this.displayWidth / 2;
+        }
+        return 0;
+    }
+    getAnchorOffsetY() {
+        if (this.anchorY === "top") {
+            return this.displayHeight / 2;
+        }
+        if (this.anchorY === "bottom") {
+            return -this.displayHeight / 2;
+        }
+        return 0;
+    }
+    /** @internal */
+    applyConfig(config) {
+        if (config.anchorX !== undefined)
+            this.anchorX = config.anchorX;
+        if (config.anchorY !== undefined)
+            this.anchorY = config.anchorY;
+        if (config.fontFamily !== undefined)
+            this.fontFamily = config.fontFamily;
+        if (config.fontSize !== undefined)
+            this.fontSize = config.fontSize;
+        if (config.fontWeight !== undefined)
+            this.fontWeight = config.fontWeight;
+        if (config.lineHeight !== undefined)
+            this.lineHeight = config.lineHeight;
+        if (config.maxWidth !== undefined)
+            this.maxWidth = config.maxWidth;
+        if (config.fixedWidth !== undefined)
+            this.fixedWidth = config.fixedWidth;
+        if (config.fixedHeight !== undefined)
+            this.fixedHeight = config.fixedHeight;
+        if (config.paddingX !== undefined)
+            this.paddingX = config.paddingX;
+        if (config.paddingY !== undefined)
+            this.paddingY = config.paddingY;
+        if (config.backgroundColor !== undefined)
+            this.backgroundColor = config.backgroundColor;
+        if (config.borderColor !== undefined)
+            this.borderColor = config.borderColor;
+        if (config.borderWidth !== undefined)
+            this.borderWidth = config.borderWidth;
+        if (config.cornerRadius !== undefined)
+            this.cornerRadius = config.cornerRadius;
+        if (config.strokeColor !== undefined)
+            this.strokeColor = config.strokeColor;
+        if (config.strokeWidth !== undefined)
+            this.strokeWidth = config.strokeWidth;
+        if (config.textAlign !== undefined)
+            this.textAlign = config.textAlign;
+        if (config.align !== undefined)
+            this.textAlign = config.align;
+    }
+    /** @internal */
+    ensureMeasured() {
+        const nextKey = [
+            this.text,
+            this.fontFamily,
+            this.fontSize,
+            this.fontWeight,
+            this.lineHeight,
+            this.maxWidth,
+            this.fixedWidth,
+            this.fixedHeight,
+            this.paddingX,
+            this.paddingY,
+            this.borderWidth,
+            this.strokeWidth,
+        ].join("|");
+        if (this._measurementCacheKey === nextKey) {
+            return;
+        }
+        if (typeof document === "undefined") {
+            this._measuredWidth = 1;
+            this._measuredHeight = 1;
+            this._measurementCacheKey = nextKey;
+            return;
+        }
+        if (TextSprite._measurementCanvas === null) {
+            TextSprite._measurementCanvas = document.createElement("canvas");
+            TextSprite._measurementContext =
+                TextSprite._measurementCanvas.getContext("2d");
+        }
+        const ctx = TextSprite._measurementContext;
+        if (!ctx) {
+            this._measuredWidth = 1;
+            this._measuredHeight = 1;
+            this._measurementCacheKey = nextKey;
+            return;
+        }
+        ctx.font = `${this.fontWeight} ${this.fontSize}px ${this.fontFamily}`;
+        const lines = this.layoutMeasuredLines(ctx);
+        const measuredWidth = Math.max(1, Math.ceil(lines.reduce((maxWidth, line) => Math.max(maxWidth, ctx.measureText(line).width), 0)));
+        const lineHeightPx = Math.max(1, Math.ceil(this.fontSize * this.lineHeight));
+        const contentHeight = Math.max(1, lineHeightPx * Math.max(lines.length, 1));
+        const borderPad = Math.max(0, this.borderWidth) * 2;
+        const strokePad = Math.max(0, this.strokeWidth) * 2;
+        this._measuredWidth = Math.max(1, Math.ceil(this.fixedWidth > 0
+            ? this.fixedWidth
+            : measuredWidth + this.paddingX * 2 + borderPad + strokePad));
+        this._measuredHeight = Math.max(1, Math.ceil(this.fixedHeight > 0
+            ? this.fixedHeight
+            : contentHeight + this.paddingY * 2 + borderPad + strokePad));
+        this._measurementCacheKey = nextKey;
+    }
+    /** @internal */
+    layoutMeasuredLines(ctx) {
+        const rawLines = this.text.split("\n");
+        const availableTextWidth = this.getAvailableTextWidth();
+        if (availableTextWidth <= 0) {
+            return rawLines.length > 0 ? rawLines : [""];
+        }
+        const wrappedLines = [];
+        for (const rawLine of rawLines) {
+            const words = rawLine.split(/\s+/).filter((word) => word.length > 0);
+            if (words.length === 0) {
+                wrappedLines.push("");
+                continue;
+            }
+            let currentLine = words[0];
+            for (let i = 1; i < words.length; i++) {
+                const candidate = `${currentLine} ${words[i]}`;
+                if (ctx.measureText(candidate).width <= availableTextWidth) {
+                    currentLine = candidate;
+                }
+                else {
+                    wrappedLines.push(currentLine);
+                    currentLine = words[i];
+                }
+            }
+            wrappedLines.push(currentLine);
+        }
+        return wrappedLines.length > 0 ? wrappedLines : [""];
+    }
+    /** @internal */
+    getAvailableTextWidth() {
+        const borderPad = Math.max(0, this.borderWidth) * 2;
+        const strokePad = Math.max(0, this.strokeWidth) * 2;
+        const limits = [];
+        if (this.maxWidth > 0) {
+            limits.push(this.maxWidth - this.paddingX * 2 - borderPad - strokePad);
+        }
+        if (this.fixedWidth > 0) {
+            limits.push(this.fixedWidth - this.paddingX * 2 - borderPad - strokePad);
+        }
+        if (limits.length === 0) {
+            return 0;
+        }
+        return Math.max(1, Math.floor(Math.min(...limits)));
+    }
+}
+/** @internal */
+TextSprite._measurementCanvas = null;
+/** @internal */
+TextSprite._measurementContext = null;
+/**
+ * A static image-based background layer rendered behind all sprites.
+ *
+ * Background layers are visual-only: they do not participate in physics,
+ * collisions, input hit-testing, or sprite queries.
+ *
+ * `x` / `y` use **top-left screen-space coordinates**, unlike {@link Sprite},
+ * which uses center-based world space.
+ *
+ * The texture referenced by {@link BackgroundLayer.imageKey} must be registered
+ * with {@link Game.loadImage} during {@link Game.onPreload}, or created
+ * dynamically with {@link Game.createTexture}.
+ *
+ * @example
+ * ```ts
+ * game.onPreload = () => {
+ *   game.loadImage("sky", "assets/sky.png");
+ * };
+ *
+ * game.onCreate = () => {
+ *   const bg = game.addBackground(new BackgroundLayer("sky"));
+ *   bg.fit = "cover";
+ * };
+ * ```
+ */
+export class BackgroundLayer {
+    /**
+     * Creates a new background layer.
+     *
+     * @param imageKey - Preloaded image key previously registered with {@link Game.loadImage}.
+     * @param x - Destination rectangle left edge in screen space. Default: `0`.
+     * @param y - Destination rectangle top edge in screen space. Default: `0`.
+     * @param width - Destination rectangle width. `0` means canvas width. Default: `0`.
+     * @param height - Destination rectangle height. `0` means canvas height. Default: `0`.
+     */
+    constructor(imageKey, x = 0, y = 0, width = 0, height = 0) {
+        /**
+         * Opacity of the layer in range `[0, 1]`.
+         */
+        this.alpha = 1;
+        /**
+         * Controls whether the layer is drawn.
+         */
+        this.visible = true;
+        /**
+         * Orders background layers relative to each other.
+         * Higher values render on top of lower background layers, but still behind sprites.
+         */
+        this.layer = 0;
+        /**
+         * How the image is fit inside the destination rectangle.
+         * Default: `"cover"`.
+         */
+        this.fit = "cover";
+        /**
+         * Optional name, so code can ask a layer what it is. Names may repeat. The
+         * engine never reads it. See {@link Sprite.name}.
+         */
+        this.name = undefined;
+        /**
+         * Tags for grouping. Empty by default. The engine never reads them. See
+         * {@link Sprite.tags}.
+         */
+        this.tags = [];
+        /**
+         * The game's own values for this layer. An empty object by default. The
+         * engine never reads it. See {@link Sprite.data}.
+         */
+        this.data = {};
+        this.imageKey = imageKey;
+        this.x = x;
+        this.y = y;
+        this.width = width;
+        this.height = height;
+    }
+}
+/**
+ * The objects {@link Game.createObjectList} created, in the order of their
+ * data, and searches on them.
+ *
+ * An `ObjectList` only holds and finds its objects; it never changes them.
+ * Remove them through the game, as any other object:
+ *
+ * ```ts
+ * for (const obj of ui.objects) {
+ *   if (obj instanceof BackgroundLayer) game.destroyBackgroundLayer(obj);
+ *   else game.destroySprite(obj);
+ * }
+ * ```
+ *
+ * Searches read each object's current {@link Sprite.name} and
+ * {@link Sprite.tags}. In TypeScript, name the type you expect:
+ * `ui.findByName<ImageSprite>("play")`.
+ */
+export class ObjectList {
+    /** @internal */
+    constructor(objects) {
+        this.objects = Object.freeze([...objects]);
+    }
+    /**
+     * Returns the first object whose `name` is `name`, in order.
+     * Throws an error naming `name` when there is none.
+     *
+     * @example
+     * ```ts
+     * const play = ui.findByName("play");
+     * ```
+     */
+    findByName(name) {
+        return findFirst(this.objects, (obj) => obj.name === name, `named "${name}"`, "the object list");
+    }
+    /** Returns every object whose `name` is `name`, in order; an empty list when there is none. */
+    findAllByName(name) {
+        return this.objects.filter((obj) => obj.name === name);
+    }
+    /**
+     * Returns the first object whose `tags` include `tag`, in order.
+     * Throws an error naming `tag` when there is none.
+     */
+    findByTag(tag) {
+        return findFirst(this.objects, (obj) => obj.tags.includes(tag), `tagged "${tag}"`, "the object list");
+    }
+    /** Returns every object whose `tags` include `tag`, in order; an empty list when there is none. */
+    findAllByTag(tag) {
+        return this.objects.filter((obj) => obj.tags.includes(tag));
+    }
+}
+/** The runtime class of each type of design object. */
+const DESIGN_OBJECT_CLASSES = {
+    image: ImageSprite,
+    emoji: EmojiSprite,
+    text: TextSprite,
+    background: BackgroundLayer,
+};
+function describeDesignObject(obj) {
+    return obj.name === undefined ? `the object ${obj.id}` : `the object "${obj.name}" (${obj.id})`;
 }
 // ---------------------------------------------------------------------------
+// Internal types (not part of the public API declarations)
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
 // Game
 // ---------------------------------------------------------------------------
 /**
@@ -212,21 +970,21 @@ export class Sprite {
  * You must import it with standard ESM syntax such as:
  *
  * ```ts
- * import { Game, Sprite } from "minimojs";
+ * import { Game, EmojiSprite } from "minimojs";
  * ```
  *
  * In the browser, use it from a module script:
  *
  * ```html
  * <script type="module">
- *   import { Game, Sprite } from "./dist/minimo.js";
+ *   import { Game, EmojiSprite } from "./dist/minimo.js";
  * </script>
  * ```
  *
  * Or from a CDN:
  *
  * ```ts
- * import { Game, Sprite } from "https://cdn.jsdelivr.net/npm/minimojs@<version>/dist/minimo.js";
+ * import { Game, EmojiSprite } from "https://cdn.jsdelivr.net/npm/minimojs@<version>/dist/minimo.js";
  * ```
  *
  * Do NOT use a classic `<script>` tag without `type="module"`.
@@ -235,12 +993,21 @@ export class Sprite {
  *
  * ---
  *
- * ## Required Font Setup
+ * ## Font Setup
  *
- * `drawText()` renders with `"Press Start 2P", monospace`.
- * You MUST load `Press Start 2P` yourself in your `index.html` before starting
- * the game. MinimoJS does NOT download, inject, or manage web fonts for you.
- * If the font is missing, the browser falls back to `monospace`.
+ * `drawText()` and `TextSprite` default to `monospace`, which every device
+ * has, so a game that names no font downloads none and waits for none. To use
+ * a web font, declare it in your page, register it with {@link Game.requireFont}
+ * before calling {@link Game.start}, and name it in {@link TextSprite.fontFamily}.
+ *
+ * Prefer {@link TextSprite} for persistent UI text, interactive labels,
+ * buttons, fixed-size text boxes, and styled text elements. Keep
+ * `drawText()` for simple screen-space overlays such as HUD counters, debug
+ * text, or other text that is redrawn every frame.
+ *
+ * You MUST still declare the fonts yourself in your `index.html`. MinimoJS
+ * does NOT download, inject, or manage web fonts for you. If a font is missing,
+ * the browser falls back to `monospace`.
  *
  * Example `index.html` `<head>` setup:
  *
@@ -253,17 +1020,32 @@ export class Sprite {
  * />
  * ```
  *
+ * Example custom font registration:
+ *
+ * ```ts
+ * const game = new Game(720, 1280);
+ * game.requireFont('"Bangers"', { weight: "400" });
+ * game.start();
+ * ```
+ *
  * ---
  *
  * ## Quick Start
  *
  * ```ts
- * import { Game, Sprite } from "https://cdn.jsdelivr.net/npm/minimojs@<version>/dist/minimo.js";
+ * import { Game, ImageSprite } from "https://cdn.jsdelivr.net/npm/minimojs@<version>/dist/minimo.js";
+ *
+ * const game = new Game(720, 1280);
  *
- * const game = new Game(800, 600);
+ * game.onPreload = () => {
+ *   game.loadImage("player", "assets/player.png");
+ * };
+ *
+ * let player: ImageSprite;
  *
- * const player = new Sprite("🐢", 400, 500, 48);
- * game.add(player);
+ * game.onCreate = () => {
+ *   player = game.add(new ImageSprite(game, "player", 400, 500));
+ * };
  *
  * game.onUpdate = (dt) => {
  *   if (game.isKeyDown("ArrowLeft"))  player.vx = -200;
@@ -276,6 +1058,13 @@ export class Sprite {
  * game.start();
  * ```
  *
+ * Prototyping, and have no art yet? Swap the texture for an emoji and drop the
+ * preload entirely — everything else stays the same:
+ *
+ * ```ts
+ * const player = game.add(new EmojiSprite("🐢", 400, 500, 48));
+ * ```
+ *
  * ---
  *
  * ## Engine Philosophy
@@ -301,13 +1090,28 @@ export class Sprite {
  *
  * ---
  *
- * ## 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.
+ * ## Choosing a Visual Source
+ *
+ * A sprite's look comes from one of four concrete types, all of which extend the
+ * shared abstract {@link Sprite} type. Use `Sprite` as the type in your own
+ * signatures; never construct it directly.
+ *
+ * 1. {@link ImageSprite} — the game's own images, and the first option to reach
+ *    for. Register a texture with {@link Game.loadImage} inside
+ *    {@link Game.onPreload}, or build one at runtime with
+ *    {@link Game.createTexture}, then render it with
+ *    `new ImageSprite(game, key, x, y)`. An image looks identical on every
+ *    device and belongs to the game.
+ * 2. {@link EmojiSprite} — a single Unicode emoji, and the shortest path to a
+ *    first prototype: `new EmojiSprite("🐢", x, y, size)`. Note that an
+ *    emoji is drawn with the player's own system emoji font, so the same game
+ *    looks different across iOS, Android, and Windows, and a glyph the platform
+ *    lacks renders as an empty box. Prefer an image whenever the look matters.
+ * 3. {@link TextSprite} — text, labels, and buttons.
+ * 4. {@link DrawSprite} — procedural Canvas 2D drawing, for shapes and gauges
+ *    the other three cannot express cleanly.
+ *
+ * Emoji and images mix freely in one game.
  *
  * ---
  *
@@ -323,7 +1127,7 @@ export class Sprite {
  *
  * 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}.
+ * {@link Game.animateRotation}, {@link Game.animateDeform}, 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`).
@@ -375,10 +1179,10 @@ export class Sprite {
  *
  * ---
  *
- * ## Scene Initialization with `onCreate`
+ * ## Scene Initialization with `IScene`
  *
- * MinimoJS has NO scene system. Use {@link Game.onCreate} to build a scene.
- * The engine calls `onCreate`:
+ * MinimoJS supports simple scene objects via {@link IScene}. The engine calls
+ * a scene's `onCreate()`:
  * - Once before the first frame (when {@link Game.start} is called).
  * - Again after each {@link Game.reset}.
  *
@@ -390,28 +1194,42 @@ export class Sprite {
  * - 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.
+ * After clearing, `reset()` calls the active scene's `onCreate()` so it can
+ * rebuild immediately. Simply re-add sprites and re-register timers.
  *
  * ```ts
- * game.onCreate = () => {
- *   // scene init: add sprites, setup timers
- *   const skull = new Sprite("💀", 400, 300, 96);
- *   game.add(skull);
- * };
+ * class SkullScene implements IScene {
+ *   onCreate() {
+ *     const skull = new EmojiSprite("💀", 400, 300, 96);
+ *     game.add(skull);
+ *   }
  *
- * game.onUpdate = (dt) => {
- *   // normal per-frame update
- * };
+ *   onUpdate(dt: number) {
+ *     // normal per-frame update
+ *   }
+ * }
  *
- * game.start(); // calls onCreate() once before first frame
+ * const scene = new SkullScene();
+ * game.start(scene); // calls onCreate() once before first frame
  * // later:
  * game.reset(); // clears + calls onCreate() again
  * ```
  *
+ * Legacy `game.onCreate` / `game.onUpdate` callbacks still work when no active
+ * {@link IScene} is set.
+ *
+ * ### Loading a Scene's Own Images
+ *
+ * Load images in {@link Game.onPreload}: once, at boot. Only a game with many
+ * scenes that each carry many assets of their own — typically a game with many
+ * levels, whose player does not reach every level in a session — should give
+ * scenes an {@link IScene.onPreload}. Entering such a scene loads its images
+ * first, with the scene being left frozen and dimmed under a progress ring, so `reset()`
+ * and `transitionTo()` may return before the new scene's `onCreate()` runs.
+ *
  * ---
  *
- * ## Sprite Lifecycle Ownership
+ * ## EmojiSprite Lifecycle Ownership
  *
  * The `Game` instance owns all sprites.
  * - Create sprites with {@link Game.add}.
@@ -425,7 +1243,7 @@ export class Sprite {
  * ## Forbidden Features
  *
  * The following do NOT exist in MinimoJS v1. Do NOT attempt to use them:
- * - Scene system or scene manager
+ * - Full scene manager architecture (scene stacks, transitions, loaders, etc.)
  * - Entity Component System (ECS)
  * - Physics engine (no Box2D, Matter.js, etc.)
  * - Camera zoom or scale
@@ -434,10 +1252,109 @@ export class Sprite {
  * - Parallax layers
  * - Multiple cameras
  * - Full physics engine (only basic explicit AABB collision helpers are provided)
- * - Image sprites (PNG, SVG, canvas, etc.)
  * - `setTimeout` or `setInterval`
  */
 export class Game {
+    // -------------------------------------------------------------------------
+    // 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
+     * ```
+     */
+    get gravityX() {
+        return this._physicsSystem.gravityX;
+    }
+    set gravityX(value) {
+        this._physicsSystem.gravityX = value;
+    }
+    /**
+     * 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
+     * ```
+     */
+    get gravityY() {
+        return this._physicsSystem.gravityY;
+    }
+    set gravityY(value) {
+        this._physicsSystem.gravityY = value;
+    }
+    /**
+     * Enables the basic collision-resolution helpers (`collide` / `collideAny`).
+     *
+     * When `false` (default), overlap detection still works, but collision
+     * resolution helpers are unavailable.
+     *
+     * Set this to `true` for simple platformer-style collision handling.
+     *
+     * @example
+     * ```ts
+     * game.physics = true;
+     * ```
+     */
+    get physics() {
+        return this._physicsSystem.enabled;
+    }
+    set physics(value) {
+        this._physicsSystem.enabled = value;
+    }
+    /**
+     * Legacy scene creation callback.
+     *
+     * Called once before the first frame on {@link Game.start}, and again after
+     * each {@link Game.reset} when no active {@link IScene} is set.
+     *
+     * @example
+     * ```ts
+     * game.onCreate = () => {
+     *   const player = new EmojiSprite("🐢");
+     *   player.x = 200;
+     *   player.y = 300;
+     *   game.add(player);
+     * };
+     * ```
+     */
+    get onCreate() {
+        return this._onCreate;
+    }
+    set onCreate(callback) {
+        this._onCreate = callback;
+    }
+    /**
+     * Currently active scene object, if any.
+     */
+    get currentScene() {
+        return this._currentScene;
+    }
+    /**
+     * Returns `true` while a full-screen scene transition is playing.
+     */
+    get isTransitioning() {
+        return this._transitionSystem.isActive;
+    }
+    /**
+     * Returns `true` while images are loading: at boot, or while a scene with
+     * pending images in its {@link IScene.onPreload} is being entered. While a
+     * scene loads, the scene being left is frozen and `reset()` and
+     * `transitionTo()` are ignored.
+     */
+    get isLoading() {
+        return this._preloadPromise !== null || this._sceneLoad !== null;
+    }
     // -------------------------------------------------------------------------
     // Constructor
     // -------------------------------------------------------------------------
@@ -447,86 +1364,30 @@ export class Game {
      * 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.
+     * For new mobile-first Minimo Games, prefer a portrait canvas such as `720x1280`.
      *
-     * @param width - Canvas width in pixels. Default: `800`.
-     * @param height - Canvas height in pixels. Default: `600`.
+     * @param width - Canvas width in pixels. Default: `720`.
+     * @param height - Canvas height in pixels. Default: `1280`.
      *
      * @throws Error if a 2D context cannot be obtained.
      *
      * @example
      * ```ts
-     * const game = new Game(800, 600);
+     * const game = new Game(720, 1280);
      * game.physics = true;
      * ```
      */
-    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._mouseDown = false;
-        /** @internal */ this._mousePressed = false;
-        /** @internal */ this._mouseX = 0;
-        /** @internal */ this._mouseY = 0;
-        /** @internal */ this._touchPointers = new Map();
-        /** @internal */ this._primaryTouchId = null;
-        /** @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._spriteGlyphCache = new Map();
-        /** @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;
-        /**
-         * Enables the basic collision-resolution helpers (`collide` / `collideAny`).
-         *
-         * When `false` (default), overlap detection still works, but collision
-         * resolution helpers are unavailable.
-         *
-         * Set this to `true` for simple platformer-style collision handling.
-         *
-         * @example
-         * ```ts
-         * game.physics = true;
-         * ```
-         */
-        this.physics = false;
+    constructor(width = 720, height = 1280) {
+        /** @internal */ this._requiredFonts = new Map();
+        /** @internal */ this._hasAppliedGlobalFontRequirements = false;
+        /** @internal */ this._isRegisteringPreloadAssets = false;
+        /** @internal */ this._hasCompletedPreload = false;
+        /** @internal */ this._preloadPromise = null;
+        /** @internal */ this._sceneLoad = null;
+        /** @internal */ this._onCreate = null;
+        /** @internal */ this._currentScene = null;
+        /** @internal */ this._buildersByTag = new Map();
+        /** @internal */ this._moduleBuilders = new Map();
         /**
          * Horizontal scroll offset of the world camera, in pixels.
          * The canvas viewport is shifted left by `scrollX` — sprites with higher `x`
@@ -571,6 +1432,20 @@ export class Game {
          * ```
          */
         this.backgroundGradient = null;
+        /**
+         * When `true`, MinimoJS draws every sprite's collision body as an overlay.
+         *
+         * This is a runtime debugging aid only. It does not change collisions,
+         * input, rendering order, or physics behavior.
+         */
+        this.debugBodies = false;
+        /**
+         * When `true`, MinimoJS draws every sprite's input area as an overlay.
+         *
+         * This is a runtime debugging aid only. It does not change input behavior,
+         * physics, or rendering.
+         */
+        this.debugInputAreas = false;
         /**
          * Background color for the full web page (`document.body`).
          * Set to any valid CSS color string. Default: `null` (engine leaves page background unchanged).
@@ -584,24 +1459,31 @@ export class Game {
          */
         this.pageBackground = null;
         /**
-         * Scene creation callback.
+         * Asset registration callback invoked once before the first scene is created.
          *
-         * 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.
+         * This is the normal place to load a game's images and sounds. Use it to register them
+         * with {@link Game.loadAssets}, {@link Game.loadImage}, or {@link Game.loadSound}. The callback is synchronous: it should only
+         * queue assets, not await network work.
+         *
+         * After `onPreload` returns, MinimoJS loads the queued images and sounds, together with
+         * those of the first scene's {@link IScene.onPreload} if it has one, and
+         * shows a loading line until they are ready. If any file fails, it asks the
+         * player with `window.confirm` whether to retry them; declining leaves the
+         * game on the loading screen and reports the failed files on the console.
          *
          * @example
          * ```ts
-         * game.onCreate = () => {
-         *   const player = new Sprite("🐢");
-         *   player.x = 200;
-         *   player.y = 300;
-         *   game.add(player);
+         * game.onPreload = () => {
+         *   game.loadImage("sky", "assets/sky.png");
+         *   game.loadImage("land", "assets/land.png");
          * };
          * ```
          */
-        this.onCreate = null;
+        this.onPreload = null;
         /**
-         * Callback invoked once per frame after physics and timer updates.
+         * Legacy per-frame callback invoked after physics and timer updates.
+         *
+         * This is used only when no active {@link IScene} is set.
          *
          * @param dt - Delta time in **seconds** since the last frame.
          *   Use this for velocity-based movement: `sprite.x += speed * dt`.
@@ -623,25 +1505,30 @@ export class Game {
         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);
+        this._canvasSystem = new CanvasSystem(this._canvas);
+        this._canvasSystem.initialize();
         const ctx = this._canvas.getContext("2d");
         if (!ctx) {
             throw new Error("MinimoJS: Could not acquire a 2D rendering context.");
         }
         this._ctx = ctx;
-        this._bindInputEvents();
+        this._timerSystem = new TimerSystem();
+        this._animationSystem = new AnimationSystem();
+        this._physicsSystem = new PhysicsSystem();
+        this._spriteSystem = new SpriteSystem(this._animationSystem, this);
+        this._backgroundSystem = new BackgroundSystem();
+        this._soundSystem = new SoundSystem();
+        this._assetSystem = new AssetSystem((src) => this._soundSystem.decode(src));
+        this._inputSystem = new InputSystem(this, this._canvas);
+        this._textSystem = new TextSystem();
+        this._renderSystem = new RenderSystem();
+        this._explosionSystem = new ExplosionSystem();
+        this._trailSystem = new TrailSystem();
+        this._transitionSystem = new TransitionSystem();
+        this._loopSystem = new LoopSystem(this._onLoopFrameCallback.bind(this));
+        this._loopSystem.onCreate = this._invokeCreate.bind(this);
+        this._inputSystem.bindInputEvents();
+        this.applyGlobalFontRequirements();
     }
     // -------------------------------------------------------------------------
     // Canvas dimensions (read-only)
@@ -663,9 +1550,14 @@ export class Game {
      * 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`.
+     *
+     * On a touch screen the pointer is one finger: the first to touch while no
+     * finger is followed. Other fingers never move it, and when the followed
+     * finger lifts, the pointer stays where it left the screen even if others
+     * are still down. Use {@link Game.getPointers} to follow several fingers.
      */
     get pointerX() {
-        return this._pointerX;
+        return this._inputSystem.pointerX;
     }
     /**
      * Current pointer (mouse or touch) Y position in **canvas/screen space**,
@@ -674,13 +1566,14 @@ export class Game {
      * To convert to world space: `worldY = game.pointerY + game.scrollY`.
      */
     get pointerY() {
-        return this._pointerY;
+        return this._inputSystem.pointerY;
     }
     // -------------------------------------------------------------------------
-    // Sprite management
+    // EmojiSprite management
     // -------------------------------------------------------------------------
     /**
      * Registers a {@link Sprite} (or subclass instance) with the engine.
+     *
      * After calling `add`, the sprite is rendered and, if dynamic
      * (`isStatic = false`), receives built-in velocity/gravity integration every
      * frame until {@link Game.destroySprite} or {@link Game.reset} is called.
@@ -689,7 +1582,7 @@ export class Game {
      * 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
+     * The engine stores and processes it as a live sprite; your custom properties
      * are preserved on the instance.
      *
      * @param sprite - A {@link Sprite} instance (or subclass) to add.
@@ -698,22 +1591,39 @@ export class Game {
      * @example
      * ```ts
      * // Plain sprite
-     * const coin = new Sprite("🪙", 300, 200, 32);
+     * const coin = new EmojiSprite("🪙", 300, 200, 32);
      * game.add(coin);
      *
      * // Custom subclass
-     * class Enemy extends Sprite {
+     * class Enemy extends EmojiSprite {
      *   speed = 150;
      *   constructor(x: number, y: number) {
      *     super("👾", x, y, 40);
      *   }
-     * }
+     *   }
      * const enemy = game.add(new Enemy(600, 100));
      * ```
      */
     add(sprite) {
-        this._sprites.push(sprite);
-        return sprite;
+        return this._spriteSystem.add(sprite);
+    }
+    /**
+     * Registers a {@link BackgroundLayer} with the engine.
+     *
+     * Background layers are rendered behind all sprites and are not affected by
+     * physics, collisions, or sprite queries.
+     *
+     * @param layer - The background layer to add.
+     * @returns The same background layer instance.
+     *
+     * @example
+     * ```ts
+     * const sky = game.addBackground(new BackgroundLayer("sky"));
+     * sky.fit = "cover";
+     * ```
+     */
+    addBackground(layer) {
+        return this._backgroundSystem.add(layer);
     }
     /**
      * Removes a sprite from the engine, stopping its rendering and physics updates.
@@ -733,10 +1643,18 @@ export class 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);
+        this._trailSystem.clearSpriteTrails(sprite);
+        this._spriteSystem.destroySprite(sprite);
+    }
+    /**
+     * Removes a background layer from the engine.
+     *
+     * If the layer is not currently registered, this is a safe no-op.
+     *
+     * @param layer - The background layer to remove.
+     */
+    destroyBackgroundLayer(layer) {
+        this._backgroundSystem.destroyLayer(layer);
     }
     /**
      * Returns a **read-only snapshot** of all currently active sprites.
@@ -754,7 +1672,409 @@ export class Game {
      * ```
      */
     getSprites() {
-        return [...this._sprites];
+        return this._spriteSystem.getSprites();
+    }
+    /**
+     * Returns a read-only snapshot of all active background layers.
+     *
+     * Background layers are returned in creation order within each layer value.
+     */
+    getBackgroundLayers() {
+        return this._backgroundSystem.getLayers();
+    }
+    // -------------------------------------------------------------------------
+    // Assets
+    // -------------------------------------------------------------------------
+    /**
+     * Queues an image to be loaded during {@link Game.onPreload}.
+     *
+     * This method registers the asset only. The actual network/image fetch begins
+     * after `onPreload` returns and is managed automatically by the engine.
+     *
+     * `loadImage` may only be called from within {@link Game.onPreload} or a
+     * scene's {@link IScene.onPreload}.
+     *
+     * Images are requested with CORS, as sounds are, so the canvas stays
+     * readable and exportable. An image on another origin loads only when its
+     * host answers with CORS headers.
+     *
+     * @param key - Stable key used later by {@link BackgroundLayer.imageKey} or {@link Game.getImage}.
+     * @param src - Image URL or relative path.
+     *
+     * @example
+     * ```ts
+     * game.onPreload = () => {
+     *   game.loadImage("sky", "assets/sky.png");
+     * };
+     * ```
+     */
+    loadImage(key, src) {
+        if (!this._isRegisteringPreloadAssets) {
+            throw new Error("MinimoJS: loadImage() may only be called inside game.onPreload or a scene's onPreload().");
+        }
+        this._assetSystem.queueImage(key, src);
+    }
+    /**
+     * Queues an audio file to be loaded during {@link Game.onPreload}, to play
+     * later with {@link Game.playSound}.
+     *
+     * Like {@link Game.loadImage}, it only registers the sound, and may only be
+     * called from within {@link Game.onPreload} or a scene's
+     * {@link IScene.onPreload}. The file loads and decodes with the images,
+     * under the same loading line, and a file that fails is retried with them.
+     * Keys are unique in the whole game: a sound cannot share its key with an
+     * image. Prefer declaring sounds in an asset file, as `sound` entries
+     * loaded with {@link Game.loadAssets}.
+     *
+     * MP3 plays in every browser; WAV does too, but its files are large. OGG
+     * does not play in every Safari.
+     *
+     * @param key - Stable key used later by {@link Game.playSound}.
+     * @param src - Audio file URL or relative path.
+     *
+     * @example
+     * ```ts
+     * game.onPreload = () => {
+     *   game.loadSound("jump", "assets/jump.mp3");
+     *   game.loadSound("theme", "assets/theme.mp3");
+     * };
+     * ```
+     */
+    loadSound(key, src) {
+        if (!this._isRegisteringPreloadAssets) {
+            throw new Error("MinimoJS: loadSound() may only be called inside game.onPreload or a scene's onPreload().");
+        }
+        this._assetSystem.queueSound(key, src);
+    }
+    /**
+     * Queues every asset an asset file declares, as one {@link Game.loadImage}
+     * call per `image` entry and one {@link Game.loadSound} call per `sound`
+     * entry would.
+     *
+     * Pass the content of a `*.assets.json` file, obtained by JSON import. The
+     * file is checked with {@link parseAssetFile}, and an invalid one throws an
+     * error naming what is wrong. Like `loadImage`, `loadAssets` may only be
+     * called from within {@link Game.onPreload} or a scene's
+     * {@link IScene.onPreload}.
+     *
+     * - Keys are unique in the whole game. A key that another asset file
+     *   declares, or that {@link Game.loadImage}, {@link Game.loadSound}, or
+     *   {@link Game.createTexture} registered, throws an error naming it, and so does a later
+     *   `loadImage` or `createTexture` of a key an asset file declares.
+     * - Loading the same file again, as a scene's `onPreload()` does each time
+     *   the scene is entered, queues only its files that are not loaded.
+     * - An entry of a type this engine does not support is skipped, with a
+     *   console warning naming it, so the game still loads every asset it can.
+     *
+     * @param assets - The content of a `*.assets.json` file. See {@link AssetFile}.
+     *
+     * @example
+     * ```ts
+     * import common from "./common.assets.json" with { type: "json" };
+     *
+     * game.onPreload = () => game.loadAssets(common);
+     * ```
+     */
+    loadAssets(assets) {
+        if (!this._isRegisteringPreloadAssets) {
+            throw new Error("MinimoJS: loadAssets() may only be called inside game.onPreload or a scene's onPreload().");
+        }
+        const file = parseAssetFile(assets);
+        const isFirstLoad = this._assetSystem.registerAssetFile(file, assets);
+        if (!isFirstLoad)
+            return;
+        for (const entry of file.assets) {
+            if (entry.type !== "image" && entry.type !== "sound") {
+                console.warn(`MinimoJS: Skipped the asset "${entry.key}", whose type "${entry.type}" this version of MinimoJS does not support.`);
+            }
+        }
+    }
+    /**
+     * Creates a dynamic texture immediately and registers it under a stable key.
+     *
+     * Unlike {@link Game.loadImage}, this does not require {@link Game.onPreload}.
+     * The `painter` callback receives a fresh offscreen canvas and should draw the
+     * full texture contents into it.
+     *
+     * The resulting texture can be used anywhere a normal image key is accepted,
+     * including {@link ImageSprite}, background layers, and optional modules.
+     *
+     * @param key - Stable texture key used later by sprites and render helpers.
+     * @param width - Texture width in pixels. Minimum `1`.
+     * @param height - Texture height in pixels. Minimum `1`.
+     * @param painter - Function that paints into the offscreen texture canvas.
+     *
+     * @example
+     * ```ts
+     * game.createTexture("checkpoint", 128, 64, (ctx, canvas) => {
+     *   ctx.fillStyle = "#101820";
+     *   ctx.fillRect(0, 0, canvas.width, canvas.height);
+     *   ctx.fillStyle = "#ffd54f";
+     *   ctx.fillRect(8, 8, canvas.width - 16, canvas.height - 16);
+     * });
+     * ```
+     */
+    createTexture(key, width, height, painter) {
+        return this._assetSystem.createTexture(key, width, height, painter);
+    }
+    /**
+     * Returns a loaded image or created texture previously registered with
+     * {@link Game.loadImage} or {@link Game.createTexture}, or `undefined` if it
+     * is not available.
+     */
+    getImage(key) {
+        return this._assetSystem.getImage(key);
+    }
+    /** @internal */
+    getImageVersion(key) {
+        return this._assetSystem.getImageVersion(key);
+    }
+    /**
+     * Returns `true` if a texture key is available.
+     */
+    hasImage(key) {
+        return this._assetSystem.hasImage(key);
+    }
+    // -------------------------------------------------------------------------
+    // Designs
+    // -------------------------------------------------------------------------
+    /**
+     * Creates one runtime object from object data, such as a template found in
+     * a {@link Design}, and adds it to the game.
+     *
+     * The object is built through the same public constructors and
+     * {@link Game.add} or {@link Game.addBackground} that code uses, so it
+     * behaves as the equivalent code. Its type picks its class: `image` builds
+     * an {@link ImageSprite}, `emoji` an {@link EmojiSprite}, `text` a
+     * {@link TextSprite}, and `background` a {@link BackgroundLayer}, unless a
+     * builder registered with {@link Game.registerBuilderByTag} matches one of
+     * its tags. Then every property the data holds is applied, including
+     * `name`, `tags`, and a copy of `data`.
+     *
+     * A `module` object is built by its module, such as a `Flame` by the
+     * `fire` module, which the scene must have created first, such as with
+     * `new Fire(game)` in `onCreate()`; otherwise the creation throws an error
+     * naming the module. Tag builders do not apply to it, and its tags are added
+     * to those the module gives it.
+     *
+     * Each call creates a new object, so one template can be created any number
+     * of times. Set its position afterwards to place it; the object is never
+     * drawn at the template's position.
+     *
+     * Throws an error naming what is wrong when the data is not a valid design
+     * object, or naming the key when it uses an image key that is not loaded.
+     *
+     * @param data - One design object, such as `design.findByName("player")`. Not a `Design`.
+     * @param options - `add: false` creates the object without adding it to the game. Default: added.
+     * @returns The created object. In TypeScript, name its type: `game.createObject<ImageSprite>(data)`.
+     *
+     * @example
+     * ```ts
+     * import charactersJson from "./characters.design.json" with { type: "json" };
+     * const characters = new Design(charactersJson);
+     *
+     * const bat = game.createObject(characters.findByName("bat"));
+     * bat.x = spawn.x;
+     * bat.y = spawn.y;
+     * ```
+     */
+    createObject(data, options = {}) {
+        if (data instanceof Design) {
+            throw new Error("MinimoJS: createObject() takes one object's data, not a Design. Pass a search's result, such as design.findByName(\"player\"), or use createObjectList(design.objects).");
+        }
+        const obj = parseDesignObject(data, "the object", "design object");
+        this._assertDesignImageLoaded(obj);
+        const created = this._buildDesignObject(obj);
+        if (options.add !== false)
+            this._addDesignObject(created);
+        return created;
+    }
+    /**
+     * Creates a runtime object from each object data, in order, and adds them
+     * to the game, as {@link Game.createObject} does for one. Objects in the
+     * same layer draw in the order of the data.
+     *
+     * Every object is checked before any is created, so invalid data or an
+     * image key that is not loaded creates nothing.
+     *
+     * @param objects - Object data, such as `design.objects` or `design.findAllByTag("enemy")`. Not a `Design`.
+     * @param options - `add: false` creates the objects without adding them to the game. Default: added.
+     * @returns An {@link ObjectList} of the created objects, to find them by name or tag.
+     *
+     * @example
+     * ```ts
+     * import menuJson from "./menu.design.json" with { type: "json" };
+     * const menu = new Design(menuJson);
+     *
+     * class MenuScene {
+     *   onCreate() {
+     *     const ui = game.createObjectList(menu.objects);
+     *     this.play = ui.findByName("play");
+     *   }
+     *   onUpdate() {
+     *     if (game.isPointerPressedOverSprite(this.play)) start(this.play.data.action);
+     *   }
+     * }
+     * ```
+     */
+    createObjectList(objects, options = {}) {
+        if (!Array.isArray(objects)) {
+            throw new Error("MinimoJS: createObjectList() takes a list of object data, such as design.objects or design.findAllByTag(\"enemy\").");
+        }
+        const parsed = objects.map((data, index) => parseDesignObject(data, `objects[${index}]`, "design object"));
+        for (const obj of parsed)
+            this._assertDesignImageLoaded(obj);
+        const created = parsed.map((obj) => this._buildDesignObject(obj));
+        if (options.add !== false) {
+            for (const obj of created)
+                this._addDesignObject(obj);
+        }
+        return new ObjectList(created);
+    }
+    /**
+     * Makes {@link Game.createObject} and {@link Game.createObjectList} build
+     * the design objects tagged `tag` with `builder`, such as an `Enemy` class
+     * of the game's own.
+     *
+     * - The builder returns an instance of the object's type class or a
+     *   subclass of it: {@link ImageSprite} for `image`, {@link EmojiSprite} for
+     *   `emoji`, {@link TextSprite} for `text`, and {@link BackgroundLayer} for
+     *   `background`. Anything else throws an error naming the object.
+     * - The engine then applies every property the data holds, so the file wins
+     *   over the constructor. Properties the data omits keep what the builder set.
+     *   An `emoji` object's `size` cannot be changed after construction, so a
+     *   builder must pass it on, or the creation throws.
+     * - An object matching the builders of two of its tags throws an error
+     *   naming the object and both tags.
+     * - Builders are scene state: {@link Game.reset} clears them, as it clears
+     *   timers, so each scene registers its own in `onCreate()`.
+     * - A `module` object is always built by its module, never by a builder.
+     *
+     * @param tag - The tag whose objects the builder builds.
+     * @param builder - Receives the object's data and the game, and returns the object, not yet added.
+     *
+     * @example
+     * ```ts
+     * class Enemy extends ImageSprite {
+     *   update(dt) { this.x += this.data.speed * dt; }
+     * }
+     *
+     * class Level1Scene {
+     *   onCreate() {
+     *     game.registerBuilderByTag("enemy", (obj, game) => new Enemy(game, obj.imageKey));
+     *     this.enemies = game.createObjectList(level1.findAllByTag("enemy")).objects;
+     *   }
+     * }
+     * ```
+     */
+    registerBuilderByTag(tag, builder) {
+        if (typeof tag !== "string" || tag.length === 0) {
+            throw new Error("MinimoJS: registerBuilderByTag() requires a non-empty tag.");
+        }
+        if (typeof builder !== "function") {
+            throw new Error(`MinimoJS: registerBuilderByTag("${tag}") requires a builder function.`);
+        }
+        if (this._buildersByTag.has(tag)) {
+            throw new Error(`MinimoJS: A builder is already registered for the tag "${tag}". game.reset() clears builders, so register each in a scene's onCreate().`);
+        }
+        this._buildersByTag.set(tag, builder);
+    }
+    /** @internal */
+    _assertDesignImageLoaded(obj) {
+        if ((obj.type === "image" || obj.type === "background") && !this.hasImage(obj.imageKey)) {
+            throw new Error(`MinimoJS: ${describeDesignObject(obj)} uses the image key "${obj.imageKey}", which is not loaded. Declare it in an asset file and load that file with game.loadAssets() in an onPreload hook.`);
+        }
+    }
+    /**
+     * Makes {@link Game.createObject} and {@link Game.createObjectList} build
+     * the design's objects of `module` with `builder`. A module calls it when
+     * it is created; the first module created for an id keeps it until
+     * {@link Game.reset} clears it, as it clears builders.
+     *
+     * @internal
+     */
+    _registerDesignModule(module, builder) {
+        if (!this._moduleBuilders.has(module))
+            this._moduleBuilders.set(module, builder);
+    }
+    /** @internal */
+    _buildModuleObject(obj) {
+        const builder = this._moduleBuilders.get(obj.module);
+        if (builder === undefined) {
+            const className = designModules[obj.module]?.className ?? "the module";
+            throw new Error(`MinimoJS: ${describeDesignObject(obj)} is a "${obj.module}" object, but this scene has not created the ${obj.module} module. Create it in the scene's onCreate(), such as with new ${className}(game), before creating the design's objects.`);
+        }
+        const created = builder(obj, this);
+        if (!(created instanceof Sprite)) {
+            throw new Error(`MinimoJS: The ${obj.module} module did not build a sprite for ${describeDesignObject(obj)}.`);
+        }
+        const target = created;
+        for (const [field, value] of Object.entries(obj)) {
+            if (field === "id" || field === "type" || field === "module" || field === "kind" || field === "options")
+                continue;
+            // The module's own tags, such as "fire", stay beside the design's.
+            if (field === "tags") {
+                created.tags = [...new Set([...created.tags, ...value])];
+                continue;
+            }
+            target[field] = value;
+        }
+        return created;
+    }
+    /** @internal */
+    _buildDesignObject(obj) {
+        if (obj.type === "module")
+            return this._buildModuleObject(obj);
+        const matchingTags = [...new Set(obj.tags ?? [])].filter((tag) => this._buildersByTag.has(tag));
+        if (matchingTags.length > 1) {
+            throw new Error(`MinimoJS: ${describeDesignObject(obj)} matches the builders of two of its tags, "${matchingTags[0]}" and "${matchingTags[1]}". An object may match at most one builder.`);
+        }
+        const tag = matchingTags[0];
+        const builder = tag === undefined ? undefined : this._buildersByTag.get(tag);
+        let created;
+        if (builder === undefined) {
+            created =
+                obj.type === "image"
+                    ? new ImageSprite(this, obj.imageKey)
+                    : obj.type === "emoji"
+                        ? new EmojiSprite(obj.sprite, 0, 0, obj.size)
+                        : obj.type === "text"
+                            ? new TextSprite(obj.text, 0, 0, obj.fontSize)
+                            : new BackgroundLayer(obj.imageKey);
+        }
+        else {
+            created = builder(obj, this);
+            const expected = DESIGN_OBJECT_CLASSES[obj.type];
+            if (!(created instanceof expected)) {
+                throw new Error(`MinimoJS: The builder for the tag "${tag}" did not return an instance of ${expected.name} or of a subclass of it for ${describeDesignObject(obj)}, whose type is "${obj.type}".`);
+            }
+            if (obj.type === "emoji" && obj.size !== undefined && created.size !== obj.size) {
+                throw new Error(`MinimoJS: The builder for the tag "${tag}" built ${describeDesignObject(obj)} with the size ${created.size}, but its data says ${obj.size}. An EmojiSprite's size is set only by its constructor, so pass obj.size to it.`);
+            }
+        }
+        const target = created;
+        for (const [field, value] of Object.entries(obj)) {
+            if (field === "id" || field === "type")
+                continue;
+            if (field === "size" && created instanceof EmojiSprite)
+                continue;
+            if (field === "imageKey" && created instanceof ImageSprite) {
+                created.setTexture(value);
+                continue;
+            }
+            target[field] = value;
+        }
+        return created;
+    }
+    /** @internal */
+    _addDesignObject(obj) {
+        if (obj instanceof BackgroundLayer) {
+            if (!this._backgroundSystem.getMutableLayers().includes(obj))
+                this.addBackground(obj);
+        }
+        else if (!this._spriteSystem.getMutableSprites().includes(obj)) {
+            this.add(obj);
+        }
     }
     // -------------------------------------------------------------------------
     // Collision
@@ -781,10 +2101,7 @@ export class Game {
      * ```
      */
     overlap(a, b) {
-        const halfA = a.displaySize / 2;
-        const halfB = b.displaySize / 2;
-        return (Math.abs(a.x - b.x) < halfA + halfB &&
-            Math.abs(a.y - b.y) < halfA + halfB);
+        return this._physicsSystem.overlap(a, b);
     }
     /**
      * Tests for any overlap between two groups of sprites.
@@ -796,7 +2113,7 @@ export class Game {
      *
      * @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,
+     * @returns A `[EmojiSprite, EmojiSprite]` tuple of the first overlapping pair,
      *   or `null` if no pair overlaps.
      *
      * @example
@@ -810,13 +2127,7 @@ export class Game {
      * ```
      */
     overlapAny(listA, listB) {
-        for (const a of listA) {
-            for (const b of listB) {
-                if (this.overlap(a, b))
-                    return [a, b];
-            }
-        }
-        return null;
+        return this._physicsSystem.overlapAny(listA, listB);
     }
     /**
      * Tests and resolves a basic AABB collision between two sprites.
@@ -847,33 +2158,7 @@ export class Game {
      * ```
      */
     collide(a, b) {
-        this._assertPhysicsEnabled();
-        if (a === b)
-            return null;
-        const collision = this._getCollisionResolution(a, b);
-        if (!collision)
-            return null;
-        if (!a.isStatic) {
-            a.x += collision.separationX;
-            a.y += collision.separationY;
-            if (collision.axis === "x") {
-                a.vx = 0;
-            }
-            else {
-                a.vy = 0;
-            }
-        }
-        else if (!b.isStatic) {
-            b.x -= collision.separationX;
-            b.y -= collision.separationY;
-            if (collision.axis === "x") {
-                b.vx = 0;
-            }
-            else {
-                b.vy = 0;
-            }
-        }
-        return collision.info;
+        return this._physicsSystem.collide(a, b);
     }
     /**
      * Tests and resolves the first collision found between two groups of sprites.
@@ -884,7 +2169,7 @@ export class Game {
      *
      * @param listA - First group of sprites.
      * @param listB - Second group of sprites.
-     * @returns A `[Sprite, Sprite, CollisionInfo]` tuple for the first collision found,
+     * @returns A `[EmojiSprite, EmojiSprite, CollisionInfo]` tuple for the first collision found,
      *   or `null` if no pair overlaps.
      * @throws Error if the game's physics helpers are not enabled.
      *
@@ -897,15 +2182,7 @@ export class Game {
      * ```
      */
     collideAny(listA, listB) {
-        this._assertPhysicsEnabled();
-        for (const a of listA) {
-            for (const b of listB) {
-                const info = this.collide(a, b);
-                if (info)
-                    return [a, b, info];
-            }
-        }
-        return null;
+        return this._physicsSystem.collideAny(listA, listB);
     }
     // -------------------------------------------------------------------------
     // Input — Keyboard
@@ -929,7 +2206,7 @@ export class Game {
      * ```
      */
     isKeyDown(key) {
-        return this._keysDown.has(key);
+        return this._inputSystem.isKeyDown(key);
     }
     /**
      * Returns `true` only on the **single frame** the key was first pressed.
@@ -947,7 +2224,7 @@ export class Game {
      * ```
      */
     isKeyPressed(key) {
-        return this._keysPressed.has(key);
+        return this._inputSystem.isKeyPressed(key);
     }
     // -------------------------------------------------------------------------
     // Input — Pointer (mouse / touch)
@@ -957,6 +2234,8 @@ export class Game {
      * Use this for continuous pointer actions.
      *
      * **Hold behavior:** returns `true` every frame from press until release.
+     * On a touch screen it follows one finger, as {@link Game.pointerX} does,
+     * so it turns `false` when that finger lifts, even if another is down.
      *
      * @returns `true` if the pointer is currently pressed.
      *
@@ -966,7 +2245,7 @@ export class Game {
      * ```
      */
     isPointerDown() {
-        return this._pointerDown;
+        return this._inputSystem.isPointerDown();
     }
     /**
      * Returns `true` only on the **single frame** the pointer was first pressed.
@@ -983,82 +2262,77 @@ export class Game {
      * ```
      */
     isPointerPressed() {
-        return this._pointerPressed;
+        return this._inputSystem.isPointerPressed();
+    }
+    /**
+     * True on the frame the primary touch ended in a `touchcancel` rather than
+     * lifting, so a module can drop the gesture instead of reading it as a tap.
+     *
+     * @internal
+     */
+    isPointerCancelled() {
+        return this._inputSystem.isPointerCancelled();
+    }
+    /**
+     * The canvas the game draws on, for a module in this package that lays HTML
+     * over it, as `leaderboard` does with its table. Games never need it.
+     *
+     * @internal
+     */
+    getCanvasElement() {
+        return this._canvas;
     }
     /**
      * Returns `true` while any active pointer is held down over the target sprite.
      * Works with both mouse input and multiple simultaneous touches.
      *
-     * Pointer hit testing uses a circular area centered on the sprite. The radius
-     * is `sprite.displaySize * radiusScale`. World-space sprites are tested against the
-     * current camera scroll. HUD sprites with `ignoreScroll = true` are tested in
-     * screen space.
+     * Pointer hit testing uses the sprite's exact displayed rectangular bounds.
+     * World-space sprites are tested against the current camera scroll. HUD
+     * sprites with `ignoreScroll = true` are tested in screen space. For
+     * anchored {@link TextSprite} instances, the engine first resolves
+     * `anchorX` / `anchorY` into the final rendered center, then tests against
+     * that rectangle.
      *
      * Use this for continuous virtual buttons such as touch movement controls.
      *
      * @param sprite - Target sprite to test. If `null` / `undefined`, returns `false`.
-     * @param radiusScale - Multiplier applied to `sprite.displaySize` to define the hit radius.
-     *   Default: `0.5`.
      * @returns `true` if any currently held pointer overlaps the sprite hit area.
      *
      * @example
      * ```ts
-     * if (game.isPointerDownOverSprite(leftButton, 0.72)) {
+     * if (game.isPointerDownOverSprite(leftButton)) {
      *   player.x -= 200 * dt;
      * }
      * ```
      */
-    isPointerDownOverSprite(sprite, radiusScale = 0.5) {
-        if (!sprite)
-            return false;
-        if (this._mouseDown &&
-            this._isScreenPointOverSprite(this._mouseX, this._mouseY, sprite, radiusScale)) {
-            return true;
-        }
-        for (const pointer of this._touchPointers.values()) {
-            if (this._isScreenPointOverSprite(pointer.x, pointer.y, sprite, radiusScale)) {
-                return true;
-            }
-        }
-        return false;
+    isPointerDownOverSprite(sprite) {
+        return this._inputSystem.isPointerDownOverSprite(sprite);
     }
     /**
      * Returns `true` only on the frame any pointer first pressed over the target
      * sprite. Works with both mouse input and multiple simultaneous touches.
      *
-     * Pointer hit testing uses a circular area centered on the sprite. The radius
-     * is `sprite.displaySize * radiusScale`. World-space sprites are tested against the
-     * current camera scroll. HUD sprites with `ignoreScroll = true` are tested in
-     * screen space.
+     * Pointer hit testing uses the sprite's exact displayed rectangular bounds.
+     * World-space sprites are tested against the current camera scroll. HUD
+     * sprites with `ignoreScroll = true` are tested in screen space. For
+     * anchored {@link TextSprite} instances, the engine first resolves
+     * `anchorX` / `anchorY` into the final rendered center, then tests against
+     * that rectangle.
      *
      * Use this for one-shot virtual buttons such as menu taps.
      *
      * @param sprite - Target sprite to test. If `null` / `undefined`, returns `false`.
-     * @param radiusScale - Multiplier applied to `sprite.displaySize` to define the hit radius.
-     *   Default: `0.5`.
      * @returns `true` if any pointer began pressing this frame over the sprite hit area.
      *
      * @example
      * ```ts
-     * if (game.isPointerPressedOverSprite(startButton, 0.8)) {
+     * if (game.isPointerPressedOverSprite(startButton)) {
      *   startGame();
      * }
      * ```
      */
-    isPointerPressedOverSprite(sprite, radiusScale = 0.5) {
-        if (!sprite)
-            return false;
-        if (this._mousePressed &&
-            this._isScreenPointOverSprite(this._mouseX, this._mouseY, sprite, radiusScale)) {
-            return true;
-        }
-        for (const pointer of this._touchPointers.values()) {
-            if (pointer.pressed &&
-                this._isScreenPointOverSprite(pointer.x, pointer.y, sprite, radiusScale)) {
-                return true;
-            }
-        }
-        return false;
+    isPointerPressedOverSprite(sprite) {
+        return this._inputSystem.isPointerPressedOverSprite(sprite);
     }
     /**
      * Returns a read-only snapshot of all currently active pointers.
@@ -1082,38 +2356,36 @@ export class Game {
      * ```
      */
     getPointers() {
-        return this._collectPointers();
+        return this._inputSystem.getPointers();
     }
     /**
      * Returns a read-only snapshot of all active pointers currently overlapping
      * the target sprite.
      *
-     * Pointer hit testing uses a circular area centered on the sprite. The radius
-     * is `sprite.displaySize * radiusScale`. World-space sprites are tested against the
-     * current camera scroll. HUD sprites with `ignoreScroll = true` are tested in
-     * screen space.
+     * Pointer hit testing uses the sprite's exact displayed rectangular bounds.
+     * World-space sprites are tested against the current camera scroll. HUD
+     * sprites with `ignoreScroll = true` are tested in screen space. For
+     * anchored {@link TextSprite} instances, the engine first resolves
+     * `anchorX` / `anchorY` into the final rendered center, then tests against
+     * that rectangle.
      *
      * Use this when you need more than a boolean result, such as reading the exact
      * pointer position over a virtual joystick or draggable control.
      *
      * @param sprite - Target sprite to test. If `null` / `undefined`, returns an empty array.
-     * @param radiusScale - Multiplier applied to `sprite.displaySize` to define the hit radius.
-     *   Default: `0.5`.
      * @returns A read-only array of active pointer snapshots currently over the sprite.
      *
      * @example
      * ```ts
-     * const touches = game.getPointersOverSprite(joystickBase, 1.0);
+     * const touches = game.getPointersOverSprite(joystickBase);
      * if (touches.length > 0) {
      *   const p = touches[0];
      *   const dx = p.x - joystickBase.x;
      * }
      * ```
      */
-    getPointersOverSprite(sprite, radiusScale = 0.5) {
-        if (!sprite)
-            return [];
-        return this._collectPointers().filter((pointer) => this._isScreenPointOverSprite(pointer.x, pointer.y, sprite, radiusScale));
+    getPointersOverSprite(sprite) {
+        return this._inputSystem.getPointersOverSprite(sprite);
     }
     /**
      * Returns `true` when the current device appears to be mobile/touch-first.
@@ -1126,140 +2398,510 @@ export class Game {
      *
      * @example
      * ```ts
-     * if (game.isMobileDevice()) {
-     *   // Show touch buttons
-     * } else {
-     *   // Show keyboard hints
-     * }
+     * if (game.isMobileDevice()) {
+     *   // Show touch buttons
+     * } else {
+     *   // Show keyboard hints
+     * }
+     * ```
+     */
+    isMobileDevice() {
+        return this._inputSystem.isMobileDevice();
+    }
+    // -------------------------------------------------------------------------
+    // Sound
+    // -------------------------------------------------------------------------
+    /**
+     * Plays a sound loaded with {@link Game.loadSound} or an asset file's
+     * `sound` entry, and returns its {@link SoundPlayback}.
+     *
+     * Plays overlap: playing a sound that is already playing starts another
+     * play of it. Keep the returned playback to pause, resume, or stop it, such
+     * as the game's music. A one-shot play stops by itself when it ends; a
+     * looping one plays until stopped.
+     *
+     * - **Before the first tap.** Browsers keep a page silent until the player
+     *   taps, clicks, or presses a key. A looping sound started earlier, such as
+     *   music started in a scene's `onCreate()`, waits and begins with that
+     *   first gesture. A one-shot sound played earlier is dropped, and its
+     *   playback is returned already stopped.
+     * - **Scenes.** {@link Game.reset} and {@link Game.transitionTo} do not stop
+     *   sounds. Stop the music yourself when a scene should change it.
+     * - **Hidden page.** Every sound pauses while the page is hidden, and
+     *   continues when it is shown again.
+     *
+     * Throws an error naming the key when no sound is loaded under it.
+     *
+     * @param key - A key loaded with {@link Game.loadSound} or an asset file.
+     * @param options - `loop` to repeat until stopped, and `volume` from `0` to `1`.
+     *
+     * @example
+     * ```ts
+     * game.playSound("jump");
+     * const music = game.playSound("theme", { loop: true, volume: 0.6 });
+     * music.pause();
+     * music.resume();
+     * music.stop();
+     * ```
+     */
+    playSound(key, options) {
+        const buffer = this._assetSystem.getSound(key);
+        if (buffer === undefined) {
+            throw new Error(`MinimoJS: No sound is loaded under the key "${key}". Load it with game.loadSound() or an asset file's "sound" entry in an onPreload hook.`);
+        }
+        return this._soundSystem.play(key, buffer, options);
+    }
+    /**
+     * Stops every sound playing from a file, such as music and effects started
+     * with {@link Game.playSound}. Synthesized tones are not affected.
+     *
+     * @example
+     * ```ts
+     * game.stopAllSounds();
+     * ```
+     */
+    stopAllSounds() {
+        this._soundSystem.stopAll();
+    }
+    /**
+     * Plays a square-wave beep using the Web Audio API.
+     *
+     * **Retro tone, not a game's sound.** This synthesizes a square-wave tone and
+     * needs no file, so it sounds like an old arcade machine. A game's music and
+     * sound effects are audio files: declare them as `sound` entries in an asset
+     * file, or load them with {@link Game.loadSound}, and play them with
+     * {@link Game.playSound}. Use tones only for a deliberately retro game, or
+     * when no audio file can be obtained.
+     *
+     * 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.
+     *
+     * If you need a melody/sequence, use {@link Game.soundSequence} instead of
+     * multiple `sound()` calls in the same frame.
+     *
+     * 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
+     * ```
+     */
+    sound(freq, durationMs) {
+        this._soundSystem.sound(freq, durationMs);
+    }
+    /**
+     * Plays multiple square-wave tones in strict sequence.
+     *
+     * Like {@link Game.sound}, this is a retro tone, not a game's sound: for
+     * music and sound effects, play audio files with {@link Game.playSound}.
+     *
+     * Each tuple is `[frequencyHz, durationMs]`. The next tone starts when the
+     * previous one ends.
+     *
+     * @param tones - Tone tuples in playback order.
+     *
+     * @example
+     * ```ts
+     * game.soundSequence([660, 80], [820, 90], [980, 110], [1180, 150]);
+     * ```
+     */
+    soundSequence(...tones) {
+        this._soundSystem.soundSequence(...tones);
+    }
+    // -------------------------------------------------------------------------
+    // 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._animationSystem.animateAlpha(sprite, to, durationMs, 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._animationSystem.animateRotation(sprite, to, durationMs, onComplete);
+    }
+    /**
+     * Animates a sprite's visual deformation using non-uniform scaling around a
+     * normalized pivot point.
+     *
+     * This affects rendering only. Physics and collision bounds continue to use
+     * {@link EmojiSprite.displaySize} and ignore the deform result.
+     *
+     * `pivotX` / `pivotY` are normalized anchors in the sprite's square display box:
+     * - `0` = left/top
+     * - `0.5` = center
+     * - `1` = right/bottom
+     *
+     * For example, `pivotY = 1` keeps the bottom visually pinned while squashing
+     * or stretching, which is useful for floor-contact animation.
+     *
+     * Like other MinimoJS animations, this animates from the sprite's current
+     * deform state to the requested target and leaves the final result applied.
+     *
+     * @param sprite - The sprite to deform.
+     * @param toScaleX - Target horizontal deform scale. `1` = unchanged.
+     * @param toScaleY - Target vertical deform scale. `1` = unchanged.
+     * @param pivotX - Horizontal pivot in normalized `[0, 1]` sprite space.
+     * @param pivotY - Vertical pivot in normalized `[0, 1]` sprite space.
+     * @param durationMs - Duration of the animation in **milliseconds**.
+     * @param onComplete - Optional callback invoked when the animation finishes.
+     *
+     * @example
+     * ```ts
+     * game.animateDeform(player, 1.18, 0.85, 0.5, 1, 90, () => {
+     *   game.animateDeform(player, 1, 1, 0.5, 1, 120);
+     * });
+     * ```
+     */
+    animateDeform(sprite, toScaleX, toScaleY, pivotX, pivotY, durationMs, onComplete) {
+        this._animationSystem.animateDeform(sprite, toScaleX, toScaleY, pivotX, pivotY, durationMs, onComplete);
+    }
+    /**
+     * Convenience helper that squashes a sprite around its horizontal center.
+     *
+     * This is equivalent to animating toward a wider, shorter visual pose using
+     * {@link Game.animateDeform}. `pivotY = 1` is the common floor-anchored case.
+     *
+     * @param sprite - The sprite to squash.
+     * @param pivotY - Vertical pivot in normalized `[0, 1]` sprite space.
+     * @param durationMs - Duration of the animation in **milliseconds**.
+     * @param onComplete - Optional callback invoked when the animation finishes.
+     */
+    animateSquash(sprite, pivotY, durationMs, onComplete) {
+        this._animationSystem.animateDeform(sprite, 1.18, 0.85, 0.5, pivotY, durationMs, onComplete);
+    }
+    /**
+     * Convenience helper that stretches a sprite around its horizontal center.
+     *
+     * This is equivalent to animating toward a narrower, taller visual pose using
+     * {@link Game.animateDeform}. `pivotY = 1` is the common floor-anchored case.
+     *
+     * @param sprite - The sprite to stretch.
+     * @param pivotY - Vertical pivot in normalized `[0, 1]` sprite space.
+     * @param durationMs - Duration of the animation in **milliseconds**.
+     * @param onComplete - Optional callback invoked when the animation finishes.
+     */
+    animateStretch(sprite, pivotY, durationMs, onComplete) {
+        this._animationSystem.animateDeform(sprite, 0.85, 1.18, 0.5, pivotY, durationMs, onComplete);
+    }
+    /**
+     * Convenience helper that applies a centered uniform scale pulse and then
+     * returns the sprite to its neutral shape.
+     *
+     * Internally this runs two deform animations back-to-back using
+     * {@link Game.animateDeform}.
+     *
+     * @param sprite - The sprite to pulse.
+     * @param scale - Peak uniform scale reached midway through the pulse. `1` leaves the sprite unchanged.
+     * @param durationMs - Total pulse duration in **milliseconds**.
+     * @param onComplete - Optional callback invoked after the sprite returns to neutral.
+     *
+     * @example
+     * ```ts
+     * game.animatePulse(coin, 1.25, 220);
+     * ```
+     */
+    animatePulse(sprite, scale, durationMs, onComplete) {
+        const target = Number.isFinite(scale) ? Math.max(0, scale) : 1;
+        const firstHalf = Math.max(1, Math.round(durationMs / 2));
+        const secondHalf = Math.max(1, durationMs - firstHalf);
+        this._animationSystem.animateDeform(sprite, target, target, 0.5, 0.5, firstHalf, () => {
+            this._animationSystem.animateDeform(sprite, 1, 1, 0.5, 0.5, secondHalf, onComplete);
+        });
+    }
+    /**
+     * Applies a decaying screen-space shake to a sprite without changing its
+     * logical position.
+     *
+     * This is a render-only effect. Physics, collisions, and the sprite's
+     * `x` / `y` values are not modified.
+     *
+     * @param sprite - The sprite to shake.
+     * @param intensity - Maximum shake offset in pixels.
+     * @param durationMs - Duration of the shake in **milliseconds**.
+     * @param onComplete - Optional callback invoked when the shake ends.
+     *
+     * @example
+     * ```ts
+     * game.animateShake(player, 18, 300);
+     * ```
+     */
+    animateShake(sprite, intensity, durationMs, onComplete) {
+        this._animationSystem.animateShake(sprite, intensity, durationMs, onComplete);
+    }
+    /**
+     * Moves a sprite upward and back down to its starting position along a simple
+     * parabolic arc.
+     *
+     * This animation writes directly to {@link Sprite.x} / {@link Sprite.y} while
+     * it is active.
+     *
+     * @param sprite - The sprite to bounce.
+     * @param height - Peak bounce height in pixels.
+     * @param durationMs - Total bounce duration in **milliseconds**.
+     * @param onComplete - Optional callback invoked when the bounce ends.
+     *
+     * @example
+     * ```ts
+     * game.animateBounce(ball, 120, 600);
+     * ```
+     */
+    animateBounce(sprite, height, durationMs, onComplete) {
+        this._animationSystem.animateBounce(sprite, height, durationMs, onComplete);
+    }
+    /**
+     * Moves a sprite upward and back down with a smooth sine-shaped float motion.
+     *
+     * This animation writes directly to {@link Sprite.x} / {@link Sprite.y} while
+     * it is active.
+     *
+     * @param sprite - The sprite to float.
+     * @param distance - Maximum upward travel in pixels.
+     * @param durationMs - Total float duration in **milliseconds**.
+     * @param onComplete - Optional callback invoked when the float ends.
+     *
+     * @example
+     * ```ts
+     * game.animateFloat(balloon, 90, 1200);
+     * ```
+     */
+    animateFloat(sprite, distance, durationMs, onComplete) {
+        this._animationSystem.animateFloat(sprite, distance, durationMs, onComplete);
+    }
+    /**
+     * Toggles a sprite's rendered opacity on and off a fixed number of times.
+     *
+     * This is a render-only effect. The sprite remains present in the world and
+     * keeps receiving physics updates while blinking.
+     *
+     * @param sprite - The sprite to blink.
+     * @param times - Number of visible/invisible toggle cycles.
+     * @param durationMs - Total blink duration in **milliseconds**.
+     * @param onComplete - Optional callback invoked when blinking ends.
+     *
+     * @example
+     * ```ts
+     * game.animateBlink(player, 4, 700);
+     * ```
+     */
+    animateBlink(sprite, times, durationMs, onComplete) {
+        this._animationSystem.animateBlink(sprite, times, durationMs, onComplete);
+    }
+    /**
+     * Applies a rapid irregular alpha variation to create a damaged, unstable, or
+     * ghost-like flicker.
+     *
+     * This is a render-only effect and does not change the sprite's logical
+     * position or collision state.
+     *
+     * @param sprite - The sprite to flicker.
+     * @param durationMs - Total flicker duration in **milliseconds**.
+     * @param onComplete - Optional callback invoked when the flicker ends.
+     *
+     * @example
+     * ```ts
+     * game.animateFlicker(ghost, 900);
+     * ```
+     */
+    animateFlicker(sprite, durationMs, onComplete) {
+        this._animationSystem.animateFlicker(sprite, durationMs, onComplete);
+    }
+    /**
+     * Moves a sprite from its current position to a target position along a
+     * parabolic arc.
+     *
+     * This animation writes directly to {@link Sprite.x} / {@link Sprite.y} while
+     * it is active.
+     *
+     * @param sprite - The sprite to move.
+     * @param toX - Destination X position in world space.
+     * @param toY - Destination Y position in world space.
+     * @param arcHeight - Maximum height of the arc above the linear path, in pixels.
+     * @param durationMs - Total arc duration in **milliseconds**.
+     * @param onComplete - Optional callback invoked when the arc ends.
+     *
+     * @example
+     * ```ts
+     * game.animateArc(coin, player.x, player.y, 80, 420);
+     * ```
+     */
+    animateArc(sprite, toX, toY, arcHeight, durationMs, onComplete) {
+        this._animationSystem.animateArc(sprite, toX, toY, arcHeight, durationMs, onComplete);
+    }
+    /**
+     * Emits temporary afterimages from a sprite to create a motion trail.
+     *
+     * This is a render-only effect. Trail ghosts are not real sprites and do not
+     * appear in {@link Game.getSprites}, collide, or receive physics.
+     *
+     * @param sprite - The sprite to sample for trail ghosts.
+     * @param options - Optional trail tuning values.
+     * @param onComplete - Optional callback invoked when the emitter stops spawning ghosts.
+     *
+     * @example
+     * ```ts
+     * game.animateTrail(player, { durationMs: 300, spacingMs: 30, fadeMs: 180 });
      * ```
      */
-    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;
+    animateTrail(sprite, options, onComplete) {
+        this._trailSystem.animateTrail(sprite, options, onComplete);
     }
-    // -------------------------------------------------------------------------
-    // 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.
+     * Breaks a sprite into visual pieces that burst outward from its current
+     * rendered appearance.
      *
-     * 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.
+     * This is a render-only effect. The spawned pieces are not real sprites and do
+     * not appear in {@link Game.getSprites}, receive physics, or collide.
      *
-     * The tone fades out exponentially over `durationMs` to avoid clicks.
+     * By default, the original sprite is destroyed immediately after the explosion
+     * effect is spawned. Set `destroySprite: false` to hide the sprite during the
+     * effect and restore it when the explosion ends.
      *
-     * @param freq - Frequency in Hz. Middle C = 261.6. Typical range: 100–4000 Hz.
-     * @param durationMs - Duration of the sound in **milliseconds**.
+     * @param sprite - The sprite to explode.
+     * @param options - Optional explosion tuning values.
+     * @param onComplete - Optional callback invoked when the effect finishes.
      *
      * @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)
+     * game.animateExplode(enemy, { rows: 4, cols: 4, durationMs: 650, speed: 320 });
      * ```
      */
-    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);
+    animateExplode(sprite, options, onComplete) {
+        const glyphCanvas = this._renderSystem.getSpriteGlyphCanvasForEffects(sprite);
+        this._explosionSystem.animateExplode(sprite, glyphCanvas, options, onComplete);
+        if (options?.destroySprite !== false) {
+            this.destroySprite(sprite);
+        }
     }
-    // -------------------------------------------------------------------------
-    // Animations
-    // -------------------------------------------------------------------------
     /**
-     * Animates a sprite's {@link Sprite.alpha} from its current value to `to`
-     * over `durationMs` milliseconds using **linear interpolation**.
+     * Spawns visual pieces around a sprite and converges them back into its
+     * current rendered appearance.
      *
-     * If an alpha animation is already running on this sprite, it is replaced
-     * by the new one immediately (no queuing).
+     * This is a render-only effect. The spawned pieces are not real sprites and
+     * do not appear in {@link Game.getSprites}, receive physics, or collide.
      *
-     * **Timing:** driven by the rAF loop, not `setTimeout`. Duration is in ms.
+     * The original sprite is hidden while the assembly plays and is restored when
+     * the effect finishes.
      *
-     * @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.
+     * @param sprite - The sprite to assemble.
+     * @param options - Optional assembly tuning values.
+     * @param onComplete - Optional callback invoked when the effect finishes.
+     */
+    animateAssemble(sprite, options, onComplete) {
+        const glyphCanvas = this._renderSystem.getSpriteGlyphCanvasForEffects(sprite);
+        this._explosionSystem.animateAssemble(sprite, glyphCanvas, options, onComplete);
+    }
+    /**
+     * Breaks a sprite apart locally inside its own bounds using a directional
+     * dissolve sweep.
      *
-     * @example
-     * ```ts
-     * // Fade out a sprite over 1 second, then destroy it
-     * game.animateAlpha(coin, 0, 1000, () => game.destroySprite(coin));
-     * ```
+     * This is a render-only effect. The spawned pieces are not real sprites and
+     * do not appear in {@link Game.getSprites}, receive physics, or collide.
+     *
+     * By default, the original sprite is destroyed immediately after the effect
+     * is spawned. Set `destroySprite: false` to leave the sprite hidden instead.
+     *
+     * @param sprite - The sprite to disintegrate.
+     * @param options - Optional disintegration tuning values.
+     * @param onComplete - Optional callback invoked when the effect finishes.
      */
-    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,
-        });
+    animateDisintegrate(sprite, options, onComplete) {
+        const glyphCanvas = this._renderSystem.getSpriteGlyphCanvasForEffects(sprite);
+        this._explosionSystem.animateDisintegrate(sprite, glyphCanvas, options, onComplete);
+        if (options?.destroySprite !== false) {
+            this.destroySprite(sprite);
+        }
     }
     /**
-     * Animates a sprite's {@link Sprite.rotation} from its current value to `to`
-     * (in degrees) over `durationMs` milliseconds using **linear interpolation**.
+     * Reconstructs a sprite locally inside its own bounds using a directional
+     * integration sweep.
      *
-     * If a rotation animation is already running on this sprite, it is replaced
-     * immediately (no queuing).
+     * This is a render-only effect. The spawned pieces are not real sprites and
+     * do not appear in {@link Game.getSprites}, receive physics, or collide.
      *
-     * **Timing:** driven by the rAF loop, not `setTimeout`. Duration is in ms.
-     * **Units:** `to` is in **degrees**.
+     * The original sprite is hidden while the integration plays and is restored
+     * when the effect finishes.
      *
-     * @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.
+     * @param sprite - The sprite to integrate.
+     * @param options - Optional integration tuning values.
+     * @param onComplete - Optional callback invoked when the effect finishes.
+     */
+    animateIntegrate(sprite, options, onComplete) {
+        const glyphCanvas = this._renderSystem.getSpriteGlyphCanvasForEffects(sprite);
+        this._explosionSystem.animateIntegrate(sprite, glyphCanvas, options, onComplete);
+    }
+    /**
+     * Reveals or covers a sprite with a directional wipe mask.
      *
-     * @example
-     * ```ts
-     * // Spin a sprite 360° over 2 seconds
-     * game.animateRotation(star, 360, 2000);
+     * This is a render-only effect that captures the sprite's current appearance
+     * and animates a clipping region over that snapshot.
      *
-     * // Tilt on hit, then straighten
-     * game.animateRotation(player, 45, 200, () => {
-     *   game.animateRotation(player, 0, 200);
-     * });
-     * ```
+     * For `mode: "reveal"`, the original sprite is hidden during the wipe and is
+     * restored when the effect finishes.
+     *
+     * For `mode: "cover"`, the effect hides the sprite over time. If
+     * `destroySprite` is omitted or `true`, the sprite is destroyed immediately
+     * after the wipe starts and only the wipe snapshot remains visible.
+     *
+     * @param sprite - The sprite to wipe.
+     * @param options - Optional wipe tuning values.
+     * @param onComplete - Optional callback invoked when the effect finishes.
      */
-    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,
-        });
+    animateWipe(sprite, options, onComplete) {
+        const snapshot = this._renderSystem.getSpriteRenderSnapshot(sprite);
+        this._explosionSystem.animateWipe(sprite, snapshot, options, onComplete);
+        if ((options?.mode ?? "reveal") === "cover" && options?.destroySprite !== false) {
+            this.destroySprite(sprite);
+        }
     }
     // -------------------------------------------------------------------------
     // Timers
@@ -1294,9 +2936,7 @@ export class Game {
      * ```
      */
     addTimer(delayMs, repeat, callback) {
-        const id = ++this._timerIdCounter;
-        this._timers.push({ id, delayMs, elapsed: 0, repeat, callback });
-        return id;
+        return this._timerSystem.addTimer(delayMs, repeat, callback);
     }
     /**
      * Cancels a timer previously created with {@link Game.addTimer}.
@@ -1313,27 +2953,32 @@ export class Game {
      * ```
      */
     clearTimer(id) {
-        this._timers = this._timers.filter((t) => t.id !== id);
+        this._timerSystem.clearTimer(id);
     }
     // -------------------------------------------------------------------------
     // Text
     // -------------------------------------------------------------------------
     /**
-     * Draws text on screen as a **screen-space overlay** this frame.
+     * Draws text on screen as a **simple 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.
+     * Use this for lightweight 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 uses `"Press Start 2P", monospace`.
-     * You MUST load `Press Start 2P` yourself in `index.html` (for example via
-     * Google Fonts) before calling {@link Game.start}. MinimoJS does NOT load
-     * external fonts for you. If the font is unavailable, the browser falls back
-     * to `monospace`. Font family cannot be customized in MinimoJS v1.
+     * **Font:** Text always uses `monospace`. Use {@link TextSprite} for any
+     * other family.
+     *
+     * Prefer {@link TextSprite} for UI buttons or labels that need persistent
+     * bounds, hit testing, fixed sizes, backgrounds, borders, or text stroke.
+     * `drawText()` is the lightweight overlay API, not the primary UI API.
+     *
+     * For controls that are only a single emoji, prefer {@link EmojiSprite} over
+     * {@link TextSprite}. Emoji-only buttons do not benefit from text padding and
+     * usually fit more naturally in the sprite pipeline.
      *
      * @param text - The string to render. Supports emoji and Unicode.
      * @param x - X position in **screen space** (pixels from canvas left edge).
@@ -1354,7 +2999,7 @@ export class Game {
      * ```
      */
     drawText(text, x, y, fontSize, color = "#ffffff", centered = false) {
-        this._textOverlays.push({ text, x, y, fontSize, color, centered });
+        this._textSystem.drawText(text, x, y, fontSize, color, centered);
     }
     // -------------------------------------------------------------------------
     // Misc
@@ -1375,7 +3020,46 @@ export class Game {
      * ```
      */
     clearSpriteCache() {
-        this._spriteGlyphCache.clear();
+        this._renderSystem.clearSpriteCache();
+    }
+    /**
+     * Registers a web font family that must be loaded before the first frame.
+     *
+     * Call this before {@link Game.start}, typically right after constructing the
+     * game or inside {@link Game.onPreload}. MinimoJS waits for every registered
+     * font via `document.fonts.load(...)` before rendering anything. Host
+     * environments may also pre-register fonts by setting
+     * `globalThis.__MINIMO_WEB_FONT_REQUIREMENTS__` before your game code runs.
+     *
+     * The font itself must still be declared by your page (for example with a
+     * `<link rel="stylesheet">` in `index.html`). MinimoJS only waits for it.
+     *
+     * @example
+     * ```ts
+     * game.requireFont('"Press Start 2P"');
+     * game.requireFont('"Bangers"', { weight: "700" });
+     * ```
+     */
+    requireFont(family, options = {}) {
+        const normalizedFamily = family.trim();
+        if (normalizedFamily.length === 0) {
+            return;
+        }
+        const requirement = {
+            family: normalizedFamily,
+            weight: options.weight ?? "400",
+            style: options.style ?? "normal",
+            size: Number.isFinite(options.size) ? Math.max(1, options.size) : 16,
+            sampleText: options.sampleText ?? "",
+        };
+        const key = [
+            requirement.family,
+            requirement.weight,
+            requirement.style,
+            requirement.size,
+            requirement.sampleText,
+        ].join("|");
+        this._requiredFonts.set(key, requirement);
     }
     /**
      * Returns a pseudo-random floating-point number in the range `[0, 1)`.
@@ -1400,9 +3084,12 @@ export class Game {
      * Performs a full engine state reset to enable scene switching.
      *
      * **Cleared by reset:**
+     * - All background layers
      * - All sprites (equivalent to calling {@link Game.destroySprite} on every sprite)
      * - All timers (regardless of repeat state)
      * - All running animations
+     * - All active explosion effects
+     * - All active trail effects
      * - All pending text overlays
      * - Scroll position (`scrollX = 0`, `scrollY = 0`)
      * - Per-frame input state (pressed keys, pressed pointer)
@@ -1415,38 +3102,125 @@ export class Game {
      * - Canvas dimensions
      * - AudioContext
      *
-     * After clearing, `reset()` immediately calls `onCreate()` so your callback
-     * can rebuild the new scene synchronously.
+     * After clearing, `reset()` immediately calls the active scene's
+     * `onCreate()` (or legacy {@link Game.onCreate} if no scene is active) so it
+     * can rebuild synchronously.
+     *
+     * The exception is a scene whose {@link IScene.onPreload} registers images
+     * that are not loaded yet. Then the current scene freezes and dims under a progress
+     * ring, nothing is cleared until the images load, and `reset()` returns
+     * before the scene is rebuilt; its `onCreate()` runs once they have loaded.
+     * A `reset()` called while a scene is loading is ignored.
+     *
+     * @param scene - Optional new scene to make active before rebuilding.
      *
      * @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("💀", 400, 300, 96);
-     *   game.add(skull);
-     *   game.addTimer(3000, false, () => game.reset()); // auto-restart
-     * };
+     * class GameOverScene {
+     *   onCreate() {
+     *     const skull = new EmojiSprite("💀", 400, 300, 96);
+     *     game.add(skull);
+     *     game.addTimer(3000, false, () => game.reset());
+     *   }
+   * }
+   *
+     * game.reset(new GameOverScene());
      * ```
      */
-    reset() {
-        this._sprites = [];
-        this._timers = [];
-        this._animations = [];
-        this._textOverlays = [];
-        this._keysPressed.clear();
-        this._mousePressed = false;
-        for (const pointer of this._touchPointers.values()) {
-            pointer.pressed = false;
-        }
-        this._syncPrimaryPointer();
+    reset(scene) {
+        if (this._sceneLoad !== null) {
+            return;
+        }
+        if (!this._hasCompletedPreload) {
+            if (scene !== undefined) {
+                this._currentScene = scene;
+            }
+            // Boot builds the active scene once its images load, so a scene chosen
+            // now is only recorded. Before start(), a scene with images of its own
+            // waits for start() to load them.
+            if (this._preloadPromise !== null || this._currentScene?.onPreload) {
+                return;
+            }
+            this._resetNow();
+            return;
+        }
+        this._registerSceneAssets(scene ?? this._currentScene);
+        if (this._assetSystem.getQueuedAssetCount() === 0) {
+            this._resetNow(scene);
+            return;
+        }
+        this._beginSceneLoad(() => this._resetNow(scene));
+    }
+    /** @internal */
+    _resetNow(scene) {
+        if (scene !== undefined) {
+            this._currentScene = scene;
+        }
+        this._transitionSystem.clear();
+        this._backgroundSystem.clearAll();
+        this._spriteSystem.clearAll();
+        this._timerSystem.clearAll();
+        this._animationSystem.clearAll();
+        this._explosionSystem.clearAll();
+        this._trailSystem.clearAll();
+        this._textSystem.clear();
+        this._inputSystem.resetPressedState();
+        this._buildersByTag.clear();
+        this._moduleBuilders.clear();
         this.scrollX = 0;
         this.scrollY = 0;
-        this._invokeCreate();
+        this._loopSystem.invokeCreate();
+    }
+    /**
+     * Changes to a new scene using a full-screen transition between frozen scene
+     * snapshots.
+     *
+     * `transitionTo()` does not change the behavior of {@link Game.reset}. It
+     * captures the current scene as a snapshot, rebuilds the target scene
+     * immediately, captures the new scene as another snapshot, and then animates
+     * between those two images for the requested duration.
+     *
+     * While the transition is active, gameplay updates are paused.
+     *
+     * If the target scene's {@link IScene.onPreload} registers images that are
+     * not loaded yet, the current scene first freezes and dims under a progress ring
+     * until they load, and the transition plays after that. `transitionTo()`
+     * then returns before the target scene exists; continue in its
+     * `onCreate()` or in `onComplete`. If the player declines to retry failed
+     * images, the game stays on the current scene and `onComplete` is not
+     * called.
+     *
+     * A call made while a transition plays or a scene loads is ignored.
+     *
+     * If the game loop is not running yet, this falls back to
+     * {@link Game.reset}.
+     *
+     * @param scene - Target scene to make active.
+     * @param options - Transition style and optional tuning values.
+     * @param onComplete - Optional callback invoked when the transition finishes.
+     */
+    transitionTo(scene, options, onComplete) {
+        if (!this._loopSystem.isRunning || !this._hasCompletedPreload) {
+            this.reset(scene);
+            onComplete?.();
+            return;
+        }
+        if (this._transitionSystem.isActive || this._sceneLoad !== null) {
+            return;
+        }
+        this._registerSceneAssets(scene);
+        if (this._assetSystem.getQueuedAssetCount() === 0) {
+            this._transitionNow(scene, options, onComplete);
+            return;
+        }
+        this._beginSceneLoad(() => this._transitionNow(scene, options, onComplete));
+    }
+    /** @internal */
+    _transitionNow(scene, options, onComplete) {
+        const fromCanvas = this._captureFrameSnapshot();
+        this._resetNow(scene);
+        const toCanvas = this._captureFrameSnapshot();
+        this._transitionSystem.start(fromCanvas, toCanvas, this.width, this.height, options, onComplete);
     }
     // -------------------------------------------------------------------------
     // Loop control
@@ -1454,483 +3228,404 @@ export class Game {
     /**
      * 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:
+     * On the first start, MinimoJS runs {@link Game.onPreload} and the active
+     * scene's {@link IScene.onPreload}, loads the images they queued while
+     * showing a thin loading line, and waits for all fonts registered via
+     * {@link Game.requireFont}. After that, the active scene's `onCreate()` is
+     * called before the first frame.
+     *
+     * The loop calls the active scene's `onUpdate(dt)` (or legacy
+     * {@link Game.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.
+     * 3. Advance active piece and wipe effects.
+     * 4. Apply gravity to sprite velocities.
+     * 5. Apply velocities to sprite positions.
+     * 6. Call `onUpdate(dt)`.
+     * 7. Advance active trail effects.
+     * 8. Render sprites/effects (with scroll offset).
+     * 9. Render text overlays (screen space, on top of sprites).
+     * 10. Clear per-frame input state.
      *
      * @example
      * ```ts
-     * game.onUpdate = (dt) => { ... };
-     * game.start();
+     * class DemoScene {
+     *   onCreate() {}
+     *   onUpdate(dt: number) {}
+     * }
+     *
+     * game.start(new DemoScene());
      * ```
      */
-    start() {
-        if (this._running)
+    start(scene) {
+        if (scene !== undefined) {
+            this._currentScene = scene;
+        }
+        this.applyGlobalFontRequirements();
+        if (this._hasCompletedPreload) {
+            this._loopSystem.start();
             return;
-        if (!this._hasCreated)
-            this._invokeCreate();
-        this._running = true;
-        this._lastTimestamp = null;
-        this._rafId = requestAnimationFrame(this._loop.bind(this));
+        }
+        if (this._preloadPromise !== null) {
+            return;
+        }
+        if (this.onPreload !== null) {
+            this._isRegisteringPreloadAssets = true;
+            try {
+                this.onPreload();
+            }
+            finally {
+                this._isRegisteringPreloadAssets = false;
+            }
+        }
+        const preloadPromise = Promise.all([
+            this._loadBootImages(),
+            this.waitForDocumentFonts(),
+        ]).then(([loaded]) => {
+            if (this._preloadPromise !== preloadPromise)
+                return;
+            this._preloadPromise = null;
+            if (!loaded)
+                return;
+            this._hasCompletedPreload = true;
+            this._loopSystem.start();
+        });
+        this._preloadPromise = preloadPromise;
+        preloadPromise.catch((error) => {
+            if (this._preloadPromise === preloadPromise) {
+                this._preloadPromise = null;
+            }
+            throw error;
+        });
+    }
+    /**
+     * Loads the boot images, then those of any scene made active while they
+     * loaded, retrying failures while the player agrees. Resolves `false` when
+     * the player declines, which leaves the game on the loading screen.
+     *
+     * @internal
+     */
+    async _loadBootImages() {
+        let registeredScene = undefined;
+        for (;;) {
+            if (registeredScene !== this._currentScene) {
+                registeredScene = this._currentScene;
+                this._registerSceneAssets(registeredScene);
+            }
+            const failed = await this._assetSystem.loadQueuedAssets((settled, total) => {
+                if (total > 0)
+                    this._renderLoadingScreen(settled / total);
+            });
+            if (failed.length > 0) {
+                this._reportFailedAssets(failed);
+                if (!this._confirmAssetRetry(failed.length)) {
+                    this._assetSystem.discardQueuedAssets();
+                    return false;
+                }
+                continue;
+            }
+            if (registeredScene === this._currentScene) {
+                return true;
+            }
+        }
     }
     /**
      * 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;
+        this._loopSystem.stop();
     }
     // -------------------------------------------------------------------------
-    // Private — input binding
+    // Private — rendering
     // -------------------------------------------------------------------------
-    /** @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 = (clientX, clientY) => {
-            const rect = this._canvas.getBoundingClientRect();
-            const scaleX = this._canvas.width / rect.width;
-            const scaleY = this._canvas.height / rect.height;
-            return {
-                x: (clientX - rect.left) * scaleX,
-                y: (clientY - rect.top) * scaleY,
-            };
-        };
-        this._canvas.addEventListener("mousedown", (e) => {
-            const p = getCanvasPoint(e.clientX, e.clientY);
-            this._mouseX = p.x;
-            this._mouseY = p.y;
-            this._mouseDown = true;
-            this._mousePressed = true;
-            this._syncPrimaryPointer();
-        });
-        this._canvas.addEventListener("mouseup", () => {
-            this._mouseDown = false;
-            this._syncPrimaryPointer();
-        });
-        this._canvas.addEventListener("mousemove", (e) => {
-            const p = getCanvasPoint(e.clientX, e.clientY);
-            this._mouseX = p.x;
-            this._mouseY = p.y;
-            this._syncPrimaryPointer();
-        });
-        this._canvas.addEventListener("touchstart", (e) => {
-            for (const touch of Array.from(e.changedTouches)) {
-                const p = getCanvasPoint(touch.clientX, touch.clientY);
-                this._touchPointers.set(touch.identifier, {
-                    x: p.x,
-                    y: p.y,
-                    pressed: true,
-                });
-                if (this._primaryTouchId === null) {
-                    this._primaryTouchId = touch.identifier;
-                }
-            }
-            this._syncPrimaryPointer();
-            e.preventDefault();
-        }, { passive: false });
-        this._canvas.addEventListener("touchend", (e) => {
-            for (const touch of Array.from(e.changedTouches)) {
-                this._touchPointers.delete(touch.identifier);
-                if (this._primaryTouchId === touch.identifier) {
-                    this._primaryTouchId = null;
-                }
-            }
-            this._syncPrimaryPointer();
-            e.preventDefault();
-        }, { passive: false });
-        this._canvas.addEventListener("touchcancel", (e) => {
-            for (const touch of Array.from(e.changedTouches)) {
-                this._touchPointers.delete(touch.identifier);
-                if (this._primaryTouchId === touch.identifier) {
-                    this._primaryTouchId = null;
-                }
+    /** @internal */ _onLoopFrameCallback(dt, dtMs) {
+        this._renderSystem.beginDynamicSurfacePass();
+        if (this._sceneLoad !== null) {
+            this._renderInterruption();
+            return;
+        }
+        if (this._transitionSystem.isActive) {
+            this._transitionSystem.update(dtMs);
+            if (this._transitionSystem.isActive) {
+                this._renderTransition();
             }
-            this._syncPrimaryPointer();
-            e.preventDefault();
-        }, { passive: false });
-        this._canvas.addEventListener("touchmove", (e) => {
-            for (const touch of Array.from(e.changedTouches)) {
-                const p = getCanvasPoint(touch.clientX, touch.clientY);
-                const existing = this._touchPointers.get(touch.identifier);
-                if (existing) {
-                    existing.x = p.x;
-                    existing.y = p.y;
-                }
-                else {
-                    this._touchPointers.set(touch.identifier, {
-                        x: p.x,
-                        y: p.y,
-                        pressed: false,
-                    });
-                }
+            else {
+                this._render();
             }
-            this._syncPrimaryPointer();
-            e.preventDefault();
-        }, { passive: false });
+            this._inputSystem.clearFramePressedState();
+            this._textSystem.clear();
+            return;
+        }
+        this._timerSystem.update(dtMs);
+        if (this._isSceneChangeInterrupting()) {
+            this._renderInterruption();
+            return;
+        }
+        this._animationSystem.update(dtMs);
+        this._explosionSystem.update(dt, dtMs);
+        this._physicsSystem.update(this._spriteSystem.getMutableSprites(), dt);
+        if (this._isSceneChangeInterrupting()) {
+            this._renderInterruption();
+            return;
+        }
+        if (this._currentScene?.onUpdate)
+            this._currentScene.onUpdate(dt);
+        else if (this.onUpdate)
+            this.onUpdate(dt);
+        if (this._isSceneChangeInterrupting()) {
+            this._renderInterruption();
+            return;
+        }
+        this._trailSystem.update(dtMs, this._renderSystem.getSpriteRenderSnapshot.bind(this._renderSystem));
+        this._render();
+        this._inputSystem.clearFramePressedState();
+        this._textSystem.clear();
     }
     /** @internal */
-    _isScreenPointOverSprite(x, y, sprite, radiusScale) {
-        const safeScale = Math.max(0, radiusScale);
-        const radius = sprite.displaySize * safeScale;
-        const drawX = sprite.ignoreScroll ? sprite.x : sprite.x - this.scrollX;
-        const drawY = sprite.ignoreScroll ? sprite.y : sprite.y - this.scrollY;
-        const dx = x - drawX;
-        const dy = y - drawY;
-        return dx * dx + dy * dy <= radius * radius;
+    _isSceneChangeInterrupting() {
+        return this._transitionSystem.isActive || this._sceneLoad !== null;
     }
-    /** @internal */
-    _collectPointers() {
-        const pointers = [];
-        if (this._mouseDown) {
-            pointers.push({
-                id: "mouse",
-                kind: "mouse",
-                x: this._mouseX,
-                y: this._mouseY,
-                pressed: this._mousePressed,
+    /**
+     * Draws a frame in which gameplay does not advance: a loading scene under
+     * its ring, or a transition.
+     *
+     * @internal
+     */
+    _renderInterruption() {
+        const load = this._sceneLoad;
+        if (load !== null) {
+            this._renderSystem.renderSceneLoading({
+                canvas: this._canvas,
+                context: this._ctx,
+                pageBackground: this.pageBackground,
+                snapshot: load.snapshot,
+                progress: load.progress,
+                reveal: (performance.now() - load.startedAt - SCENE_LOADING_INDICATOR_DELAY_MS) /
+                    SCENE_LOADING_FADE_MS,
+                ink: load.ink,
             });
         }
-        for (const [id, pointer] of this._touchPointers.entries()) {
-            pointers.push({
-                id,
-                kind: "touch",
-                x: pointer.x,
-                y: pointer.y,
-                pressed: pointer.pressed,
-            });
+        else {
+            this._renderTransition();
         }
-        return pointers;
+        this._inputSystem.clearFramePressedState();
+        this._textSystem.clear();
     }
-    /** @internal */
-    _syncPrimaryPointer() {
-        if (this._primaryTouchId !== null) {
-            const primaryTouch = this._touchPointers.get(this._primaryTouchId);
-            if (primaryTouch) {
-                this._pointerX = primaryTouch.x;
-                this._pointerY = primaryTouch.y;
-                this._pointerDown = true;
-                this._pointerPressed = primaryTouch.pressed;
-                return;
-            }
-            this._primaryTouchId = null;
-        }
-        if (this._touchPointers.size > 0) {
-            const firstTouchEntry = this._touchPointers.entries().next().value;
-            if (firstTouchEntry) {
-                const [touchId, touch] = firstTouchEntry;
-                this._primaryTouchId = touchId;
-                this._pointerX = touch.x;
-                this._pointerY = touch.y;
-                this._pointerDown = true;
-                this._pointerPressed = touch.pressed;
-                return;
-            }
+    /**
+     * Runs a scene's `onPreload()`, if it has one, with image registration
+     * allowed.
+     *
+     * @internal
+     */
+    _registerSceneAssets(scene) {
+        if (!scene?.onPreload)
+            return;
+        this._isRegisteringPreloadAssets = true;
+        try {
+            scene.onPreload();
         }
-        this._primaryTouchId = null;
-        this._pointerX = this._mouseX;
-        this._pointerY = this._mouseY;
-        this._pointerDown = this._mouseDown;
-        this._pointerPressed = this._mousePressed;
-    }
-    /** @internal */
-    _assertPhysicsEnabled() {
-        if (!this.physics) {
-            throw new Error("MinimoJS: collide() and collideAny() require game.physics = true.");
+        finally {
+            this._isRegisteringPreloadAssets = false;
         }
     }
-    /** @internal */
-    _getCollisionResolution(a, b) {
-        const halfA = a.displaySize / 2;
-        const halfB = b.displaySize / 2;
-        const dx = b.x - a.x;
-        const dy = b.y - a.y;
-        const overlapX = halfA + halfB - Math.abs(dx);
-        const overlapY = halfA + halfB - Math.abs(dy);
-        if (overlapX <= 0 || overlapY <= 0) {
-            return null;
-        }
-        let axis;
-        if (overlapX < overlapY) {
-            axis = "x";
-        }
-        else if (overlapY < overlapX) {
-            axis = "y";
-        }
-        else {
-            const relVX = Math.abs(a.vx - b.vx);
-            const relVY = Math.abs(a.vy - b.vy);
-            axis = relVX > relVY ? "x" : "y";
-        }
-        const info = {
-            left: false,
-            right: false,
-            top: false,
-            bottom: false,
-            grounded: false,
-        };
-        if (axis === "x") {
-            if (dx >= 0) {
-                info.right = true;
-                return {
-                    info,
-                    axis,
-                    separationX: -overlapX,
-                    separationY: 0,
-                };
-            }
-            info.left = true;
-            return {
-                info,
-                axis,
-                separationX: overlapX,
-                separationY: 0,
-            };
-        }
-        if (dy >= 0) {
-            info.bottom = true;
-            info.grounded = true;
-            return {
-                info,
-                axis,
-                separationX: 0,
-                separationY: -overlapY,
-            };
-        }
-        info.top = true;
-        return {
-            info,
-            axis,
-            separationX: 0,
-            separationY: overlapY,
+    /**
+     * Freezes the current scene under a progress ring while the queued images
+     * load, then calls `finish` to enter the next scene. If images fail and the
+     * player declines to retry, the current scene resumes instead.
+     *
+     * @internal
+     */
+    _beginSceneLoad(finish) {
+        this._transitionSystem.clear();
+        const snapshot = document.createElement("canvas");
+        snapshot.width = this._canvas.width;
+        snapshot.height = this._canvas.height;
+        snapshot.getContext("2d")?.drawImage(this._canvas, 0, 0);
+        const load = {
+            snapshot,
+            ink: this._renderSystem.pickSceneLoadingInk(snapshot),
+            progress: 0,
+            startedAt: performance.now(),
         };
+        this._sceneLoad = load;
+        void this._loadSceneImages(load, finish);
     }
-    // -------------------------------------------------------------------------
-    // 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._mousePressed = false;
-        for (const pointer of this._touchPointers.values()) {
-            pointer.pressed = false;
+    async _loadSceneImages(load, finish) {
+        for (;;) {
+            const failed = await this._assetSystem.loadQueuedAssets((settled, total) => {
+                load.progress = total === 0 ? 1 : settled / total;
+            });
+            if (failed.length === 0)
+                break;
+            this._reportFailedAssets(failed);
+            if (!this._confirmAssetRetry(failed.length)) {
+                this._assetSystem.discardQueuedAssets();
+                this._sceneLoad = null;
+                return;
+            }
+            load.progress = 0;
         }
-        this._syncPrimaryPointer();
-        this._textOverlays = [];
-        this._rafId = requestAnimationFrame(this._loop.bind(this));
+        this._sceneLoad = null;
+        finish();
     }
     /** @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);
-                }
-            }
+    _reportFailedAssets(keys) {
+        const list = keys
+            .map((key) => `"${key}" (${this._assetSystem.getAssetSource(key) ?? "no source"})`)
+            .join(", ");
+        console.error(`MinimoJS: ${keys.length} file${keys.length === 1 ? "" : "s"} failed to load: ${list}.`);
+    }
+    /**
+     * Asks the player whether to retry failed images and sounds, with the browser's own
+     * confirmation dialog. Returns `false` where no dialog can be shown.
+     *
+     * @internal
+     */
+    _confirmAssetRetry(failedCount) {
+        if (typeof window === "undefined" || typeof window.confirm !== "function") {
+            return false;
         }
-        if (toRemove.length > 0) {
-            this._timers = this._timers.filter((t) => !toRemove.includes(t.id));
+        const noun = failedCount === 1 ? "file" : "files";
+        try {
+            return window.confirm(`${failedCount} ${noun} could not be loaded. Try again?`);
         }
-        for (const timer of toFire) {
-            timer.callback();
+        catch {
+            return false;
         }
     }
     /** @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);
-        }
+    _invokeCreate() {
+        if (this._currentScene?.onCreate)
+            this._currentScene.onCreate();
+        else
+            this._onCreate?.();
     }
     /** @internal */
-    _updatePhysics(dt) {
-        for (const sprite of this._sprites) {
-            if (sprite.isStatic) {
-                continue;
-            }
-            if (sprite.gravityScale !== 0) {
-                sprite.vx += this.gravityX * sprite.gravityScale * dt;
-                sprite.vy += this.gravityY * sprite.gravityScale * dt;
+    waitForDocumentFonts() {
+        if (typeof document === "undefined") {
+            return Promise.resolve();
+        }
+        const fontSet = document.fonts;
+        if (!fontSet || typeof fontSet.ready?.then !== "function") {
+            return Promise.resolve();
+        }
+        const fontLoads = [];
+        if (typeof fontSet.load === "function") {
+            for (const requirement of this._requiredFonts.values()) {
+                const descriptor = `${requirement.style} ${requirement.weight} ${requirement.size}px ${requirement.family}`;
+                fontLoads.push(fontSet.load(descriptor, requirement.sampleText).catch(() => []));
             }
-            sprite.x += sprite.vx * dt;
-            sprite.y += sprite.vy * dt;
         }
-    }
-    // -------------------------------------------------------------------------
-    // Private — rendering
-    // -------------------------------------------------------------------------
-    /** @internal */
-    _getSpriteGlyphCanvas(sprite) {
-        const size = Math.max(1, Math.round(sprite.size));
-        const color = sprite.color;
-        const cacheKey = `${sprite.sprite}::${size}::${color}`;
-        const cached = this._spriteGlyphCache.get(cacheKey);
-        if (cached)
-            return cached;
-        const glyphCanvas = document.createElement("canvas");
-        const boxSize = Math.max(2, Math.ceil(size * 2));
-        glyphCanvas.width = boxSize;
-        glyphCanvas.height = boxSize;
-        const glyphCtx = glyphCanvas.getContext("2d");
-        if (!glyphCtx) {
-            throw new Error("MinimoJS: Could not acquire a glyph rendering context.");
-        }
-        glyphCtx.clearRect(0, 0, boxSize, boxSize);
-        glyphCtx.shadowColor = "transparent";
-        glyphCtx.shadowBlur = 0;
-        glyphCtx.shadowOffsetX = 0;
-        glyphCtx.shadowOffsetY = 0;
-        glyphCtx.fillStyle = color;
-        glyphCtx.font = `${size}px "Apple Color Emoji", "Segoe UI Emoji", "Noto Color Emoji", sans-serif`;
-        glyphCtx.textAlign = "center";
-        glyphCtx.textBaseline = "middle";
-        glyphCtx.fillText(sprite.sprite, boxSize / 2, boxSize / 2);
-        this._spriteGlyphCache.set(cacheKey, glyphCanvas);
-        return glyphCanvas;
+        fontLoads.push(fontSet.ready);
+        return Promise.all(fontLoads).then(() => undefined);
     }
     /** @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)
+    applyGlobalFontRequirements() {
+        if (this._hasAppliedGlobalFontRequirements) {
+            return;
+        }
+        this._hasAppliedGlobalFontRequirements = true;
+        const root = globalThis;
+        const requirements = root.__MINIMO_WEB_FONT_REQUIREMENTS__;
+        if (!Array.isArray(requirements)) {
+            return;
+        }
+        for (const entry of requirements) {
+            if (!entry || typeof entry !== "object") {
                 continue;
-            ctx.save();
-            ctx.globalAlpha = Math.max(0, Math.min(1, sprite.alpha));
-            const drawX = Math.round(sprite.ignoreScroll ? sprite.x : sprite.x - this.scrollX);
-            const drawY = Math.round(sprite.ignoreScroll ? sprite.y : sprite.y - this.scrollY);
-            ctx.translate(drawX, drawY);
-            if (sprite.rotation !== 0) {
-                ctx.rotate((sprite.rotation * Math.PI) / 180);
             }
-            const safeRenderScale = Number.isFinite(sprite.scale)
-                ? Math.max(0, sprite.scale)
-                : 1;
-            if (sprite.flipX || sprite.flipY || safeRenderScale !== 1) {
-                ctx.scale((sprite.flipX ? -1 : 1) * safeRenderScale, (sprite.flipY ? -1 : 1) * safeRenderScale);
+            const requirement = entry;
+            const family = typeof requirement.family === "string" ? requirement.family.trim() : "";
+            if (!family) {
+                continue;
             }
-            ctx.shadowColor = "transparent";
-            ctx.shadowBlur = 0;
-            ctx.shadowOffsetX = 0;
-            ctx.shadowOffsetY = 0;
-            const glyphCanvas = this._getSpriteGlyphCanvas(sprite);
-            ctx.drawImage(glyphCanvas, -glyphCanvas.width / 2, -glyphCanvas.height / 2);
-            ctx.restore();
-        }
-        for (const entry of this._textOverlays) {
-            ctx.save();
-            ctx.font = `${entry.fontSize}px "Press Start 2P", 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();
+            const sampleText = typeof requirement.sample_text === "string"
+                ? requirement.sample_text
+                : typeof requirement.sampleText === "string"
+                    ? requirement.sampleText
+                    : "";
+            this.requireFont(`"${family}"`, {
+                weight: typeof requirement.weight === "string" && requirement.weight.trim()
+                    ? requirement.weight.trim()
+                    : undefined,
+                style: requirement.style === "normal" ||
+                    requirement.style === "italic" ||
+                    requirement.style === "oblique"
+                    ? requirement.style
+                    : undefined,
+                size: typeof requirement.size === "number" && Number.isFinite(requirement.size)
+                    ? requirement.size
+                    : undefined,
+                sampleText,
+            });
         }
     }
-    /** @internal */
-    _applyPageBackground() {
-        if (!document.body)
-            return;
-        if (this._lastAppliedPageBackground === this.pageBackground)
+    /** @internal */ _render() {
+        this._renderSystem.render({
+            canvas: this._canvas,
+            context: this._ctx,
+            backgroundLayers: this._backgroundSystem.getMutableLayers(),
+            resolveImage: this._assetSystem.getImage.bind(this._assetSystem),
+            sprites: this._spriteSystem.getMutableSprites(),
+            trails: this._trailSystem.getRenderEntries(),
+            explosions: this._explosionSystem.getRenderEntries(),
+            wipes: this._explosionSystem.getWipeEntries(),
+            textEntries: this._textSystem.getEntries(),
+            scrollX: this.scrollX,
+            scrollY: this.scrollY,
+            background: this.background,
+            backgroundGradient: this.backgroundGradient,
+            pageBackground: this.pageBackground,
+            debugBodies: this.debugBodies,
+            debugInputAreas: this.debugInputAreas,
+        });
+    }
+    /** @internal */ _renderTransition() {
+        const transition = this._transitionSystem.getRenderEntry();
+        if (!transition) {
+            this._render();
             return;
-        if (this.pageBackground === null) {
-            document.body.style.removeProperty("background");
         }
-        else {
-            document.body.style.background = this.pageBackground;
-        }
-        this._lastAppliedPageBackground = this.pageBackground;
+        this._renderSystem.renderScreenTransition({
+            canvas: this._canvas,
+            context: this._ctx,
+            pageBackground: this.pageBackground,
+            transition,
+        });
     }
-    /** @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 */ _captureFrameSnapshot() {
+        this._renderSystem.beginDynamicSurfacePass();
+        return this._renderSystem.captureFrame({
+            canvas: this._canvas,
+            context: this._ctx,
+            backgroundLayers: this._backgroundSystem.getMutableLayers(),
+            resolveImage: this._assetSystem.getImage.bind(this._assetSystem),
+            sprites: this._spriteSystem.getMutableSprites(),
+            trails: this._trailSystem.getRenderEntries(),
+            explosions: this._explosionSystem.getRenderEntries(),
+            wipes: this._explosionSystem.getWipeEntries(),
+            textEntries: this._textSystem.getEntries(),
+            scrollX: this.scrollX,
+            scrollY: this.scrollY,
+            background: this.background,
+            backgroundGradient: this.backgroundGradient,
+            pageBackground: this.pageBackground,
+            debugBodies: this.debugBodies,
+            debugInputAreas: this.debugInputAreas,
+        });
     }
     /** @internal */
-    _invokeCreate() {
-        this._hasCreated = true;
-        if (this.onCreate)
-            this.onCreate();
+    _renderLoadingScreen(progress) {
+        this._renderSystem.renderLoadingScreen({
+            canvas: this._canvas,
+            context: this._ctx,
+            pageBackground: this.pageBackground,
+            background: this.background,
+            backgroundGradient: this.backgroundGradient,
+            progress,
+        });
     }
 }