@waica/cli 0.6.0 → 0.7.0

package/dist/mcp/node_modules/@waica/archetype-topdown/dist/ui.js

@@ -0,0 +1,43 @@
+/**
+ * The archetype's default UI pieces: self-contained HTML fragments
+ * (markup + <style>, {{stat}} bindings) keyed by piece name. Projects
+ * override them with src/ui/<name>.html files; scenes list the pieces
+ * they start with in their "ui" field.
+ *
+ * TS template literals (not .html files) because this package builds
+ * with plain tsc — no bundler to inline raw imports.
+ */
+export const TOPDOWN_UI = {
+    'potion-counter': `<style>
+  .potion-counter {
+    position: absolute;
+    top: 12px;
+    left: 12px;
+    font: 600 20px system-ui, sans-serif;
+    color: #ff6b6b;
+    text-shadow: 0 1px 3px #000a;
+    user-select: none;
+  }
+</style>
+<div class="potion-counter">🧪 {{points}}</div>
+`,
+    'npc-line': `<style>
+  .npc-line {
+    position: absolute;
+    left: 50%;
+    bottom: 24px;
+    transform: translateX(-50%);
+    max-width: 70%;
+    padding: 10px 18px;
+    border-radius: 8px;
+    background: #1a1a2ecc;
+    border: 1px solid #ffffff2e;
+    font: 500 18px system-ui, sans-serif;
+    color: #f5f5f5;
+    text-shadow: 0 1px 2px #000a;
+    user-select: none;
+  }
+</style>
+<div class="npc-line">{{npcLine}}</div>
+`,
+};

package/dist/mcp/node_modules/@waica/archetype-topdown/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@waica/archetype-topdown",
+  "version": "0.7.0",
+  "description": "Waica top-down archetype — opinionated setup for Zelda-like overhead adventures",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chichex/waica",
+    "directory": "packages/archetype-topdown"
+  },
+  "files": [
+    "dist",
+    "assets"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./manifest": {
+      "types": "./dist/manifest.d.ts",
+      "default": "./dist/manifest.js"
+    }
+  },
+  "dependencies": {
+    "@waica/behaviors": "^0.7.0",
+    "@waica/engine": "^0.7.0"
+  }
+}

package/dist/mcp/node_modules/@waica/behaviors/dist/index.d.ts

@@ -1,5 +1,8 @@
 export { PlatformerMotor } from './platformer-motor.js';
 export { PLAYER_ROLE, PLAYER_STATE_GRAPH, playerUpdate } from './player-states.js';
+export { TopDownMotor, type TopDownFacing } from './topdown-motor.js';
+export { TOPDOWN_PLAYER_ROLE, TOPDOWN_PLAYER_STATE_GRAPH, topdownPlayerUpdate, } from './topdown-player-states.js';
+export { Interactable, interactUpdate } from './interactable.js';
 export { Collectible } from './collectible.js';
 export { Patrol, PATROLLER_ROLE, PATROLLER_STATE_GRAPH, type PatrolAxis } from './patrol.js';
 export { Chaser, CHASER_ROLE, CHASER_STATE_GRAPH, type ChaserMode } from './chaser.js';

package/dist/mcp/node_modules/@waica/behaviors/dist/index.js

@@ -1,5 +1,8 @@
 export { PlatformerMotor } from './platformer-motor.js';
 export { PLAYER_ROLE, PLAYER_STATE_GRAPH, playerUpdate } from './player-states.js';
+export { TopDownMotor } from './topdown-motor.js';
+export { TOPDOWN_PLAYER_ROLE, TOPDOWN_PLAYER_STATE_GRAPH, topdownPlayerUpdate, } from './topdown-player-states.js';
+export { Interactable, interactUpdate } from './interactable.js';
 export { Collectible } from './collectible.js';
 export { Patrol, PATROLLER_ROLE, PATROLLER_STATE_GRAPH } from './patrol.js';
 export { Chaser, CHASER_ROLE, CHASER_STATE_GRAPH } from './chaser.js';

package/dist/mcp/node_modules/@waica/behaviors/dist/interactable.d.ts

