@waica/engine 0.17.0 → 0.18.0

package/README.md

@@ -224,3 +224,25 @@ bar.remove()
 - **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/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;
+}

package/dist/assets/asset-loader.js

@@ -0,0 +1,138 @@
+import * as THREE from 'three';
+import { ThreeTextureBackend } from './texture-backend.js';
+/**
+ * Not `base.clone()`: `Texture.copy` sets `needsUpdate`, which bumps the
+ * shared Source's version — a GPU re-upload of the same image for every
+ * clone — and, while the image is still missing, makes the renderer warn
+ * on every frame. Sharing the Source and mirroring `version` instead marks
+ * the clone uploadable exactly when the base is, and three then keeps one
+ * GPU texture per (Source, sampler parameters), reference-counted across
+ * clones (WebGLTextures). Colour space is the base's; filters, repeat and
+ * offset are the clone's own.
+ */
+function cloneOf(base) {
+    const clone = new THREE.Texture();
+    clone.source = base.source;
+    clone.colorSpace = base.colorSpace;
+    clone.version = base.version;
+    return clone;
+}
+/**
+ * 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 class AssetLoader {
+    backend;
+    resolveAsset;
+    entries = new Map();
+    pendingCount = 0;
+    loadedCount = 0;
+    failedCount = 0;
+    constructor(options = {}) {
+        this.backend = options.backend ?? new ThreeTextureBackend();
+        this.resolveAsset = options.resolveAsset ?? ((uri) => uri);
+    }
+    /** A fresh object on every read: `pending` is current, `loaded` and `failed` only grow until `dispose()`. */
+    get status() {
+        return { pending: this.pendingCount, loaded: this.loadedCount, failed: this.failedCount };
+    }
+    /**
+     * 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) {
+        const entry = this.request(url);
+        const texture = cloneOf(entry.base);
+        if (entry.outcome === null) {
+            // Chained here, before the consumer chains its own continuation on
+            // `settled`, so the clone is uploadable by the time that one runs.
+            void entry.settled.then((outcome) => {
+                if (outcome === 'loaded')
+                    texture.version = entry.base.version;
+            });
+        }
+        return { texture, settled: entry.settled };
+    }
+    /**
+     * 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.
+     */
+    async preload(uris) {
+        await Promise.all(uris.map((uri) => this.request(this.resolveAsset(uri)).settled));
+    }
+    /**
+     * 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.
+     */
+    async ready() {
+        while (this.pendingCount > 0) {
+            const inFlight = [...this.entries.values()].filter((entry) => entry.outcome === null);
+            await Promise.all(inFlight.map((entry) => entry.settled));
+        }
+    }
+    /** Disposes every cached base exactly once and forgets everything; called by `Game.dispose()`. */
+    dispose() {
+        for (const entry of this.entries.values())
+            entry.base.dispose();
+        this.entries.clear();
+        this.pendingCount = 0;
+        this.loadedCount = 0;
+        this.failedCount = 0;
+    }
+    request(url) {
+        const existing = this.entries.get(url);
+        if (existing)
+            return existing;
+        const base = new THREE.Texture();
+        base.colorSpace = THREE.SRGBColorSpace;
+        const entry = { base, outcome: null, settled: Promise.resolve('failed') };
+        // Registered and counted before the backend runs, so a backend that
+        // throws synchronously still settles this very entry.
+        this.entries.set(url, entry);
+        this.pendingCount += 1;
+        entry.settled = this.load(url, entry);
+        return entry;
+    }
+    async load(url, entry) {
+        const attempt = await this.attempt(url);
+        // A dispose() in flight already forgot this entry and disposed its base:
+        // nothing to write, warn about or count. Only the settlement is still
+        // owed, so a consumer awaiting it never hangs; it reports what the
+        // backend did.
+        if (this.entries.get(url) !== entry)
+            return attempt.outcome;
+        if (attempt.outcome === 'loaded') {
+            // The image lands on the base's Source, which every clone shares.
+            entry.base.image = attempt.texture.image;
+            entry.base.needsUpdate = true;
+            this.loadedCount += 1;
+        }
+        else {
+            console.warn(`[waica] assets: failed to load "${url}"`, attempt.error);
+            this.failedCount += 1;
+        }
+        entry.outcome = attempt.outcome;
+        this.pendingCount -= 1;
+        return attempt.outcome;
+    }
+    /** One backend load as an outcome, never a rejection — a backend that throws synchronously included. */
+    async attempt(url) {
+        try {
+            return { outcome: 'loaded', texture: await this.backend.load(url) };
+        }
+        catch (error) {
+            return { outcome: 'failed', error };
+        }
+    }
+}

