@waica/cli 0.3.0

package/dist/mcp/node_modules/@waica/engine/dist/input.js

@@ -0,0 +1,84 @@
+/** Neutral engine baseline; archetypes own their action vocabulary. */
+export const DEFAULT_BINDINGS = {};
+/**
+ * Action-based input with archetype default bindings.
+ * v0: keyboard. TODO(H1): gamepad and touch.
+ */
+export class Input {
+    bindings = new Map();
+    down = new Set();
+    justDown = new Set();
+    used = new Set();
+    /** Installs exactly the action map supplied by the active archetype/project. */
+    constructor(bindings = DEFAULT_BINDINGS) {
+        for (const [action, codes] of Object.entries(bindings)) {
+            this.bindings.set(action, new Set(codes));
+        }
+        window.addEventListener('keydown', this.onKeyDown);
+        window.addEventListener('keyup', this.onKeyUp);
+        window.addEventListener('blur', this.releaseAll);
+        document.addEventListener('visibilitychange', this.onVisibilityChange);
+    }
+    /** Is the action held this frame? */
+    held(action) {
+        return this.isActive(action, this.down);
+    }
+    /** Was the action pressed exactly this frame? */
+    justPressed(action) {
+        return this.isActive(action, this.justDown);
+    }
+    /** -1..1 axis from two actions (left/right by default). */
+    axis(negative = 'left', positive = 'right') {
+        return (this.held(positive) ? 1 : 0) - (this.held(negative) ? 1 : 0);
+    }
+    /**
+     * Marks this frame's press of the action as spent, so consumers that
+     * honor consumption (state-machine 'input:' triggers) ignore it. One
+     * press does one thing: the press that launches a ground jump can't
+     * also fire a "key press jump" transition on the very same frame.
+     */
+    consume(action) {
+        this.used.add(action);
+    }
+    /** Was this frame's press already spent by someone? */
+    consumed(action) {
+        return this.used.has(action);
+    }
+    /** Called by the Game at the end of each frame. */
+    endFrame() {
+        this.justDown.clear();
+        this.used.clear();
+    }
+    dispose() {
+        window.removeEventListener('keydown', this.onKeyDown);
+        window.removeEventListener('keyup', this.onKeyUp);
+        window.removeEventListener('blur', this.releaseAll);
+        document.removeEventListener('visibilitychange', this.onVisibilityChange);
+    }
+    isActive(action, set) {
+        const codes = this.bindings.get(action);
+        if (!codes)
+            return false;
+        for (const code of codes)
+            if (set.has(code))
+                return true;
+        return false;
+    }
+    releaseAll = () => {
+        this.down.clear();
+        this.justDown.clear();
+    };
+    onVisibilityChange = () => {
+        if (document.visibilityState === 'hidden')
+            this.releaseAll();
+    };
+    onKeyDown = (e) => {
+        if (e.repeat)
+            return;
+        this.down.add(e.code);
+        this.justDown.add(e.code);
+    };
+    onKeyUp = (e) => {
+        this.down.delete(e.code);
+    };
+}

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

