@waica/engine 0.15.0 → 0.17.0

package/README.md

@@ -170,3 +170,57 @@ class PathFinder extends Component {
 ```
 
 The return value still passes through the bounded safe projector; it is not serialized with arbitrary `toJSON()`. The package root exports the Runtime Snapshot, projection marker, metadata, control and activation types plus `RUNTIME_BRIDGE_PROTOCOL_VERSION` and `RUNTIME_PROJECTION_LIMITS`.
+
+## game.time: simulated timers and tweens
+
+Every `Game` owns a `time: GameTime` service — `after`, `every`, a single-number `tween`, and a `now` reader — advanced only by Simulation Steps (ADR 0014), never by the wall clock:
+
+```ts
+const stun = game.time.after(0.3, () => fsm.goto('idle'), { owner: entity })
+game.time.every(1, () => game.stats.set('clock', game.time.now), { scope: 'session' })
+game.time.tween({
+  from: 0, to: 1, seconds: 0.5, easing: 'quadOut',
+  onUpdate: (v) => { overlay.opacity = v },
+  onComplete: () => game.loadSceneByName('b'),
+  owner: entity,
+})
+stun.remaining // seconds left, counting down
+game.time.now  // seconds of Game Time since the Game started
+```
+
+- **`after(seconds, callback, options?)`** runs `callback` once, `seconds` of Game Time later (0 or a negative duration: the start of the next step). **`every(seconds, callback, options?)`** runs it every `max(seconds, 1/60)`, first one interval after creation, with no drift. **`tween(options)`** carries `from` to `to` over `seconds`, calling `onUpdate(value)` synchronously on creation and again on every later step, finishing with exactly `to` then `onComplete()`. Easing is `'linear'` (default), `'quadIn'`/`'quadOut'`/`'quadInOut'`, `'cubicIn'`/`'cubicOut'`/`'cubicInOut'`, `'sineInOut'`, or a custom `(t) => number`.
+- All three return a `TimerHandle`: `cancel()`, `active`, `elapsed`, `remaining` (seconds of Game Time). `cancel()` — and owner/scene cancellation — leaves a tween's last applied value in place and never calls `onComplete`.
+- **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/entity.js

@@ -55,6 +55,10 @@ export class Entity {
         if (this.destroyed)
             return;
         this.destroyed = true;
+        // Immediately, before any onDestroy hook runs, whatever the scope
+        // (ADR 0017, CA-5) — `alive` is already false by the time any of this
+        // entity's own timers/tweens could observe it.
+        this.game.time.cancelOwnedBy(this);
         for (const c of [...this.components])
             c.onDestroy?.();
         this.components.length = 0;