@@ -0,0 +1,31 @@
+import { Component, 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
+ * player role's always-hook does the lookup (see interactUpdate), so an
+ * NPC stays code-free: Interactable + the npc role is a whole villager.
+ */
+export declare class Interactable extends Component {
+    static componentName: string;
+    static params: {
+        line: {
+            label: string;
+        };
+        radius: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+    };
+    /** What pressing interact within the radius says. */
+    line: string;
+    radius: number;
+}
+/**
+ * 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.
+ */
+export declare function interactUpdate({ entity, game }: StateContext): void;

package/dist/mcp/node_modules/@waica/behaviors/dist/interactable.js

@@ -0,0 +1,49 @@
+import { Component } 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
+ * player role's always-hook does the lookup (see interactUpdate), so an
+ * NPC stays code-free: Interactable + the npc role is a whole villager.
+ */
+export class Interactable extends Component {
+    static componentName = 'Interactable';
+    static params = {
+        line: { label: 'Line' },
+        radius: { label: 'Radius', min: 0.5, max: 10, step: 0.25 },
+    };
+    /** What pressing interact within the radius says. */
+    line = 'Hello, traveler!';
+    radius = 1.5;
+}
+/**
+ * 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.
+ */
+export function interactUpdate({ entity, game }) {
+    let nearest = null;
+    let nearestDistance = Infinity;
+    for (const other of game.entities) {
+        if (other === entity)
+            continue;
+        const interactable = other.get(Interactable);
+        if (!interactable)
+            continue;
+        const distance = Math.hypot(other.position.x - entity.position.x, other.position.y - entity.position.y);
+        if (distance <= interactable.radius && distance < nearestDistance) {
+            nearest = interactable;
+            nearestDistance = distance;
+        }
+    }
+    if (!nearest) {
+        game.ui.hide('npc-line');
+        return;
+    }
+    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);
+        game.ui.show('npc-line');
+    }
+}

package/dist/mcp/node_modules/@waica/behaviors/dist/platformer-motor.d.ts

@@ -1,4 +1,4 @@
-import { Component } from '@waica/engine';
+import { Component, type CameraVelocity, type CameraVelocityProvider } from '@waica/engine';
 /**
  * Passive platformer motor: tuning params, physical state and movement
  * methods for state code to call. It has no onUpdate of its own — the
@@ -9,7 +9,7 @@ import { Component } from '@waica/engine';
  * Per-axis collision against the scene's Solids — deterministic genre
  * movement (Celeste-style), not "realistic" physics.
  */
