@waica/engine 0.16.0 → 0.17.0

package/README.md

@@ -193,3 +193,34 @@ game.time.now  // seconds of Game Time since the Game started
 - **Step placement.** At the start of every Simulation Step, before the Component Update Schedule, `game.time` advances `now`, runs every due timer (due time, then creation order), then advances every tween that existed before that step (creation order). Work a callback creates is never run or advanced in that same step.
 - **Scope.** A timer or tween is scene-scoped by default: `unloadScene()` and every scene load — including a Game's first — cancel it, running no callback. `{ scope: 'session' }` survives a scene change. `{ owner: entity }` cancels it immediately when that entity is destroyed, whatever its scope; an owner already dead at scheduling time yields an inactive handle. `game.dispose()` cancels everything in both scopes. This is the opposite default from `game.onUpdate`/`game.events` (ADR 0011), which survive a scene change by construction, and the same one `game.audio.play()` uses (ADR 0012) — see ADR 0017 for why timers follow audio's rule rather than the host-subscription one: a timer's callback almost always closes over the scene that scheduled it.
 - **No Promises.** Nothing here returns one, and nothing is async — a `.then` continuation is not step-exact (it runs after the whole synchronous frame), which is exactly what `game.time` exists to avoid. Compose delays with `after`, not `await`.
+
+## game.ui.attach: Anchored Pieces
+
+A UI Piece shown with `game.ui.show(name)` is a screen-space singleton. `game.ui.attach(piece, entity, options?)` instead creates an **Anchored Piece**: a new instance of the piece that follows `entity` across the screen, with its own shadow root and its own values. Every call is a new instance — five orcs can each carry a `health-bar` — and the screen piece of the same name is never mounted, shown or changed by it.
+
+```ts
+const hit = game.ui.attach('damage-number', orc, { offset: [0, 1.2], seconds: 0.8, values: { amount: 3 } })
+const bar = game.ui.attach('health-bar', orc, { offset: [0, 1.4], values: { current: 7, max: 10 } })
+bar.set('current', 6) // {{current}} and --current update live
+bar.remove()
+```
+
+```html
+<style>
+  .bar { position: absolute; transform: translate(-50%, -100%); width: calc(1.2 * var(--waica-unit)); height: 4px; background: #0008 }
+  .fill { width: calc(var(--current) / var(--max) * 100%); height: 100%; background: #ef476f }
+</style>
+<div class="bar"><div class="fill"></div></div>
+```
+
+- **Options.** `offset: [x, y]` (default `[0, 0]`) is in world units, added to the entity's render point in render space: `[0, 1]` is one unit up on screen, under `projection: 'isometric'` too. `seconds` gives the instance its own lifetime (below). `values` are the instance's own values.
+- **Handle.** `set(name, value)`, `remove()`, `alive` and `element` — the piece's content root inside the instance's shadow root, `null` once removed.
+- **Placement.** Once per render frame — after the isometric projection and the camera step, before the render, never per Simulation Step — each instance's shadow host is placed as a zero-size box at its anchor point, converted to whole CSS pixels from the top-left corner of the game viewport; the piece's own CSS centres itself around that point (e.g. `transform: translate(-50%, -100%)`). A move therefore shows on the next frame, not before. All instances live in one layer fitted to the game viewport — the whole canvas, or the letterboxed rectangle under a fixed `resolution` — with `overflow: hidden`, so they never draw over the letterbox bars.
+- **Per-instance values.** Inside an instance, `{{name}}` renders the instance's own value when it has one and the Game stat of that name otherwise (booleans as ✓/✕, missing as empty); `set` updates it in place, and a stat change still updates every placeholder with no instance value. Every number value is also published as the custom property `--name` on the instance (`values: { current: 7, max: 10 }` gives `--current: 7` and `--max: 10`), booleans as `1`/`0`; strings are text only. There are no binding expressions: arithmetic belongs in CSS `calc()`.
+- **`--waica-unit`.** Every frame, the anchored layer carries `--waica-unit` inline, and every instance inherits it through its shadow host: CSS pixels per world unit, the game viewport's CSS height divided by the current view height. It follows camera zoom and the letterbox scale, so `calc(1.1 * var(--waica-unit))` sizes a piece in world units while everything else keeps its CSS pixel size.
+- **Draw order.** The anchored layer sits below every screen-space piece. Within it, every frame, the instance lower on screen draws on top, like y-sort; equal heights keep creation order, later on top.
+- **Lifetime.** Without `seconds`, an instance is removed before its entity's `destroy()` returns. With `seconds: S`, it is removed exactly when a `game.time.after(S, …)` scheduled at the same moment would fire — it counts Game Time (ADR 0017), so it never runs out while the Game is paused or not simulating, and until then it counts in `game.time.pending`. If its entity is destroyed first, it lingers frozen where the entity was at `destroy()` time (still moving with the camera) until it expires. `unloadScene()`, every scene load that unloads and `game.dispose()` remove every instance: none outlives its scene. `remove()` is immediate; `set` and `remove` on a removed handle are silent no-ops. CSS animations and transitions inside an instance follow Game Time, not the wall clock: every frame each is paused at the Game Time since it started (the attach, for those the piece starts with), so a paused Game freezes a damage number mid-flight — it resumes from there, even after the overlay hid while not simulating — and `step { frames: N }` advances it by N/60 s.
+- **Invalid attach never throws.** An undefined piece name logs one `[waica]` warning per name per Game; an entity that is no longer `alive` logs one per call. Both return a handle with `alive: false` and `element: null` that mounts nothing. To attach only when the project defines the piece, as `Interactable` does with `npc-bubble` and `interact-prompt`, check `game.ui.has(name)` first.
+- **Runtime Snapshot.** Every snapshot carries `ui: { shown, anchored }`: the visible screen pieces by name, and each live instance in creation order as `{ piece, entity, x, y, clipped, values }`, with the pixel coordinates of its last placement; `values` are bounded like component state (a string over 4 KiB becomes a `$waica: 'truncated'` marker), and once every entity is cut the 1 MiB snapshot cap drops instances from the end.
+
+The trade-off is ADR 0018's: Anchored Pieces are HTML drawn over the game view, not text rendered in the three scene. They always draw above the world — a label behind a tree draws over it — hide with the rest of the UI overlay while the Game is not simulating (including the editor's edit mode), and do not align to a pixel-art grid.

