@waica/engine 0.16.0 → 0.18.0

package/README.md

@@ -193,3 +193,56 @@ game.time.now  // seconds of Game Time since the Game started
 - **Step placement.** At the start of every Simulation Step, before the Component Update Schedule, `game.time` advances `now`, runs every due timer (due time, then creation order), then advances every tween that existed before that step (creation order). Work a callback creates is never run or advanced in that same step.
 - **Scope.** A timer or tween is scene-scoped by default: `unloadScene()` and every scene load — including a Game's first — cancel it, running no callback. `{ scope: 'session' }` survives a scene change. `{ owner: entity }` cancels it immediately when that entity is destroyed, whatever its scope; an owner already dead at scheduling time yields an inactive handle. `game.dispose()` cancels everything in both scopes. This is the opposite default from `game.onUpdate`/`game.events` (ADR 0011), which survive a scene change by construction, and the same one `game.audio.play()` uses (ADR 0012) — see ADR 0017 for why timers follow audio's rule rather than the host-subscription one: a timer's callback almost always closes over the scene that scheduled it.
 - **No Promises.** Nothing here returns one, and nothing is async — a `.then` continuation is not step-exact (it runs after the whole synchronous frame), which is exactly what `game.time` exists to avoid. Compose delays with `after`, not `await`.
