@waica/engine 0.15.0 → 0.17.0

package/dist/game.js

@@ -1,4 +1,5 @@
 import * as THREE from 'three';
+import { gameViewport } from './anchored-pieces.js';
 import { AudioSubsystem } from './audio/audio-subsystem.js';
 import { dispatchCollisions as dispatchHitboxCollisions } from './collision-dispatch.js';
 import { isCameraVelocityProvider, resolveSceneCamera, stepSceneCamera, } from './camera.js';
@@ -6,6 +7,7 @@ import { resolveComponentUpdateSchedule } from './component-update-schedule.js';
 import { Entity } from './entity.js';
 import { Emitter } from './events.js';
 import { consumeSimulationSteps, MAX_CHAINED_HOPS, SIMULATION_STEP, snapElapsedToStep, } from './fixed-step.js';
+import { advanceGameTime, GameTime } from './game-time.js';
 import { Input } from './input.js';
 import { Pointer } from './pointer.js';
 import { activeRuntimeBridgeHook, EngineRuntimeBridge, } from './runtime-bridge.js';
@@ -15,7 +17,7 @@ import { isYSortParticipant, ySortZ } from './render-sort.js';
 import { loadScene, registryEntry, spawnFromJson, } from './scene.js';
 import { createSpatialQuery } from './spatial-query.js';
 import { Stats } from './stats.js';
-import { GameUi } from './ui.js';
+import { anchoredPiecesOf, GameUi } from './ui.js';
 /**
  * Engine core: loop, unified 2D/3D three scene, orthographic camera,
  * entities with components, and input. See DESIGN.md.
@@ -33,6 +35,8 @@ export class Game {
     ui;
     /** The audio mixer: channels, master, playback. See ADR 0012, ADR 0013. */
     audio;
+    /** Simulated scheduling: `after`, `every`, `tween`, `now`. See ADR 0017. */
+    time = new GameTime();
     /** Registry retained by loadScene for runtime prefab spawning. */
     registry = null;
     paramOverrides = {};
