cocos-web-inspector-mcp 2.3.0 → 2.4.0

package/dist/src/browser.js

@@ -82,8 +82,10 @@ export class BrowserConnection {
         if (pageUrl) {
             const wanted = validateLocalUrl(pageUrl, true).href;
             const selected = pages.filter(candidate => new URL(candidate.url()).href === wanted);
-            if (selected.length === 0)
-                throw new InspectorError('PAGE_NOT_FOUND', `Local page not found: ${sanitizeUrl(pageUrl)}`);
+            if (selected.length === 0) {
+                const open = pages.slice(0, 10).map(candidate => sanitizeUrl(candidate.url())).join(', ');
+                throw new InspectorError('PAGE_NOT_FOUND', `Local page not found: ${sanitizeUrl(pageUrl)} (pageUrl must equal the full open page URL including query and fragment; open pages, shown without them: ${open || 'none'})`);
+            }
             if (selected.length > 1)
                 throw new InspectorError('MULTIPLE_PAGES', `Multiple localhost pages match pageUrl: ${sanitizeUrl(pageUrl)}; close duplicate tabs or use a separate Chromium per project`);
             return selected[0];
@@ -139,7 +141,8 @@ export class BrowserConnection {
             const hint = /\b404\b/.test(message)
                 ? '; port is likely held by Chrome built-in remote debugging (chrome://inspect/#remote-debugging), which has no /json/version: turn it off or use another port, check with lsof -nP -iTCP:<port> -sTCP:LISTEN'
                 : '';
-            throw new InspectorError('CDP_UNAVAILABLE', `Unable to connect to Chromium CDP: ${message}${hint}`);
+            const launch = /ECONNREFUSED/.test(message) ? '; no Chromium is listening there: start one with --remote-debugging-port=<port> --user-data-dir=<dir>, or point the server at the right port with --cdp-endpoint / COCOS_CDP_ENDPOINT' : '';
+            throw new InspectorError('CDP_UNAVAILABLE', `Unable to connect to Chromium CDP at ${sanitizeUrl(this.endpoint)}: ${message}${hint}${launch}`);
         });
         this.#connecting = connecting;
         try {

package/dist/src/native.d.ts

@@ -13,9 +13,9 @@ export declare class NativeConnection {
 }
 export declare function nativeClick(page: Page, uuid: string): Promise<unknown>;
 export declare function nativeDrag(page: Page, uuid: string, dx: number, dy: number, durationMs?: number): Promise<unknown>;
-export declare function nativeCaptureNode(page: Page, uuid: string): Promise<unknown>;
+export declare function nativeCaptureNode(page: Page, uuid: string, maxBytes?: number): Promise<unknown>;
 /** Crops a raw screencap to the clip and encodes an RGB PNG, sampling every n-th pixel until it fits the response. */
-export declare function cropPng(raw: Buffer, clip: Clip): unknown;
+export declare function cropPng(raw: Buffer, clip: Clip, maxBytes?: number): unknown;
 /**
  * The inspector port from the engine's own "Debugger listening" logcat lines: the latest one, or `expected` only when
  * some line names it. Any app can log under the Cocos tag, so reconnects pass the port they already used.
@@ -34,6 +34,7 @@ export declare function nativeConsoleMessages(page: Page, options: {
     textContains?: string | undefined;
     limit?: number | undefined;
 }): Promise<unknown>;
+export declare function nativePressKey(_page: Page, key: string): Promise<unknown>;
 export declare function nativeTypeText(page: Page, uuid: string, text: string, submit: boolean): Promise<unknown>;
 export declare function nativeNetworkRequests(page: Page, options: Parameters<typeof selectRequests>[1]): Promise<unknown>;
 export declare function nativeNetworkRequest(page: Page, id: number, includeBody: boolean): Promise<unknown>;

package/dist/src/native.js

@@ -122,15 +122,15 @@ export async function nativeDrag(page, uuid, dx, dy, durationMs = 300) {
 // Raw `screencap` output: width, height, and pixel format as uint32 LE, a colorspace word on Android 12+, then RGBA rows
 // in the current display rotation. The device gzips it (18 MB raw takes ~20 s over Wi-Fi adb, ~1.5 s gzipped), and cropping
 // raw pixels needs only zlib here, where decoding `screencap -p` would need a PNG decoder.
-export async function nativeCaptureNode(page, uuid) {
+export async function nativeCaptureNode(page, uuid, maxBytes) {
     const clip = await visibleClip(page, uuid);
     if ('reason' in clip)
         return { captured: false, reason: clip.reason };
     const raw = gunzipSync(await adbBuffer(['exec-out', 'screencap | gzip -1']), { maxOutputLength: 256 * 1024 * 1024 });
-    return cropPng(raw, clip);
+    return cropPng(raw, clip, maxBytes);
 }
 /** Crops a raw screencap to the clip and encodes an RGB PNG, sampling every n-th pixel until it fits the response. */
-export function cropPng(raw, clip) {
+export function cropPng(raw, clip, maxBytes) {
     if (raw.length < 12)
         return { captured: false, reason: 'SCREENCAP_FAILED' };
     const screenWidth = raw.readUInt32LE(0);
@@ -158,7 +158,7 @@ export function cropPng(raw, clip) {
                 raw.copy(rows, out + x * 3, source + x * step * 4, source + x * step * 4 + 3);
         }
         const data = png(width, height, rows).toString('base64');
-        if (fitsImage(data))
+        if (fitsImage(data, maxBytes))
             return { captured: true, mimeType: 'image/png', data, width: right - left, height: bottom - top, ...(step > 1 ? { scale: 1 / step } : {}) };
     }
     return { captured: false, reason: 'RESPONSE_LIMIT' };
@@ -229,6 +229,17 @@ export async function nativeConsoleMessages(page, options) {
         note: 'Cocos-tagged logcat lines of the app process since it started, bounded by the device log buffer. Engine lines start with D/ or E/; an uncaught JS error spans several error lines (message, then stack).',
     };
 }
+const androidKeys = { Enter: 'KEYCODE_ENTER', Escape: 'KEYCODE_ESCAPE', Tab: 'KEYCODE_TAB', Delete: 'KEYCODE_DEL', Space: 'KEYCODE_SPACE', ArrowUp: 'KEYCODE_DPAD_UP', ArrowDown: 'KEYCODE_DPAD_DOWN', ArrowLeft: 'KEYCODE_DPAD_LEFT', ArrowRight: 'KEYCODE_DPAD_RIGHT', Home: 'KEYCODE_MOVE_HOME', End: 'KEYCODE_MOVE_END', PageUp: 'KEYCODE_PAGE_UP', PageDown: 'KEYCODE_PAGE_DOWN' };
+// The native engine reports AKEYCODE_DEL (the physical Backspace key) as Delete, has no entry for FORWARD_DEL, and reports Backspace only for
+// AKEYCODE_BACK, which leaves the app. So Delete maps to DEL and Backspace is refused rather than sent as a key the game would misread.
+export async function nativePressKey(_page, key) {
+    if (key === 'Backspace')
+        throw new Error('Invalid mutation: native builds deliver Backspace only for the system Back key, which leaves the app; use Delete, which the engine reports for the device Backspace key');
+    // Only validated key names reach adb, never free text.
+    await adb(['shell', 'input', 'keyevent', androidKeys[key] ?? `KEYCODE_${key.toUpperCase()}`]);
+    await settle();
+    return { pressed: true, key, input: 'adb', runtimeOnly: true };
+}
 // Tapping an EditBox on Android opens CocosEditBoxActivity, a native EditText whose every change fires text-changed in the game.
 export async function nativeTypeText(page, uuid, text, submit) {
     // input text only types printable ASCII and turns "%s" into a space, so refuse what it would silently mangle.

package/dist/src/server.js

@@ -2,11 +2,15 @@ import { readFileSync } from 'node:fs';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { InspectorError, sanitizeUrl } from './browser.js';
-import { nativeCaptureNode, nativeClick, nativeConsoleMessages, nativeDrag, nativeNetworkRequest, nativeNetworkRequests, nativeTypeText } from './native.js';
+import { nativeCaptureNode, nativeClick, nativeConsoleMessages, nativeDrag, nativeNetworkRequest, nativeNetworkRequests, nativePressKey, nativeTypeText } from './native.js';
 import { consoleMessages, networkRequest, networkRequests, storage } from './browser-data.js';
-import { captureNode, clickNode, devicePresetNames, dragNode, emulateDevice, inspectCocosPage, networkProfileNames, runBridge, typeText } from './bridge.js';
+import { captureNode, clickNode, devicePresetNames, dragNode, emulateDevice, fitsResponse, inspectCocosPage, networkProfileNames, keyPattern, pressKey, runBridge, typeText } from './bridge.js';
 const { version } = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
-const pageUrl = z.url().optional();
+// Agents send "" for unused optional fields; treat it as omitted.
+const blank = (schema) => z.preprocess(value => value === '' ? undefined : value, schema.optional());
+// Strict object whose unknown-key error also lists the accepted keys.
+const obj = (shape) => z.object(shape, { error: issue => issue.code === 'unrecognized_keys' ? `Unrecognized key(s): ${issue.keys.join(', ')}; accepted: ${Object.keys(shape).join(', ')}` : undefined }).strict();
+const pageUrl = blank(z.url());
 const readOnly = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
 const temporaryMutation = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false };
 const runtimeMutation = { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false };
@@ -24,9 +28,9 @@ const propertyValue = z.union([
     z.object({ r: finiteNumber, g: finiteNumber, b: finiteNumber, a: finiteNumber }).strict(),
 ]);
 // Every node tool takes uuid or path. Paths survive reloads but are not unique, so a path must match exactly one node.
-const target = { uuid: z.string().min(1).max(200).optional(), path: z.string().min(1).max(10_000).optional() };
+const target = { uuid: blank(z.string().min(1).max(200)), path: blank(z.string().min(1).max(10_000)) };
 const oneTarget = (value) => (value.uuid === undefined) !== (value.path === undefined);
-const oneTargetMessage = 'Provide uuid or path, not both';
+const oneTargetMessage = { error: (issue) => issue.input?.uuid === undefined && issue.input?.path === undefined ? 'Provide uuid or path' : 'Provide uuid or path, not both' };
 async function resolveUuid(page, input) {
     if (input.uuid)
         return input.uuid;
@@ -51,10 +55,10 @@ function failure(error) {
     // Playwright wraps in-page errors as "page.evaluate: Error: <message>\n<stack>".
     const message = raw.replace(/^page\.evaluate: (?:Error: )?/, '').split('\n')[0];
     const code = message === 'Cocos Creator 3.x runtime not found' ? 'COCOS_NOT_FOUND'
-        : message === 'Active Cocos scene not found' ? 'SCENE_NOT_READY'
+        : message.startsWith('Active Cocos scene not found') ? 'SCENE_NOT_READY'
             : message.startsWith('Node not found') ? 'NODE_NOT_FOUND'
-                : message === 'Component not found' ? 'COMPONENT_NOT_FOUND'
-                    : message === 'Ambiguous component type' ? 'AMBIGUOUS_COMPONENT'
+                : message.startsWith('Component not found') ? 'COMPONENT_NOT_FOUND'
+                    : message.startsWith('Ambiguous component type') ? 'AMBIGUOUS_COMPONENT'
                         : message.startsWith('Invalid mutation') ? 'INVALID_MUTATION'
                             : 'CDP_UNAVAILABLE';
     return { ...response({ code, message }), isError: true };
@@ -65,6 +69,73 @@ export function createServer(browser, options = {}) {
     // the DOM overlays draw nothing, the 2D batcher runs in C++ where analyze_batches cannot observe it,
     // and game.step renders outside the native frame loop, which crashed a 3.8.8 Android build in the GFX pipeline.
     const web = !options.native;
+    const pageIds = new WeakMap();
+    const baselines = new Map();
+    let nextPageId = 1;
+    let revision = 0;
+    const pageId = (page) => {
+        let id = pageIds.get(page);
+        if (id === undefined) {
+            id = nextPageId++;
+            pageIds.set(page, id);
+        }
+        return id;
+    };
+    const observeChanges = async (input) => {
+        try {
+            const page = await browser.page(input.pageUrl);
+            const uuid = input.uuid ?? (input.path ? await resolveUuid(page, input) : undefined);
+            const snapshot = JSON.parse(JSON.stringify(await runBridge(page, { action: 'semanticSnapshot', uuid, maxDepth: input.maxDepth, maxNodes: input.maxNodes })));
+            const selector = input.uuid ? `uuid:${input.uuid}` : input.path ? `path:${input.path}` : 'scene';
+            const key = JSON.stringify([pageId(page), page.url(), snapshot.documentId ?? null, selector, input.maxDepth ?? 6, input.maxNodes ?? 500]);
+            const prior = baselines.get(key);
+            if (input.reset)
+                baselines.delete(key);
+            const baseline = input.reset ? undefined : prior;
+            const full = (reason) => {
+                const next = { snapshot, revision: ++revision };
+                baselines.delete(key);
+                baselines.set(key, next);
+                while (baselines.size > 32)
+                    baselines.delete(baselines.keys().next().value);
+                return { mode: 'full', reason, revision: next.revision, snapshot };
+            };
+            if (!baseline)
+                return response(full(input.reset ? 'RESET' : 'BASELINE_MISSING'));
+            baselines.delete(key);
+            baselines.set(key, baseline);
+            const before = new Map((baseline.snapshot.nodes ?? []).map((node) => [node.uuid, node]));
+            const after = new Map((snapshot.nodes ?? []).map((node) => [node.uuid, node]));
+            const nodes = [...after.values()];
+            const added = nodes.filter(node => !before.has(node.uuid));
+            const removed = [...before.keys()].filter(uuid => !after.has(uuid));
+            const changed = nodes.flatMap(node => {
+                const old = before.get(node.uuid);
+                if (!old)
+                    return [];
+                const changes = Object.fromEntries([...new Set([...Object.keys(old), ...Object.keys(node)])]
+                    .filter(field => field !== 'uuid' && JSON.stringify(node[field]) !== JSON.stringify(old[field]))
+                    .map(field => [field, field in node ? node[field] : null]));
+                return Object.keys(changes).length ? [{ uuid: node.uuid, changes }] : [];
+            });
+            const metadataChanged = JSON.stringify({ truncated: snapshot.truncated, truncationReasons: snapshot.truncationReasons }) !== JSON.stringify({ truncated: baseline.snapshot.truncated, truncationReasons: baseline.snapshot.truncationReasons });
+            if (!added.length && !removed.length && !changed.length && !metadataChanged)
+                return response({ mode: 'unchanged', revision: baseline.revision });
+            if (metadataChanged)
+                return response(full('TRUNCATION_CHANGED'));
+            const delta = { added, removed, changed };
+            const deltaResult = { mode: 'delta', revision: revision + 1, delta };
+            if (JSON.stringify(delta).length >= JSON.stringify(snapshot).length || !fitsResponse(deltaResult))
+                return response(full('DELTA_NOT_SMALLER_THAN_FULL'));
+            const next = { snapshot, revision: ++revision };
+            baselines.delete(key);
+            baselines.set(key, next);
+            return response({ ...deltaResult, revision: next.revision });
+        }
+        catch (error) {
+            return failure(error);
+        }
+    };
     const execute = async (request, selectedPage) => {
         try {
             return response(await runBridge(await browser.page(selectedPage), request));
@@ -85,7 +156,7 @@ export function createServer(browser, options = {}) {
     const executeNode = (input, build) => withNode(input, (page, uuid) => runBridge(page, build(uuid)));
     server.registerTool('cocos_list_pages', {
         description: 'List bounded summaries of eligible localhost Chromium pages.',
-        inputSchema: z.object({}).strict(),
+        inputSchema: obj({}),
         annotations: readOnly,
     }, async () => {
         try {
@@ -102,95 +173,120 @@ export function createServer(browser, options = {}) {
     });
     server.registerTool('cocos_runtime_info', {
         description: 'Return bounded runtime information for one localhost Cocos Creator 3.x page.',
-        inputSchema: z.object({ pageUrl }).strict(),
+        inputSchema: obj({ pageUrl }),
         annotations: readOnly,
     }, input => execute({ action: 'runtimeInfo' }, input.pageUrl));
     server.registerTool('cocos_runtime_diagnostics', {
         description: 'Return bounded passive Cocos scene hierarchy diagnostics.',
-        inputSchema: z.object({ pageUrl }).strict(),
+        inputSchema: obj({ pageUrl }),
         annotations: readOnly,
     }, input => execute({ action: 'runtimeDiagnostics' }, input.pageUrl));
     server.registerTool('cocos_scene_tree', {
         description: 'Return a bounded Cocos Creator 3.x scene tree from a localhost Chromium page.',
-        inputSchema: z.object({ pageUrl, maxDepth: z.number().int().min(0).max(20).optional(), maxNodes: z.number().int().min(1).max(5_000).optional() }).strict(),
+        inputSchema: obj({ pageUrl, maxDepth: z.number().int().min(0).max(20).optional(), maxNodes: z.number().int().min(1).max(5_000).optional() }),
         annotations: readOnly,
     }, input => execute({ action: 'sceneTree', maxDepth: input.maxDepth, maxNodes: input.maxNodes }, input.pageUrl));
     server.registerTool('cocos_find_node', {
         description: 'Find Cocos nodes with bounded exact and filter criteria.',
-        inputSchema: z.object({ pageUrl, uuid: z.string().min(1).max(200).optional(), name: z.string().min(1).max(500).optional(), path: z.string().min(1).max(10_000).optional(), nameContains: z.string().min(1).max(500).optional(), componentType: z.string().min(1).max(120).optional(), active: z.boolean().optional(), pathPrefix: z.string().min(1).max(10_000).optional(), limit: z.number().int().min(1).max(100).optional() }).strict()
+        inputSchema: obj({ pageUrl, uuid: blank(z.string().min(1).max(200)), name: blank(z.string().min(1).max(500)), path: blank(z.string().min(1).max(10_000)), nameContains: blank(z.string().min(1).max(500)), componentType: blank(z.string().min(1).max(120)), active: z.boolean().optional(), pathPrefix: blank(z.string().min(1).max(10_000)), limit: z.number().int().min(1).max(100).optional() }).strict()
             .refine(value => [value.uuid, value.name, value.path, value.nameContains, value.componentType, value.active, value.pathPrefix].some(item => item !== undefined), 'Provide at least one filter'),
         annotations: readOnly,
     }, input => execute({ action: 'findNode', uuid: input.uuid, name: input.name, path: input.path, nameContains: input.nameContains, componentType: input.componentType, active: input.active, pathPrefix: input.pathPrefix, limit: input.limit }, input.pageUrl));
     server.registerTool('cocos_get_node', {
         description: 'Return bounded context for one exact Cocos node UUID.',
-        inputSchema: z.object({ pageUrl, ...target }).strict().refine(oneTarget, oneTargetMessage),
+        inputSchema: obj({ pageUrl, ...target }).refine(oneTarget, oneTargetMessage),
         annotations: readOnly,
     }, input => executeNode(input, uuid => ({ action: 'getNode', uuid })));
     server.registerTool('cocos_snapshot_subtree', {
         description: 'Return a bounded stateless subtree snapshot for one exact Cocos node UUID.',
-        inputSchema: z.object({ pageUrl, ...target, maxDepth: z.number().int().min(0).max(20).optional(), maxNodes: z.number().int().min(1).max(5_000).optional() }).strict().refine(oneTarget, oneTargetMessage),
+        inputSchema: obj({ pageUrl, ...target, maxDepth: z.number().int().min(0).max(20).optional(), maxNodes: z.number().int().min(1).max(5_000).optional() }).refine(oneTarget, oneTargetMessage),
         annotations: readOnly,
     }, input => executeNode(input, uuid => ({ action: 'snapshotSubtree', uuid, maxDepth: input.maxDepth, maxNodes: input.maxNodes })));
+    server.registerTool('cocos_observe_changes', {
+        description: 'Observe bounded semantic scene changes since the prior matching call.',
+        inputSchema: obj({ pageUrl, ...target, reset: z.boolean().optional(), maxDepth: z.number().int().min(0).max(20).optional(), maxNodes: z.number().int().min(1).max(5_000).optional() }).refine(value => !(value.uuid && value.path), oneTargetMessage),
+        annotations: readOnly,
+    }, input => observeChanges(input));
     server.registerTool('cocos_get_node_bounds', {
         description: 'Return bounded canvas and viewport bounds for one Cocos UI node UUID.',
-        inputSchema: z.object({ pageUrl, ...target }).strict().refine(oneTarget, oneTargetMessage),
+        inputSchema: obj({ pageUrl, ...target }).refine(oneTarget, oneTargetMessage),
         annotations: readOnly,
     }, input => executeNode(input, uuid => ({ action: 'getNodeBounds', uuid })));
     server.registerTool('cocos_capture_node', {
-        description: 'Capture a bounded viewport-clipped PNG for one visible Cocos UI node UUID.',
-        inputSchema: z.object({ pageUrl, ...target }).strict().refine(oneTarget, oneTargetMessage),
+        description: 'Capture a bounded viewport-clipped PNG for one visible Cocos UI node UUID. Pass maxBytes to cap the base64 image size when the client rejects large results.',
+        inputSchema: obj({ pageUrl, ...target, maxBytes: z.number().int().min(1_000).max(200_000).optional() }).refine(oneTarget, oneTargetMessage),
         annotations: readOnly,
-    }, input => withNode(input, web ? captureNode : nativeCaptureNode));
+    }, input => withNode(input, (page, uuid) => (web ? captureNode : nativeCaptureNode)(page, uuid, input.maxBytes)));
     server.registerTool('cocos_get_components', {
         description: 'List bounded component summaries for one Cocos node UUID.',
-        inputSchema: z.object({ pageUrl, ...target }).strict().refine(oneTarget, oneTargetMessage),
+        inputSchema: obj({ pageUrl, ...target }).refine(oneTarget, oneTargetMessage),
         annotations: readOnly,
     }, input => executeNode(input, uuid => ({ action: 'getComponents', uuid })));
     server.registerTool('cocos_get_properties', {
         description: 'Read bounded, cycle-safe public properties from a Cocos node or one component.',
-        inputSchema: z.object({ pageUrl, ...target, componentType: z.string().min(1).optional(), componentUuid: z.string().min(1).optional(), maxDepth: z.number().int().min(0).max(6).optional() }).strict().refine(oneTarget, oneTargetMessage)
+        inputSchema: obj({ pageUrl, ...target, componentType: blank(z.string().min(1)), componentUuid: blank(z.string().min(1)), maxDepth: z.number().int().min(0).max(6).optional() }).refine(oneTarget, oneTargetMessage)
             .refine(value => !(value.componentType && value.componentUuid), 'Provide componentType or componentUuid, not both'),
         annotations: readOnly,
     }, input => executeNode(input, uuid => ({ action: 'getProperties', uuid, componentType: input.componentType, componentUuid: input.componentUuid, maxDepth: input.maxDepth })));
     server.registerTool('cocos_wait_for_property', {
         description: 'Poll one top-level property of a Cocos node or component until it equals a value or the timeout passes.',
-        inputSchema: z.object({ pageUrl, ...target, componentType: z.string().min(1).optional(), componentUuid: z.string().min(1).optional(), key: z.string().min(1).max(200), equals: z.union([z.boolean(), finiteNumber, z.string().max(2_000), z.null()]), timeoutMs: z.number().int().min(100).max(30_000).optional(), intervalMs: z.number().int().min(50).max(5_000).optional() }).strict().refine(oneTarget, oneTargetMessage)
+        inputSchema: obj({ pageUrl, ...target, componentType: blank(z.string().min(1)), componentUuid: blank(z.string().min(1)), key: z.string().min(1).max(200), equals: z.union([z.boolean(), finiteNumber, z.string().max(2_000), z.null()]), timeoutMs: z.number().int().min(100).max(30_000).optional(), intervalMs: z.number().int().min(50).max(5_000).optional() }).refine(oneTarget, oneTargetMessage)
             .refine(value => !(value.componentType && value.componentUuid), 'Provide componentType or componentUuid, not both'),
         annotations: readOnly,
-    }, input => withNode(input, async (page, uuid) => {
-        const request = { action: 'getProperties', uuid, componentType: input.componentType, componentUuid: input.componentUuid, maxDepth: 0 };
-        const deadline = Date.now() + (input.timeoutMs ?? 5_000);
-        let polls = 0;
-        let value;
-        for (;;) {
-            polls++;
-            value = (await runBridge(page, request)).properties?.[input.key];
-            if (value === input.equals || Date.now() >= deadline)
-                break;
-            await new Promise(resolve => setTimeout(resolve, input.intervalMs ?? 200));
+    }, async (input) => {
+        try {
+            const page = await browser.page(input.pageUrl);
+            const deadline = Date.now() + (input.timeoutMs ?? 5_000);
+            let polls = 0;
+            let value;
+            let gone;
+            // A path is resolved on every poll so a scene switch or a node still being created does not end the wait early.
+            for (let uuid = input.uuid;;) {
+                polls++;
+                try {
+                    uuid ??= await resolveUuid(page, input);
+                    value = (await runBridge(page, { action: 'getProperties', uuid, componentType: input.componentType, componentUuid: input.componentUuid, maxDepth: 0 })).properties?.[input.key];
+                    gone = undefined;
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : '';
+                    if (!/Node not found|Active Cocos scene not found|Component not found/.test(message))
+                        throw error;
+                    gone = message.replace(/^page\.evaluate: (?:Error: )?/, '').split('\n')[0];
+                    value = undefined;
+                    if (!input.uuid)
+                        uuid = undefined;
+                }
+                if (gone === undefined && value === input.equals || Date.now() >= deadline)
+                    break;
+                await new Promise(resolve => setTimeout(resolve, input.intervalMs ?? 200));
+            }
+            return response({ matched: gone === undefined && value === input.equals, key: input.key, value: value ?? null, polls, ...(gone ? { gone } : {}) });
+        }
+        catch (error) {
+            return failure(error);
         }
-        return { matched: value === input.equals, key: input.key, value: value ?? null, polls };
-    }));
+    });
     if (options.allowRuntimeMutation) {
         server.registerTool('cocos_set_node_active', {
             description: 'Set the active state of one Cocos node selected by exact UUID.',
-            inputSchema: z.object({ pageUrl, ...target, active: z.boolean() }).strict().refine(oneTarget, oneTargetMessage),
+            inputSchema: obj({ pageUrl, ...target, active: z.boolean() }).refine(oneTarget, oneTargetMessage),
             annotations: runtimeMutation,
         }, input => executeNode(input, uuid => ({ action: 'setNodeActive', uuid, active: input.active })));
         server.registerTool('cocos_set_transform', {
             description: 'Update selected Cocos node position, rotation, or scale by exact UUID.',
-            inputSchema: z.object({ pageUrl, ...target, position: vector3.optional(), rotation: quaternion.optional(), scale: vector3.optional() }).strict().refine(oneTarget, oneTargetMessage)
+            inputSchema: obj({ pageUrl, ...target, position: vector3.optional(), rotation: quaternion.optional(), scale: vector3.optional() }).refine(oneTarget, oneTargetMessage)
                 .refine(value => !!value.position || !!value.rotation || !!value.scale, 'Provide position, rotation, or scale'),
             annotations: runtimeMutation,
         }, input => executeNode(input, uuid => ({ action: 'setTransform', uuid, position: input.position, rotation: input.rotation, scale: input.scale })));
         server.registerTool('cocos_set_property', {
             description: 'Update one bounded public data property selected by node and component UUID.',
-            inputSchema: z.object({ pageUrl, ...target, componentUuid: z.string().min(1), key: z.string().min(1).max(200), value: propertyValue }).strict().refine(oneTarget, oneTargetMessage),
+            inputSchema: obj({ pageUrl, ...target, componentUuid: z.string().min(1), key: z.string().min(1).max(200), value: propertyValue }).refine(oneTarget, oneTargetMessage),
             annotations: runtimeMutation,
         }, input => executeNode(input, uuid => ({ action: 'setProperty', uuid, componentUuid: input.componentUuid, key: input.key, value: input.value })));
         server.registerTool('cocos_click_node', {
             description: 'Dispatch a real mouse click at the visible center of one Cocos UI node, so Button and touch handlers run. Handlers may call game servers or make irreversible changes.',
-            inputSchema: z.object({ pageUrl, ...target }).strict().refine(oneTarget, oneTargetMessage),
+            inputSchema: obj({ pageUrl, ...target }).refine(oneTarget, oneTargetMessage),
             // Game click handlers run arbitrary code: a login button reaches real servers, a buy button spends currency.
             annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
         }, input => withNode(input, web ? clickNode : nativeClick));
@@ -198,48 +294,65 @@ export function createServer(browser, options = {}) {
         const realInput = { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true };
         server.registerTool('cocos_drag_node', {
             description: 'Drag from the visible center of one Cocos UI node by dx/dy CSS pixels with real pointer input, to scroll a ScrollView, flip a PageView, or move a Slider. Under touch emulation the drag arrives as touch. Handlers may call game servers.',
-            inputSchema: z.object({ pageUrl, ...target, dx: z.number().min(-4_000).max(4_000), dy: z.number().min(-4_000).max(4_000), steps: z.number().int().min(1).max(60).optional(), durationMs: z.number().int().min(0).max(5_000).optional() }).strict().refine(oneTarget, oneTargetMessage)
+            inputSchema: obj({ pageUrl, ...target, dx: z.number().min(-4_000).max(4_000), dy: z.number().min(-4_000).max(4_000), steps: z.number().int().min(1).max(60).optional(), durationMs: z.number().int().min(0).max(5_000).optional() }).refine(oneTarget, oneTargetMessage)
                 .refine(value => value.dx !== 0 || value.dy !== 0, 'Provide a non-zero dx or dy'),
             annotations: realInput,
         }, input => withNode(input, (page, uuid) => web ? dragNode(page, uuid, input.dx, input.dy, input.steps, input.durationMs) : nativeDrag(page, uuid, input.dx, input.dy, input.durationMs)));
         server.registerTool('cocos_type_text', {
             description: 'Tap one Cocos EditBox and type text with real keyboard input, replacing its content, so text-changed and editing events fire; submit presses Enter (editing-return on single-line boxes, a newline in multi-line ones). Password text is never echoed back.',
-            inputSchema: z.object({ pageUrl, ...target, text: z.string().max(2_000), submit: z.boolean().optional() }).strict().refine(oneTarget, oneTargetMessage),
+            inputSchema: obj({ pageUrl, ...target, text: z.string().max(2_000), submit: z.boolean().optional() }).refine(oneTarget, oneTargetMessage),
             annotations: realInput,
         }, input => withNode(input, (page, uuid) => (web ? typeText : nativeTypeText)(page, uuid, input.text, input.submit ?? false)));
+        server.registerTool('cocos_press_key', {
+            description: 'Press and release one key with real keyboard input, for game keyboard handlers and focused inputs: Enter, Escape, Tab, Backspace, Delete, Space, arrows, Home, End, PageUp, PageDown, a letter, or a digit. To fill an EditBox use cocos_type_text. Handlers may call game servers.',
+            inputSchema: obj({ pageUrl, key: z.string().regex(keyPattern, 'Use Enter, Escape, Tab, Backspace, Delete, Space, ArrowUp/Down/Left/Right, Home, End, PageUp, PageDown, or one letter or digit') }),
+            annotations: realInput,
+        }, async (input) => {
+            try {
+                return response(await (web ? pressKey : nativePressKey)(await browser.page(input.pageUrl), input.key));
+            }
+            catch (error) {
+                return failure(error);
+            }
+        });
         if (web)
             server.registerTool('cocos_analyze_batches', {
                 description: 'Capture the 2D draw batches of the next rendered frame: the node that starts each batch and why the previous batch broke (TEXTURE, MATERIAL, MASK, STENCIL, LAYER, BUFFER, MODEL, MIDDLEWARE, ...). Wraps engine batcher methods for that one frame only; the game must be running. tintMs overlays each batch\'s nodes in its own color for that long.',
-                inputSchema: z.object({ pageUrl, limit: z.number().int().min(1).max(500).optional(), tintMs: z.number().int().min(100).max(30_000).optional() }).strict(),
+                inputSchema: obj({ pageUrl, limit: z.number().int().min(1).max(500).optional(), tintMs: z.number().int().min(100).max(30_000).optional() }),
                 annotations: { ...runtimeMutation, idempotentHint: false },
             }, input => execute({ action: 'analyzeBatches', limit: input.limit, tintMs: input.tintMs }, input.pageUrl));
+        server.registerTool('cocos_event_trace', {
+            description: 'Count Node events (emit calls) per event name and node for a bounded window, to find event storms such as a TRANSFORM_CHANGED or custom event fired every frame. Wraps Node.prototype.emit for durationMs and restores it; arguments are never recorded.',
+            inputSchema: obj({ pageUrl, durationMs: z.number().int().min(100).max(10_000).optional(), limit: z.number().int().min(1).max(200).optional() }),
+            annotations: { ...runtimeMutation, idempotentHint: false },
+        }, input => execute({ action: 'eventTrace', durationMs: input.durationMs, limit: input.limit }, input.pageUrl));
         for (const action of ['pause', 'resume']) {
             server.registerTool(`cocos_${action}`, {
                 description: `${action === 'pause' ? 'Pause' : 'Resume'} the Cocos director through its public API.`,
-                inputSchema: z.object({ pageUrl }).strict(),
+                inputSchema: obj({ pageUrl }),
                 annotations: runtimeMutation,
             }, input => execute({ action }, input.pageUrl));
         }
         if (web)
             server.registerTool('cocos_step_frame', {
                 description: 'Advance a paused Cocos game by fixed-delta frames through cc.game.step; requires cocos_pause first.',
-                inputSchema: z.object({ pageUrl, frames: z.number().int().min(1).max(60).optional() }).strict(),
+                inputSchema: obj({ pageUrl, frames: z.number().int().min(1).max(60).optional() }),
                 annotations: { ...runtimeMutation, idempotentHint: false },
             }, input => execute({ action: 'stepFrame', frames: input.frames }, input.pageUrl));
         server.registerTool('cocos_set_time_scale', {
             description: 'Speed up or slow down the whole game by scaling the delta time of every frame (components, scheduler, tweens, animation, physics). 1 restores normal speed; omit scale to read it.',
-            inputSchema: z.object({ pageUrl, scale: z.number().gt(0).max(100).optional() }).strict(),
+            inputSchema: obj({ pageUrl, scale: z.number().gt(0).max(100).optional() }),
             annotations: runtimeMutation,
         }, input => execute({ action: 'timeScale', scale: input.scale }, input.pageUrl));
         server.registerTool('cocos_show_stats', {
             description: 'Show or hide the Cocos profiler overlay (FPS, draw calls, triangles) through the public profiler API.',
-            inputSchema: z.object({ pageUrl, visible: z.boolean() }).strict(),
+            inputSchema: obj({ pageUrl, visible: z.boolean() }),
             annotations: runtimeMutation,
         }, input => execute({ action: 'showStats', visible: input.visible }, input.pageUrl));
         if (web)
             server.registerTool('cocos_emulate_device', {
                 description: 'Emulate a mobile device (viewport, DPR, touch, user agent, orientation) and optionally slow the CPU or network, like the Chrome device toolbar. Settings merge across calls and last until reset or server disconnect; reload lets the game re-detect touch and user agent.',
-                inputSchema: z.object({
+                inputSchema: obj({
                     pageUrl,
                     reset: z.boolean().optional(),
                     preset: z.enum(devicePresetNames).optional(),
@@ -268,34 +381,55 @@ export function createServer(browser, options = {}) {
     }
     server.registerTool('cocos_explain_click', {
         description: 'Explain whether a tap on a node (or at viewport x/y) reaches it, replaying the engine touch dispatch order without dispatching: which node would claim the touch, the hit stack, and reasons such as INACTIVE, BUTTON_NOT_INTERACTABLE, BLOCKED_BY_BLOCK_INPUT_EVENTS, COVERED_BY_OTHER_NODE, NO_TOUCH_LISTENER, or OUTSIDE_VIEWPORT.',
-        inputSchema: z.object({ pageUrl, ...target, x: z.number().min(0).max(20_000).optional(), y: z.number().min(0).max(20_000).optional() }).strict()
+        inputSchema: obj({ pageUrl, ...target, x: z.number().min(0).max(20_000).optional(), y: z.number().min(0).max(20_000).optional() }).strict()
             .refine(value => (value.x === undefined) === (value.y === undefined), 'Provide x and y together')
-            .refine(value => value.uuid !== undefined || value.path !== undefined || value.x !== undefined, 'Provide uuid, path, or x and y')
-            .refine(value => !(value.uuid !== undefined && value.path !== undefined), oneTargetMessage),
+            .refine(value => value.x !== undefined
+            ? value.uuid === undefined && value.path === undefined
+            : oneTarget(value), 'Provide uuid, path, or x and y'),
         annotations: readOnly,
     }, input => input.uuid === undefined && input.path === undefined
         ? execute({ action: 'explainClick', x: input.x, y: input.y }, input.pageUrl)
         : executeNode(input, uuid => ({ action: 'explainClick', uuid, x: input.x, y: input.y })));
     server.registerTool('cocos_listener_report', {
         description: 'Report scheduler timers, update callbacks, tweens, and director/game/view listeners that outlive their owner: those on destroyed or detached nodes and components, and unowned ones (arrow functions, bind(this), plain objects) the engine can never purge, grouped by event and name with counts. Compare two calls around opening and closing a popup; a growing count is a leak.',
-        inputSchema: z.object({ pageUrl, limit: z.number().int().min(1).max(500).optional() }).strict(),
+        inputSchema: obj({ pageUrl, limit: z.number().int().min(1).max(500).optional() }),
         annotations: readOnly,
     }, input => execute({ action: 'listenerReport', limit: input.limit }, input.pageUrl));
+    for (const [name, action, description] of [
+        ['cocos_explain_visibility', 'explainVisibility', 'Explain why a node is not visible: inactive ancestors, disabled or transparent renderer, missing spriteFrame, empty Label, zero opacity/scale/size, a layer no active camera renders, outside the viewport, clipped by a Mask, or possibly covered by an opaque Sprite. Returns reasons (definite) and warnings (possible) without changing anything.'],
+        ['cocos_explain_layout', 'explainLayout', 'Explain why a node has its size and position: its Widget edges and align mode, a parent Layout that places or resizes it, Label/Sprite size modes, ancestor scale, and the resulting viewport rectangle. Pair with cocos_emulate_device to compare resolutions.'],
+    ]) {
+        server.registerTool(name, {
+            description,
+            inputSchema: obj({ pageUrl, ...target }).refine(oneTarget, oneTargetMessage),
+            annotations: readOnly,
+        }, input => executeNode(input, uuid => ({ action, uuid })));
+    }
+    server.registerTool('cocos_animation_report', {
+        description: 'List what is animating now: Animation components with playing states (speed, wrap mode, time), Spine/DragonBones components with their current animation, and tween targets with action counts. Read-only; nothing is played or stopped.',
+        inputSchema: obj({ pageUrl, limit: z.number().int().min(1).max(500).optional() }),
+        annotations: readOnly,
+    }, input => execute({ action: 'animationReport', limit: input.limit }, input.pageUrl));
+    server.registerTool('cocos_frame_profile', {
+        description: 'Sample real frames for a while and report frame time (avg, p50, p95, max), fps, spike count, the worst frames, and draw call and triangle ranges. Needs the game running (not paused). Subscribes to the director for the sample window only.',
+        inputSchema: obj({ pageUrl, frames: z.number().int().min(2).max(600).optional(), timeoutMs: z.number().int().min(100).max(30_000).optional() }),
+        annotations: { ...readOnly, idempotentHint: false },
+    }, input => execute({ action: 'frameProfile', frames: input.frames, timeoutMs: input.timeoutMs }, input.pageUrl));
     server.registerTool('cocos_dynamic_atlas', {
         description: 'Report the Cocos dynamic atlas: config, each atlas page with its packed textures, positions, fill ratio, and GPU bytes, plus why visible sprites stayed out of it (DISABLED, COMPRESSED, TOO_LARGE, FILTER, NOT_PACKABLE, ATLAS_FULL, ...).',
-        inputSchema: z.object({ pageUrl, limit: z.number().int().min(1).max(500).optional() }).strict(),
+        inputSchema: obj({ pageUrl, limit: z.number().int().min(1).max(500).optional() }),
         annotations: readOnly,
     }, input => execute({ action: 'dynamicAtlas', limit: input.limit }, input.pageUrl));
     server.registerTool('cocos_asset_report', {
         description: 'List assets held in the Cocos asset cache with type, refCount, bundle, texture GPU bytes, and which scene nodes use them; unused marks assets no active renderer references. Compare two calls (before and after a scene or popup closes) to find leaks.',
-        inputSchema: z.object({ pageUrl, type: z.string().min(1).max(120).optional(), unusedOnly: z.boolean().optional(), limit: z.number().int().min(1).max(500).optional() }).strict(),
+        inputSchema: obj({ pageUrl, type: blank(z.string().min(1).max(120)), unusedOnly: z.boolean().optional(), limit: z.number().int().min(1).max(500).optional() }),
         annotations: readOnly,
     }, input => execute({ action: 'assetReport', type: input.type, unusedOnly: input.unusedOnly, limit: input.limit }, input.pageUrl));
     if (options.allowMethodCall) {
         const jsonValue = z.lazy(() => z.union([z.null(), z.boolean(), finiteNumber, z.string().max(10_000), z.array(jsonValue).max(100), z.record(z.string().max(200), jsonValue)]));
         server.registerTool('cocos_call_method', {
             description: 'Call one public method on a Cocos node or component selected by UUID, with JSON arguments; {"$node": uuid}, {"$path": path}, {"$component": uuid}, and {"$asset": uuid} pass live objects. Runs arbitrary game code: it can change state, reach servers, or spend currency. Returns the bounded result or the thrown error; awaitMs waits for a returned promise.',
-            inputSchema: z.object({ pageUrl, ...target, componentUuid: z.string().min(1).optional(), method: z.string().min(1).max(200).regex(/^[A-Za-z$][\w$]*$/), args: z.array(jsonValue).max(20).optional(), awaitMs: z.number().int().min(0).max(30_000).optional(), maxDepth: z.number().int().min(0).max(6).optional() }).strict().refine(oneTarget, oneTargetMessage),
+            inputSchema: obj({ pageUrl, ...target, componentUuid: blank(z.string().min(1)), method: z.string().min(1).max(200).regex(/^[A-Za-z$][\w$]*$/), args: z.array(jsonValue).max(20).optional(), awaitMs: z.number().int().min(0).max(30_000).optional(), maxDepth: z.number().int().min(0).max(6).optional() }).refine(oneTarget, oneTargetMessage),
             annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
         }, input => executeNode(input, uuid => ({ action: 'callMethod', uuid, componentUuid: input.componentUuid, method: input.method, args: input.args ?? [], awaitMs: input.awaitMs, maxDepth: input.maxDepth })));
     }
@@ -312,36 +446,36 @@ export function createServer(browser, options = {}) {
         };
         server.registerTool('cocos_console_messages', {
             description: 'List recent console messages and uncaught page errors since the server attached (newest last). Secret-like values, JWTs, and bearer tokens are masked; text is untrusted page output.',
-            inputSchema: z.object({ pageUrl, types: z.array(z.enum(['log', 'debug', 'info', 'error', 'warning', 'assert', 'trace', 'pageerror'])).max(8).optional(), textContains: z.string().min(1).max(200).optional(), limit: z.number().int().min(1).max(200).optional() }).strict(),
+            inputSchema: obj({ pageUrl, types: z.array(z.enum(['log', 'debug', 'info', 'error', 'warning', 'assert', 'trace', 'pageerror'])).max(8).optional(), textContains: blank(z.string().min(1).max(200)), limit: z.number().int().min(1).max(200).optional() }),
             annotations: browserData,
         }, input => run(async () => (web ? consoleMessages : nativeConsoleMessages)(await browser.page(input.pageUrl), input)));
         server.registerTool('cocos_network_requests', {
             description: 'List recent network requests since the server attached: id, method, URL with secret query values masked, resource type, status, failure, and duration. Use cocos_network_request for headers and bodies.',
-            inputSchema: z.object({ pageUrl, urlContains: z.string().min(1).max(500).optional(), resourceType: z.string().min(1).max(40).optional(), failedOnly: z.boolean().optional(), limit: z.number().int().min(1).max(200).optional() }).strict(),
+            inputSchema: obj({ pageUrl, urlContains: blank(z.string().min(1).max(500)), resourceType: blank(z.string().min(1).max(40)), failedOnly: z.boolean().optional(), limit: z.number().int().min(1).max(200).optional() }),
             annotations: browserData,
         }, input => run(async () => (web ? networkRequests : nativeNetworkRequests)(await browser.page(input.pageUrl), input)));
         server.registerTool('cocos_network_request', {
             description: 'Return one request by id from cocos_network_requests: headers with authorization and cookies masked, status, timing, and optionally text bodies up to 20 KB with secret-like JSON and form fields masked.',
-            inputSchema: z.object({ pageUrl, id: z.number().int().min(1), includeBody: z.boolean().optional() }).strict(),
+            inputSchema: obj({ pageUrl, id: z.number().int().min(1), includeBody: z.boolean().optional() }),
             annotations: browserData,
         }, input => run(async () => (web ? networkRequest : nativeNetworkRequest)(await browser.page(input.pageUrl), input.id, input.includeBody ?? false)));
         server.registerTool('cocos_storage', {
             description: 'Read localStorage or sessionStorage entries, or cookie names and attributes for the page. Secret-like keys and every cookie value are masked; JSON values are masked by key.',
-            inputSchema: z.object({ pageUrl, area: z.enum(['local', 'session', 'cookies']), keyContains: z.string().min(1).max(200).optional(), limit: z.number().int().min(1).max(500).optional() }).strict(),
+            inputSchema: obj({ pageUrl, area: z.enum(['local', 'session', 'cookies']), keyContains: blank(z.string().min(1).max(200)), limit: z.number().int().min(1).max(500).optional() }),
             annotations: browserData,
         }, input => run(async () => storage(await browser.page(input.pageUrl), input.area, input.keyContains, input.limit)));
     }
     if (web)
         server.registerTool('cocos_get_selection', {
             description: 'Return the node the user last Alt+clicked on the game canvas. The first call installs the picker; Alt+clicks are kept from the game, other input is untouched. disable removes the picker, overlay, and selection.',
-            inputSchema: z.object({ pageUrl, disable: z.boolean().optional() }).strict(),
+            inputSchema: obj({ pageUrl, disable: z.boolean().optional() }),
             // Installs a page-level listener and DOM overlay only; never touches the Cocos graph.
             annotations: { ...readOnly, readOnlyHint: false },
         }, input => execute({ action: 'selection', disable: input.disable }, input.pageUrl));
     if (web)
         server.registerTool('cocos_highlight_node', {
             description: 'Temporarily draw a pointer-transparent DOM overlay around one Cocos UI node.',
-            inputSchema: z.object({ pageUrl, ...target, durationMs: z.number().int().min(100).max(10_000).optional() }).strict().refine(oneTarget, oneTargetMessage),
+            inputSchema: obj({ pageUrl, ...target, durationMs: z.number().int().min(100).max(10_000).optional() }).refine(oneTarget, oneTargetMessage),
             annotations: temporaryMutation,
         }, input => executeNode(input, uuid => ({ action: 'highlightNode', uuid, durationMs: input.durationMs })));
     return server;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cocos-web-inspector-mcp",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "MCP server to inspect and debug Cocos Creator 3.x web builds in local Chromium over CDP",
   "license": "MIT",
   "repository": {