-export declare class PlatformerMotor extends Component {
+export declare class PlatformerMotor extends Component implements CameraVelocityProvider {
     static componentName: string;
     static displayName: string;
     static params: {
@@ -103,6 +103,8 @@ export declare class PlatformerMotor extends Component {
     private bufferTimer;
     private squashX;
     private squashY;
+    /** The scene camera reads follow velocity through this explicit seam. */
+    getCameraVelocity(): CameraVelocity;
     /**
      * Per-frame bookkeeping: forgiveness timers, squash decay and the
      * facing flip. The logic set's '*' hook runs it in every state, so

package/dist/mcp/node_modules/@waica/behaviors/dist/platformer-motor.js

@@ -1,4 +1,4 @@
-import { Component, resolveSolidAxis, THREE } from '@waica/engine';
+import { Component, resolveSolidAxis, THREE, } from '@waica/engine';
 /**
  * Passive platformer motor: tuning params, physical state and movement
  * methods for state code to call. It has no onUpdate of its own — the
@@ -60,6 +60,10 @@ export class PlatformerMotor extends Component {
     bufferTimer = 0;
     squashX = 1;
     squashY = 1;
+    /** The scene camera reads follow velocity through this explicit seam. */
+    getCameraVelocity() {
+        return { vx: this.vx, vy: this.vy };
+    }
     /**
      * Per-frame bookkeeping: forgiveness timers, squash decay and the
      * facing flip. The logic set's '*' hook runs it in every state, so

package/dist/mcp/node_modules/@waica/behaviors/dist/topdown-motor.d.ts

@@ -0,0 +1,72 @@
+import { Component, type AnimationFacingProvider, type CameraVelocity, type CameraVelocityProvider } from '@waica/engine';
+/** The four facings the top-down animation contract declares. */
+export type TopDownFacing = 'n' | 's' | 'e' | 'w';
+/**
+ * Passive top-down motor: tuning params, physical state and movement
+ * methods for state code to call. It has no onUpdate of its own — the
+ * StateMachine is the only owner of the frame; this is the toolbox the
+ * active state moves the body with. Eight-direction movement with the
+ * input vector normalized so diagonals match cardinal speed, no gravity,
+ * and per-axis collision against the scene's Solids — deterministic
+ * genre movement (Zelda-style), not "realistic" physics.
+ */
+export declare class TopDownMotor extends Component implements CameraVelocityProvider, AnimationFacingProvider {
+    static componentName: string;
+    static displayName: string;
+    static params: {
+        moveSpeed: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+        acceleration: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+        deceleration: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+        walkThreshold: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+    };
+    static transient: string[];
+    moveSpeed: number;
+    acceleration: number;
+    deceleration: number;
+    /** Speed above this reads as walking (the idle ↔ walk edge). */
+    walkThreshold: number;
+    /** The character's AABB hitbox — a footprint, shorter than the sprite. */
+    hitboxWidth: number;
+    hitboxHeight: number;
+    vx: number;
+    vy: number;
+    /** Four-direction facing; starts looking at the camera. */
+    facing: TopDownFacing;
+    /** The scene camera reads follow velocity through this explicit seam. */
+    getCameraVelocity(): CameraVelocity;
+    /** The StateMachine resolves directional clips through this explicit seam. */
+    getAnimationFacing(): string;
+    /**
+     * Accelerates toward the input vector (each axis -1..1) * moveSpeed.
+     * The vector is normalized so diagonals move at cardinal speed, and
+     * facing follows the dominant input axis — ties keep the last facing.
+     */
+    run(inputX: number, inputY: number, dt: number): void;
+    /** Live speed, for the idle ↔ walk edge. */
+    speed(): number;
+    /** Integrates velocity and resolves each axis against Solids. */
+    step(dt: number): void;
+    halt(): void;
+    private resolveAxis;
+    private collisionBody;
+}

package/dist/mcp/node_modules/@waica/behaviors/dist/topdown-motor.js

@@ -0,0 +1,102 @@
+import { Component, resolveSolidAxis, THREE, } from '@waica/engine';
+/**
+ * Passive top-down motor: tuning params, physical state and movement
+ * methods for state code to call. It has no onUpdate of its own — the
+ * StateMachine is the only owner of the frame; this is the toolbox the
+ * active state moves the body with. Eight-direction movement with the
+ * input vector normalized so diagonals match cardinal speed, no gravity,
+ * and per-axis collision against the scene's Solids — deterministic
+ * genre movement (Zelda-style), not "realistic" physics.
+ */
+export class TopDownMotor extends Component {
+    static componentName = 'TopDownMotor';
+    static displayName = 'Motor';
+    static params = {
+        moveSpeed: { label: 'Speed', min: 1, max: 30, step: 0.5 },
+        acceleration: { label: 'Acceleration', min: 5, max: 200, step: 5 },
+        deceleration: { label: 'Deceleration', min: 5, max: 200, step: 5 },
+        walkThreshold: { label: 'Walk threshold', min: 0, max: 5, step: 0.1 },
+    };
+    static transient = ['vx', 'vy', 'facing'];
+    moveSpeed = 6;
+    acceleration = 60;
+    deceleration = 80;
+    /** Speed above this reads as walking (the idle ↔ walk edge). */
+    walkThreshold = 0.5;
+    /** The character's AABB hitbox — a footprint, shorter than the sprite. */
+    hitboxWidth = 0.9;
+    hitboxHeight = 0.6;
+    vx = 0;
+    vy = 0;
+    /** Four-direction facing; starts looking at the camera. */
+    facing = 's';
+    /** The scene camera reads follow velocity through this explicit seam. */
+    getCameraVelocity() {
+        return { vx: this.vx, vy: this.vy };
+    }
+    /** The StateMachine resolves directional clips through this explicit seam. */
+    getAnimationFacing() {
+        return this.facing;
+    }
+    /**
+     * Accelerates toward the input vector (each axis -1..1) * moveSpeed.
+     * The vector is normalized so diagonals move at cardinal speed, and
+     * facing follows the dominant input axis — ties keep the last facing.
+     */
+    run(inputX, inputY, dt) {
+        let x = inputX;
+        let y = inputY;
+        const length = Math.hypot(x, y);
+        if (length > 1) {
+            x /= length;
+            y /= length;
+        }
+        const rateX = x !== 0 ? this.acceleration : this.deceleration;
+        const rateY = y !== 0 ? this.acceleration : this.deceleration;
+        this.vx = THREE.MathUtils.damp(this.vx, x * this.moveSpeed, rateX / this.moveSpeed, dt);
+        this.vy = THREE.MathUtils.damp(this.vy, y * this.moveSpeed, rateY / this.moveSpeed, dt);
+        const absX = Math.abs(inputX);
+        const absY = Math.abs(inputY);
+        if (absX > absY)
+            this.facing = inputX < 0 ? 'w' : 'e';
+        else if (absY > absX)
+            this.facing = inputY < 0 ? 's' : 'n';
+    }
+    /** Live speed, for the idle ↔ walk edge. */
+    speed() {
+        return Math.hypot(this.vx, this.vy);
+    }
+    /** Integrates velocity and resolves each axis against Solids. */
+    step(dt) {
+        const pos = this.entity.position;
+        const previousX = pos.x;
+        pos.x += this.vx * dt;
+        if (this.resolveAxis('x', previousX))
+            this.vx = 0;
+        const previousY = pos.y;
+        pos.y += this.vy * dt;
+        if (this.resolveAxis('y', previousY))
+            this.vy = 0;
+    }
+    halt() {
+        this.vx = 0;
+        this.vy = 0;
+    }
+    resolveAxis(axis, previous) {
+        return resolveSolidAxis({
+            entity: this.entity,
+            axis,
+            previous,
+            body: () => this.collisionBody(),
+        });
+    }
+    collisionBody() {
+        return {
+            x: this.entity.position.x,
+            y: this.entity.position.y,
+            width: this.hitboxWidth,
+            height: this.hitboxHeight,
+            shape: 'rectangle',
+        };
+    }
+}

package/dist/mcp/node_modules/@waica/behaviors/dist/topdown-player-states.d.ts

@@ -0,0 +1,18 @@
+import { type RoleDefinition, type RoleGraph, type StateContext } from '@waica/engine';
+/**
+ * The top-down 'player' role: the character you control from above. Both
+ * default states share one body update; they differ only in the edges
+ * their prefab data declares. Extending the player is defineStates
+ * ('player', { yourState: {...} }) plus a state in the prefab — never a
+ * fight with a parallel controller.
+ */
+/** The state graph new top-down player characters start with, as prefab data. */
+export declare const TOPDOWN_PLAYER_STATE_GRAPH: RoleGraph;
+/**
+ * One body update shared by every default state: read the four-direction
+ * actions, accelerate, collide, then report what the body is doing as
+ * signals. Unmatched signals are no-ops, so each state only reacts to
+ * the edges its data declares.
+ */
+export declare function topdownPlayerUpdate({ entity, game, fsm }: StateContext, dt: number): void;
+export declare const TOPDOWN_PLAYER_ROLE: RoleDefinition;

package/dist/mcp/node_modules/@waica/behaviors/dist/topdown-player-states.js

@@ -0,0 +1,86 @@
+import {} from '@waica/engine';
+import { Health } from './health.js';
+import { interactUpdate } from './interactable.js';
+import { Respawnable } from './respawnable.js';
+import { TopDownMotor } from './topdown-motor.js';
+/**
+ * The top-down 'player' role: the character you control from above. Both
+ * default states share one body update; they differ only in the edges
+ * their prefab data declares. Extending the player is defineStates
+ * ('player', { yourState: {...} }) plus a state in the prefab — never a
+ * fight with a parallel controller.
+ */
+/** The state graph new top-down player characters start with, as prefab data. */
+export const TOPDOWN_PLAYER_STATE_GRAPH = {
+    initial: 'idle',
+    states: {
+        idle: {
+            transitions: [{ on: 'signal:move', to: 'walk' }],
+        },
+        walk: {
+            transitions: [{ on: 'signal:stop', to: 'idle' }],
+        },
+        dead: {
+            // Freeze on idle (resolved directionally) rather than name a death
+            // clip the stock sheets do not have and warn every frame.
+            clip: 'idle',
+            // A beat before control comes back, so death reads as an event.
+            transitions: [{ on: 'timer:0.8', to: 'idle' }],
+        },
+        // Dying is the same from every state, so the edge lives on '*'. Its
+        // presence is also the contract Health checks before signalling: a graph
+        // without it gets its entity destroyed instead.
+        '*': { transitions: [{ on: 'signal:death', to: 'dead' }] },
+    },
+};
+/**
+ * One body update shared by every default state: read the four-direction
+ * actions, accelerate, collide, then report what the body is doing as
+ * signals. Unmatched signals are no-ops, so each state only reacts to
+ * the edges its data declares.
+ */
+export function topdownPlayerUpdate({ entity, game, fsm }, dt) {
+    const motor = entity.get(TopDownMotor);
+    if (!motor)
+        return;
+    motor.run(game.input.axis('left', 'right'), game.input.axis('down', 'up'), dt);
+    motor.step(dt);
+    fsm.signal(motor.speed() > motor.walkThreshold ? 'move' : 'stop');
+}
+export const TOPDOWN_PLAYER_ROLE = {
+    description: 'You control this character with the project controls: eight-direction ' +
+        'top-down movement with normalized diagonals and no gravity. Its ' +
+        'states move the Motor.',
+    driver: 'TopDownMotor',
+    graph: TOPDOWN_PLAYER_STATE_GRAPH,
+    signals: {
+        move: 'moving',
+        stop: 'standing still',
+    },
+    states: {
+        // Always-hook: the interact lookup must survive custom states like an
+        // attack, so it runs in every state.
+        '*': {
+            onUpdate(ctx) {
+                interactUpdate(ctx);
+            },
+        },
+        // Fallback: a custom state without its own onUpdate keeps the full
+        // body update — its file only has to say what makes it special.
+        default: { onUpdate: topdownPlayerUpdate },
+        idle: { onUpdate: topdownPlayerUpdate },
+        walk: { onUpdate: topdownPlayerUpdate },
+        // Coming back is what leaving death means, so it hangs off onExit: any
+        // other way out of this state (a project's own edge) revives too.
+        dead: {
+            // A state without its own onUpdate falls back to the role's default
+            // body update, so without this no-op the player kept walking for the
+            // whole death beat instead of the graph taking control away.
+            onUpdate() { },
+            onExit({ entity }) {
+                entity.get(Respawnable)?.respawn();
+                entity.get(Health)?.heal(Infinity);
+            },
+        },
+    },
+};

package/dist/mcp/node_modules/@waica/behaviors/package.json

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

package/dist/mcp/node_modules/@waica/engine/dist/animation/directional.d.ts

@@ -0,0 +1,48 @@
+import type { AnimationContract } from './contract.js';
+/**
+ * Directional animation contract: the archetype declares which facing
+ * directions exist, how clips are named per direction (`<state>-<dir>`),
+ * and how a missing direction degrades — including mirroring, so west can
+ * reuse east art flipped. Extends the base AnimationContract thesis to
+ * genres where characters face more than one way (top-down, isometric).
+ */
+export interface DirectionalFallback<Dir extends string = string> {
+    dir: Dir;
+    /** Mirror the resolved clip horizontally (e.g. west plays east flipped). */
+    flip?: boolean;
+}
+export interface DirectionalAnimation<Dir extends string = string> {
+    /** Declared facing directions, e.g. ['n', 's', 'e', 'w'] — 8 for isometric. */
+    directions: readonly Dir[];
+    /** Directional degradation: a missing facing resolves to another, optionally mirrored. */
+    fallbacks?: Partial<Record<Dir, DirectionalFallback<Dir>>>;
+    /** State-level degradation chain applied when no directional clip resolves. */
+    contract: AnimationContract;
+}
+export interface ResolvedDirectionalClip {
+    clip: string | undefined;
+    flip: boolean;
+}
+/**
+ * Resolves state × facing to a playable clip: the exact `<state>-<dir>`
+ * clip, else the declared directional fallback chain (accumulating flips).
+ * On a dead end, walks the base AnimationContract's state fallback chain
+ * (cycle-safe) and, for each candidate state in turn, retries the
+ * directional chain against it before trying its bare name. An invalid
+ * facing, or a chain that dead-ends everywhere, resolves to nothing rather
+ * than guessing — the caller's name-based fallback path handles that.
+ */
+export declare function resolveDirectionalClip(animation: DirectionalAnimation, available: Iterable<string>, state: string, facing: string): ResolvedDirectionalClip;
+/** Installs (or clears, with null) the active directional contract. */
+export declare function installDirectionalAnimation(animation: DirectionalAnimation | null): void;
+/** The active directional contract, if an archetype installed one. */
+export declare function installedDirectionalAnimation(): DirectionalAnimation | null;
+/**
+ * The explicit seam a driving component (a motor) opts into so StateMachine
+ * can resolve directional clips: it reports the entity's current facing as
+ * one of the contract's declared directions.
+ */
+export interface AnimationFacingProvider {
+    getAnimationFacing(): string;
+}
+export declare function isAnimationFacingProvider(value: unknown): value is AnimationFacingProvider;

package/dist/mcp/node_modules/@waica/engine/dist/animation/directional.js

@@ -0,0 +1,68 @@
+/**
+ * Walks the exact `<state>-<dir>` clip, then the declared directional
+ * fallback chain (accumulating flips), cycle-safe. Undefined at a dead end —
+ * callers decide what to try next, instead of this reaching for anything else.
+ */
+function directionalChain(animation, available, state, facing) {
+    const seen = new Set();
+    let dir = facing;
+    let flip = false;
+    while (dir && !seen.has(dir)) {
+        const candidate = `${state}-${dir}`;
+        if (available.has(candidate))
+            return { clip: candidate, flip };
+        seen.add(dir);
+        const fallback = animation.fallbacks?.[dir];
+        if (!fallback)
+            break;
+        if (fallback.flip)
+            flip = !flip;
+        dir = fallback.dir;
+    }
+    return undefined;
+}
+/**
+ * Resolves state × facing to a playable clip: the exact `<state>-<dir>`
+ * clip, else the declared directional fallback chain (accumulating flips).
+ * On a dead end, walks the base AnimationContract's state fallback chain
+ * (cycle-safe) and, for each candidate state in turn, retries the
+ * directional chain against it before trying its bare name. An invalid
+ * facing, or a chain that dead-ends everywhere, resolves to nothing rather
+ * than guessing — the caller's name-based fallback path handles that.
+ */
+export function resolveDirectionalClip(animation, available, state, facing) {
+    if (!animation.directions.includes(facing))
+        return { clip: undefined, flip: false };
+    const set = new Set(available);
+    const direct = directionalChain(animation, set, state, facing);
+    if (direct)
+        return direct;
+    const seenStates = new Set();
+    let candidate = state;
+    while (candidate && !seenStates.has(candidate)) {
+        seenStates.add(candidate);
+        if (candidate !== state) {
+            const viaDirection = directionalChain(animation, set, candidate, facing);
+            if (viaDirection)
+                return viaDirection;
+        }
+        if (set.has(candidate))
+            return { clip: candidate, flip: false };
+        candidate = animation.contract.fallbacks[candidate];
+    }
+    return { clip: undefined, flip: false };
+}
+let installed = null;
+/** Installs (or clears, with null) the active directional contract. */
+export function installDirectionalAnimation(animation) {
+    installed = animation;
+}
+/** The active directional contract, if an archetype installed one. */
+export function installedDirectionalAnimation() {
+    return installed;
+}
+export function isAnimationFacingProvider(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.getAnimationFacing === 'function');
+}

package/dist/mcp/node_modules/@waica/engine/dist/archetype.d.ts

@@ -1,3 +1,4 @@
+import type { DirectionalAnimation } from './animation/directional.js';
 import type { InputBindings } from './input.js';
 import type { PrefabJson, SceneEntityJson, SceneJson, SceneRegistry } from './scene.js';
 import type { ArchetypeBundle } from './state/hooks.js';
@@ -30,6 +31,8 @@ export interface ArchetypeManifest {
     bindings: Readonly<InputBindings>;
     actionLabels: Readonly<Record<string, string>>;
     bundle: ArchetypeBundle;
+    /** Directional animation contract, for genres where characters face around. */
+    animation?: DirectionalAnimation;
 }
 /** Browser manifest enriched with URLs produced by an asset-aware bundler. */
 export interface BrowserArchetypeManifest extends ArchetypeManifest {