@@ -0,0 +1,80 @@
+import type { SceneCameraJson } from './camera.js';
+import type { ComponentClass } from './component.js';
+import type { Entity } from './entity.js';
+import type { Game } from './game.js';
+/**
+ * Waica's scene format: declarative, git-friendly data, editable by the
+ * visual editor. The scene is the source of truth; the Game is its live
+ * projection.
+ */
+export interface SceneComponentJson {
+    type: string;
+    props?: Record<string, unknown>;
+}
+export interface SceneEntityJson {
+    name: string;
+    position?: [number, number];
+    /** Prefab ref like "characters/slime", resolved against SceneRegistry.prefabs. */
+    prefab?: string;
+    /** Per-component prop overrides on top of the prefab: componentType -> propName -> value. */
+    overrides?: Record<string, Record<string, unknown>>;
+    components?: SceneComponentJson[];
+    /** Editor-only grouping label; spawning ignores it. */
+    folder?: string;
+}
+/** A reusable entity template: a typed bag of components a scene can reference. */
+export interface PrefabJson {
+    waicaPrefab: 1;
+    type: 'character' | 'object' | 'tile';
+    components: SceneComponentJson[];
+}
+export interface SceneJson {
+    waicaScene: 1 | 2 | 3;
+    /** The scene's built-in camera (v3); absent = the host keeps control. */
+    camera?: SceneCameraJson;
+    entities: SceneEntityJson[];
+    /** UI pieces (src/ui/*.html) mounted visible when the scene loads. */
+    ui?: string[];
+    /**
+     * Editor-only folder registry: keeps empty folders alive and ordered.
+     * Folders group entities in the editor's explorer; the runtime ignores them.
+     */
+    folders?: string[];
+}
+/** Which components exist and how to resolve archetype assets (waica:*). */
+export interface SceneRegistry {
+    components: Record<string, ComponentClass>;
+    /**
+     * Resolves asset URIs — "waica:dog" registry keys or project paths like
+     * "src/art/hero.png" — to loadable URLs. MUST return unknown strings
+     * unchanged: every string prop goes through it.
+     */
+    resolveAsset?: (uri: string) => string;
+    /** Prefab definitions keyed by ref ("characters/slime"). */
+    prefabs?: Record<string, PrefabJson>;
+    /** UI piece sources keyed by name ("coin-counter" → its HTML). */
+    ui?: Record<string, string>;
+}
+/**
+ * Own-property lookup. Scene JSON is data — a component or prefab named
+ * "constructor" or "toString" must read as missing, not as whatever sits
+ * on Object.prototype.
+ */
+export declare function registryEntry<T>(record: Record<string, T> | undefined, key: string): T | undefined;
+/**
+ * Runs every string prop through the registry's asset resolver (if any),
+ * recursing into arrays and plain objects — nested textures (e.g. an
+ * AnimatedSprite's extraSheets) resolve like top-level ones. Safe because
+ * resolvers return unknown strings unchanged.
+ */
+export declare function resolveProps(props: Record<string, unknown> | undefined, registry: SceneRegistry): Record<string, unknown>;
+/**
+ * Expands an entity's prefab (with its overrides) into the final component
+ * list: prefab components first, inline extras appended after. Pure — inputs
+ * are never mutated; merged components are fresh objects.
+ */
+export declare function resolveEntityComponents(entity: SceneEntityJson, prefabs?: Record<string, PrefabJson>): SceneComponentJson[];
+/** Instantiates a scene entity into the game. */
+export declare function spawnFromJson(game: Game, json: SceneEntityJson, registry: SceneRegistry): Entity;
+/** Loads a full scene into the game. */
+export declare function loadScene(game: Game, scene: SceneJson, registry: SceneRegistry): void;

package/dist/mcp/node_modules/@waica/engine/dist/scene.js