package/dist/assets/texture-backend.d.ts

@@ -0,0 +1,17 @@
+import * as THREE from 'three';
+/**
+ * The seam between `game.assets` and the browser (ADR 0013's move, applied
+ * to textures — ADR 0019). `load` resolves once the image behind `url` is
+ * decoded, with a texture whose `image` the loader adopts into its own
+ * cached base; it rejects on a load error and never throws synchronously.
+ * `happy-dom` decodes no images, so a test injects `FakeTextureBackend`
+ * (assets/test-helpers.ts) through `GameOptions.textures`.
+ */
+export interface TextureBackend {
+    load(url: string): Promise<THREE.Texture>;
+}
+/** The real implementation: one `THREE.TextureLoader` per Game, wrapped in a promise. */
+export declare class ThreeTextureBackend implements TextureBackend {
+    private readonly loader;
+    load(url: string): Promise<THREE.Texture>;
+}

package/dist/assets/texture-backend.js

@@ -0,0 +1,15 @@
+import * as THREE from 'three';
+/** The real implementation: one `THREE.TextureLoader` per Game, wrapped in a promise. */
+export class ThreeTextureBackend {
+    loader = new THREE.TextureLoader();
+    load(url) {
+        return new Promise((resolve, reject) => {
+            try {
+                this.loader.load(url, resolve, undefined, reject);
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+    }
+}

package/dist/components/animated-sprite.d.ts

@@ -6,10 +6,11 @@ import type { YSortParticipant } from '../render-sort.js';
  * Sprite animated from one or more spritesheets. The main sheet is the
  * top-level texture/cols/rows (or explicit cells); extraSheets append after
  * it, and clip frames index the sheets consecutively (sheet 0 owns 0..n0-1,
- * sheet 1 the next n1, …). Each instance clones its textures to animate UVs
- * independently. On sheets with explicit cells the frames vary in pixel size,
- * so the quad rescales per frame, anchored bottom-center — width/height size
- * the sheet's largest frame and smaller ones keep their feet planted.
+ * sheet 1 the next n1, …). Each instance owns its own clones of the cached
+ * sheets (game.assets, ADR 0019) to animate UVs independently. On sheets
+ * with explicit cells the frames vary in pixel size, so the quad rescales
+ * per frame, anchored bottom-center — width/height size the sheet's largest
+ * frame and smaller ones keep their feet planted.
  */
 export declare class AnimatedSprite extends Component implements YSortParticipant {
     static componentName: string;
@@ -91,6 +92,7 @@ export declare class AnimatedSprite extends Component implements YSortParticipan
     private readonly player;
     private sheets;
     private texs;
+    private readonly failedSheets;
     private mesh?;
     private frame;
     private frameScaleX;
@@ -100,6 +102,17 @@ export declare class AnimatedSprite extends Component implements YSortParticipan
     play(name: string): void;
     onUpdate(dt: number): void;
     onDestroy(): void;
+    /**
+     * The sheet's own clone of the cached base. Non-uniform slicing needs
+     * the image's pixel size, so the current frame is re-applied once the
+     * sheet settles — on a cache hit too, whose settlement is already
+     * resolved — unless this sprite was destroyed meanwhile. A sheet that
+     * fails is remembered so the quad shows its flat material on that
+     * sheet's frames instead of sampling an image that never arrived (CA-4).
+     * An empty url (a sheet not authored yet) owns a bare texture and never
+     * touches game.assets, so it counts nowhere and warns about nothing.
+     */
+    private sheetTexture;
     private showFrame;
     /** Repositions/rescales the displayed frame inside its anchored full-size box. */
     private syncQuad;

package/dist/components/animated-sprite.js

@@ -3,16 +3,16 @@ import { Component } from '../component.js';
 import { ClipPlayer } from '../animation/clip-player.js';
 import { locateFrame, sheetCell } from '../animation/sheet.js';
 import { spritePlacement } from '../sprite-placement.js';
-const loader = new THREE.TextureLoader();
 const clampAnchor = (value) => Math.min(1, Math.max(0, value));
 /**
  * Sprite animated from one or more spritesheets. The main sheet is the
  * top-level texture/cols/rows (or explicit cells); extraSheets append after
  * it, and clip frames index the sheets consecutively (sheet 0 owns 0..n0-1,
- * sheet 1 the next n1, …). Each instance clones its textures to animate UVs
- * independently. On sheets with explicit cells the frames vary in pixel size,
- * so the quad rescales per frame, anchored bottom-center — width/height size
- * the sheet's largest frame and smaller ones keep their feet planted.
+ * sheet 1 the next n1, …). Each instance owns its own clones of the cached
+ * sheets (game.assets, ADR 0019) to animate UVs independently. On sheets
+ * with explicit cells the frames vary in pixel size, so the quad rescales
+ * per frame, anchored bottom-center — width/height size the sheet's largest
+ * frame and smaller ones keep their feet planted.
  */
 export class AnimatedSprite extends Component {
     static componentName = 'AnimatedSprite';
@@ -30,6 +30,7 @@ export class AnimatedSprite extends Component {
         'player',
         'sheets',
         'texs',
+        'failedSheets',
         'mesh',
         'frame',
         'frameScaleX',
@@ -135,6 +136,8 @@ export class AnimatedSprite extends Component {
     player = new ClipPlayer();
     sheets = [];
     texs = [];
+    // Clones whose sheet failed to load: applyFrame never installs them (CA-4).
+    failedSheets = new Set();
     mesh;
     frame = 0;
     // Current frame's quad scale relative to the sheet's largest cell: always
@@ -157,10 +160,7 @@ export class AnimatedSprite extends Component {
             main.cells = this.cells;
         this.sheets = [main, ...this.extraSheets];
         this.texs = this.sheets.map((sheet) => {
-            // Non-uniform slicing needs the image's pixel size, so re-apply the
-            // current frame once each texture is in.
-            const tex = loader.load(sheet.texture, () => this.applyFrame());
-            tex.colorSpace = THREE.SRGBColorSpace;
+            const tex = this.sheetTexture(sheet.texture);
             if (this.pixelArt) {
                 tex.magFilter = THREE.NearestFilter;
                 tex.minFilter = THREE.NearestFilter;
@@ -195,8 +195,34 @@ export class AnimatedSprite extends Component {
         this.mesh?.removeFromParent();
         this.mesh?.geometry.dispose();
         this.mesh?.material.dispose();
+        // Only this sprite's clones: the cached bases live with the Game.
         for (const tex of this.texs)
             tex.dispose();
+        this.texs = [];
+        this.failedSheets.clear();
+    }
+    /**
+     * The sheet's own clone of the cached base. Non-uniform slicing needs
+     * the image's pixel size, so the current frame is re-applied once the
+     * sheet settles — on a cache hit too, whose settlement is already
+     * resolved — unless this sprite was destroyed meanwhile. A sheet that
+     * fails is remembered so the quad shows its flat material on that
+     * sheet's frames instead of sampling an image that never arrived (CA-4).
+     * An empty url (a sheet not authored yet) owns a bare texture and never
+     * touches game.assets, so it counts nowhere and warns about nothing.
+     */
+    sheetTexture(url) {
+        if (!url)
+            return new THREE.Texture();
+        const { texture, settled } = this.game.assets.texture(url);
+        void settled.then((outcome) => {
+            if (!this.texs.includes(texture))
+                return;
+            if (outcome === 'failed')
+                this.failedSheets.add(texture);
+            this.applyFrame();
+        });
+        return texture;
     }
     showFrame(index) {
         this.frame = index;
@@ -227,9 +253,12 @@ export class AnimatedSprite extends Component {
         const tex = this.texs[located.sheet];
         if (!sheet || !tex)
             return;
-        if (this.mesh && this.mesh.material.map !== tex) {
-            this.mesh.material.map = tex;
-            this.mesh.material.needsUpdate = true;
+        if (this.mesh) {
+            const map = this.failedSheets.has(tex) ? null : tex;
+            if (this.mesh.material.map !== map) {
+                this.mesh.material.map = map;
+                this.mesh.material.needsUpdate = true;
+            }
         }
         const cells = sheet.cells;
         if (cells?.length) {

package/dist/components/sprite.d.ts

@@ -69,6 +69,12 @@ export declare class Sprite extends Component implements YSortParticipant {
     private mesh?;
     onReady(): void;
     onDestroy(): void;
+    /**
+     * CA-4's failure rule: an image that never arrives leaves the flat
+     * `color`, not a white quad over an empty map. Skipped once the sprite
+     * was destroyed or the clone is no longer this material's map.
+     */
+    private dropFailedTexture;
     private syncQuad;
     private createGeometry;
 }

package/dist/components/sprite.js

@@ -1,7 +1,6 @@
 import * as THREE from 'three';
 import { Component } from '../component.js';
 import { spritePlacement } from '../sprite-placement.js';
-const loader = new THREE.TextureLoader();
 const clampAnchor = (value) => Math.min(1, Math.max(0, value));
 /**
  * Textured or flat-color quad. In the unified pipeline, a 2D sprite is a
@@ -109,14 +108,20 @@ export class Sprite extends Component {
     onReady() {
         const material = new THREE.MeshBasicMaterial({ color: this.color, transparent: true });
         if (this.texture) {
-            const tex = loader.load(this.texture);
+            // Its own clone of the cached base (game.assets, ADR 0019): filters
+            // are per clone, colour space comes with the base, and the image lands
+            // on the Source every clone of this URL shares.
+            const { texture, settled } = this.game.assets.texture(this.texture);
             if (this.pixelArt) {
-                tex.magFilter = THREE.NearestFilter;
-                tex.minFilter = THREE.NearestFilter;
+                texture.magFilter = THREE.NearestFilter;
+                texture.minFilter = THREE.NearestFilter;
             }
-            tex.colorSpace = THREE.SRGBColorSpace;
-            material.map = tex;
+            material.map = texture;
             material.color.set(0xffffff);
+            void settled.then((outcome) => {
+                if (outcome === 'failed')
+                    this.dropFailedTexture(texture);
+            });
         }
         this.mesh = new THREE.Mesh(this.createGeometry(), material);
         this.mesh.position.z = this.layer * 0.01;
@@ -126,7 +131,24 @@ export class Sprite extends Component {
     onDestroy() {
         this.mesh?.removeFromParent();
         this.mesh?.geometry.dispose();
+        // Only this sprite's clone: the cached base lives with the Game.
+        this.mesh?.material.map?.dispose();
         this.mesh?.material.dispose();
+        this.mesh = undefined;
+    }
+    /**
+     * CA-4's failure rule: an image that never arrives leaves the flat
+     * `color`, not a white quad over an empty map. Skipped once the sprite
+     * was destroyed or the clone is no longer this material's map.
+     */
+    dropFailedTexture(texture) {
+        const material = this.mesh?.material;
+        if (!material || material.map !== texture)
+            return;
+        material.map = null;
+        texture.dispose();
+        material.color.setHex(this.color);
+        material.needsUpdate = true;
     }
     syncQuad() {
         if (!this.mesh)

package/dist/components/tilemap.d.ts

@@ -107,6 +107,12 @@ export declare class Tilemap extends Component implements SolidSource {
     private gridSpec;
     private rebuildMap;
     private rebuildMaterial;
+    /**
+     * CA-4's failure rule: an image that never arrives leaves the flat
+     * `color`, not a white map over an empty texture. Only reached while the
+     * failed clone is still the current one (see rebuildMaterial).
+     */
+    private dropFailedTexture;
     private makeMaterial;
     private rebuildGeometry;
     private rebuildSolids;

package/dist/components/tilemap.js

@@ -5,7 +5,6 @@ import { projectIsometric } from '../projection.js';
 import { SOLID_SOURCE_SYMBOL } from '../scene-solids.js';
 import { cellAt as gridCellAt, cellBounds as gridCellBounds, cellIndex as gridCellIndex, } from '../tilemap-grid.js';
 import { Solid } from './solid.js';
-const loader = new THREE.TextureLoader();
 /** One authorable cell map rendered as a single merged geometry. */
 export class Tilemap extends Component {
     static componentName = 'Tilemap';
@@ -212,20 +211,45 @@ export class Tilemap extends Component {
         if (!this.texture)
             return;
         const requested = this.texture;
-        const texture = loader.load(requested, () => {
-            if (this.loadedTexture === texture && this.texture === requested)
+        // Its own clone of the cached base (game.assets, ADR 0019). The image's
+        // pixel size drives the UVs, so the geometry is rebuilt once the texture
+        // settles — on a cache hit too, whose settlement is already resolved —
+        // and a texture that fails is dropped for the flat colour; neither
+        // happens if the texture was replaced or the component destroyed
+        // meanwhile.
+        const { texture, settled } = this.game.assets.texture(requested);
+        void settled.then((outcome) => {
+            if (this.loadedTexture !== texture || this.texture !== requested)
+                return;
+            if (outcome === 'loaded')
                 this.rebuildGeometry();
+            else
+                this.dropFailedTexture();
         });
         if (this.pixelArt) {
             texture.magFilter = THREE.NearestFilter;
             texture.minFilter = THREE.NearestFilter;
         }
-        texture.colorSpace = THREE.SRGBColorSpace;
         this.loadedTexture = texture;
         mesh.material.map = texture;
         mesh.material.color.set(0xffffff);
         mesh.material.needsUpdate = true;
     }
+    /**
+     * CA-4's failure rule: an image that never arrives leaves the flat
+     * `color`, not a white map over an empty texture. Only reached while the
+     * failed clone is still the current one (see rebuildMaterial).
+     */
+    dropFailedTexture() {
+        const mesh = this.mesh;
+        if (!mesh)
+            return;
+        this.loadedTexture?.dispose();
+        this.loadedTexture = undefined;
+        mesh.material.map = null;
+        mesh.material.color.setHex(this.color);
+        mesh.material.needsUpdate = true;
+    }
     makeMaterial() {
         return new THREE.MeshBasicMaterial({
             color: this.color,

package/dist/game.d.ts

@@ -1,4 +1,6 @@
 import * as THREE from 'three';
+import { AssetLoader } from './assets/asset-loader.js';
+import type { TextureBackend } from './assets/texture-backend.js';
 import type { AudioBackend } from './audio/backend.js';
 import { AudioSubsystem } from './audio/audio-subsystem.js';
 import { type SceneCameraJson } from './camera.js';
@@ -38,6 +40,13 @@ export interface GameOptions {
      * first unlock (CA-6), never eagerly here.
      */
     audio?: AudioBackend;
+    /**
+     * Replaces the real `THREE.TextureLoader` implementation behind
+     * `game.assets` (ADR 0013's seam, applied to textures — ADR 0019), mainly
+     * for a project's own tests: `happy-dom` decodes no images. Defaults to
+     * the real backend either way; `game.assets` always exists.
+     */
+    textures?: TextureBackend;
 }
 export type UpdateFn = (dt: number) => void;
 export interface SpawnPrefabOptions {
@@ -68,6 +77,12 @@ export declare class Game {
     readonly ui: GameUi;
     /** The audio mixer: channels, master, playback. See ADR 0012, ADR 0013. */
     readonly audio: AudioSubsystem;
+    /**
+     * The texture cache: keep-all for the Game's life, `preload`, `status`
+     * and the Assets Ready promise `ready()`. Session-scoped by construction
+     * (ADR 0011): `unloadScene()` never touches it. See ADR 0019.
+     */
+    readonly assets: AssetLoader;
     /** Simulated scheduling: `after`, `every`, `tween`, `now`. See ADR 0017. */
     readonly time: GameTime;
     /** Registry retained by loadScene for runtime prefab spawning. */

package/dist/game.js

@@ -1,5 +1,6 @@
 import * as THREE from 'three';
 import { gameViewport } from './anchored-pieces.js';
+import { AssetLoader } from './assets/asset-loader.js';
 import { AudioSubsystem } from './audio/audio-subsystem.js';
 import { dispatchCollisions as dispatchHitboxCollisions } from './collision-dispatch.js';
 import { isCameraVelocityProvider, resolveSceneCamera, stepSceneCamera, } from './camera.js';
@@ -35,6 +36,12 @@ export class Game {
     ui;
     /** The audio mixer: channels, master, playback. See ADR 0012, ADR 0013. */
     audio;
+    /**
+     * The texture cache: keep-all for the Game's life, `preload`, `status`
+     * and the Assets Ready promise `ready()`. Session-scoped by construction
+     * (ADR 0011): `unloadScene()` never touches it. See ADR 0019.
+     */
+    assets;
     /** Simulated scheduling: `after`, `every`, `tween`, `now`. See ADR 0017. */
     time = new GameTime();
     /** Registry retained by loadScene for runtime prefab spawning. */
@@ -103,6 +110,12 @@ export class Game {
             // music bed needs across a scene swap.
             resolveAsset: (uri) => this.sceneCatalog?.registry.resolveAsset?.(uri) ?? uri,
         });
+        this.assets = new AssetLoader({
+            backend: options.textures,
+            // Same late lookup as audio's: preload() resolves through whatever
+            // catalog is registered at call time, which outlives every scene.
+            resolveAsset: (uri) => this.sceneCatalog?.registry.resolveAsset?.(uri) ?? uri,
+        });
         this.renderer = new THREE.WebGLRenderer({ canvas, antialias: true });
         this.renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
         this.scene.background = new THREE.Color(background);
@@ -310,6 +323,7 @@ export class Game {
                     },
                     loadScene: (name) => this.loadSceneByName(name),
                     availableScenes: () => this.availableScenes,
+                    assets: () => this.assets.status,
                 });
                 activation.register(this.runtimeBridge);
                 this.audio.setSilenced(true);
@@ -357,6 +371,9 @@ export class Game {
         this.time.cancelAll();
         for (const entity of [...this.entities])
             entity.destroy();
+        // After the entities: their clones go with the cascade above, the
+        // cached bases go here, exactly once (ADR 0019).
+        this.assets.dispose();
         this.renderer.dispose();
     }
     /**

package/dist/index.d.ts

@@ -1,5 +1,8 @@
 export { Game } from './game.js';
 export type { GameOptions, GameResolution, SceneCatalog, SpawnPrefabOptions, UpdateFn, ParamOverrides, } from './game.js';
+export { AssetLoader } from './assets/asset-loader.js';
+export type { AssetStatus } from './assets/asset-loader.js';
+export type { TextureBackend } from './assets/texture-backend.js';
 export { AudioSubsystem } from './audio/audio-subsystem.js';
 export type { AudioSubsystemOptions } from './audio/audio-subsystem.js';
 export type { AudioBackend, AudioResource, BackendPlayHandle, BackendPlayOptions } from './audio/backend.js';

package/dist/index.js

@@ -1,4 +1,5 @@
 export { Game } from './game.js';
+export { AssetLoader } from './assets/asset-loader.js';
 export { AudioSubsystem } from './audio/audio-subsystem.js';
 export { installDirectionalAnimation, installedDirectionalAnimation, isAnimationFacingProvider, resolveDirectionalClip, } from './animation/directional.js';
 export { isYSortParticipant, ySortZ } from './render-sort.js';

package/dist/runtime-bridge.d.ts

@@ -1,3 +1,4 @@
+import type { AssetStatus } from './assets/asset-loader.js';
 import type { RuntimeSnapshot, RuntimeSnapshotFilters } from './runtime-inspection.js';
 export declare const RUNTIME_BRIDGE_PROTOCOL_VERSION: 1;
 export declare const RUNTIME_BRIDGE_SYMBOL: unique symbol;
@@ -10,9 +11,13 @@ export type RuntimeMode = 'paused' | 'real-time';
  * gating on capabilities check for (review finding #4) — protocol 1 alone
  * doesn't distinguish an engine that silently no-ops an unknown operation
  * from one that runs it. `fixed-step` (ADR 0014) announces that `step`
- * advances whole 1/60 s Simulation Steps and takes no `dt`.
+ * advances whole 1/60 s Simulation Steps and takes no `dt`. `assets`
+ * (ADR 0019) announces that every metadata carries `assets: { pending,
+ * loaded, failed }` from `game.assets.status`, so a Run Session can wait
+ * for Assets Ready (`pending === 0`) at readiness, after a `scene`
+ * operation and before a screenshot.
  */
-export declare const RUNTIME_BRIDGE_CAPABILITIES: readonly ['click', 'scene', 'fixed-step'];
+export declare const RUNTIME_BRIDGE_CAPABILITIES: readonly ['click', 'scene', 'fixed-step', 'assets'];
 export interface RuntimeMetadata {
     bridgeVersion: typeof RUNTIME_BRIDGE_PROTOCOL_VERSION;
     engineVersion: string;
@@ -20,6 +25,8 @@ export interface RuntimeMetadata {
     frame: number;
     simulationTime: number;
     capabilities: readonly string[];
+    /** `game.assets.status` at the moment of the read — reading it never advances `frame`. */
+    assets: AssetStatus;
 }
 export type RuntimeControlRequest = {
     operation: 'press' | 'hold' | 'release';
@@ -81,6 +88,8 @@ export interface RuntimeBridgeHost {
     /** Resolves `name` through the registered catalog and loads it. */
     loadScene(name: string): boolean;
     availableScenes(): string[];
+    /** A fresh `game.assets.status`. */
+    assets(): AssetStatus;
 }
 export declare class EngineRuntimeBridge implements RuntimeBridge {
     readonly surface: HTMLCanvasElement;

package/dist/runtime-bridge.js

@@ -10,9 +10,13 @@ export const RUNTIME_BRIDGE_SYMBOL = Symbol.for('@waica/runtime-bridge/v1');
  * gating on capabilities check for (review finding #4) — protocol 1 alone
  * doesn't distinguish an engine that silently no-ops an unknown operation
  * from one that runs it. `fixed-step` (ADR 0014) announces that `step`
- * advances whole 1/60 s Simulation Steps and takes no `dt`.
+ * advances whole 1/60 s Simulation Steps and takes no `dt`. `assets`
+ * (ADR 0019) announces that every metadata carries `assets: { pending,
+ * loaded, failed }` from `game.assets.status`, so a Run Session can wait
+ * for Assets Ready (`pending === 0`) at readiness, after a `scene`
+ * operation and before a screenshot.
  */
-export const RUNTIME_BRIDGE_CAPABILITIES = ['click', 'scene', 'fixed-step'];
+export const RUNTIME_BRIDGE_CAPABILITIES = ['click', 'scene', 'fixed-step', 'assets'];
 export class RuntimeBridgeOperationError extends Error {
     code;
     availableActions;
@@ -61,6 +65,7 @@ export class EngineRuntimeBridge {
             // Derived, never summed: 60 steps are exactly 1 s, with no float drift.
             simulationTime: this.frame * SIMULATION_STEP,
             capabilities: RUNTIME_BRIDGE_CAPABILITIES,
+            assets: this.host.assets(),
         };
     }
     inspect(filters = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waica/engine",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Waica game engine core — archetype-driven, web-first, 2D & 3D",
   "license": "MIT",
   "type": "module",