package/dist/anchored-pieces.d.ts

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

package/dist/anchored-pieces.js

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

package/dist/component.d.ts

@@ -12,7 +12,7 @@ export interface ParamSpec {
     /** Allowed values for a string param; rendered as a dropdown. Takes precedence over ref. */
     options?: string[];
     /** Project value this string param names; rendered and validated as a typed reference. */
-    ref?: 'prefab' | 'stat' | 'action' | 'clip' | 'sound';
+    ref?: 'prefab' | 'stat' | 'action' | 'clip' | 'sound' | 'ui';
 }
 export interface ComponentClass<T extends Component = Component> {
     new (): T;

package/dist/game.d.ts

@@ -171,7 +171,7 @@ export declare class Game {
     setSceneCamera(json?: SceneCameraJson): void;
     start(): void;
     stop(): void;
-    /** Internal: called by Entity.destroy(). */
+    /** Internal: called by Entity.destroy(). Its Anchored Pieces go (or freeze) with it. */
     removeEntity(entity: Entity): void;
     /** The scene's render projection; null keeps logical and render space identical. */
     get projection(): 'isometric' | null;

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';
@@ -16,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.
@@ -88,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,
@@ -318,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);
@@ -511,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

@@ -32,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, RuntimeSnapshotTime, 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/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

@@ -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.17.0",
   "description": "Waica game engine core — archetype-driven, web-first, 2D & 3D",
   "license": "MIT",
   "type": "module",