@@ -0,0 +1,93 @@
+/**
+ * Own-property lookup. Scene JSON is data — a component or prefab named
+ * "constructor" or "toString" must read as missing, not as whatever sits
+ * on Object.prototype.
+ */
+export function registryEntry(record, key) {
+    if (!record || !Object.prototype.hasOwnProperty.call(record, key))
+        return undefined;
+    return record[key];
+}
+/**
+ * Runs every string prop through the registry's asset resolver (if any),
+ * recursing into arrays and plain objects — nested textures (e.g. an
+ * AnimatedSprite's extraSheets) resolve like top-level ones. Safe because
+ * resolvers return unknown strings unchanged.
+ */
+export function resolveProps(props, registry) {
+    if (!props)
+        return {};
+    const resolve = registry.resolveAsset;
+    if (!resolve)
+        return { ...props };
+    const walk = (value) => {
+        if (typeof value === 'string')
+            return resolve(value);
+        if (Array.isArray(value))
+            return value.map(walk);
+        if (value && typeof value === 'object' && value.constructor === Object) {
+            const out = {};
+            for (const [key, entry] of Object.entries(value))
+                out[key] = walk(entry);
+            return out;
+        }
+        return value;
+    };
+    return walk(props);
+}
+/**
+ * Expands an entity's prefab (with its overrides) into the final component
+ * list: prefab components first, inline extras appended after. Pure — inputs
+ * are never mutated; merged components are fresh objects.
+ */
+export function resolveEntityComponents(entity, prefabs) {
+    const inline = entity.components ?? [];
+    if (!entity.prefab)
+        return inline;
+    const prefab = registryEntry(prefabs, entity.prefab);
+    if (!prefab) {
+        console.warn(`[waica] unknown prefab in scene: "${entity.prefab}" (${entity.name})`);
+        return inline;
+    }
+    const fromPrefab = prefab.components.map((comp) => ({
+        type: comp.type,
+        props: { ...comp.props, ...entity.overrides?.[comp.type] },
+    }));
+    return [...fromPrefab, ...inline];
+}
+/** Instantiates a scene entity into the game. */
+export function spawnFromJson(game, json, registry) {
+    const entity = game.spawn(json.name);
+    if (json.position)
+        entity.position.set(json.position[0], json.position[1], 0);
+    for (const comp of resolveEntityComponents(json, registry.prefabs)) {
+        const Class = registryEntry(registry.components, comp.type);
+        if (!Class) {
+            console.warn(`[waica] unknown component in scene: "${comp.type}" (${json.name})`);
+            continue;
+        }
+        // The registry now carries project-owned classes, i.e. arbitrary user
+        // code. A throwing constructor or onReady costs that one component —
+        // never the rest of the scene, and never the editor hosting it.
+        try {
+            entity.add(Class, resolveProps(comp.props, registry));
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(`[waica] component "${comp.type}" failed on "${json.name}": ${message}`);
+        }
+    }
+    return entity;
+}
+/** Loads a full scene into the game. */
+export function loadScene(game, scene, registry) {
+    game.registry = registry;
+    for (const entityJson of scene.entities)
+        spawnFromJson(game, entityJson, registry);
+    // After the spawns: with a follow target, the camera starts centered on it.
+    game.setSceneCamera(scene.camera);
+    if (registry.ui)
+        game.ui.defineAll(registry.ui);
+    for (const name of scene.ui ?? [])
+        game.ui.show(name);
+}

package/dist/mcp/node_modules/@waica/engine/dist/solid-axis.d.ts

@@ -0,0 +1,21 @@
+import { type CollisionBody } from './collision-shape.js';
+import { Solid } from './components/solid.js';
+import type { Entity } from './entity.js';
+export type CollisionAxis = 'x' | 'y';
+export interface SolidAxisOptions {
+    /** Dynamic entity whose axis position has already been moved to its target. */
+    entity: Entity;
+    axis: CollisionAxis;
+    /** Known pre-move position on this axis. */
+    previous: number;
+    /** Current world-space collision body; read again as the axis position changes. */
+    body(): CollisionBody;
+    /** Receives each nearest Solid that blocks this axis move. */
+    onContact?(solid: Solid): void;
+}
+/**
+ * Resolves one axis against scene Solids. Large displacements are split into
+ * body-sized steps so a thin wall cannot sit entirely between two samples.
+ * Returns whether a new contact blocked the move.
+ */
+export declare function resolveSolidAxis({ entity, axis, previous, body, onContact, }: SolidAxisOptions): boolean;

package/dist/mcp/node_modules/@waica/engine/dist/solid-axis.js

