@waica/cli 0.5.0 → 0.6.0

package/dist/mcp/node_modules/@waica/engine/dist/runtime-bridge.d.ts

@@ -0,0 +1,69 @@
+import type { RuntimeSnapshot, RuntimeSnapshotFilters } from './runtime-inspection.js';
+export declare const RUNTIME_BRIDGE_PROTOCOL_VERSION: 1;
+export declare const RUNTIME_BRIDGE_SYMBOL: unique symbol;
+export type RuntimeMode = 'paused' | 'real-time';
+export interface RuntimeMetadata {
+    bridgeVersion: typeof RUNTIME_BRIDGE_PROTOCOL_VERSION;
+    engineVersion: string;
+    mode: RuntimeMode;
+    frame: number;
+    simulationTime: number;
+}
+export type RuntimeControlRequest = {
+    operation: 'press' | 'hold' | 'release';
+    action: string;
+} | {
+    operation: 'pause' | 'resume';
+} | {
+    operation: 'step';
+    dt?: number;
+    frames?: number;
+};
+export interface RuntimeControlResult extends RuntimeMetadata {
+    heldActions: string[];
+}
+export declare class RuntimeBridgeOperationError extends Error {
+    readonly code: 'runtime-invalid-state' | 'runtime-operation-failed';
+    readonly availableActions?: string[] | undefined;
+    readonly stage: 'control';
+    constructor(code: 'runtime-invalid-state' | 'runtime-operation-failed', message: string, availableActions?: string[] | undefined);
+}
+/** Engine-owned capability registered only in an MCP-activated page. */
+export interface RuntimeBridge {
+    readonly surface: HTMLCanvasElement;
+    metadata(): RuntimeMetadata;
+    inspect(filters?: RuntimeSnapshotFilters): RuntimeSnapshot;
+    control(request: RuntimeControlRequest): RuntimeControlResult;
+}
+/** Ephemeral pre-page hook installed by the owner of a browser context. */
+export interface RuntimeBridgeActivation {
+    readonly protocolVersion: typeof RUNTIME_BRIDGE_PROTOCOL_VERSION;
+    register(bridge: RuntimeBridge): void;
+    unregister(bridge: RuntimeBridge): void;
+}
+export declare function activeRuntimeBridgeHook(): RuntimeBridgeActivation | null;
+export interface RuntimeBridgeHost {
+    step(dt: number): void;
+    resume(frame: (dt: number) => void): void;
+    pause(): void;
+    injectAction(action: string, operation: 'press' | 'hold' | 'release'): boolean;
+    availableActions(): string[];
+    heldActions(): string[];
+    inspect(metadata: RuntimeMetadata, filters?: RuntimeSnapshotFilters): RuntimeSnapshot;
+}
+export declare class EngineRuntimeBridge implements RuntimeBridge {
+    readonly surface: HTMLCanvasElement;
+    private readonly activation;
+    private readonly host;
+    readonly engineVersion: string;
+    private registered;
+    private mode;
+    private frame;
+    private simulationTime;
+    constructor(surface: HTMLCanvasElement, activation: RuntimeBridgeActivation, host: RuntimeBridgeHost);
+    metadata(): RuntimeMetadata;
+    inspect(filters?: RuntimeSnapshotFilters): RuntimeSnapshot;
+    control(request: RuntimeControlRequest): RuntimeControlResult;
+    private advance;
+    unregister(): void;
+}

package/dist/mcp/node_modules/@waica/engine/dist/runtime-bridge.js

