@waica/behaviors 0.15.0 → 0.17.0

package/dist/anchor-height.d.ts

@@ -0,0 +1,10 @@
+import { type Entity } from '@waica/engine';
+/**
+ * How far above its entity a behavior's Anchored Piece is attached
+ * (issue #72, CA-14): the top edge of the entity's first Sprite or
+ * AnimatedSprite box — the box the pointer picks against, so
+ * `offsetY + height × (1 − anchorY)` — plus a small margin, or one world
+ * unit when it has neither. Read at attach time; no behavior carries a
+ * height param of its own.
+ */
+export declare function anchorHeight(entity: Entity): number;

package/dist/anchor-height.js

@@ -0,0 +1,21 @@
+import { AnimatedSprite, Sprite } from '@waica/engine';
+/** World units left between the top of the sprite box and an Anchored Piece. */
+const ANCHOR_MARGIN = 0.2;
+/** Where an Anchored Piece sits on an entity that draws no sprite. */
+const SPRITELESS_ANCHOR_HEIGHT = 1;
+/**
+ * How far above its entity a behavior's Anchored Piece is attached
+ * (issue #72, CA-14): the top edge of the entity's first Sprite or
+ * AnimatedSprite box — the box the pointer picks against, so
+ * `offsetY + height × (1 − anchorY)` — plus a small margin, or one world
+ * unit when it has neither. Read at attach time; no behavior carries a
+ * height param of its own.
+ */
+export function anchorHeight(entity) {
+    for (const component of entity.components) {
+        if (component instanceof Sprite || component instanceof AnimatedSprite) {
+            return component.offsetY + component.height * (1 - component.anchorY) + ANCHOR_MARGIN;
+        }
+    }
+    return SPRITELESS_ANCHOR_HEIGHT;
+}