@@ -0,0 +1,77 @@
+import { collisionBounds, collisionOverlap } from './collision-shape.js';
+import { Solid } from './components/solid.js';
+const CONTACT_TOLERANCE = 1e-7;
+function bodyFor(solid) {
+    return {
+        x: solid.entity.position.x + solid.offsetX,
+        y: solid.entity.position.y + solid.offsetY,
+        width: solid.width,
+        height: solid.height,
+        shape: solid.shape,
+        points: solid.points,
+    };
+}
+/**
+ * Resolves one axis against scene Solids. Large displacements are split into
+ * body-sized steps so a thin wall cannot sit entirely between two samples.
+ * Returns whether a new contact blocked the move.
+ */
+export function resolveSolidAxis({ entity, axis, previous, body, onContact, }) {
+    const position = entity.position;
+    const target = position[axis];
+    const solids = entity.game.entities
+        .filter((other) => other !== entity)
+        .map((other) => other.get(Solid))
+        .filter((solid) => solid !== undefined);
+    position[axis] = previous;
+    // Preserve the established spawn-inside-wall bail: pre-existing overlaps
+    // are ignored for this move rather than becoming arbitrary push-out rules.
+    const ignored = new Set(solids.filter((solid) => collisionOverlap(body(), bodyFor(solid))));
+    const bounds = collisionBounds(body());
+    const extent = axis === 'x' ? bounds.right - bounds.left : bounds.top - bounds.bottom;
+    const maxStep = Math.max(extent / 2, 0.05);
+    const displacement = target - previous;
+    const steps = Math.max(1, Math.ceil(Math.abs(displacement) / maxStep));
+    let free = previous;
+    for (let step = 1; step <= steps; step++) {
+        const candidate = previous + displacement * (step / steps);
+        position[axis] = candidate;
+        const blockers = solids.filter((solid) => !ignored.has(solid) && collisionOverlap(body(), bodyFor(solid)));
+        if (blockers.length === 0) {
+            free = candidate;
+            continue;
+        }
+        // More than one Solid can occupy a sample. Resolve against each from the
+        // same known-free point and keep the nearest contact along this move.
+        let contact = candidate;
+        let contactDistance = Infinity;
+        let contacts = [];
+        for (const solid of blockers) {
+            let open = free;
+            let blocked = candidate;
+            for (let iteration = 0; iteration < 14; iteration++) {
+                const middle = (open + blocked) / 2;
+                position[axis] = middle;
+                if (collisionOverlap(body(), bodyFor(solid)))
+                    blocked = middle;
+                else
+                    open = middle;
+            }
+            const distance = Math.abs(open - free);
+            if (distance < contactDistance - CONTACT_TOLERANCE) {
+                contact = open;
+                contactDistance = distance;
+                contacts = [solid];
+            }
+            else if (Math.abs(distance - contactDistance) <= CONTACT_TOLERANCE) {
+                contacts.push(solid);
+            }
+        }
+        position[axis] = contact;
+        for (const solid of contacts)
+            onContact?.(solid);
+        return true;
+    }
+    position[axis] = target;
+    return false;
+}

package/dist/mcp/node_modules/@waica/engine/dist/state/hooks.d.ts