@@ -0,0 +1,105 @@
+import enginePackage from '../package.json' with { type: 'json' };
+export const RUNTIME_BRIDGE_PROTOCOL_VERSION = 1;
+export const RUNTIME_BRIDGE_SYMBOL = Symbol.for('@waica/runtime-bridge/v1');
+export class RuntimeBridgeOperationError extends Error {
+    code;
+    availableActions;
+    stage = 'control';
+    constructor(code, message, availableActions) {
+        super(message);
+        this.code = code;
+        this.availableActions = availableActions;
+        this.name = 'RuntimeBridgeOperationError';
+    }
+}
+export function activeRuntimeBridgeHook() {
+    const candidate = globalThis[RUNTIME_BRIDGE_SYMBOL];
+    if (!candidate || typeof candidate !== 'object')
+        return null;
+    const hook = candidate;
+    if (hook.protocolVersion !== RUNTIME_BRIDGE_PROTOCOL_VERSION ||
+        typeof hook.register !== 'function' ||
+        typeof hook.unregister !== 'function') {
+        return null;
+    }
+    return hook;
+}
+export class EngineRuntimeBridge {
+    surface;
+    activation;
+    host;
+    engineVersion = enginePackage.version;
+    registered = true;
+    mode = 'paused';
+    frame = 0;
+    simulationTime = 0;
+    constructor(surface, activation, host) {
+        this.surface = surface;
+        this.activation = activation;
+        this.host = host;
+    }
+    metadata() {
+        return {
+            bridgeVersion: RUNTIME_BRIDGE_PROTOCOL_VERSION,
+            engineVersion: this.engineVersion,
+            mode: this.mode,
+            frame: this.frame,
+            simulationTime: this.simulationTime,
+        };
+    }
+    inspect(filters = {}) {
+        return this.host.inspect(this.metadata(), filters);
+    }
+    control(request) {
+        switch (request.operation) {
+            case 'pause':
+                if (this.mode === 'real-time') {
+                    this.host.pause();
+                    this.mode = 'paused';
+                }
+                break;
+            case 'resume':
+                if (this.mode === 'paused') {
+                    this.mode = 'real-time';
+                    this.host.resume((dt) => this.advance(dt));
+                }
+                break;
+            case 'press':
+            case 'hold':
+            case 'release':
+                if (!this.host.injectAction(request.action, request.operation)) {
+                    const available = this.host.availableActions();
+                    throw new RuntimeBridgeOperationError('runtime-operation-failed', `Unknown action "${request.action}". Available actions: ${available.join(', ') || '(none)'}.`, available);
+                }
+                break;
+            case 'step': {
+                if (this.mode !== 'paused') {
+                    throw new RuntimeBridgeOperationError('runtime-invalid-state', 'step is only available while the Runtime Bridge is paused.');
+                }
+                const dt = request.dt ?? 1 / 60;
+                const frames = request.frames ?? 1;
+                if (!Number.isFinite(dt) || dt <= 0 || dt > 0.1) {
+                    throw new RuntimeBridgeOperationError('runtime-operation-failed', 'dt must be finite and greater than 0 and at most 0.1.');
+                }
+                if (!Number.isInteger(frames) || frames < 1 || frames > 600) {
+                    throw new RuntimeBridgeOperationError('runtime-operation-failed', 'frames must be an integer from 1 through 600.');
+                }
+                for (let index = 0; index < frames; index += 1)
+                    this.advance(dt);
+                break;
+            }
+        }
+        return { ...this.metadata(), heldActions: this.host.heldActions() };
+    }
+    advance(dt) {
+        this.host.step(dt);
+        this.frame += 1;
+        this.simulationTime += dt;
+    }
+    unregister() {
+        if (!this.registered)
+            return;
+        this.registered = false;
+        this.activation.unregister(this);
+    }
+}

package/dist/mcp/node_modules/@waica/engine/dist/runtime-inspection.d.ts