package/dist/anchored-ui-pieces.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The names of the stock Anchored Pieces (issue #72, ADR 0018): every piece
+ * these behaviors ship except npc-line, the screen-space fallback. Their
+ * `{{bindings}}` are per-instance values, not Game stats, so tooling such as
+ * validate_project reads this list to tell them apart.
+ */
+export declare const ANCHORED_UI_PIECES: readonly string[];

package/dist/anchored-ui-pieces.js

@@ -0,0 +1,12 @@
+import { HEALTH_UI } from './health-ui.js';
+import { INTERACTABLE_UI, INTERACTABLE_UI_PIECE } from './interactable.js';
+/**
+ * The names of the stock Anchored Pieces (issue #72, ADR 0018): every piece
+ * these behaviors ship except npc-line, the screen-space fallback. Their
+ * `{{bindings}}` are per-instance values, not Game stats, so tooling such as
+ * validate_project reads this list to tell them apart.
+ */
+export const ANCHORED_UI_PIECES = Object.freeze([
+    ...Object.keys(INTERACTABLE_UI).filter((name) => name !== INTERACTABLE_UI_PIECE),
+    ...Object.keys(HEALTH_UI),
+]);

package/dist/click-to-move.js

@@ -1,5 +1,5 @@
 import { Component, Sprite, screenInputToLogical, } from '@waica/engine';
-import { fireInteract, INTERACTABLE_UI_PIECE, Interactable } from './interactable.js';
+import { Interactable, interactWith } from './interactable.js';
 import { Health } from './health.js';
 import { MeleeAttack } from './melee-attack.js';
 import { buildNavigationGrid } from './navigation-grid.js';
@@ -198,10 +198,8 @@ function driveNpcOrder(clickToMove, entity, game, order) {
         return null;
     }
     if (distance(pointOf(entity), pointOf(target)) <= interactable.radius) {
-        game.stats.set('npcLine', interactable.line);
-        // Scene-scoped, same reason as interactUpdate's prompt (grill decision 8).
-        game.ui.show(INTERACTABLE_UI_PIECE, { scope: 'scene' });
-        fireInteract(target, entity);
+        // The interact key's own path: bubble or npc-line, npcLine, onInteract (grill S8).
+        interactWith(game, entity, target, interactable);
         clickToMove.cancel(); // CA-5: one trigger per arrival, no key simulated
         return null;
     }

package/dist/health-ui.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The stock Anchored Pieces (issue #72, ADR 0018) a Health can name
+ * through its damageNumber and healthBar params. Registering them only
+ * makes them available: nothing shows until a Health names one. Each draws
+ * itself above its zero-size anchor box, centred on it.
+ *
+ * damage-number reads the hit's `{{amount}}` and rises and fades over the
+ * 0.8 s the instance lives. health-bar has no text at all: it is driven by
+ * the `--current` / `--max` custom properties its instance publishes, and
+ * is one world unit wide (`--waica-unit`) at any zoom.
+ */
+export declare const HEALTH_UI: Readonly<Record<string, string>>;

package/dist/health-ui.js

@@ -0,0 +1,70 @@
+/**
+ * The stock Anchored Pieces (issue #72, ADR 0018) a Health can name
+ * through its damageNumber and healthBar params. Registering them only
+ * makes them available: nothing shows until a Health names one. Each draws
+ * itself above its zero-size anchor box, centred on it.
+ *
+ * damage-number reads the hit's `{{amount}}` and rises and fades over the
+ * 0.8 s the instance lives. health-bar has no text at all: it is driven by
+ * the `--current` / `--max` custom properties its instance publishes, and
+ * is one world unit wide (`--waica-unit`) at any zoom.
+ */
+export const HEALTH_UI = {
+    'damage-number': `<style>
+  .damage-number {
+    position: absolute;
+    left: 0;
+    bottom: 0;
+    transform: translate(-50%, 0);
+    width: max-content;
+    font: 800 20px/1 system-ui, sans-serif;
+    color: #ff5d73;
+    white-space: nowrap;
+    text-shadow: 0 2px 0 #000, 0 0 4px #000c;
+    pointer-events: none;
+    user-select: none;
+    animation: damage-number-rise 0.8s ease-out forwards;
+  }
+  @keyframes damage-number-rise {
+    from {
+      transform: translate(-50%, 0) scale(1.25);
+      opacity: 1;
+    }
+    60% {
+      opacity: 1;
+    }
+    to {
+      transform: translate(-50%, calc(-0.8 * var(--waica-unit, 40px))) scale(1);
+      opacity: 0;
+    }
+  }
+</style>
+<div class="damage-number">-{{amount}}</div>
+`,
+    'health-bar': `<style>
+  .health-bar {
+    position: absolute;
+    left: 0;
+    bottom: 0;
+    transform: translate(-50%, 0);
+    box-sizing: border-box;
+    width: var(--waica-unit, 40px);
+    height: 7px;
+    padding: 1px;
+    border-radius: 4px;
+    background: #1a1a2ecc;
+    border: 1px solid #ffffff2e;
+    pointer-events: none;
+    user-select: none;
+  }
+  .health-bar-fill {
+    width: calc(var(--current) / var(--max) * 100%);
+    height: 100%;
+    border-radius: 2px;
+    background: #ef476f;
+    transition: width 0.15s ease-out;
+  }
+</style>
+<div class="health-bar"><div class="health-bar-fill"></div></div>
+`,
+};

package/dist/health.d.ts

@@ -49,6 +49,14 @@ export declare class Health extends Component {
             label: string;
             ref: 'sound';
         };
+        damageNumber: {
+            label: string;
+            ref: 'ui';
+        };
+        healthBar: {
+            label: string;
+            ref: 'ui';
+        };
     };
     static transient: string[];
     max: number;
@@ -61,14 +69,35 @@ export declare class Health extends Component {
     stat: string;
     /** Sound played at this entity's position on every accepted hit. Empty plays nothing (CA-12). */
     hurtSound: string;
+    /** UI piece shown over this entity on every accepted hit, with `{{amount}}`. Empty shows nothing. */
+    damageNumber: string;
+    /** UI piece shown over this entity below max health, with `{{current}}`/`{{max}}`. Empty shows nothing. */
+    healthBar: string;
     /** Health left; 0 is dead. Filled in from max on ready. */
     current: number;
     /** Whoever dealt the last accepted hit, for the state that reacts to it. */
     lastDamageSource: Entity | undefined;
-    /** Seconds left in the invulnerability window. */
-    private invulnerable;
-    /** Seconds into the current blink, for the 10 Hz toggle. */
-    private blinkClock;
+    /**
+     * The open invulnerability window, on `game.time`. Null once
+     * `closeWindow()` has run. A window ended by owner destroy or scene
+     * unload instead of a natural close never runs `closeWindow()` — cancellation
+     * runs no callback — so this can also be present but inactive; `blinking`
+     * and `inspectState().invulnerable` both read through `.active`/`.remaining`,
+     * so that case still reports correctly.
+     */
+    private windowHandle;
+    /**
+     * The 10 Hz blink toggle, on `game.time`. Null once `closeWindow()` has
+     * run, same asymmetry as `windowHandle`: a window cancelled by owner
+     * destroy or scene unload leaves this present but inactive instead.
+     */
+    private blinkHandle;
+    /**
+     * The healthBar instance while the entity is hurt but alive (issue #72,
+     * CA-15); null at full health, at 0 and before the first hit. One the
+     * engine removed with its entity or its scene reads `alive: false`.
+     */
+    private healthBarHandle;
     /** Whether the node is being flashed: exactly while a window is open. */
     get blinking(): boolean;
     /** Whether the signalled death must be checked on this component's next update. */
@@ -82,7 +111,7 @@ export declare class Health extends Component {
      */
     inspectState(): Record<string, unknown>;
     onReady(): void;
-    onUpdate(dt: number): void;
+    onUpdate(): void;
     /**
      * Makes good on a death the graph said it would handle. Signalling is
      * fire-and-forget, so "it declared an edge" is a promise, not a receipt:
@@ -103,11 +132,41 @@ export declare class Health extends Component {
     /** Mirrors current into the named stat, when one is named. */
     private publish;
     /**
-     * Flashes the node at 10 Hz for as long as the window stays open, and
-     * leaves it visible the frame the window closes — the flash is feedback,
-     * never a state a hit can leave the entity stuck in.
+     * Floats the damageNumber piece over the entity for an accepted hit
+     * (issue #72, CA-13). Called before die(), so a killing blow's number is
+     * already attached when the entity goes, and lingers where it stood for
+     * its own 0.8 s. A non-finite amount (OutOfBounds' Infinity) has no number
+     * worth showing.
+     */
+    private showDamageNumber;
+    /**
+     * Keeps the healthBar piece in step with current (issue #72, CA-15): none
+     * at full health; attached by the first hit that leaves the entity below
+     * max, then updated in place through `set` by every later hit or heal;
+     * removed once current is back at max, or at 0 (die() removes it too).
+     */
+    private syncHealthBar;
+    private removeHealthBar;
+    /**
+     * Opens a fresh invulnerability window on `game.time`, starting visible:
+     * `after(invulnerability)` closes it, and `every(0.1)` flashes the node
+     * at 10 Hz for as long as it stays open (CA-11). `invulnerability <= 0`
+     * schedules nothing and touches no `game.time` at all — the window never
+     * opens. Both are owned by this entity, so `Entity.destroy()` cancels
+     * them immediately mid-window.
+     *
+     * The `invulnerability <= 0` check below runs once, here, before either
+     * handle is touched — it is not re-checked later. So lowering
+     * `invulnerability` to 0 while a window is already open does not close it
+     * early: that window keeps blinking and rejecting damage until it runs
+     * its normal course. Deliberate, not a bug: nothing re-reads
+     * `invulnerability` once a window is open.
      */
-    private blink;
+    private openWindow;
+    /** Cancels the blink and restores visibility the moment the window closes. */
+    private closeWindow;
+    /** The 10 Hz flash while a window is open: openWindow() starts it visible, so a plain toggle lands on the right phase every time. */
+    private toggleBlink;
     /**
      * Announces the death, then lets the role decide — but only if it says it
      * can: a graph with no death edge would swallow the signal silently, so

package/dist/health.js

@@ -1,4 +1,5 @@
-import { Component, SIMULATION_TIME_EPSILON, StateMachine, } from '@waica/engine';
+import { Component, StateMachine, } from '@waica/engine';
+import { anchorHeight } from './anchor-height.js';
 /**
  * Below this, current is treated as exactly zero. Repeated fractional
  * damage (e.g. ten hits of 0.1 against max: 1) can leave a floating-point
@@ -9,6 +10,8 @@ import { Component, SIMULATION_TIME_EPSILON, StateMachine, } from '@waica/engine
 const DEATH_EPSILON = 1e-9;
 /** Seconds each blink phase lasts while invulnerable: 10 Hz on/off. */
 const BLINK_PERIOD = 0.1;
+/** Seconds of Game Time a damage number lives (issue #72, CA-13). */
+const DAMAGE_NUMBER_SECONDS = 0.8;
 /**
  * Where a 'signal:death' from `current` could land: the targets of every
  * death edge on the current state or on '*'. Mirrors the merge
@@ -48,14 +51,17 @@ export class Health extends Component {
         invulnerability: { label: 'Invulnerability', min: 0, max: 5, step: 0.1 },
         stat: { label: 'Stat', ref: 'stat' },
         hurtSound: { label: 'Hurt sound', ref: 'sound' },
+        damageNumber: { label: 'Damage number', ref: 'ui' },
+        healthBar: { label: 'Health bar', ref: 'ui' },
     };
     static transient = [
         'current',
-        'invulnerable',
         'deathPending',
         'expectedStates',
         'lastDamageSource',
-        'blinkClock',
+        'windowHandle',
+        'blinkHandle',
+        'healthBarHandle',
     ];
     max = 3;
     /** Seconds of immunity granted by taking a hit. 0 disables i-frames. */
@@ -67,17 +73,38 @@ export class Health extends Component {
     stat = '';
     /** Sound played at this entity's position on every accepted hit. Empty plays nothing (CA-12). */
     hurtSound = '';
+    /** UI piece shown over this entity on every accepted hit, with `{{amount}}`. Empty shows nothing. */
+    damageNumber = '';
+    /** UI piece shown over this entity below max health, with `{{current}}`/`{{max}}`. Empty shows nothing. */
+    healthBar = '';
     /** Health left; 0 is dead. Filled in from max on ready. */
     current = 0;
     /** Whoever dealt the last accepted hit, for the state that reacts to it. */
     lastDamageSource;
-    /** Seconds left in the invulnerability window. */
-    invulnerable = 0;
-    /** Seconds into the current blink, for the 10 Hz toggle. */
-    blinkClock = 0;
+    /**
+     * The open invulnerability window, on `game.time`. Null once
+     * `closeWindow()` has run. A window ended by owner destroy or scene
+     * unload instead of a natural close never runs `closeWindow()` — cancellation
+     * runs no callback — so this can also be present but inactive; `blinking`
+     * and `inspectState().invulnerable` both read through `.active`/`.remaining`,
+     * so that case still reports correctly.
+     */
+    windowHandle = null;
+    /**
+     * The 10 Hz blink toggle, on `game.time`. Null once `closeWindow()` has
+     * run, same asymmetry as `windowHandle`: a window cancelled by owner
+     * destroy or scene unload leaves this present but inactive instead.
+     */
+    blinkHandle = null;
+    /**
+     * The healthBar instance while the entity is hurt but alive (issue #72,
+     * CA-15); null at full health, at 0 and before the first hit. One the
+     * engine removed with its entity or its scene reads `alive: false`.
+     */
+    healthBarHandle = null;
     /** Whether the node is being flashed: exactly while a window is open. */
     get blinking() {
-        return this.invulnerable > 0;
+        return this.windowHandle?.active ?? false;
     }
     /** Whether the signalled death must be checked on this component's next update. */
     deathPending = false;
@@ -94,7 +121,7 @@ export class Health extends Component {
             invulnerability: this.invulnerability,
             stat: this.stat,
             current: this.current,
-            invulnerable: this.invulnerable,
+            invulnerable: this.windowHandle?.remaining ?? 0,
             blinking: this.blinking,
             lastDamageSource: this.lastDamageSource?.name ?? null,
         };
@@ -110,17 +137,9 @@ export class Health extends Component {
         if (this.current === 0)
             this.die();
     }
-    onUpdate(dt) {
-        if (this.invulnerable > 0) {
-            this.invulnerable = Math.max(0, this.invulnerable - dt);
-            // this.invulnerable is a countdown of SIMULATION_STEP-sized dts, which
-            // float error can leave as a tiny positive residual instead of
-            // exactly 0 on the step that should close the window; without this,
-            // `> 0` above stays true for one whole extra step.
-            if (this.invulnerable <= SIMULATION_TIME_EPSILON)
-                this.invulnerable = 0;
-            this.blink(dt);
-        }
+    onUpdate() {
+        // The invulnerability window and its blink now run entirely on
+        // game.time (ADR 0017, CA-11): this no longer drives either.
         if (this.deathPending) {
             this.deathPending = false;
             this.settleDeath();
@@ -154,13 +173,14 @@ export class Health extends Component {
         // too — every NaN comparison is false, so amount <= 0 lets it through
         // and poisons current (NaN - anything is NaN, and every guard against
         // it is false forever after).
-        if (!(amount > 0) || this.current <= 0 || this.invulnerable > 0)
+        if (!(amount > 0) || this.current <= 0 || this.blinking)
             return;
         this.current = Math.max(0, this.current - amount);
         if (this.current < DEATH_EPSILON)
             this.current = 0;
         this.lastDamageSource = source;
         this.publish();
+        this.syncHealthBar();
         this.game.events.emit('damage', {
             entity: this.entity,
             amount,
@@ -169,8 +189,8 @@ export class Health extends Component {
         });
         if (this.hurtSound)
             this.game.audio.play(this.hurtSound, { at: this.entity });
-        this.invulnerable = this.invulnerability;
-        this.blinkClock = 0;
+        this.showDamageNumber(amount);
+        this.openWindow();
         if (this.current === 0) {
             this.die();
             return;
@@ -185,6 +205,7 @@ export class Health extends Component {
             return;
         this.current = Math.min(this.max, this.current + amount);
         this.publish();
+        this.syncHealthBar();
     }
     /** Mirrors current into the named stat, when one is named. */
     publish() {
@@ -192,31 +213,100 @@ export class Health extends Component {
             this.game.stats.set(this.stat, this.current);
     }
     /**
-     * Flashes the node at 10 Hz for as long as the window stays open, and
-     * leaves it visible the frame the window closes — the flash is feedback,
-     * never a state a hit can leave the entity stuck in.
+     * Floats the damageNumber piece over the entity for an accepted hit
+     * (issue #72, CA-13). Called before die(), so a killing blow's number is
+     * already attached when the entity goes, and lingers where it stood for
+     * its own 0.8 s. A non-finite amount (OutOfBounds' Infinity) has no number
+     * worth showing.
      */
-    blink(dt) {
-        if (this.invulnerable > 0) {
-            this.blinkClock += dt;
-            this.entity.node.visible = Math.floor(this.blinkClock / BLINK_PERIOD) % 2 === 0;
+    showDamageNumber(amount) {
+        if (!this.damageNumber || !Number.isFinite(amount))
+            return;
+        this.game.ui.attach(this.damageNumber, this.entity, {
+            offset: [0, anchorHeight(this.entity)],
+            seconds: DAMAGE_NUMBER_SECONDS,
+            values: { amount },
+        });
+    }
+    /**
+     * Keeps the healthBar piece in step with current (issue #72, CA-15): none
+     * at full health; attached by the first hit that leaves the entity below
+     * max, then updated in place through `set` by every later hit or heal;
+     * removed once current is back at max, or at 0 (die() removes it too).
+     */
+    syncHealthBar() {
+        if (!this.healthBar)
+            return;
+        if (this.current <= 0 || this.current >= this.max) {
+            this.removeHealthBar();
             return;
         }
+        const bar = this.healthBarHandle;
+        if (bar?.alive) {
+            bar.set('current', this.current);
+            bar.set('max', this.max);
+            return;
+        }
+        this.healthBarHandle = this.game.ui.attach(this.healthBar, this.entity, {
+            offset: [0, anchorHeight(this.entity)],
+            values: { current: this.current, max: this.max },
+        });
+    }
+    removeHealthBar() {
+        this.healthBarHandle?.remove();
+        this.healthBarHandle = null;
+    }
+    /**
+     * Opens a fresh invulnerability window on `game.time`, starting visible:
+     * `after(invulnerability)` closes it, and `every(0.1)` flashes the node
+     * at 10 Hz for as long as it stays open (CA-11). `invulnerability <= 0`
+     * schedules nothing and touches no `game.time` at all — the window never
+     * opens. Both are owned by this entity, so `Entity.destroy()` cancels
+     * them immediately mid-window.
+     *
+     * The `invulnerability <= 0` check below runs once, here, before either
+     * handle is touched — it is not re-checked later. So lowering
+     * `invulnerability` to 0 while a window is already open does not close it
+     * early: that window keeps blinking and rejecting damage until it runs
+     * its normal course. Deliberate, not a bug: nothing re-reads
+     * `invulnerability` once a window is open.
+     */
+    openWindow() {
+        if (this.invulnerability <= 0)
+            return;
+        this.entity.node.visible = true;
+        this.windowHandle = this.game.time.after(this.invulnerability, () => this.closeWindow(), { owner: this.entity });
+        this.blinkHandle = this.game.time.every(BLINK_PERIOD, () => this.toggleBlink(), { owner: this.entity });
+    }
+    /** Cancels the blink and restores visibility the moment the window closes. */
+    closeWindow() {
+        this.blinkHandle?.cancel();
+        this.blinkHandle = null;
+        this.windowHandle = null;
         this.entity.node.visible = true;
     }
+    /** The 10 Hz flash while a window is open: openWindow() starts it visible, so a plain toggle lands on the right phase every time. */
+    toggleBlink() {
+        this.entity.node.visible = !this.entity.node.visible;
+    }
     /**
      * Announces the death, then lets the role decide — but only if it says it
      * can: a graph with no death edge would swallow the signal silently, so
      * destroying is the fallback rather than the exception.
      */
     die() {
-        // The killing blow opened a window like any other hit; close it. The
-        // death pose must hold steady, and a revived entity starts without
-        // leftover immunity. The node is visible here by construction: blink()
-        // restores it the frame a window closes, and a lethal hit only lands
-        // while no window is open.
-        this.invulnerable = 0;
-        this.blinkClock = 0;
+        // The killing blow opened a window like any other hit; cancel it here
+        // (running no callback, per game.time's cancel contract) rather than
+        // let it run its course. The death pose must hold steady, and a
+        // revived entity starts without leftover immunity.
+        this.windowHandle?.cancel();
+        this.windowHandle = null;
+        this.blinkHandle?.cancel();
+        this.blinkHandle = null;
+        this.entity.node.visible = true;
+        // Before 'death' goes out, even when a death state keeps the entity
+        // alive: a dead entity shows no bar (CA-15).
+        this.removeHealthBar();
         this.game.events.emit('death', { entity: this.entity });
         const machine = this.entity.get(StateMachine);
         const targets = machine ? deathTargets(machine.states, machine.current) : [];

package/dist/index.d.ts

@@ -13,6 +13,8 @@ export { NPC_ROLE, NPC_STATE_GRAPH } from './npc.js';
 export { Hazard, resolveHazardTouch, type HazardTouch } from './hazard.js';
 export { MeleeAttack } from './melee-attack.js';
 export { Health, declaresDeathHandling, deathTargets } from './health.js';
+export { HEALTH_UI } from './health-ui.js';
+export { ANCHORED_UI_PIECES } from './anchored-ui-pieces.js';
 export { Respawnable } from './respawnable.js';
 export { OutOfBounds } from './out-of-bounds.js';
 export { Lifetime } from './lifetime.js';

package/dist/index.js

@@ -13,6 +13,8 @@ export { NPC_ROLE, NPC_STATE_GRAPH } from './npc.js';
 export { Hazard, resolveHazardTouch } from './hazard.js';
 export { MeleeAttack } from './melee-attack.js';
 export { Health, declaresDeathHandling, deathTargets } from './health.js';
+export { HEALTH_UI } from './health-ui.js';
+export { ANCHORED_UI_PIECES } from './anchored-ui-pieces.js';
 export { Respawnable } from './respawnable.js';
 export { OutOfBounds } from './out-of-bounds.js';
 export { Lifetime } from './lifetime.js';

package/dist/interactable.d.ts

@@ -1,4 +1,4 @@
-import { Component, type Entity, type StateContext } from '@waica/engine';
+import { Component, type Entity, type Game, type StateContext } from '@waica/engine';
 /**
  * Something the player can talk to or examine: a dialogue line and the
  * radius it can be triggered from. The component is pure data — the
@@ -23,7 +23,11 @@ export declare class Interactable extends Component {
     radius: number;
 }
 export declare const INTERACTABLE_UI_PIECE = "npc-line";
-/** The UI fragment every archetype using Interactable must register. */
+/**
+ * The UI fragments every archetype using Interactable must register:
+ * npc-line is the screen-space fallback; npc-bubble and interact-prompt are
+ * Anchored Pieces (ADR 0018), each drawn above its zero-size anchor box.
+ */
 export declare const INTERACTABLE_UI: Readonly<Record<string, string>>;
 /**
  * Runs onInteract on every component of `target` — the winner of the
@@ -33,10 +37,23 @@ export declare const INTERACTABLE_UI: Readonly<Record<string, string>>;
  * fires the same way from either input scheme.
  */
 export declare function fireInteract(target: Entity, initiator: Entity): void;
+/**
+ * `player` interacts with `target`, the NPC its Interactable belongs to.
+ * The one interaction both paths run — the interact key (interactUpdate)
+ * and a ClickToMove arrival (grill S8): publishes the line through the
+ * npcLine stat; shows it in an npc-bubble anchored to the NPC when the
+ * project defines that piece, replacing any bubble already open and
+ * taking the prompt's place (CA-11, CA-12), else in the npc-line screen
+ * piece as before; then fires onInteract.
+ */
+export declare function interactWith(game: Game, player: Entity, target: Entity, interactable: Interactable): void;
 /**
  * The player role's interact lookup, run by its '*' hook in every state:
- * pressing interact near an Interactable publishes its line through the
- * npcLine stat and shows the npc-line UI piece; walking out of every
- * radius hides it again. Nearest one wins when several are in range.
+ * pressing interact near an Interactable interacts with it (interactWith),
+ * and the nearest one in range carries the interact prompt. The bubble
+ * belongs to the nearest Interactable in range too: it closes when another
+ * one becomes the nearest, and walking out of every radius closes it,
+ * removes the prompt and hides npc-line. Nearest one wins when several are
+ * in range.
  */
 export declare function interactUpdate({ entity, game }: StateContext): void;

package/dist/interactable.js

@@ -1,4 +1,5 @@
-import { Component } from '@waica/engine';
+import { Component, } from '@waica/engine';
+import { anchorHeight } from './anchor-height.js';
 /**
  * Something the player can talk to or examine: a dialogue line and the
  * radius it can be triggered from. The component is pure data — the
@@ -16,7 +17,15 @@ export class Interactable extends Component {
     radius = 1.5;
 }
 export const INTERACTABLE_UI_PIECE = 'npc-line';
-/** The UI fragment every archetype using Interactable must register. */
+/** The speech bubble anchored to the NPC, used instead of npc-line when defined (issue #72). */
+const NPC_BUBBLE_PIECE = 'npc-bubble';
+/** The "Press E" prompt anchored to the nearest NPC in range, when defined (issue #72). */
+const INTERACT_PROMPT_PIECE = 'interact-prompt';
+/**
+ * The UI fragments every archetype using Interactable must register:
+ * npc-line is the screen-space fallback; npc-bubble and interact-prompt are
+ * Anchored Pieces (ADR 0018), each drawn above its zero-size anchor box.
+ */
 export const INTERACTABLE_UI = {
     [INTERACTABLE_UI_PIECE]: `<style>
   .npc-line {
@@ -36,6 +45,73 @@ export const INTERACTABLE_UI = {
   }
 </style>
 <div class="npc-line">{{npcLine}}</div>
+`,
+    [NPC_BUBBLE_PIECE]: `<style>
+  .npc-bubble {
+    position: absolute;
+    left: 0;
+    bottom: 0;
+    transform: translate(-50%, -10px);
+    width: max-content;
+    max-width: 260px;
+    padding: 8px 14px;
+    border-radius: 10px;
+    background: #1a1a2ee6;
+    border: 1px solid #ffffff2e;
+    font: 500 16px/1.35 system-ui, sans-serif;
+    color: #f5f5f5;
+    text-align: center;
+    white-space: normal;
+    overflow-wrap: break-word;
+    text-shadow: 0 1px 2px #000a;
+    pointer-events: none;
+    user-select: none;
+  }
+  .npc-bubble::after {
+    content: '';
+    position: absolute;
+    left: 50%;
+    top: 100%;
+    transform: translateX(-50%);
+    border: 8px solid transparent;
+    border-top-color: #1a1a2ee6;
+  }
+</style>
+<div class="npc-bubble">{{line}}</div>
+`,
+    [INTERACT_PROMPT_PIECE]: `<style>
+  .interact-prompt {
+    position: absolute;
+    left: 0;
+    bottom: 0;
+    transform: translate(-50%, -6px);
+    width: max-content;
+    padding: 3px 8px;
+    border-radius: 8px;
+    background: #1a1a2ecc;
+    border: 1px solid #ffffff2e;
+    font: 500 13px/1.4 system-ui, sans-serif;
+    color: #f5f5f5;
+    white-space: nowrap;
+    text-shadow: 0 1px 2px #000a;
+    pointer-events: none;
+    user-select: none;
+  }
+  .interact-prompt kbd {
+    display: inline-block;
+    min-width: 1.4em;
+    margin-left: 2px;
+    padding: 0 5px;
+    border-radius: 4px;
+    background: #f5f5f5;
+    box-shadow: 0 2px 0 #9a9ab0;
+    font: 700 13px/1.4 system-ui, sans-serif;
+    color: #1a1a2e;
+    text-align: center;
+    text-shadow: none;
+  }
+</style>
+<div class="interact-prompt">Press <kbd>{{key}}</kbd></div>
 `,
 };
 /**
@@ -49,11 +125,97 @@ export function fireInteract(target, initiator) {
     for (const component of [...target.components])
         component.onInteract?.(initiator);
 }
+/**
+ * Keyed by the player entity, so the interact key and a ClickToMove arrival
+ * share one bubble, and nothing outlives the player or its Game.
+ */
+const piecesByPlayer = new WeakMap();
+function piecesOf(player) {
+    let pieces = piecesByPlayer.get(player);
+    if (!pieces) {
+        pieces = { bubble: null, prompt: null };
+        piecesByPlayer.set(player, pieces);
+    }
+    return pieces;
+}
+function closeBubble(pieces) {
+    pieces.bubble?.handle.remove();
+    pieces.bubble = null;
+}
+function closePrompt(pieces) {
+    pieces.prompt?.handle.remove();
+    pieces.prompt = null;
+}
+/** A key code as the prompt shows it: 'KeyE' → 'E', 'Digit1' → '1', 'Space' and 'ArrowUp' as they are. */
+function keyLabel(code) {
+    return code.replace(/^(?:Key|Digit)/, '');
+}
+/**
+ * Keeps the interact prompt (CA-12) on `nearest`, the nearest Interactable
+ * in range: exactly one interact-prompt with values { key }, the first key
+ * bound to interact — when the project defines the piece and binds the
+ * action, and never while a bubble is open. Otherwise none, and nothing
+ * logged: the piece's presence is checked before any attach.
+ */
+function syncPrompt(game, pieces, nearest) {
+    const code = game.ui.has(INTERACT_PROMPT_PIECE)
+        ? game.input.bindingsFor('interact')[0]
+        : undefined;
+    if (code === undefined || pieces.bubble?.handle.alive) {
+        closePrompt(pieces);
+        return;
+    }
+    if (pieces.prompt?.handle.alive && pieces.prompt.npc === nearest)
+        return;
+    closePrompt(pieces);
+    pieces.prompt = {
+        npc: nearest,
+        handle: game.ui.attach(INTERACT_PROMPT_PIECE, nearest, {
+            offset: [0, anchorHeight(nearest)],
+            values: { key: keyLabel(code) },
+        }),
+    };
+}
+/**
+ * `player` interacts with `target`, the NPC its Interactable belongs to.
+ * The one interaction both paths run — the interact key (interactUpdate)
+ * and a ClickToMove arrival (grill S8): publishes the line through the
+ * npcLine stat; shows it in an npc-bubble anchored to the NPC when the
+ * project defines that piece, replacing any bubble already open and
+ * taking the prompt's place (CA-11, CA-12), else in the npc-line screen
+ * piece as before; then fires onInteract.
+ */
+export function interactWith(game, player, target, interactable) {
+    game.stats.set('npcLine', interactable.line);
+    if (game.ui.has(NPC_BUBBLE_PIECE)) {
+        const pieces = piecesOf(player);
+        closeBubble(pieces);
+        pieces.bubble = {
+            npc: target,
+            handle: game.ui.attach(NPC_BUBBLE_PIECE, target, {
+                offset: [0, anchorHeight(target)],
+                values: { line: interactable.line },
+            }),
+        };
+        // The bubble answers the prompt: it goes while the bubble is open (CA-12).
+        closePrompt(pieces);
+    }
+    else {
+        // Scene-scoped: the scan that hides npc-line dies with the scene, so
+        // without a scope the line would survive a swap into a map where
+        // nothing knows to hide it — stale text and all (grill decision 8).
+        game.ui.show(INTERACTABLE_UI_PIECE, { scope: 'scene' });
+    }
+    fireInteract(target, player);
+}
 /**
  * The player role's interact lookup, run by its '*' hook in every state:
- * pressing interact near an Interactable publishes its line through the
- * npcLine stat and shows the npc-line UI piece; walking out of every
- * radius hides it again. Nearest one wins when several are in range.
+ * pressing interact near an Interactable interacts with it (interactWith),
+ * and the nearest one in range carries the interact prompt. The bubble
+ * belongs to the nearest Interactable in range too: it closes when another
+ * one becomes the nearest, and walking out of every radius closes it,
+ * removes the prompt and hides npc-line. Nearest one wins when several are
+ * in range.
  */
 export function interactUpdate({ entity, game }) {
     const nearestEntity = game.query.nearest(entity.position.x, entity.position.y, {
@@ -61,19 +223,19 @@ export function interactUpdate({ entity, game }) {
         exclude: entity,
         where: (candidate, { distance }) => distance <= candidate.get(Interactable).radius,
     });
+    const pieces = piecesOf(entity);
     if (!nearestEntity) {
         game.ui.hide(INTERACTABLE_UI_PIECE);
+        closeBubble(pieces);
+        closePrompt(pieces);
         return;
     }
-    const nearest = nearestEntity.get(Interactable);
+    if (pieces.bubble && pieces.bubble.npc !== nearestEntity)
+        closeBubble(pieces);
     if (game.input.justPressed('interact') && !game.input.consumed('interact')) {
         // The press is spent: an input:interact edge needs a NEW press.
         game.input.consume('interact');
-        game.stats.set('npcLine', nearest.line);
-        // Scene-scoped: the scan that hides this prompt dies with the scene, so
-        // without a scope the prompt would survive a swap into a map where
-        // nothing knows to hide it — stale line and all (grill decision 8).
-        game.ui.show(INTERACTABLE_UI_PIECE, { scope: 'scene' });
-        fireInteract(nearestEntity, entity);
+        interactWith(game, entity, nearestEntity, nearestEntity.get(Interactable));
     }
+    syncPrompt(game, pieces, nearestEntity);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waica/behaviors",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "Waica built-in behaviors — the curated game-feel library",
   "license": "MIT",
   "type": "module",
@@ -19,6 +19,6 @@
     }
   },
   "dependencies": {
-    "@waica/engine": "^0.15.0"
+    "@waica/engine": "^0.17.0"
   }
 }