@@ -0,0 +1,90 @@
+import type { Entity } from '../entity.js';
+import type { Game } from '../game.js';
+import type { StateJson, StateMachine } from './state-machine.js';
+/** What state code receives: the entity, the game, and the machine itself. */
+export interface StateContext {
+    entity: Entity;
+    game: Game;
+    fsm: StateMachine;
+}
+/** Code for one state. Every hook is optional — a state can be pure data. */
+export interface StateHooks {
+    onEnter?(ctx: StateContext): void;
+    onUpdate?(ctx: StateContext, dt: number): void;
+    onCollide?(ctx: StateContext, other: Entity): void;
+    onExit?(ctx: StateContext): void;
+}
+/**
+ * A named bundle of state code. Two entries are special: '*' is the
+ * always-hook — it runs every frame no matter which state is active
+ * (per-frame bookkeeping like motor timers lives there) — and 'default'
+ * is the fallback — a state that doesn't define a phase inherits it, so
+ * a custom state keeps the stock body update unless it overrides it.
+ */
+export type StateLogic = Record<string, StateHooks>;
+/**
+ * Registers state code under a logic-set name. A role's name is also its
+ * logic-set name, so this is how a role's code is extended: registering
+ * again with the same name merges per state.
+ */
+export declare function defineStates(name: string, states: StateLogic): void;
+/** A role's starter state graph — what new characters of the role begin with. */
+export interface RoleGraph {
+    initial: string;
+    states: Record<string, StateJson>;
+}
+/**
+ * A character role: the whole behavior package behind one answer to
+ * "what is this character?". The editor uses the description to let the
+ * role explain itself, and the driver + graph to install the package.
+ */
+export interface RoleDefinition {
+    /** One plain-language line: what this role is and does. */
+    description: string;
+    /**
+     * Component the role's states move (they early-return without it).
+     * Several roles may share one driver — the contract is N roles : 1 driver.
+     */
+    driver?: string;
+    /** Starter graph installed when a character adopts this role. */
+    graph?: RoleGraph;
+    /** The role's state code, registered as the role's logic set. */
+    states?: StateLogic;
+    /**
+     * Signals the role's code emits (name → plain-language description).
+     * The editor lists them wherever a transition asks for a signal, so
+     * users pick from a vocabulary instead of typing names blind.
+     */
+    signals?: Record<string, string>;
+}
+/** All state-registry data an archetype installs before project extensions. */
+export interface ArchetypeBundle {
+    roles: Readonly<Record<string, RoleDefinition>>;
+    /** Extra named logic sets that are not themselves roles. */
+    logicSets?: Readonly<Record<string, StateLogic>>;
+}
+/** Clears role definitions and every named logic set. */
+export declare function resetRegistries(): void;
+/**
+ * Replaces the active registry contents with one archetype's complete bundle.
+ * Project defineRole/defineStates calls may extend this clean baseline after it
+ * is installed.
+ */
+export declare function installArchetype(bundle: ArchetypeBundle): void;
+/**
+ * Registers a character role. Prefabs adopt it via the StateMachine's
+ * `role` prop; the role's name doubles as its logic-set name, so
+ * defineStates(name, {...}) extends its code. Registering an existing
+ * role again merges its definition (and its states).
+ */
+export declare function defineRole(name: string, def: RoleDefinition): void;
+/** The registered role, if any — driver, graph and description included. */
+export declare function roleDefinition(name: string): RoleDefinition | undefined;
+/** Every registered role name — for the editor's Role pickers. */
+export declare function registeredRoles(): string[];
+/** The registered code for a set, if any. */
+export declare function logicSet(name: string): StateLogic | undefined;
+/** Every registered set name — for error messages and editor pickers. */
+export declare function registeredLogicSets(): string[];
+/** Closest registered set to a (likely typo'd) name, for the not-found error. */
+export declare function closestLogicSet(name: string): string | undefined;

package/dist/mcp/node_modules/@waica/engine/dist/state/hooks.js

@@ -0,0 +1,81 @@
+const sets = new Map();
+/**
+ * Registers state code under a logic-set name. A role's name is also its
+ * logic-set name, so this is how a role's code is extended: registering
+ * again with the same name merges per state.
+ */
+export function defineStates(name, states) {
+    sets.set(name, { ...sets.get(name), ...states });
+}
+const roles = new Map();
+/** Clears role definitions and every named logic set. */
+export function resetRegistries() {
+    roles.clear();
+    sets.clear();
+}
+/**
+ * Replaces the active registry contents with one archetype's complete bundle.
+ * Project defineRole/defineStates calls may extend this clean baseline after it
+ * is installed.
+ */
+export function installArchetype(bundle) {
+    resetRegistries();
+    for (const [name, def] of Object.entries(bundle.roles))
+        defineRole(name, def);
+    for (const [name, states] of Object.entries(bundle.logicSets ?? {})) {
+        defineStates(name, states);
+    }
+}
+/**
+ * Registers a character role. Prefabs adopt it via the StateMachine's
+ * `role` prop; the role's name doubles as its logic-set name, so
+ * defineStates(name, {...}) extends its code. Registering an existing
+ * role again merges its definition (and its states).
+ */
+export function defineRole(name, def) {
+    roles.set(name, { ...roles.get(name), ...def });
+    if (def.states)
+        defineStates(name, def.states);
+}
+/** The registered role, if any — driver, graph and description included. */
+export function roleDefinition(name) {
+    return roles.get(name);
+}
+/** Every registered role name — for the editor's Role pickers. */
+export function registeredRoles() {
+    return [...roles.keys()];
+}
+/** The registered code for a set, if any. */
+export function logicSet(name) {
+    return sets.get(name);
+}
+/** Every registered set name — for error messages and editor pickers. */
+export function registeredLogicSets() {
+    return [...sets.keys()];
+}
+/** Closest registered set to a (likely typo'd) name, for the not-found error. */
+export function closestLogicSet(name) {
+    let best;
+    let bestDistance = Infinity;
+    for (const candidate of sets.keys()) {
+        const distance = editDistance(name, candidate);
+        if (distance < bestDistance) {
+            bestDistance = distance;
+            best = candidate;
+        }
+    }
+    return bestDistance <= Math.max(2, Math.floor(name.length / 3)) ? best : undefined;
+}
+function editDistance(a, b) {
+    const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        let diagonal = row[0];
+        row[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const previous = row[j];
+            row[j] = Math.min(previous + 1, row[j - 1] + 1, diagonal + (a[i - 1] === b[j - 1] ? 0 : 1));
+            diagonal = previous;
+        }
+    }
+    return row[b.length];
+}