@@ -0,0 +1,71 @@
+import type { Game } from './game.js';
+import type { RuntimeMetadata } from './runtime-bridge.js';
+import type { StatValue } from './stats.js';
+export type ProjectionMarkerKind = 'cycle' | 'unsupported' | 'error' | 'truncated';
+export interface ProjectionMarker {
+    $waica: ProjectionMarkerKind | 'date' | 'bigint' | 'map' | 'set';
+    [key: string]: unknown;
+}
+export type ProjectedValue = null | boolean | number | string | ProjectionMarker | ProjectedValue[] | {
+    [key: string]: ProjectedValue;
+};
+export interface ProjectionIssue {
+    path: string;
+    marker: ProjectionMarkerKind;
+    omitted?: number;
+}
+export interface RuntimeSnapshotFilters {
+    entity_ids?: string[];
+    entity_names?: string[];
+    component_types?: string[];
+}
+export interface RuntimeTransformSnapshot {
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    rotation: {
+        x: number;
+        y: number;
+        z: number;
+        order: string;
+    };
+    scale: {
+        x: number;
+        y: number;
+        z: number;
+    };
+}
+export interface RuntimeComponentSnapshot {
+    type: string;
+    index: number;
+    state: ProjectedValue;
+}
+export interface RuntimeEntitySnapshot {
+    id: string;
+    name: string;
+    transform: RuntimeTransformSnapshot;
+    components: RuntimeComponentSnapshot[];
+}
+export interface RuntimeSnapshot extends RuntimeMetadata {
+    stats: Record<string, StatValue>;
+    entities: RuntimeEntitySnapshot[];
+    projectionIssues: ProjectionIssue[];
+}
+export declare const RUNTIME_PROJECTION_LIMITS: {
+    readonly depth: 5;
+    readonly entries: 100;
+    readonly stringBytes: number;
+    readonly componentBytes: number;
+    readonly snapshotBytes: number;
+};
+export declare class RuntimeInspector {
+    private readonly game;
+    private readonly ids;
+    private nextId;
+    constructor(game: Game);
+    snapshot(metadata: RuntimeMetadata, filters?: RuntimeSnapshotFilters): RuntimeSnapshot;
+    private capSnapshot;
+    private idFor;
+}

package/dist/mcp/node_modules/@waica/engine/dist/runtime-inspection.js

