@waica/engine 0.16.0 → 0.18.0

package/dist/input.js

@@ -34,6 +34,14 @@ export class Input {
     availableActions() {
         return [...this.bindings.keys()].sort();
     }
+    /**
+     * The key codes bound to the action, in their declared order (e.g.
+     * `['KeyE', 'Space']`); `[]` for an unknown or unbound action. A new
+     * array every call: mutating it never changes the bindings.
+     */
+    bindingsFor(action) {
+        return [...(this.bindings.get(action) ?? [])];
+    }
     /** Currently held semantic action names in deterministic order. */
     heldActions() {
         return this.availableActions().filter((action) => this.held(action));

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/dist/runtime-inspection.d.ts

@@ -82,6 +82,30 @@ export interface RuntimeSnapshotTime {
     pending: number;
     nextInSteps: number | null;
 }
+/**
+ * `game.ui` (issue #72 CA-9), beside `audio` and `time`: `shown` lists the
+ * screen pieces whose visibility flag is on, sorted by name; `anchored`
+ * lists the live Anchored Pieces in creation order. For each, `entity` is
+ * its anchor entity's name (kept for a lingering instance whose entity is
+ * gone); `x`/`y` are the whole CSS px of its last placement inside the game
+ * viewport — for one attached since the last render frame, where the next
+ * frame will place it; `clipped` is true when its anchor point lies outside
+ * the game viewport; `values` holds only its own values, after every `set`,
+ * bounded like component state (CA-5): sorted by name, a string over 4 KiB
+ * becomes a truncated marker, and past 100 values the record does too.
+ * Emitted unconditionally, like `audio` and `time` — never filtered.
+ */
+export interface RuntimeSnapshotUi {
+    shown: string[];
+    anchored: Array<{
+        piece: string;
+        entity: string;
+        x: number;
+        y: number;
+        clipped: boolean;
+        values: Record<string, StatValue | ProjectionMarker> | ProjectionMarker;
+    }>;
+}
 export interface RuntimeSnapshot extends RuntimeMetadata {
     stats: Record<string, StatValue>;
     /** The live scene's name (its catalog key), or null with no scene loaded. */
@@ -90,6 +114,7 @@ export interface RuntimeSnapshot extends RuntimeMetadata {
     projectionIssues: ProjectionIssue[];
     audio: RuntimeSnapshotAudio;
     time: RuntimeSnapshotTime;
+    ui: RuntimeSnapshotUi;
 }
 export declare const RUNTIME_PROJECTION_LIMITS: {
     readonly depth: 5;
@@ -106,6 +131,7 @@ export declare class RuntimeInspector {
     snapshot(metadata: RuntimeMetadata, filters?: RuntimeSnapshotFilters): RuntimeSnapshot;
     private audioSnapshot;
     private timeSnapshot;
+    private uiSnapshot;
     private capSnapshot;
     private idFor;
 }

package/dist/runtime-inspection.js

@@ -1,3 +1,4 @@
+import { anchoredPiecesOf } from './ui.js';
 export const RUNTIME_PROJECTION_LIMITS = {
     depth: 5,
     entries: 100,
@@ -176,6 +177,37 @@ function boundedComponentState(component, path, context) {
         path,
     });
 }
+function fitsSnapshot(snapshot) {
+    return utf8Bytes(JSON.stringify(snapshot)) <= RUNTIME_PROJECTION_LIMITS.snapshotBytes;
+}
+/** The index of the `ui.anchored` instance an issue path points into, or null. */
+function anchoredIndex(path) {
+    const match = /^ui\.anchored\[(\d+)\]/.exec(path);
+    return match ? Number(match[1]) : null;
+}
+/**
+ * The global cap's second stage, once every entity is gone: drops
+ * `ui.anchored` instances from the end, with their projection issues,
+ * until the snapshot fits, recording how many went.
+ */
+function capAnchored(snapshot) {
+    let capped = snapshot;
+    const retained = [...snapshot.ui.anchored];
+    while (retained.length > 0) {
+        retained.pop();
+        const omitted = snapshot.ui.anchored.length - retained.length;
+        const projectionIssues = snapshot.projectionIssues
+            .filter((issue) => {
+            const index = anchoredIndex(issue.path);
+            return index === null || index < retained.length;
+        })
+            .concat({ path: `ui.anchored[${retained.length}]`, marker: 'truncated', omitted });
+        capped = { ...snapshot, ui: { ...snapshot.ui, anchored: retained }, projectionIssues };
+        if (fitsSnapshot(capped))
+            return capped;
+    }
+    return capped;
+}
 export class RuntimeInspector {
     game;
     ids = new WeakMap();
@@ -239,6 +271,7 @@ export class RuntimeInspector {
             projectionIssues,
             audio: this.audioSnapshot(),
             time: this.timeSnapshot(),
+            ui: this.uiSnapshot(projectionIssues),
         });
     }
     audioSnapshot() {
@@ -258,10 +291,21 @@ export class RuntimeInspector {
             nextInSteps: this.game.time.nextInSteps,
         };
     }
+    uiSnapshot(issues) {
+        const ui = this.game.ui;
+        return {
+            shown: ui.names().filter((name) => ui.isVisible(name)).sort(),
+            anchored: anchoredPiecesOf(ui).snapshot().map((instance, index) => ({
+                ...instance,
+                // A record of StatValues projects to one of these, never to anything else.
+                values: projectValue(instance.values, `ui.anchored[${index}].values`, { issues, seen: new Map() }),
+            })),
+        };
+    }
     capSnapshot(snapshot) {
-        if (utf8Bytes(JSON.stringify(snapshot)) <= RUNTIME_PROJECTION_LIMITS.snapshotBytes) {
+        if (fitsSnapshot(snapshot))
             return snapshot;
-        }
+        let capped = snapshot;
         const retained = [...snapshot.entities];
         const removedIds = new Set();
         while (retained.length > 0) {
@@ -272,20 +316,11 @@ export class RuntimeInspector {
             const projectionIssues = snapshot.projectionIssues
                 .filter((issue) => [...removedIds].every((id) => !issue.path.startsWith(`entities[${id}]`)))
                 .concat({ path: `entities[${retained.length}]`, marker: 'truncated', omitted });
-            const candidate = { ...snapshot, entities: retained, projectionIssues };
-            if (utf8Bytes(JSON.stringify(candidate)) <= RUNTIME_PROJECTION_LIMITS.snapshotBytes) {
-                return candidate;
-            }
+            capped = { ...snapshot, entities: retained, projectionIssues };
+            if (fitsSnapshot(capped))
+                return capped;
         }
-        return {
-            ...snapshot,
-            entities: [],
-            projectionIssues: [{
-                    path: 'entities[0]',
-                    marker: 'truncated',
-                    omitted: snapshot.entities.length,
-                }],
-        };
+        return capAnchored(capped);
     }
     idFor(entity) {
         const existing = this.ids.get(entity);

package/dist/ui-bindings.d.ts

@@ -0,0 +1,12 @@
+import type { StatValue } from './stats.js';
+/** How a bound value reads in a piece: booleans as ✓/✕, missing as empty. */
+export declare function renderStat(value: StatValue | undefined): string;
+/**
+ * Splits every {{name}} placeholder in the fragment's text into its own
+ * (empty) text node and returns those nodes with the names they bind, in
+ * document order — the caller fills and keeps them in sync. Text-only by
+ * design: the binding language has no expressions — presentation, never
+ * logic. Shared by screen pieces (Game stats) and Anchored Pieces (their
+ * own values first, then the Game stats).
+ */
+export declare function placeholders(root: HTMLElement): Array<[name: string, text: Text]>;

package/dist/ui-bindings.js

@@ -0,0 +1,51 @@
+const BINDING = /\{\{\s*([\w-]+)\s*\}\}/g;
+/** How a bound value reads in a piece: booleans as ✓/✕, missing as empty. */
+export function renderStat(value) {
+    if (value === undefined)
+        return '';
+    if (typeof value === 'boolean')
+        return value ? '✓' : '✕';
+    return String(value);
+}
+/**
+ * Splits every {{name}} placeholder in the fragment's text into its own
+ * (empty) text node and returns those nodes with the names they bind, in
+ * document order — the caller fills and keeps them in sync. Text-only by
+ * design: the binding language has no expressions — presentation, never
+ * logic. Shared by screen pieces (Game stats) and Anchored Pieces (their
+ * own values first, then the Game stats).
+ */
+export function placeholders(root) {
+    const bound = [];
+    const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
+    const targets = [];
+    for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+        // Braces inside <style>/<script> are CSS/code, not bindings.
+        if (node.parentElement?.closest('style, script'))
+            continue;
+        if ((node.nodeValue ?? '').includes('{{'))
+            targets.push(node);
+    }
+    for (const text of targets) {
+        const source = text.nodeValue ?? '';
+        const parts = [];
+        let last = 0;
+        for (const match of source.matchAll(BINDING)) {
+            const name = match[1];
+            if (name === undefined)
+                continue;
+            if (match.index > last)
+                parts.push(document.createTextNode(source.slice(last, match.index)));
+            const placeholder = document.createTextNode('');
+            bound.push([name, placeholder]);
+            parts.push(placeholder);
+            last = match.index + match[0].length;
+        }
+        if (parts.length === 0)
+            continue;
+        if (last < source.length)
+            parts.push(document.createTextNode(source.slice(last)));
+        text.replaceWith(...parts);
+    }
+    return bound;
+}

package/dist/ui.d.ts

@@ -1,4 +1,12 @@
+import { AnchoredPieces, type AnchoredPieceHandle, type AttachOptions } from './anchored-pieces.js';
+import type { Entity } from './entity.js';
 import type { Stats } from './stats.js';
+/**
+ * Module-private key for the anchored layer. Not exported, so
+ * `ui[ANCHORED]()` cannot be spelled outside this file — `anchoredPiecesOf`
+ * (below, exported, but not from the package entry) is the Game's only way in.
+ */
+declare const ANCHORED: unique symbol;
 /**
  * The HTML UI layer. Each piece is a self-contained HTML fragment
  * (markup + <style>) that only DRAWS: it declares which stats it shows
@@ -10,6 +18,10 @@ import type { Stats } from './stats.js';
  * (each in its own shadow root, so styles never leak between pieces or
  * into the hosting page). The whole overlay hides while the game is not
  * simulating (pause / editor edit mode).
+ *
+ * Screen pieces are singletons by name (show/hide). An Anchored Piece is
+ * one more instance of a piece that follows an entity (attach), in a layer
+ * below every screen piece — see ADR 0018.
  */
 export declare class GameUi {
     private readonly stats;
@@ -17,6 +29,7 @@ export declare class GameUi {
     private readonly host;
     private readonly sources;
     private readonly pieces;
+    private readonly anchored;
     private overlay?;
     private active;
     constructor(stats: Stats, 
@@ -27,6 +40,8 @@ export declare class GameUi {
     defineAll(pieces: Record<string, string>): void;
     /** Piece names available to show (defined via the registry or define()). */
     names(): string[];
+    /** Whether a piece of this name is defined — `names().includes(name)` without building the list. */
+    has(name: string): boolean;
     show(name: string, options?: ShowOptions): void;
     hide(name: string): void;
     toggle(name: string): void;
@@ -37,22 +52,39 @@ export declare class GameUi {
      * Mounts the piece hidden if it wasn't mounted yet.
      */
     element(name: string): HTMLElement | null;
+    /**
+     * Anchors a new instance of the piece to `entity` (issue #72): its own
+     * shadow root and values, placed every render frame at the entity's
+     * render point plus `offset`. Every call is a new instance; the screen
+     * piece of the same name is never touched. An undefined piece or a dead
+     * entity warns and returns an inert handle — it never throws.
+     */
+    attach(piece: string, entity: Entity, options?: AttachOptions): AnchoredPieceHandle;
     /** Called by the game loop: the overlay only draws while simulating. */
     setActive(active: boolean): void;
-    /** Unmounts every piece and removes the overlay (Game.dispose). */
+    /** Unmounts every piece and Anchored Piece and removes the overlay (Game.dispose). */
     dispose(): void;
     /**
      * Unmounts every scene-scoped piece: the ones `loadScene` showed from the
      * outgoing scene's `ui` list, plus any shown with `{ scope: 'scene' }`.
-     * A piece the host showed with no scope is untouched. The definition
-     * catalog (sources) always survives — Game.unloadScene.
+     * A piece the host showed with no scope is untouched. Every Anchored
+     * Piece goes too, lingering ones included: none outlives its scene. The
+     * definition catalog (sources) always survives — Game.unloadScene.
      */
     unloadScene(): void;
+    /** Engine-internal: see anchoredPiecesOf. */
+    [ANCHORED](): AnchoredPieces;
     private mount;
     private mountOverlay;
     private sync;
 }
+/**
+ * Engine-internal: the anchored layer behind `ui.attach`, which the Game
+ * connects to its camera and viewport and places every render frame.
+ */
+export declare function anchoredPiecesOf(ui: GameUi): AnchoredPieces;
 export interface ShowOptions {
     /** 'scene': unmounted by Game.unloadScene() along with the rest of the scene. */
     scope?: 'scene';
 }
+export {};

package/dist/ui.js

@@ -1,3 +1,11 @@
+import { AnchoredPieces } from './anchored-pieces.js';
+import { placeholders, renderStat } from './ui-bindings.js';
+/**
+ * Module-private key for the anchored layer. Not exported, so
+ * `ui[ANCHORED]()` cannot be spelled outside this file — `anchoredPiecesOf`
+ * (below, exported, but not from the package entry) is the Game's only way in.
+ */
+const ANCHORED = Symbol('waica.ui.anchored');
 /**
  * The HTML UI layer. Each piece is a self-contained HTML fragment
  * (markup + <style>) that only DRAWS: it declares which stats it shows
@@ -9,12 +17,17 @@
  * (each in its own shadow root, so styles never leak between pieces or
  * into the hosting page). The whole overlay hides while the game is not
  * simulating (pause / editor edit mode).
+ *
+ * Screen pieces are singletons by name (show/hide). An Anchored Piece is
+ * one more instance of a piece that follows an entity (attach), in a layer
+ * below every screen piece — see ADR 0018.
  */
 export class GameUi {
     stats;
     host;
     sources = new Map();
     pieces = new Map();
+    anchored;
     overlay;
     active = true;
     constructor(stats, 
@@ -22,6 +35,11 @@ export class GameUi {
     host) {
         this.stats = stats;
         this.host = host;
+        this.anchored = new AnchoredPieces({
+            stats,
+            source: (name) => this.sources.get(name),
+            overlay: () => this.mountOverlay(),
+        });
     }
     /** Registers a piece's HTML source. Re-defining an unmounted name wins. */
     define(name, html) {
@@ -35,6 +53,10 @@ export class GameUi {
     names() {
         return [...this.sources.keys()];
     }
+    /** Whether a piece of this name is defined — `names().includes(name)` without building the list. */
+    has(name) {
+        return this.sources.has(name);
+    }
     show(name, options = {}) {
         const mounted = this.pieces.has(name);
         const piece = this.mount(name);
@@ -73,6 +95,16 @@ export class GameUi {
     element(name) {
         return this.mount(name)?.root ?? null;
     }
+    /**
+     * Anchors a new instance of the piece to `entity` (issue #72): its own
+     * shadow root and values, placed every render frame at the entity's
+     * render point plus `offset`. Every call is a new instance; the screen
+     * piece of the same name is never touched. An undefined piece or a dead
+     * entity warns and returns an inert handle — it never throws.
+     */
+    attach(piece, entity, options = {}) {
+        return this.anchored.attach(piece, entity, options);
+    }
     /** Called by the game loop: the overlay only draws while simulating. */
     setActive(active) {
         if (this.active === active)
@@ -80,23 +112,26 @@ export class GameUi {
         this.active = active;
         this.sync();
     }
-    /** Unmounts every piece and removes the overlay (Game.dispose). */
+    /** Unmounts every piece and Anchored Piece and removes the overlay (Game.dispose). */
     dispose() {
         for (const piece of this.pieces.values()) {
             for (const off of piece.unsubs)
                 off();
         }
         this.pieces.clear();
+        this.anchored.dispose();
         this.overlay?.remove();
         this.overlay = undefined;
     }
     /**
      * Unmounts every scene-scoped piece: the ones `loadScene` showed from the
      * outgoing scene's `ui` list, plus any shown with `{ scope: 'scene' }`.
-     * A piece the host showed with no scope is untouched. The definition
-     * catalog (sources) always survives — Game.unloadScene.
+     * A piece the host showed with no scope is untouched. Every Anchored
+     * Piece goes too, lingering ones included: none outlives its scene. The
+     * definition catalog (sources) always survives — Game.unloadScene.
      */
     unloadScene() {
+        this.anchored.clear();
         for (const [name, piece] of this.pieces) {
             if (piece.scope !== 'scene')
                 continue;
@@ -107,6 +142,10 @@ export class GameUi {
         }
         this.sync();
     }
+    /** Engine-internal: see anchoredPiecesOf. */
+    [ANCHORED]() {
+        return this.anchored;
+    }
     mount(name) {
         const existing = this.pieces.get(name);
         if (existing)
@@ -158,50 +197,20 @@ export class GameUi {
         }
     }
 }
-const BINDING = /\{\{\s*([\w-]+)\s*\}\}/g;
-function renderStat(value) {
-    if (value === undefined)
-        return '';
-    if (typeof value === 'boolean')
-        return value ? '✓' : '✕';
-    return String(value);
+/**
+ * Engine-internal: the anchored layer behind `ui.attach`, which the Game
+ * connects to its camera and viewport and places every render frame.
+ */
+export function anchoredPiecesOf(ui) {
+    return ui[ANCHORED]();
 }
 /**
- * Replaces {{stat}} placeholders in the fragment's text with reactive text
- * nodes kept in sync with the stats. Text-only by design: the binding
- * language has no expressions — presentation, never logic.
+ * Fills each {{stat}} placeholder with the stat's value and keeps it in
+ * sync; returns the unsubscribes.
  */
 function bindStats(root, stats) {
-    const unsubs = [];
-    const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
-    const targets = [];
-    for (let node = walker.nextNode(); node; node = walker.nextNode()) {
-        // Braces inside <style>/<script> are CSS/code, not bindings.
-        if (node.parentElement?.closest('style, script'))
-            continue;
-        if ((node.nodeValue ?? '').includes('{{'))
-            targets.push(node);
-    }
-    for (const text of targets) {
-        const source = text.nodeValue ?? '';
-        const parts = [];
-        let last = 0;
-        for (const match of source.matchAll(BINDING)) {
-            const stat = match[1];
-            if (stat === undefined)
-                continue;
-            if (match.index > last)
-                parts.push(document.createTextNode(source.slice(last, match.index)));
-            const bound = document.createTextNode(renderStat(stats.get(stat)));
-            unsubs.push(stats.onChange(stat, (value) => (bound.nodeValue = renderStat(value))));
-            parts.push(bound);
-            last = match.index + match[0].length;
-        }
-        if (parts.length === 0)
-            continue;
-        if (last < source.length)
-            parts.push(document.createTextNode(source.slice(last)));
-        text.replaceWith(...parts);
-    }
-    return unsubs;
+    return placeholders(root).map(([stat, text]) => {
+        text.nodeValue = renderStat(stats.get(stat));
+        return stats.onChange(stat, (value) => (text.nodeValue = renderStat(value)));
+    });
 }

package/package.json

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