@waica/cli 0.5.0 → 0.6.0

package/dist/mcp/server.js

@@ -6,7 +6,10 @@ import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextpro
 import { createProject } from './create-project.js';
 import { describeArchetype, listComponents, projectSummary, } from './introspection.js';
 import { ABSOLUTE_PATH_MESSAGE, WaicaToolError, assertAbsoluteProjectPath, requireWaicaProject, } from './project-path.js';
-import { scaffoldComponent, scaffoldRole, scaffoldState, scaffoldUi, } from './scaffolds.js';
+import { scaffoldComponent, scaffoldPrefab, scaffoldRole, scaffoldState, scaffoldUi, } from './scaffolds.js';
+import { RuntimeToolError, } from './runtime-service.js';
+import { createDefaultRuntimeSessionManager } from './runtime-session-manager.js';
+import { ProjectComponentLoader } from './project-component-loader.js';
 import { validateProject } from './validation.js';
 const PROJECT_PATH = {
     type: 'string',
@@ -69,6 +72,29 @@ export const TOOLS = [
         inputSchema: schema({ name: { type: 'string', minLength: 1 } }, ['name']),
         annotations: { destructiveHint: false, idempotentHint: true, openWorldHint: false },
     },
+    {
+        name: 'scaffold_prefab',
+        description: 'Create the editor-compatible starter prefab for a character, object or tile.',
+        inputSchema: schema({
+            name: { type: 'string', minLength: 1, description: 'Prefab file name, without the type suffix.' },
+            type: {
+                type: 'string',
+                enum: ['character', 'object', 'tile'],
+                description: 'Prefab category; it decides the directory and the file suffix.',
+            },
+            role: {
+                type: 'string',
+                minLength: 1,
+                description: 'Character role from the active archetype (characters only); defaults to player.',
+            },
+            identity: {
+                type: 'string',
+                enum: ['player', 'enemy', 'npc', 'custom'],
+                description: 'What the character is to the game (characters only); adds its starter components.',
+            },
+        }, ['name', 'type']),
+        annotations: { destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    },
     {
         name: 'scaffold_role',
         description: 'Create the editor-compatible starter for a custom character role.',
@@ -95,7 +121,92 @@ export const TOOLS = [
         inputSchema: schema({ name: { type: 'string', minLength: 1 } }, ['name']),
         annotations: { destructiveHint: false, idempotentHint: true, openWorldHint: false },
     },
+    {
+        name: 'start_project',
+        description: 'Start or reuse a browser-backed Run Session for a trusted Waica Project.',
+        inputSchema: schema({
+            browser_executable_path: { type: 'string', minLength: 1 },
+            headless: { type: 'boolean', default: true },
+            viewport: {
+                type: 'object',
+                properties: {
+                    width: { type: 'integer', minimum: 1 },
+                    height: { type: 'integer', minimum: 1 },
+                },
+                required: ['width', 'height'],
+                additionalProperties: false,
+            },
+            timeout_ms: { type: 'integer', minimum: 1_000, maximum: 120_000, default: 30_000 },
+        }),
+        annotations: { destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    },
+    {
+        name: 'stop_project',
+        description: 'Stop a Project Run Session and all browser and process resources it owns.',
+        inputSchema: schema({}),
+        annotations: { destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    },
+    {
+        name: 'inspect_runtime',
+        description: 'Read a filtered Runtime Snapshot from a running Project.',
+        inputSchema: schema({
+            entity_ids: { type: 'array', items: { type: 'string' } },
+            entity_names: { type: 'array', items: { type: 'string' } },
+            component_types: { type: 'array', items: { type: 'string' } },
+        }),
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+    {
+        name: 'control_runtime',
+        description: 'Inject a semantic action or change deterministic frame control for a Run Session.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_path: PROJECT_PATH,
+                operation: {
+                    type: 'string',
+                    enum: ['press', 'hold', 'release', 'pause', 'resume', 'step'],
+                },
+                action: { type: 'string', minLength: 1 },
+                dt: { type: 'number', exclusiveMinimum: 0, maximum: 0.1 },
+                frames: { type: 'integer', minimum: 1, maximum: 600 },
+            },
+            required: ['project_path', 'operation'],
+            additionalProperties: false,
+            oneOf: [
+                {
+                    properties: { operation: { enum: ['press', 'hold', 'release'] } },
+                    required: ['action'],
+                    not: { anyOf: [{ required: ['dt'] }, { required: ['frames'] }] },
+                },
+                {
+                    properties: { operation: { enum: ['pause', 'resume'] } },
+                    not: {
+                        anyOf: [{ required: ['action'] }, { required: ['dt'] }, { required: ['frames'] }],
+                    },
+                },
+                {
+                    properties: { operation: { const: 'step' } },
+                    not: { anyOf: [{ required: ['action'] }] },
+                },
+            ],
+        },
+        annotations: { destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    },
+    {
+        name: 'capture_screenshot',
+        description: 'Capture the composited Waica Game surface from a running Project.',
+        inputSchema: schema({}),
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    },
 ];
+const RUNTIME_TOOL_NAMES = new Set([
+    'start_project',
+    'stop_project',
+    'inspect_runtime',
+    'control_runtime',
+    'capture_screenshot',
+]);
 function requiredString(args, name, projectPath = '') {
     const value = args[name];
     if (typeof value === 'string' && value.length > 0)
@@ -106,11 +217,131 @@ function requiredString(args, name, projectPath = '') {
         projectPath,
     });
 }
-async function execute(name, args) {
+function invalidRuntimeInput(name, projectPath, message) {
+    throw new RuntimeToolError({
+        code: 'runtime-operation-failed',
+        stage: name === 'control_runtime' ? 'control' : 'project',
+        message,
+        projectPath,
+    });
+}
+function assertOnlyRuntimeFields(name, args, allowed, projectPath) {
+    const extras = Object.keys(args).filter((key) => !allowed.includes(key));
+    if (extras.length > 0) {
+        invalidRuntimeInput(name, projectPath, `Unexpected properties: ${extras.sort().join(', ')}.`);
+    }
+}
+function assertStringArray(name, args, field, projectPath) {
+    const value = args[field];
+    if (value !== undefined && (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string'))) {
+        invalidRuntimeInput(name, projectPath, `${field} must be an array of strings.`);
+    }
+}
+function validateRuntimeArguments(name, args, projectPath) {
+    switch (name) {
+        case 'start_project': {
+            assertOnlyRuntimeFields(name, args, ['project_path', 'browser_executable_path', 'headless', 'viewport', 'timeout_ms'], projectPath);
+            if (args.browser_executable_path !== undefined &&
+                (typeof args.browser_executable_path !== 'string' || args.browser_executable_path.length === 0)) {
+                invalidRuntimeInput(name, projectPath, 'browser_executable_path must be a nonempty string.');
+            }
+            if (args.headless !== undefined && typeof args.headless !== 'boolean') {
+                invalidRuntimeInput(name, projectPath, 'headless must be a boolean.');
+            }
+            if (args.timeout_ms !== undefined) {
+                const timeout = args.timeout_ms;
+                if (typeof timeout !== 'number' || !Number.isInteger(timeout) || timeout < 1_000 || timeout > 120_000) {
+                    invalidRuntimeInput(name, projectPath, 'timeout_ms must be an integer from 1,000 through 120,000.');
+                }
+            }
+            if (args.viewport !== undefined) {
+                if (!args.viewport || typeof args.viewport !== 'object' || Array.isArray(args.viewport)) {
+                    invalidRuntimeInput(name, projectPath, 'viewport must contain width and height.');
+                }
+                const viewport = args.viewport;
+                const keys = Object.keys(viewport);
+                if (keys.some((key) => key !== 'width' && key !== 'height') ||
+                    keys.length !== 2 ||
+                    typeof viewport.width !== 'number' ||
+                    typeof viewport.height !== 'number' ||
+                    !Number.isInteger(viewport.width) ||
+                    !Number.isInteger(viewport.height) ||
+                    viewport.width <= 0 ||
+                    viewport.height <= 0 ||
+                    viewport.width * viewport.height > 1_000_000) {
+                    invalidRuntimeInput(name, projectPath, 'viewport width and height must be positive integers totaling at most 1,000,000 pixels.');
+                }
+            }
+            return;
+        }
+        case 'stop_project':
+        case 'capture_screenshot':
+            assertOnlyRuntimeFields(name, args, ['project_path'], projectPath);
+            return;
+        case 'inspect_runtime':
+            assertOnlyRuntimeFields(name, args, ['project_path', 'entity_ids', 'entity_names', 'component_types'], projectPath);
+            assertStringArray(name, args, 'entity_ids', projectPath);
+            assertStringArray(name, args, 'entity_names', projectPath);
+            assertStringArray(name, args, 'component_types', projectPath);
+            return;
+        case 'control_runtime': {
+            assertOnlyRuntimeFields(name, args, ['project_path', 'operation', 'action', 'dt', 'frames'], projectPath);
+            const operation = args.operation;
+            if (!['press', 'hold', 'release', 'pause', 'resume', 'step'].includes(String(operation))) {
+                invalidRuntimeInput(name, projectPath, 'operation is not a supported runtime control operation.');
+            }
+            if (operation === 'press' || operation === 'hold' || operation === 'release') {
+                if (typeof args.action !== 'string' || args.action.length === 0) {
+                    invalidRuntimeInput(name, projectPath, `${operation} requires a nonempty action.`);
+                }
+                if (args.dt !== undefined || args.frames !== undefined) {
+                    invalidRuntimeInput(name, projectPath, `${operation} does not accept dt or frames.`);
+                }
+            }
+            else if (operation === 'pause' || operation === 'resume') {
+                if (args.action !== undefined || args.dt !== undefined || args.frames !== undefined) {
+                    invalidRuntimeInput(name, projectPath, `${operation} accepts no additional fields.`);
+                }
+            }
+            else {
+                if (args.action !== undefined)
+                    invalidRuntimeInput(name, projectPath, 'step does not accept action.');
+                if (args.dt !== undefined &&
+                    (typeof args.dt !== 'number' || !Number.isFinite(args.dt) || args.dt <= 0 || args.dt > 0.1)) {
+                    invalidRuntimeInput(name, projectPath, 'dt must be finite and greater than 0 and at most 0.1.');
+                }
+                if (args.frames !== undefined &&
+                    (typeof args.frames !== 'number' || !Number.isInteger(args.frames) || args.frames < 1 || args.frames > 600)) {
+                    invalidRuntimeInput(name, projectPath, 'frames must be an integer from 1 through 600.');
+                }
+            }
+            return;
+        }
+    }
+}
+async function execute(name, args, runtime, signal, componentLoader) {
+    const isRuntimeTool = RUNTIME_TOOL_NAMES.has(name);
+    const rawProjectPath = args.project_path;
+    if (isRuntimeTool && (typeof rawProjectPath !== 'string' || rawProjectPath.length === 0)) {
+        invalidRuntimeInput(name, '', 'project_path must be a nonempty absolute path.');
+    }
     const projectPath = requiredString(args, 'project_path');
     // Keep this at the dispatch boundary so every tool has byte-identical
     // stdio-cwd semantics, including create_project.
-    assertAbsoluteProjectPath(projectPath);
+    if (isRuntimeTool) {
+        if (!path.isAbsolute(projectPath)) {
+            throw new RuntimeToolError({
+                code: 'runtime-prerequisite-missing',
+                stage: 'project',
+                message: ABSOLUTE_PATH_MESSAGE,
+                projectPath,
+            });
+        }
+        validateRuntimeArguments(name, args, projectPath);
+    }
+    else {
+        assertAbsoluteProjectPath(projectPath);
+    }
     switch (name) {
         case 'create_project': {
             const start = args.start === undefined ? 'demo' : requiredString(args, 'start', projectPath);
@@ -130,7 +361,7 @@ async function execute(name, args) {
         case 'project_summary':
             return projectSummary(projectPath);
         case 'validate_project':
-            return validateProject(projectPath);
+            return validateProject(projectPath, { signal, componentLoader });
         case 'scaffold_component': {
             const check = await requireWaicaProject(projectPath);
             return {
@@ -140,6 +371,15 @@ async function execute(name, args) {
                 warnings: [],
             };
         }
+        case 'scaffold_prefab': {
+            const check = await requireWaicaProject(projectPath);
+            return {
+                ...(await scaffoldPrefab(projectPath, requiredString(args, 'name', projectPath), requiredString(args, 'type', projectPath), args.role === undefined ? undefined : requiredString(args, 'role', projectPath), args.identity === undefined ? undefined : requiredString(args, 'identity', projectPath))),
+                notes: check.notes,
+                provenance: [],
+                warnings: [],
+            };
+        }
         case 'scaffold_role': {
             const check = await requireWaicaProject(projectPath);
             return {
@@ -167,6 +407,39 @@ async function execute(name, args) {
                 warnings: [],
             };
         }
+        case 'start_project':
+            return runtime.start({
+                projectPath,
+                ...(typeof args.browser_executable_path === 'string'
+                    ? { browserExecutablePath: args.browser_executable_path }
+                    : {}),
+                ...(typeof args.headless === 'boolean' ? { headless: args.headless } : {}),
+                ...(args.viewport && typeof args.viewport === 'object'
+                    ? { viewport: args.viewport }
+                    : {}),
+                ...(typeof args.timeout_ms === 'number' ? { timeoutMs: args.timeout_ms } : {}),
+            });
+        case 'stop_project':
+            return runtime.stop(projectPath);
+        case 'inspect_runtime':
+            return runtime.inspect({
+                projectPath,
+                ...(Array.isArray(args.entity_ids) ? { entityIds: args.entity_ids } : {}),
+                ...(Array.isArray(args.entity_names) ? { entityNames: args.entity_names } : {}),
+                ...(Array.isArray(args.component_types)
+                    ? { componentTypes: args.component_types }
+                    : {}),
+            });
+        case 'control_runtime':
+            return runtime.control({
+                projectPath,
+                operation: requiredString(args, 'operation', projectPath),
+                ...(typeof args.action === 'string' ? { action: args.action } : {}),
+                ...(typeof args.dt === 'number' ? { dt: args.dt } : {}),
+                ...(typeof args.frames === 'number' ? { frames: args.frames } : {}),
+            });
+        case 'capture_screenshot':
+            return runtime.captureScreenshot(projectPath);
         default:
             throw new WaicaToolError({
                 code: 'unknown-tool',
@@ -186,11 +459,39 @@ function result(payload, isError = false) {
         ...(isError ? { isError: true } : {}),
     };
 }
-function errorResult(error, args) {
+function screenshotResult(screenshot) {
+    const metadata = jsonSafe(screenshot.metadata);
+    return {
+        content: [
+            { type: 'text', text: JSON.stringify(metadata, null, 2) },
+            { type: 'image', mimeType: 'image/png', data: screenshot.data },
+        ],
+        structuredContent: metadata,
+    };
+}
+function errorResult(error, args, toolName) {
     const projectPath = typeof args.project_path === 'string' ? args.project_path : '';
+    if (error instanceof RuntimeToolError) {
+        return result({ error: error.body }, true);
+    }
     if (error instanceof WaicaToolError) {
         return result({ error: error.body, provenance: [] }, true);
     }
+    if (RUNTIME_TOOL_NAMES.has(toolName)) {
+        const stage = toolName === 'control_runtime'
+            ? 'control'
+            : toolName === 'stop_project'
+                ? 'cleanup'
+                : 'game';
+        return result({
+            error: {
+                code: 'runtime-operation-failed',
+                stage,
+                message: error instanceof Error ? error.message : String(error),
+                projectPath,
+            },
+        }, true);
+    }
     return result({
         error: {
             code: 'tool-error',
@@ -224,7 +525,9 @@ function shippedVersion() {
         directory = parent;
     }
 }
-export function createWaicaMcpServer() {
+export function createWaicaMcpServer(options = {}) {
+    const runtime = options.runtime ?? createDefaultRuntimeSessionManager();
+    const componentLoader = options.componentLoader ?? new ProjectComponentLoader();
     const server = new Server(
     // The name stays fixed: it identifies the server to the host, not the
     // package that happens to carry it.
@@ -233,15 +536,33 @@ export function createWaicaMcpServer() {
         instructions: 'Operate on user Waica projects through absolute project_path values. Keep editing JSON and TypeScript with the host file tools.',
     });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
-    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
         const args = (request.params.arguments ?? {});
         try {
-            return result(await execute(request.params.name, args));
+            const executed = await execute(request.params.name, args, runtime, extra.signal, componentLoader);
+            return request.params.name === 'capture_screenshot'
+                ? screenshotResult(executed)
+                : result(executed);
         }
         catch (error) {
-            return errorResult(error, args);
+            if (extra.signal.aborted)
+                throw (extra.signal.reason ?? error);
+            return errorResult(error, args, request.params.name);
         }
     });
+    let cleanup;
+    const cleanupResources = () => {
+        cleanup ??= Promise.all([runtime.close(), componentLoader.close()]).then(() => undefined);
+        return cleanup;
+    };
+    server.onclose = () => {
+        void cleanupResources();
+    };
+    const closeProtocol = server.close.bind(server);
+    server.close = async () => {
+        await cleanupResources();
+        await closeProtocol();
+    };
     return server;
 }
 export { ABSOLUTE_PATH_MESSAGE };

package/dist/mcp/stdio.js

@@ -1,36 +1,11 @@
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { prepareWorkspaceRuntime } from './workspace-runtime.js';
-/**
- * Logs to stderr (never stdout — that's the JSON-RPC transport) instead of
- * letting the failure reach Node's default handling. Exported so the logging
- * itself is unit-testable without touching the global process listeners.
- */
-export function reportProjectCodeFailure(kind, detail) {
-    console.error(`waica-mcp: ${kind} — likely async work scheduled by a project module executed during ` +
-        'validate_project (e.g. a floating fetch() or a throwing setTimeout callback). ' +
-        'The server keeps running:', detail);
-}
-/**
- * validate_project runs project-owned components/roles/states in-process
- * (project-component-loader.ts). That code can schedule async work that
- * rejects or throws *after* module evaluation already returned — Node's
- * default handling for that is to crash the whole process, which would take
- * down this long-lived stdio server and every other in-flight tool call for
- * one module's sloppy code. A subprocess sandbox for project code is a
- * larger, separately tracked follow-up; this keeps the blast radius to a
- * logged line for now.
- */
-function installProjectCodeGuards() {
-    process.on('unhandledRejection', (reason) => reportProjectCodeFailure('unhandledRejection', reason));
-    process.on('uncaughtException', (error) => reportProjectCodeFailure('uncaughtException', error));
-}
 /**
  * Connects the MCP server to stdio. Kept separate from the bin wrapper so the
  * waica CLI can start the same server in-process from its bundled copy without
  * importing a module that runs on load.
  */
 export async function startStdioServer() {
-    installProjectCodeGuards();
     await prepareWorkspaceRuntime();
     const { createWaicaMcpServer } = await import('./server.js');
     const server = createWaicaMcpServer();

package/dist/mcp/template/src/main.ts

@@ -14,7 +14,12 @@ import settings from './game.json'
 
 // Your components, roles and state code extend the installed archetype
 // baseline when main() imports them.
-const projectCode = import.meta.glob(['./components/*.ts', './roles/*.ts', './states/*.ts'])
+const projectCode = import.meta.glob([
+  './components/*.ts',
+  './roles/*.ts',
+  './states/*.ts',
+  '!**/*.test.ts',
+])
 
 // Your prefabs ARE these files (saved by the editor, or hand-edited — they're
 // just JSON). Nothing else: delete one and the game stops knowing about it.

package/dist/mcp/validation.js

@@ -1,9 +1,10 @@
+import { resolveComponentUpdateSchedule, } from '@waica/engine';
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { discoverArchetypes, pickArchetype } from './archetypes.js';
 import { classDefaults, objectRecord } from './component-metadata.js';
 import { PackageResolver, mixedSourceWarnings, provenanceRows, } from './package-resolver.js';
-import { loadProjectComponents } from './project-component-loader.js';
+import { loadProjectComponents, } from './project-component-loader.js';
 import { directFiles, requireWaicaProject } from './project-path.js';
 function add(context, severity, code, message, file, ref) {
     context.findings.push({ severity, code, message, file, ...(ref ? { ref } : {}) });
@@ -49,7 +50,7 @@ function componentList(value) {
 }
 function classMetadata(Class) {
     // A throwing constructor has no observable defaults, matching list_components.
-    return { params: Class.params ?? {}, defaults: classDefaults(Class) };
+    return { Class, params: Class.params ?? {}, defaults: classDefaults(Class) };
 }
 /** Clip names declared by the sibling AnimatedSprite, or undefined when there is none (no animation contract to check). */
 function siblingClips(siblings) {
@@ -171,7 +172,7 @@ function validateStateMachines(components, file, ref, context) {
                 }
                 if (typeof on === 'string' && on.startsWith('input:')) {
                     const action = on.slice('input:'.length);
-                    if (!context.bindings[action]?.length) {
+                    if (!isBoundAction(context.bindings, action)) {
                         add(context, 'warning', 'input-action-unbound', `Input action "${action}" has no bindings.`, file, action);
                     }
                 }
@@ -199,12 +200,63 @@ function resolvedEntityComponents(entity, prefab) {
     }));
     return [...inherited, ...componentList(entity.components)];
 }
+function componentUpdateIssueKey(issue) {
+    switch (issue.code) {
+        case 'duplicate-component':
+            return `${issue.code}:${issue.componentName}:${issue.count}`;
+        case 'invalid-update-constraint':
+            return `${issue.code}:${issue.reason}:${issue.declarer}:${issue.target ?? ''}`;
+        case 'component-update-cycle':
+            return `${issue.code}:${issue.componentNames.join('\0')}`;
+    }
+}
+function componentUpdateIssues(components, context) {
+    const result = resolveComponentUpdateSchedule(components.map((component) => component.type), context.componentRegistry);
+    return result.ok ? [] : [...result.issues];
+}
+function addComponentUpdateFinding(issue, file, ref, context) {
+    let findingFile = file;
+    let findingRef = ref;
+    if (issue.code === 'invalid-update-constraint') {
+        const source = context.componentMetadata.get(issue.declarer)?.sourceFile;
+        if (source) {
+            const key = `${source}:${componentUpdateIssueKey(issue)}`;
+            if (context.reportedClassConstraints.has(key))
+                return;
+            context.reportedClassConstraints.add(key);
+            findingFile = source;
+            findingRef = issue.declarer;
+        }
+    }
+    add(context, 'error', issue.code, issue.cause, findingFile, findingRef);
+}
+function validateComponentUpdateSchedule(components, file, ref, context, inheritedIssues = new Set()) {
+    for (const issue of componentUpdateIssues(components, context)) {
+        if (inheritedIssues.has(componentUpdateIssueKey(issue)))
+            continue;
+        addComponentUpdateFinding(issue, file, ref, context);
+    }
+}
+function validateComponentClassUpdateContracts(context) {
+    for (const componentName of Object.keys(context.componentRegistry).sort()) {
+        const metadata = context.componentMetadata.get(componentName);
+        const result = resolveComponentUpdateSchedule([componentName], context.componentRegistry);
+        if (result.ok)
+            continue;
+        for (const issue of result.issues) {
+            if (issue.code !== 'invalid-update-constraint')
+                continue;
+            addComponentUpdateFinding(issue, metadata?.sourceFile ?? 'package.json', componentName, context);
+        }
+    }
+}
 function validatePrefab(prefab, file, ref, context) {
     const components = componentList(prefab.components);
     for (const component of components)
         checkComponent(component, file, ref, context);
     validateParamReferences(components.map((component) => ({ component })), components, file, context);
     validateStateMachines(components, file, ref, context);
+    validateComponentUpdateSchedule(components, file, ref, context);
 }
 function validateScene(scene, file, prefabs, uiNames, context) {
     const rawEntities = Array.isArray(scene.entities) ? scene.entities : [];
@@ -305,6 +357,13 @@ function validateScene(scene, file, prefabs, uiNames, context) {
         if (changesStateBehavior) {
             validateStateMachines(effectiveComponents(), file, entityRef, context);
         }
+        // A plain prefab instance inherits the prefab-level result already emitted
+        // above. Inline components create a new effective composition; report only
+        // the issues they introduce, not every inherited issue again.
+        if (inline.length > 0) {
+            const inheritedIssues = new Set(componentUpdateIssues(componentList(prefab?.components), context).map(componentUpdateIssueKey));
+            validateComponentUpdateSchedule(effectiveComponents(), file, entityRef, context, inheritedIssues);
+        }
     }
 }
 function statBindings(html) {
@@ -321,7 +380,8 @@ function statBindings(html) {
     }
     return names;
 }
-export async function validateProject(projectPath) {
+export async function validateProject(projectPath, options = {}) {
+    options.signal?.throwIfAborted();
     const check = await requireWaicaProject(projectPath);
     const findings = [];
     const fixedPaths = [
@@ -350,7 +410,9 @@ export async function validateProject(projectPath) {
         discoverArchetypes(projectPath, resolver, discoveryWarnings, activeId ? [activeId] : []),
         projectComponentCandidates(projectPath),
         projectRoleStateSources(projectPath),
-        loadProjectComponents(projectPath, resolver),
+        options.componentLoader
+            ? options.componentLoader.load(projectPath, resolver, { signal: options.signal })
+            : loadProjectComponents(projectPath, resolver, { signal: options.signal }),
     ]);
     for (const failure of loadedProjectComponents.failures) {
         add({ findings }, 
@@ -376,14 +438,20 @@ export async function validateProject(projectPath) {
     }
     const stateFiles = new Set((await directFiles(path.join(projectPath, 'src/states'), '.ts')).map((file) => file.slice(0, -'.ts'.length)));
     const declaredStats = new Set(Object.keys(objectRecord(objectRecord(fixed.get('src/stats.json')).stats)));
-    const componentMetadata = new Map(Object.entries(manifest.registry.components).map(([name, Class]) => [
+    const componentRegistry = {
+        ...manifest.registry.components,
+    };
+    const componentMetadata = new Map(Object.entries(componentRegistry).map(([name, Class]) => [
         name,
         classMetadata(Class),
     ]));
     for (const [name, description] of Object.entries(loadedProjectComponents.components)) {
+        componentRegistry[name] = description.Class;
         componentMetadata.set(name, {
+            Class: description.Class,
             params: description.params,
             defaults: description.defaults,
+            sourceFile: description.file,
         });
         projectComponents.add(name);
     }
@@ -414,12 +482,15 @@ export async function validateProject(projectPath) {
         knownComponents: new Set(Object.keys(manifest.registry.components)),
         projectComponents,
         componentMetadata,
+        componentRegistry,
+        reportedClassConstraints: new Set(),
         prefabRefs: new Set(prefabs.keys()),
         declaredStats,
         stateFiles,
         roleStateSources,
         bindings,
     };
+    validateComponentClassUpdateContracts(context);
     for (const { prefab, relative, ref } of prefabFiles) {
         validatePrefab(prefab, relative, ref, context);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waica/cli",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Waica in one command — `npx @waica/cli` opens the editor, `waica mcp` serves the MCP server",
   "license": "MIT",
   "type": "module",
@@ -27,6 +27,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
+    "playwright-core": "^1.62.1",
     "three": "^0.185.1"
   }
 }

package/dist/mcp/native-import.cjs

@@ -1,3 +0,0 @@
-'use strict'
-
-module.exports = (specifier) => import(specifier)