@@ -0,0 +1,279 @@
+export const RUNTIME_PROJECTION_LIMITS = {
+    depth: 5,
+    entries: 100,
+    stringBytes: 4 * 1024,
+    componentBytes: 64 * 1024,
+    snapshotBytes: 1024 * 1024,
+};
+function marker(context, path, kind, detail = {}) {
+    context.issues.push({ path, marker: kind });
+    return { $waica: kind, ...detail };
+}
+function isPlainRecord(value) {
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+const textEncoder = new TextEncoder();
+function utf8Bytes(value) {
+    return textEncoder.encode(value).byteLength;
+}
+function stringPreview(value, byteLimit) {
+    let low = 0;
+    let high = value.length;
+    while (low < high) {
+        const middle = Math.ceil((low + high) / 2);
+        if (utf8Bytes(value.slice(0, middle)) <= byteLimit)
+            low = middle;
+        else
+            high = middle - 1;
+    }
+    const preview = value.slice(0, low);
+    const last = preview.charCodeAt(preview.length - 1);
+    return last >= 0xd800 && last <= 0xdbff ? preview.slice(0, -1) : preview;
+}
+function projectValue(value, path, context, depth = 0) {
+    if (depth > RUNTIME_PROJECTION_LIMITS.depth) {
+        return marker(context, path, 'truncated', {
+            reason: 'depth',
+            maxDepth: RUNTIME_PROJECTION_LIMITS.depth,
+        });
+    }
+    if (value === null || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'string') {
+        const bytes = utf8Bytes(value);
+        if (bytes <= RUNTIME_PROJECTION_LIMITS.stringBytes)
+            return value;
+        return marker(context, path, 'truncated', {
+            reason: 'string',
+            preview: stringPreview(value, RUNTIME_PROJECTION_LIMITS.stringBytes),
+            originalLength: value.length,
+            originalBytes: bytes,
+        });
+    }
+    if (typeof value === 'bigint')
+        return { $waica: 'bigint', value: value.toString() };
+    if (typeof value === 'number') {
+        return Number.isFinite(value)
+            ? value
+            : marker(context, path, 'unsupported', { type: 'non-finite-number' });
+    }
+    if (typeof value !== 'object') {
+        return marker(context, path, 'unsupported', { type: typeof value });
+    }
+    const previousPath = context.seen.get(value);
+    if (previousPath)
+        return marker(context, path, 'cycle', { path: previousPath });
+    context.seen.set(value, path);
+    if (value instanceof Date) {
+        return Number.isFinite(value.getTime())
+            ? { $waica: 'date', value: value.toISOString() }
+            : marker(context, path, 'error', { message: 'Invalid Date' });
+    }
+    if (Array.isArray(value)) {
+        const entries = value.slice(0, RUNTIME_PROJECTION_LIMITS.entries)
+            .map((entry, index) => projectValue(entry, `${path}[${index}]`, context, depth + 1));
+        const omitted = value.length - entries.length;
+        if (omitted > 0) {
+            entries.push(marker(context, path, 'truncated', { reason: 'entries', omitted }));
+        }
+        return entries;
+    }
+    if (value instanceof Map) {
+        const sourceEntries = [...value.entries()];
+        const entries = sourceEntries.slice(0, RUNTIME_PROJECTION_LIMITS.entries)
+            .map(([key, entry], index) => [
+            projectValue(key, `${path}.entries[${index}].key`, context, depth + 1),
+            projectValue(entry, `${path}.entries[${index}].value`, context, depth + 1),
+        ]);
+        const omitted = sourceEntries.length - entries.length;
+        return {
+            $waica: 'map',
+            entries,
+            ...(omitted > 0
+                ? { truncated: marker(context, path, 'truncated', { reason: 'entries', omitted }) }
+                : {}),
+        };
+    }
+    if (value instanceof Set) {
+        const sourceValues = [...value];
+        const values = sourceValues.slice(0, RUNTIME_PROJECTION_LIMITS.entries)
+            .map((entry, index) => projectValue(entry, `${path}.values[${index}]`, context, depth + 1));
+        const omitted = sourceValues.length - values.length;
+        return {
+            $waica: 'set',
+            values,
+            ...(omitted > 0
+                ? { truncated: marker(context, path, 'truncated', { reason: 'entries', omitted }) }
+                : {}),
+        };
+    }
+    if (isPlainRecord(value)) {
+        const keys = Object.keys(value).sort();
+        const projected = Object.fromEntries(keys.slice(0, RUNTIME_PROJECTION_LIMITS.entries)
+            .map((key) => [
+            key,
+            projectValue(value[key], `${path}.${key}`, context, depth + 1),
+        ]));
+        const omitted = keys.length - Object.keys(projected).length;
+        if (omitted === 0)
+            return projected;
+        return marker(context, path, 'truncated', {
+            reason: 'entries',
+            omitted,
+            value: projected,
+        });
+    }
+    return marker(context, path, 'unsupported', {
+        type: value.constructor?.name ?? 'object',
+    });
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function componentState(component, path, context) {
+    if (typeof component.inspectState === 'function') {
+        try {
+            return projectValue(component.inspectState(), path, context);
+        }
+        catch (error) {
+            return marker(context, path, 'error', { message: errorMessage(error) });
+        }
+    }
+    const keys = new Set(Object.keys(component));
+    for (let prototype = Object.getPrototypeOf(component); prototype && prototype !== Object.prototype; prototype = Object.getPrototypeOf(prototype)) {
+        for (const [key, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(prototype))) {
+            if (typeof descriptor.set === 'function')
+                keys.add(key);
+        }
+    }
+    const state = {};
+    for (const key of [...keys].sort()) {
+        if (key === 'entity' || key === 'game' || key.startsWith('_'))
+            continue;
+        const valuePath = `${path}.${key}`;
+        try {
+            const value = component[key];
+            if (typeof value === 'function')
+                continue;
+            state[key] = projectValue(value, valuePath, context, 1);
+        }
+        catch (error) {
+            state[key] = marker(context, valuePath, 'error', { message: errorMessage(error) });
+        }
+    }
+    return state;
+}
+function boundedComponentState(component, path, context) {
+    const state = componentState(component, path, context);
+    const originalBytes = utf8Bytes(JSON.stringify(state));
+    if (originalBytes <= RUNTIME_PROJECTION_LIMITS.componentBytes)
+        return state;
+    return marker(context, path, 'truncated', {
+        reason: 'component-size',
+        limit: RUNTIME_PROJECTION_LIMITS.componentBytes,
+        originalBytes,
+        path,
+    });
+}
+export class RuntimeInspector {
+    game;
+    ids = new WeakMap();
+    nextId = 1;
+    constructor(game) {
+        this.game = game;
+    }
+    snapshot(metadata, filters = {}) {
+        const projectionIssues = [];
+        const idFilter = filters.entity_ids ? new Set(filters.entity_ids) : null;
+        const nameFilter = filters.entity_names ? new Set(filters.entity_names) : null;
+        const componentFilter = filters.component_types ? new Set(filters.component_types) : null;
+        const live = this.game.entities.map((entity) => ({ entity, id: this.idFor(entity) }));
+        const entities = live.flatMap(({ entity, id }) => {
+            if (idFilter && !idFilter.has(id))
+                return [];
+            if (nameFilter && !nameFilter.has(entity.name))
+                return [];
+            const components = entity.components.flatMap((component, index) => {
+                const Class = component.constructor;
+                if (componentFilter && !componentFilter.has(Class.componentName))
+                    return [];
+                const context = { issues: projectionIssues, seen: new Map() };
+                return [{
+                        type: Class.componentName,
+                        index,
+                        state: boundedComponentState(component, `entities[${id}].components[${index}].state`, context),
+                    }];
+            });
+            if (componentFilter && components.length === 0)
+                return [];
+            return [{
+                    id,
+                    name: entity.name,
+                    transform: {
+                        position: {
+                            x: entity.position.x,
+                            y: entity.position.y,
+                            z: entity.position.z,
+                        },
+                        rotation: {
+                            x: entity.node.rotation.x,
+                            y: entity.node.rotation.y,
+                            z: entity.node.rotation.z,
+                            order: entity.node.rotation.order,
+                        },
+                        scale: {
+                            x: entity.scale.x,
+                            y: entity.scale.y,
+                            z: entity.scale.z,
+                        },
+                    },
+                    components,
+                }];
+        });
+        return this.capSnapshot({
+            ...metadata,
+            stats: Object.fromEntries([...this.game.stats.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))),
+            entities,
+            projectionIssues,
+        });
+    }
+    capSnapshot(snapshot) {
+        if (utf8Bytes(JSON.stringify(snapshot)) <= RUNTIME_PROJECTION_LIMITS.snapshotBytes) {
+            return snapshot;
+        }
+        const retained = [...snapshot.entities];
+        const removedIds = new Set();
+        while (retained.length > 0) {
+            const removed = retained.pop();
+            if (removed)
+                removedIds.add(removed.id);
+            const omitted = snapshot.entities.length - retained.length;
+            const projectionIssues = snapshot.projectionIssues
+                .filter((issue) => [...removedIds].every((id) => !issue.path.startsWith(`entities[${id}]`)))
+                .concat({ path: `entities[${retained.length}]`, marker: 'truncated', omitted });
+            const candidate = { ...snapshot, entities: retained, projectionIssues };
+            if (utf8Bytes(JSON.stringify(candidate)) <= RUNTIME_PROJECTION_LIMITS.snapshotBytes) {
+                return candidate;
+            }
+        }
+        return {
+            ...snapshot,
+            entities: [],
+            projectionIssues: [{
+                    path: 'entities[0]',
+                    marker: 'truncated',
+                    omitted: snapshot.entities.length,
+                }],
+        };
+    }
+    idFor(entity) {
+        const existing = this.ids.get(entity);
+        if (existing)
+            return existing;
+        const id = `entity-${this.nextId}`;
+        this.nextId += 1;
+        this.ids.set(entity, id);
+        return id;
+    }
+}

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

@@ -1,6 +1,6 @@
 {
   "name": "@waica/engine",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Waica game engine core — archetype-driven, web-first, 2D & 3D",
   "license": "MIT",
   "type": "module",
@@ -10,7 +10,8 @@
     "directory": "packages/engine"
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "exports": {
     ".": {