@@ -85,6 +89,11 @@ export class Game {
         this.query = createSpatialQuery(this);
         this.stats = new Stats(options.stats);
         this.ui = new GameUi(this.stats, () => canvas.parentElement ?? document.body);
+        anchoredPiecesOf(this.ui).connect(() => ({
+            camera: this.camera,
+            viewport: gameViewport(canvas.clientWidth, canvas.clientHeight, this.resolution),
+            projection: this.sceneProjection,
+        }));
         this.audio = new AudioSubsystem({
             canvas,
             backend: options.audio,
@@ -148,6 +157,9 @@ export class Game {
     unloadScene() {
         this.ui.unloadScene();
         this.audio.unloadScene();
+        // Scene-scoped timers/tweens die here too (ADR 0017): before entities are
+        // destroyed below, so an owner's own destroy() cancellation is a no-op.
+        this.time.cancelSceneScoped();
         // An explicit unload means "no scene": a swap queued earlier this frame
         // would otherwise flush next frame and resurrect one.
         this.pendingSceneLoad = null;
@@ -312,8 +324,9 @@ export class Game {
     stop() {
         this.renderer.setAnimationLoop(null);
     }
-    /** Internal: called by Entity.destroy(). */
+    /** Internal: called by Entity.destroy(). Its Anchored Pieces go (or freeze) with it. */
     removeEntity(entity) {
+        anchoredPiecesOf(this.ui).release(entity);
         const i = this.entities.indexOf(entity);
         if (i !== -1)
             this.entities.splice(i, 1);
@@ -339,6 +352,9 @@ export class Game {
         this.resizeObserver.disconnect();
         this.ui.dispose();
         this.audio.dispose();
+        // Cancels both scopes, including session-scoped work no entity owns
+        // (entity.destroy() below only ever reaches owned work) — ADR 0017.
+        this.time.cancelAll();
         for (const entity of [...this.entities])
             entity.destroy();
         this.renderer.dispose();
@@ -429,11 +445,13 @@ export class Game {
         }
     }
     /**
-     * One Simulation Step: the Component Update Schedule (ADR 0004) in full,
+     * One Simulation Step: game.time's start-of-step pass (ADR 0017, CA-3)
+     * first, then the Component Update Schedule (ADR 0004) in full,
      * collisions, the scene camera and the host's callbacks, every one of
      * them handed exactly SIMULATION_STEP (CA-1); then the input frame ends.
      */
     simulateStep() {
+        advanceGameTime(this.time);
         for (const entity of [...this.entities]) {
             const schedule = this.componentUpdateSchedule(entity);
             if (!schedule)
@@ -500,6 +518,7 @@ export class Game {
         if (this.renderSort === 'y')
             this.applyYSort();
         this.ui.setActive(this.simulate);
+        anchoredPiecesOf(this.ui).place();
         if (this.resolution) {
             // Letterbox bars: clear the whole canvas, then render inside the scissor.
             this.renderer.setScissorTest(false);

package/dist/index.d.ts

@@ -14,6 +14,8 @@ export { spritePlacement } from './sprite-placement.js';
 export type { SpritePlacement, SpritePlacementInput } from './sprite-placement.js';
 export { CAMERA_DEFAULTS, isCameraVelocityProvider, resolveSceneCamera, stepSceneCamera } from './camera.js';
 export { SIMULATION_STEP, SIMULATION_TIME_EPSILON } from './fixed-step.js';
+export { GameTime, advanceGameTime } from './game-time.js';
+export type { EasingName, TimerHandle, TimerOptions, TweenOptions } from './game-time.js';
 export type { SceneCameraJson, CameraLimitsJson, CameraVelocity, CameraVelocityProvider, ResolvedSceneCamera, } from './camera.js';
 export { Entity } from './entity.js';
 export { Component } from './component.js';
@@ -30,11 +32,12 @@ export type { PointerCamera, PointerDeps, PointerPick, PointerResolution } from
 export { RUNTIME_BRIDGE_CAPABILITIES, RUNTIME_BRIDGE_PROTOCOL_VERSION, RUNTIME_BRIDGE_SYMBOL, RuntimeBridgeOperationError, } from './runtime-bridge.js';
 export type { RuntimeBridge, RuntimeBridgeActivation, RuntimeControlRequest, RuntimeControlResult, RuntimeMetadata, RuntimeMode, } from './runtime-bridge.js';
 export { RUNTIME_PROJECTION_LIMITS } from './runtime-inspection.js';
-export type { ProjectedValue, ProjectionIssue, ProjectionMarker, ProjectionMarkerKind, RuntimeComponentSnapshot, RuntimeEntitySnapshot, RuntimeSnapshot, RuntimeSnapshotAudio, RuntimeSnapshotFilters, RuntimeTransformSnapshot, } from './runtime-inspection.js';
+export type { ProjectedValue, ProjectionIssue, ProjectionMarker, ProjectionMarkerKind, RuntimeComponentSnapshot, RuntimeEntitySnapshot, RuntimeSnapshot, RuntimeSnapshotAudio, RuntimeSnapshotFilters, RuntimeSnapshotTime, RuntimeSnapshotUi, RuntimeTransformSnapshot, } from './runtime-inspection.js';
 export type { ArchetypeArt, ArchetypeManifest, BrowserArchetypeManifest, EntityTemplate, } from './archetype.js';
 export { Stats } from './stats.js';
 export type { StatValue } from './stats.js';
 export { GameUi } from './ui.js';
+export type { AnchoredPieceHandle, AttachOptions } from './anchored-pieces.js';
 export { Sprite } from './components/sprite.js';
 export { Solid } from './components/solid.js';
 export { Hitbox } from './components/hitbox.js';

package/dist/index.js

@@ -6,6 +6,7 @@ export { projectIsometric, screenInputToLogical, unprojectIsometric } from './pr
 export { spritePlacement } from './sprite-placement.js';
 export { CAMERA_DEFAULTS, isCameraVelocityProvider, resolveSceneCamera, stepSceneCamera } from './camera.js';
 export { SIMULATION_STEP, SIMULATION_TIME_EPSILON } from './fixed-step.js';
+export { GameTime, advanceGameTime } from './game-time.js';
 export { Entity } from './entity.js';
 export { Component } from './component.js';
 export { authoringDefaults } from './authoring-defaults.js';

package/dist/input.d.ts

@@ -24,6 +24,12 @@ export declare class Input {
     justPressed(action: ActionName): boolean;
     /** Installed semantic action names in deterministic order. */
     availableActions(): ActionName[];
+    /**
+     * 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: ActionName): string[];
     /** Currently held semantic action names in deterministic order. */
     heldActions(): ActionName[];
     /** Injects an action by semantic name; false means the action is not installed. */

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

@@ -65,6 +65,47 @@ export interface RuntimeSnapshotAudio {
     channels: Record<string, AudioChannelState>;
     playing: LiveSoundInfo[];
 }
+/**
+ * `game.time`'s pending work (CA-10), beside `audio`: `pending` counts
+ * active timers plus active tweens across both scopes; `nextInSteps` is the
+ * smallest positive integer n such that `step { frames: n }` makes an
+ * active timer run or an active tween complete, or null when `pending` is
+ * 0. Emitted unconditionally, like `audio` — never filtered, and never
+ * repeats `now` (metadata already carries `simulationTime`). That promise
+ * holds only while the Game is simulating: `runFrame` runs zero steps with
+ * `simulate === false` (`game.ts`), so on a Game that is paused AND not
+ * simulating, `nextInSteps` is still reported but stepping never consumes
+ * it — a Run Session starts with `simulate === true`, so this only matters
+ * if project code flips it.
+ */
+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. */
@@ -72,6 +113,8 @@ export interface RuntimeSnapshot extends RuntimeMetadata {
     entities: RuntimeEntitySnapshot[];
     projectionIssues: ProjectionIssue[];
     audio: RuntimeSnapshotAudio;
+    time: RuntimeSnapshotTime;
+    ui: RuntimeSnapshotUi;
 }
 export declare const RUNTIME_PROJECTION_LIMITS: {
     readonly depth: 5;
@@ -87,6 +130,8 @@ export declare class RuntimeInspector {
     constructor(game: Game);
     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();
@@ -238,6 +270,8 @@ export class RuntimeInspector {
             entities,
             projectionIssues,
             audio: this.audioSnapshot(),
+            time: this.timeSnapshot(),
+            ui: this.uiSnapshot(projectionIssues),
         });
     }
     audioSnapshot() {
@@ -251,10 +285,27 @@ export class RuntimeInspector {
             playing: this.game.audio.liveSounds(),
         };
     }
+    timeSnapshot() {
+        return {
+            pending: this.game.time.pending,
+            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) {
@@ -265,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/scene.js

@@ -85,8 +85,17 @@ export function spawnFromJson(game, json, registry) {
  * at a time.
  */
 export function loadScene(game, scene, registry) {
-    if (game.registry)
+    if (game.registry) {
         game.unloadScene();
+    }
+    else {
+        // unloadScene() would otherwise be skipped on a Game's first load
+        // (F11), leaving a scene-scoped timer/tween created before it — a boot
+        // clock, say — to survive this load and die only at the next one
+        // instead. Cancel that slice of unloadScene()'s work directly; there is
+        // no scene, UI or audio yet for the rest of it to touch (ADR 0017, CA-4).
+        game.time.cancelSceneScoped();
+    }
     game.registry = registry;
     game.setSceneRender(scene.render);
     for (const entityJson of scene.entities)

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)));
+    });
 }