+
+## game.ui.attach: Anchored Pieces
+
+A UI Piece shown with `game.ui.show(name)` is a screen-space singleton. `game.ui.attach(piece, entity, options?)` instead creates an **Anchored Piece**: a new instance of the piece that follows `entity` across the screen, with its own shadow root and its own values. Every call is a new instance — five orcs can each carry a `health-bar` — and the screen piece of the same name is never mounted, shown or changed by it.
+
+```ts
+const hit = game.ui.attach('damage-number', orc, { offset: [0, 1.2], seconds: 0.8, values: { amount: 3 } })
+const bar = game.ui.attach('health-bar', orc, { offset: [0, 1.4], values: { current: 7, max: 10 } })
+bar.set('current', 6) // {{current}} and --current update live
+bar.remove()
+```
+
+```html
+<style>
+  .bar { position: absolute; transform: translate(-50%, -100%); width: calc(1.2 * var(--waica-unit)); height: 4px; background: #0008 }
+  .fill { width: calc(var(--current) / var(--max) * 100%); height: 100%; background: #ef476f }
+</style>
+<div class="bar"><div class="fill"></div></div>
+```
+
+- **Options.** `offset: [x, y]` (default `[0, 0]`) is in world units, added to the entity's render point in render space: `[0, 1]` is one unit up on screen, under `projection: 'isometric'` too. `seconds` gives the instance its own lifetime (below). `values` are the instance's own values.
+- **Handle.** `set(name, value)`, `remove()`, `alive` and `element` — the piece's content root inside the instance's shadow root, `null` once removed.
+- **Placement.** Once per render frame — after the isometric projection and the camera step, before the render, never per Simulation Step — each instance's shadow host is placed as a zero-size box at its anchor point, converted to whole CSS pixels from the top-left corner of the game viewport; the piece's own CSS centres itself around that point (e.g. `transform: translate(-50%, -100%)`). A move therefore shows on the next frame, not before. All instances live in one layer fitted to the game viewport — the whole canvas, or the letterboxed rectangle under a fixed `resolution` — with `overflow: hidden`, so they never draw over the letterbox bars.
+- **Per-instance values.** Inside an instance, `{{name}}` renders the instance's own value when it has one and the Game stat of that name otherwise (booleans as ✓/✕, missing as empty); `set` updates it in place, and a stat change still updates every placeholder with no instance value. Every number value is also published as the custom property `--name` on the instance (`values: { current: 7, max: 10 }` gives `--current: 7` and `--max: 10`), booleans as `1`/`0`; strings are text only. There are no binding expressions: arithmetic belongs in CSS `calc()`.
+- **`--waica-unit`.** Every frame, the anchored layer carries `--waica-unit` inline, and every instance inherits it through its shadow host: CSS pixels per world unit, the game viewport's CSS height divided by the current view height. It follows camera zoom and the letterbox scale, so `calc(1.1 * var(--waica-unit))` sizes a piece in world units while everything else keeps its CSS pixel size.
+- **Draw order.** The anchored layer sits below every screen-space piece. Within it, every frame, the instance lower on screen draws on top, like y-sort; equal heights keep creation order, later on top.
+- **Lifetime.** Without `seconds`, an instance is removed before its entity's `destroy()` returns. With `seconds: S`, it is removed exactly when a `game.time.after(S, …)` scheduled at the same moment would fire — it counts Game Time (ADR 0017), so it never runs out while the Game is paused or not simulating, and until then it counts in `game.time.pending`. If its entity is destroyed first, it lingers frozen where the entity was at `destroy()` time (still moving with the camera) until it expires. `unloadScene()`, every scene load that unloads and `game.dispose()` remove every instance: none outlives its scene. `remove()` is immediate; `set` and `remove` on a removed handle are silent no-ops. CSS animations and transitions inside an instance follow Game Time, not the wall clock: every frame each is paused at the Game Time since it started (the attach, for those the piece starts with), so a paused Game freezes a damage number mid-flight — it resumes from there, even after the overlay hid while not simulating — and `step { frames: N }` advances it by N/60 s.
+- **Invalid attach never throws.** An undefined piece name logs one `[waica]` warning per name per Game; an entity that is no longer `alive` logs one per call. Both return a handle with `alive: false` and `element: null` that mounts nothing. To attach only when the project defines the piece, as `Interactable` does with `npc-bubble` and `interact-prompt`, check `game.ui.has(name)` first.
+- **Runtime Snapshot.** Every snapshot carries `ui: { shown, anchored }`: the visible screen pieces by name, and each live instance in creation order as `{ piece, entity, x, y, clipped, values }`, with the pixel coordinates of its last placement; `values` are bounded like component state (a string over 4 KiB becomes a `$waica: 'truncated'` marker), and once every entity is cut the 1 MiB snapshot cap drops instances from the end.
+
+The trade-off is ADR 0018's: Anchored Pieces are HTML drawn over the game view, not text rendered in the three scene. They always draw above the world — a label behind a tree draws over it — hide with the rest of the UI overlay while the Game is not simulating (including the editor's edit mode), and do not align to a pixel-art grid.
+
+## game.assets: textures, preload and Assets Ready
+
+Every `Game` owns an `assets: AssetLoader` — the engine's texture cache. `Sprite`, `AnimatedSprite` and `Tilemap` load through it: one fetch and one base texture per URL for the whole life of the Game, and every component gets its own clone of that base (three shares the GPU upload between clones with equal sampler parameters and reference-counts their disposal), so eight crates cost one image. A scene load never waits for images — `loadScene` stays synchronous — and **Assets Ready** is a promise beside it (ADR 0019):
+
+```ts
+game.registerSceneCatalog({ scenes, registry })
+game.loadSceneByName('main')
+await game.assets.ready() // every texture requested so far has loaded, or failed and been recorded
+game.start()
+
+await game.assets.preload(['waica:iso-crate', 'src/art/tree.png']) // ahead of a later scene
+game.assets.status // { pending, loaded, failed } — a fresh object on every read
+```
+
+- **Cache rule.** Keyed by the URL as received: components pass what `resolveProps` resolved, `preload` resolves each uri through the registered scene catalog first (identity before `registerSceneCatalog`, and for a uri the resolver leaves unchanged). N requests of one URL call the backend once; `status.loaded` counts URLs, not requests. Keep-all: `unloadScene()`, `loadScene` and `loadSceneByName` never dispose, evict or reset an entry — `main → cave → main` re-downloads nothing — and only `game.dispose()` disposes every cached base, exactly once, leaving `status` at zeros. Components dispose only their own clone.
+- **`ready()`.** Resolves the first time `pending` is 0 after the call: at once when nothing is pending, otherwise once every URL requested before or while waiting has settled. Readiness is relative to the moment it is awaited — a later spawn that requests new art reopens it until that art settles — and concurrent callers all resolve. It never rejects, and it has no timeout: a stalled image with no error event holds a host that awaits it (a Run Session is bounded by the MCP's session timeout instead).
+- **`preload(uris)`.** Requests every uri and resolves once all of them settled, failures included. A component that later asks for the same resolved URL is a cache hit.
+- **`status`.** `pending` is current; `loaded` and `failed` are cumulative for the Game and only grow until `dispose()`. A host that wants a loading bar reads it from `game.onUpdate`.
+- **Failure rule.** A texture that fails to load is recorded, not thrown: `console.warn('[waica] assets: failed to load "<url>"', error)` once per Game per URL, `failed` counts it, `ready()` resolves, and every consumer falls back to its flat material — `Sprite` and `Tilemap` drop the failed map, dispose their clone and render their `color` again; `AnimatedSprite` never installs the failed sheet's clone, so that sheet's frames show a plain white quad. Asking for that URL again on the same Game is a cached failure — no retry, no second warning.
+- **`GameOptions.textures`.** Replaces the real `THREE.TextureLoader` backend for that Game (ADR 0013's seam, applied to textures): `happy-dom` decodes no images, so a project's own tests inject a backend that resolves at once. The Runtime Bridge reports `assets` in its metadata under the `'assets'` capability, and a Run Session waits for `pending === 0` at readiness, after a `scene` operation and before every screenshot.
+

package/dist/anchored-pieces.d.ts

@@ -0,0 +1,122 @@
+import type { Entity } from './entity.js';
+import type { PointerCamera, PointerResolution } from './pointer.js';
+import type { RuntimeSnapshotUi } from './runtime-inspection.js';
+import type { Stats, StatValue } from './stats.js';
+/** Options for `game.ui.attach` (issue #72). */
+export interface AttachOptions {
+    /**
+     * World units added to the entity's render point, in render space:
+     * `[0, 1]` is one unit up on screen, under isometric projection too.
+     * Default `[0, 0]`. Pixel fine-tuning belongs in the piece's CSS.
+     */
+    offset?: [number, number];
+    /**
+     * Seconds of Game Time the instance lives for (ADR 0017). It outlives its
+     * entity, frozen where the entity last was, until then. Absent: the
+     * instance dies with its entity.
+     */
+    seconds?: number;
+    /**
+     * The instance's own values: `{{name}}` reads these before the Game's
+     * stats, and every number (verbatim) or boolean (`1`/`0`) is also
+     * published as the custom property `--name` on the instance.
+     */
+    values?: Record<string, StatValue>;
+}
+/** One Anchored Piece, as `game.ui.attach` hands it back. */
+export interface AnchoredPieceHandle {
+    /** Sets one of the instance's own values: its `{{name}}` text and `--name` update in place. */
+    set(name: string, value: StatValue): void;
+    /** Removes the instance now. `set` and `remove` on a removed handle are silent no-ops. */
+    remove(): void;
+    /** False once removed, and from the start on an invalid attach. */
+    readonly alive: boolean;
+    /** The piece's content root inside the instance's own shadow root; null once removed. */
+    readonly element: HTMLElement | null;
+}
+/** A rectangle in CSS px, relative to the canvas's top-left corner. */
+export interface ViewportRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** What the Game tells the anchored layer each time it places: read live, never cached. */
+export interface AnchorView {
+    camera: PointerCamera;
+    /** The game viewport: see gameViewport. */
+    viewport: ViewportRect;
+    projection: 'isometric' | null;
+}
+/**
+ * The game viewport (issue #72): the rectangle the renderer draws into —
+ * the whole canvas without a fixed resolution, the largest centred rect
+ * with its aspect (letterbox) with one. The same math as Game.resize() and
+ * the Pointer's letterbox, whose screen→world mapping placement inverts.
+ */
+export declare function gameViewport(width: number, height: number, resolution: PointerResolution | null): ViewportRect;
+/** What GameUi lends the anchored layer: its catalog, the stats and its overlay. */
+export interface AnchoredPiecesDeps {
+    stats: Stats;
+    /** A piece's HTML source, or undefined when the piece was never defined. */
+    source(name: string): string | undefined;
+    /** GameUi's overlay, mounted on demand. */
+    overlay(): HTMLElement;
+}
+/**
+ * Anchored Pieces (issue #72, ADR 0018) — instances of a UI Piece, as many
+ * as needed, each following an entity in one layer of GameUi's overlay,
+ * each with its own shadow root and its own values ahead of the Game's stats.
+ * Owned by GameUi, which reaches it through `attach`; the Game drives the
+ * rest through `anchoredPiecesOf` (ui.ts): `connect` once, `place` every
+ * render frame.
+ */
+export declare class AnchoredPieces {
+    private readonly deps;
+    private readonly instances;
+    /** Undefined piece names already warned about: one warning per name per Game. */
+    private readonly warnedPieces;
+    private layer?;
+    private view;
+    constructor(deps: AnchoredPiecesDeps);
+    /** Called once by the Game: where the camera, viewport and projection are read from. */
+    connect(view: () => AnchorView): void;
+    attach(piece: string, entity: Entity, options?: AttachOptions): AnchoredPieceHandle;
+    /**
+     * Called by the Game before an entity's destroy() returns: its instances
+     * go with it, except those given `seconds`, which stay frozen at its
+     * current anchor point until they expire.
+     */
+    release(entity: Entity): void;
+    /**
+     * The live instances for the Runtime Snapshot, in creation order, with
+     * the coordinates of their last placement — or, for one attached since
+     * the last render frame, where the next frame will place it.
+     */
+    snapshot(): RuntimeSnapshotUi['anchored'];
+    /** Removes every instance, lingering ones too (GameUi.unloadScene). */
+    clear(): void;
+    /** Removes every instance and forgets the layer along with the overlay (GameUi.dispose). */
+    dispose(): void;
+    /**
+     * Called by the Game once per render frame, after the isometric pass and
+     * before the render (never per Simulation Step, never on attach): fits
+     * the layer to the game viewport, sets the frame's `--waica-unit` on it
+     * (every instance inherits it through its shadow host) and puts every
+     * instance's zero-size shadow host at its anchor point, its CSS
+     * animations set to Game Time (followGameTime).
+     */
+    place(): void;
+    private bind;
+    /** Writes a name's current value — the instance's own, else the Game stat — into its placeholders. */
+    private render;
+    private set;
+    private remove;
+    private handleFor;
+    /**
+     * The single layer every instance lives in, kept as the overlay's first
+     * child — even when a screen piece created the overlay first — so every
+     * screen-space piece draws above every anchored instance.
+     */
+    private mountLayer;
+}

package/dist/anchored-pieces.js

@@ -0,0 +1,330 @@
+import { projectIsometric } from './projection.js';
+import { placeholders, renderStat } from './ui-bindings.js';
+/**
+ * The game viewport (issue #72): the rectangle the renderer draws into —
+ * the whole canvas without a fixed resolution, the largest centred rect
+ * with its aspect (letterbox) with one. The same math as Game.resize() and
+ * the Pointer's letterbox, whose screen→world mapping placement inverts.
+ */
+export function gameViewport(width, height, resolution) {
+    if (!resolution)
+        return { x: 0, y: 0, width, height };
+    const aspect = resolution.width / resolution.height;
+    const vw = Math.min(width, height * aspect);
+    const vh = vw / aspect;
+    return { x: (width - vw) / 2, y: (height - vh) / 2, width: vw, height: vh };
+}
+/** The handle of an invalid attach (CA-7): nothing mounted, nothing to change. */
+const INERT_HANDLE = Object.freeze({
+    set() { },
+    remove() { },
+    alive: false,
+    element: null,
+});
+/** A GameUi no Game connected has no viewport: nothing it holds is ever placed. */
+const UNPLACED = { x: 0, y: 0, clipped: true, depth: 0 };
+/**
+ * Anchored Pieces (issue #72, ADR 0018) — instances of a UI Piece, as many
+ * as needed, each following an entity in one layer of GameUi's overlay,
+ * each with its own shadow root and its own values ahead of the Game's stats.
+ * Owned by GameUi, which reaches it through `attach`; the Game drives the
+ * rest through `anchoredPiecesOf` (ui.ts): `connect` once, `place` every
+ * render frame.
+ */
+export class AnchoredPieces {
+    deps;
+    instances = [];
+    /** Undefined piece names already warned about: one warning per name per Game. */
+    warnedPieces = new Set();
+    layer;
+    view = null;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** Called once by the Game: where the camera, viewport and projection are read from. */
+    connect(view) {
+        this.view = view;
+    }
+    attach(piece, entity, options = {}) {
+        const html = this.deps.source(piece);
+        if (html === undefined && !this.warnedPieces.has(piece)) {
+            this.warnedPieces.add(piece);
+            console.warn(`[waica] cannot attach unknown ui piece: "${piece}"`);
+        }
+        if (!entity.alive) {
+            console.warn(`[waica] cannot attach ui piece "${piece}" to destroyed entity "${entity.name}"`);
+        }
+        if (html === undefined || !entity.alive)
+            return INERT_HANDLE;
+        const host = document.createElement('div');
+        host.style.cssText = 'position:absolute;left:0;top:0;width:0;height:0;pointer-events:none';
+        const shadow = host.attachShadow({ mode: 'open' });
+        const root = document.createElement('div');
+        root.style.display = 'contents';
+        root.innerHTML = html;
+        shadow.append(root);
+        const offset = options.offset ?? [0, 0];
+        const instance = {
+            piece,
+            entity,
+            offset: [offset[0], offset[1]],
+            values: new Map(Object.entries(options.values ?? {})),
+            host,
+            root,
+            texts: new Map(),
+            unsubs: [],
+            born: entity.game.time.now,
+            clocks: new WeakMap(),
+            named: new WeakMap(),
+            expiry: null,
+            frozen: null,
+            placed: null,
+            alive: true,
+        };
+        this.bind(instance);
+        for (const [name, value] of instance.values)
+            publish(host, name, value);
+        this.mountLayer().append(host);
+        this.instances.push(instance);
+        if (options.seconds !== undefined) {
+            // Not owned by the entity: it must outlive it. Scene-scoped, like the
+            // instance itself. A duration game.time rejects (it warns) leaves the
+            // instance to die with its entity instead of lingering forever.
+            const expiry = entity.game.time.after(options.seconds, () => this.remove(instance));
+            instance.expiry = expiry.active ? expiry : null;
+        }
+        return this.handleFor(instance);
+    }
+    /**
+     * Called by the Game before an entity's destroy() returns: its instances
+     * go with it, except those given `seconds`, which stay frozen at its
+     * current anchor point until they expire.
+     */
+    release(entity) {
+        for (const instance of this.instances.filter((candidate) => candidate.entity === entity)) {
+            if (instance.expiry)
+                instance.frozen = anchorPoint(instance, this.view?.().projection ?? null);
+            else
+                this.remove(instance);
+        }
+    }
+    /**
+     * The live instances for the Runtime Snapshot, in creation order, with
+     * the coordinates of their last placement — or, for one attached since
+     * the last render frame, where the next frame will place it.
+     */
+    snapshot() {
+        return this.instances.map((instance) => {
+            const { x, y, clipped } = instance.placed ?? (this.view ? locate(instance, this.view()) : UNPLACED);
+            return {
+                piece: instance.piece,
+                entity: instance.entity.name,
+                x,
+                y,
+                clipped,
+                values: Object.fromEntries(instance.values),
+            };
+        });
+    }
+    /** Removes every instance, lingering ones too (GameUi.unloadScene). */
+    clear() {
+        for (const instance of [...this.instances])
+            this.remove(instance);
+    }
+    /** Removes every instance and forgets the layer along with the overlay (GameUi.dispose). */
+    dispose() {
+        this.clear();
+        this.layer = undefined;
+    }
+    /**
+     * Called by the Game once per render frame, after the isometric pass and
+     * before the render (never per Simulation Step, never on attach): fits
+     * the layer to the game viewport, sets the frame's `--waica-unit` on it
+     * (every instance inherits it through its shadow host) and puts every
+     * instance's zero-size shadow host at its anchor point, its CSS
+     * animations set to Game Time (followGameTime).
+     */
+    place() {
+        const layer = this.layer;
+        if (!layer || !this.view)
+            return;
+        const view = this.view();
+        const { camera, viewport } = view;
+        layer.style.left = `${viewport.x}px`;
+        layer.style.top = `${viewport.y}px`;
+        layer.style.width = `${viewport.width}px`;
+        layer.style.height = `${viewport.height}px`;
+        // The camera frames exactly viewHeight world units vertically (Game.resize).
+        layer.style.setProperty('--waica-unit', `${viewport.height / (camera.top - camera.bottom)}px`);
+        // Before any instance's style writes below: getAnimations() flushes style.
+        for (const instance of this.instances)
+            followGameTime(instance);
+        const byDepth = [];
+        for (const instance of this.instances) {
+            const placement = locate(instance, view);
+            instance.placed = placement;
+            instance.host.style.left = `${placement.x}px`;
+            instance.host.style.top = `${placement.y}px`;
+            byDepth.push([instance, placement.depth]);
+        }
+        // Lower on screen draws on top, like y-sort; the sort is stable, so
+        // equal heights keep creation order, later on top.
+        byDepth.sort(([, a], [, b]) => a - b);
+        for (const [index, [instance]] of byDepth.entries())
+            instance.host.style.zIndex = String(index + 1);
+    }
+    bind(instance) {
+        for (const [name, text] of placeholders(instance.root)) {
+            const texts = instance.texts.get(name);
+            if (texts)
+                texts.push(text);
+            else
+                instance.texts.set(name, [text]);
+        }
+        for (const name of instance.texts.keys()) {
+            this.render(instance, name);
+            instance.unsubs.push(this.deps.stats.onChange(name, () => {
+                if (!instance.values.has(name))
+                    this.render(instance, name);
+            }));
+        }
+    }
+    /** Writes a name's current value — the instance's own, else the Game stat — into its placeholders. */
+    render(instance, name) {
+        const value = instance.values.has(name) ? instance.values.get(name) : this.deps.stats.get(name);
+        for (const text of instance.texts.get(name) ?? [])
+            text.nodeValue = renderStat(value);
+    }
+    set(instance, name, value) {
+        if (!instance.alive)
+            return;
+        instance.values.set(name, value);
+        this.render(instance, name);
+        publish(instance.host, name, value);
+    }
+    remove(instance) {
+        if (!instance.alive)
+            return;
+        instance.alive = false;
+        instance.expiry?.cancel();
+        for (const off of instance.unsubs)
+            off();
+        instance.host.remove();
+        this.instances.splice(this.instances.indexOf(instance), 1);
+    }
+    handleFor(instance) {
+        const pieces = this;
+        return {
+            set(name, value) {
+                pieces.set(instance, name, value);
+            },
+            remove() {
+                pieces.remove(instance);
+            },
+            get alive() {
+                return instance.alive;
+            },
+            get element() {
+                return instance.alive ? instance.root : null;
+            },
+        };
+    }
+    /**
+     * The single layer every instance lives in, kept as the overlay's first
+     * child — even when a screen piece created the overlay first — so every
+     * screen-space piece draws above every anchored instance.
+     */
+    mountLayer() {
+        if (this.layer)
+            return this.layer;
+        const layer = document.createElement('div');
+        // Until the first frame fits it to the game viewport, it covers the overlay.
+        // Its own stacking context (z-index:0) keeps every instance's z-index
+        // below the screen-piece shells that follow it.
+        layer.style.cssText =
+            'position:absolute;left:0;top:0;width:100%;height:100%;overflow:hidden;z-index:0;pointer-events:none';
+        this.deps.overlay().prepend(layer);
+        this.layer = layer;
+        return layer;
+    }
+}
+/** The entity's render point plus the offset, in render space — or the point frozen at its destroy(). */
+function anchorPoint(instance, projection) {
+    if (instance.frozen)
+        return instance.frozen;
+    const { x, y } = instance.entity.position;
+    const render = projection === 'isometric' ? projectIsometric(x, y) : { x, y };
+    return { x: render.x + instance.offset[0], y: render.y + instance.offset[1] };
+}
+/**
+ * The anchor point in whole CSS px from the game viewport's top-left
+ * corner: the exact inverse of the Pointer's screen→world mapping.
+ */
+function locate(instance, view) {
+    const anchor = anchorPoint(instance, view.projection);
+    const { camera, viewport } = view;
+    const nx = (anchor.x - (camera.position.x + camera.left)) / (camera.right - camera.left);
+    const ny = (camera.position.y + camera.top - anchor.y) / (camera.top - camera.bottom);
+    return {
+        x: whole(nx * viewport.width),
+        y: whole(ny * viewport.height),
+        clipped: nx < 0 || nx > 1 || ny < 0 || ny > 1,
+        depth: ny,
+    };
+}
+/**
+ * Drives the instance's CSS animations from Game Time instead of the
+ * document timeline: each is paused at the Game Time elapsed since it
+ * started, so a frame that runs no Simulation Step leaves it exactly where
+ * it was. One there at the first placement started with the instance (its
+ * attach); a later one (a transition a set() started) with the frame it
+ * first shows up in. Called before the frame updates `placed`. A DOM
+ * without the Web Animations API (happy-dom returns none) is left alone.
+ */
+function followGameTime(instance) {
+    const animations = instance.host.shadowRoot?.getAnimations?.() ?? [];
+    const now = instance.entity.game.time.now;
+    const firstSeen = instance.placed ? now : instance.born;
+    for (const animation of animations) {
+        const start = animationStart(instance, animation, firstSeen);
+        animation.pause();
+        animation.currentTime = (now - start) * 1000;
+    }
+}
+/**
+ * The Game Time `animation` counts from, recorded as `firstSeen` the first
+ * time it is met. A named CSS animation is known by its target element and
+ * name, not by object: hiding the overlay (not simulating) cancels it, and
+ * the new one the browser makes when it shows again resumes mid-flight. A
+ * transition, or anything else without a name, is known by object.
+ */
+function animationStart(instance, animation, firstSeen) {
+    const name = 'animationName' in animation ? animation.animationName : undefined;
+    const effect = animation.effect;
+    const target = effect && 'target' in effect ? effect.target : null;
+    if (typeof name === 'string' && target instanceof Element) {
+        let byName = instance.named.get(target);
+        if (!byName)
+            instance.named.set(target, (byName = new Map()));
+        const start = byName.get(name) ?? firstSeen;
+        byName.set(name, start);
+        return start;
+    }
+    const start = instance.clocks.get(animation) ?? firstSeen;
+    instance.clocks.set(animation, start);
+    return start;
+}
+/** Rounds to a whole pixel, never -0. */
+function whole(value) {
+    return Math.round(value) || 0;
+}
+/** Numbers verbatim and booleans as 1/0 become `--name`; a string publishes nothing. */
+function publish(host, name, value) {
+    const property = `--${name}`;
+    if (typeof value === 'number')
+        host.style.setProperty(property, String(value));
+    else if (typeof value === 'boolean')
+        host.style.setProperty(property, value ? '1' : '0');
+    else
+        host.style.removeProperty(property);
+}

package/dist/assets/asset-loader.d.ts

@@ -0,0 +1,76 @@
+import * as THREE from 'three';
+import { type TextureBackend } from './texture-backend.js';
+/** `game.assets.status`: a fresh snapshot of the cache's counters, cumulative for the Game. */
+export interface AssetStatus {
+    /** Requested URLs that have not settled yet. */
+    pending: number;
+    /** Settled URLs whose image arrived. */
+    loaded: number;
+    /** Settled URLs whose load failed — recorded, warned once, never retried. */
+    failed: number;
+}
+export type TextureOutcome = 'loaded' | 'failed';
+/** What a consumer gets from `game.assets.texture(url)`: its own clone, and when the image settled. */
+export interface TextureHandle {
+    texture: THREE.Texture;
+    settled: Promise<TextureOutcome>;
+}
+export interface AssetLoaderOptions {
+    /** Replaces the real `THREE.TextureLoader` implementation (ADR 0013); defaults to it. */
+    backend?: TextureBackend;
+    /**
+     * Resolves a uri for `preload()` the way the scene loader resolves every
+     * prefab's string prop (`resolveProps` in scene.ts). Looked up on every
+     * call: `Game` wires this to its registered scene catalog, which survives
+     * `unloadScene()`. Defaults to identity, so an already-resolved or
+     * unresolvable uri passes through unchanged either way.
+     */
+    resolveAsset?: (uri: string) => string;
+}
+/**
+ * The engine's texture cache (`game.assets`, ADR 0019): keep-all for the
+ * Game's whole life, keyed by the URL as received, one backend load and one
+ * base texture per URL. `ready()` is the **Assets Ready** signal — a
+ * promise beside the synchronous scene load — and a failed image is
+ * recorded, not thrown, so it never breaks a host or a Run Session that
+ * awaits it. `unloadScene()` never touches this cache; `dispose()` empties it.
+ */
+export declare class AssetLoader {
+    private readonly backend;
+    private readonly resolveAsset;
+    private readonly entries;
+    private pendingCount;
+    private loadedCount;
+    private failedCount;
+    constructor(options?: AssetLoaderOptions);
+    /** A fresh object on every read: `pending` is current, `loaded` and `failed` only grow until `dispose()`. */
+    get status(): AssetStatus;
+    /**
+     * The consumer entry (Sprite, AnimatedSprite, Tilemap): requests `url`
+     * — already resolved by `resolveProps` — and returns a clone of its base
+     * right away, so a mesh exists before the image arrives, plus the
+     * settlement of that URL, which also fires on a cache hit.
+     */
+    texture(url: string): TextureHandle;
+    /**
+     * Requests every uri ahead of time, each resolved through the registered
+     * scene catalog. Resolves once all of them settled, failures included —
+     * a failure still only warns once, the same as a component's request.
+     */
+    preload(uris: string[]): Promise<void>;
+    /**
+     * Assets Ready: resolves the first time `pending` is 0 after the call —
+     * at once when nothing is pending, otherwise once every URL requested
+     * before or while waiting has settled. Never rejects. Resolves after the
+     * `settled` continuations consumers chained before the call, so a host
+     * that does `await game.assets.ready()` then `game.start()` renders its
+     * first frame with the textures in place.
+     */
+    ready(): Promise<void>;
+    /** Disposes every cached base exactly once and forgets everything; called by `Game.dispose()`. */
+    dispose(): void;
+    private request;
+    private load;
+    /** One backend load as an outcome, never a rejection — a backend that throws synchronously included. */
+    private attempt;
+}