package/dist/mcp/node_modules/@waica/engine/dist/state/state-machine.d.ts

@@ -0,0 +1,83 @@
+import { Component } from '../component.js';
+import type { Entity } from '../entity.js';
+import { type StateHooks } from './hooks.js';
+/** One outgoing edge: when `on` fires, the machine moves to `to`. */
+export interface StateTransitionJson {
+    /** Trigger: 'input:<action>' | 'timer:<seconds>' | 'signal:<name>'. */
+    on: string;
+    to: string;
+}
+/**
+ * One state, as prefab data. Its code (if any) is looked up by state name
+ * in the machine's logic set. The '*' state key holds from-any-state
+ * transitions instead of a real state.
+ */
+export interface StateJson {
+    /** Clip to play on enter; defaults to the state's own name. */
+    clip?: string;
+    transitions?: StateTransitionJson[];
+}
+/** What a trigger string is checked against. */
+export interface TriggerEnv {
+    /** An unconsumed press of the action this frame (see Input.consume). */
+    justPressed(action: string): boolean;
+    /** Seconds spent in the current state. */
+    elapsed: number;
+    signals: ReadonlySet<string>;
+}
+/** Whether one trigger fires. Unknown or malformed triggers never fire. */
+export declare function evaluateTrigger(on: string, env: TriggerEnv): boolean;
+/** The first firing transition: the state's own edges, then '*''s. */
+export declare function nextTransition(states: Record<string, StateJson>, current: string, env: TriggerEnv): StateTransitionJson | undefined;
+/**
+ * The hooks that actually run for one phase of a state: the state's own
+ * (logic set + instance), or — when none of them define the phase — the
+ * set's 'default' entry. A custom state keeps the role's stock body
+ * update unless it brings its own.
+ */
+export declare function phaseHooks(hooks: StateHooks[], fallback: StateHooks | undefined, phase: keyof StateHooks): StateHooks[];
+/**
+ * Finite state machine: the single owner of a character's per-frame
+ * logic — only the active state's code moves the body, so behaviors
+ * never fight over velocity. States and transitions are prefab data;
+ * state code lives in the role's logic set (defineRole / defineStates)
+ * picked by `role`. Entering a state plays the sibling AnimatedSprite
+ * clip of the same name (or the state's `clip` override); a missing
+ * clip warns and keeps the previous one.
+ */
+export declare class StateMachine extends Component {
+    static componentName: string;
+    static displayName: string;
+    static params: {
+        role: {
+            label: string;
+        };
+    };
+    /** The character's role — names the logic set providing its state code. */
+    role: string;
+    /** Starting state; defaults to the first declared state. */
+    initial: string;
+    states: Record<string, StateJson>;
+    /** Active state name. */
+    current: string;
+    /** Seconds spent in the active state. */
+    elapsed: number;
+    private readonly instanceHooks;
+    private readonly signals;
+    private readonly warnedClips;
+    onReady(): void;
+    /** Adds instance-level hooks on top of the logic set — the escape hatch. */
+    on(state: string, hooks: StateHooks): void;
+    /** Queues a signal for 'signal:<name>' transitions, consumed this frame or the next. */
+    signal(name: string): void;
+    /** Jumps straight to a state, ignoring transitions. */
+    goto(state: string): void;
+    onUpdate(dt: number): void;
+    onCollide(other: Entity): void;
+    private env;
+    private hooksFor;
+    private run;
+    private runCollision;
+    private enter;
+    private playClip;
+}