cocos-web-inspector-mcp 2.2.1 → 2.4.0

package/dist/src/bridge.js

@@ -1,21 +1,30 @@
 const MAX_BYTES = 200_000;
+/** Whether a tool result, sent as both text and structuredContent, stays under the response ceiling. */
+export function fitsResponse(result) {
+    const encoded = JSON.stringify({ content: [{ type: 'text', text: JSON.stringify(result) }], structuredContent: result });
+    return Buffer.byteLength(encoded, 'utf8') <= MAX_BYTES - 4_096;
+}
 export async function runBridge(page, request) {
     const result = await page.evaluate(inspectCocos, request);
-    const text = JSON.stringify(result);
-    const encoded = JSON.stringify({ content: [{ type: 'text', text }], structuredContent: result });
-    if (Buffer.byteLength(encoded, 'utf8') > MAX_BYTES - 4_096) {
-        return { truncated: true, truncationReasons: ['RESPONSE_LIMIT'] };
-    }
-    return result;
+    return fitsResponse(result) ? result : { truncated: true, truncationReasons: ['RESPONSE_LIMIT'] };
 }
-export async function captureNode(page, uuid) {
+/** The node's visible viewport rectangle, or why it has none. */
+export async function visibleClip(page, uuid) {
     const result = await page.evaluate(inspectCocos, { action: 'getNodeBounds', uuid });
     if (!result.available || !result.visible)
-        return { captured: false, reason: result.reason ?? 'OUTSIDE_VIEWPORT' };
+        return { reason: result.reason ?? 'OUTSIDE_VIEWPORT' };
     const clip = result.clippedViewport;
-    if (!clip || !Number.isFinite(clip.x) || !Number.isFinite(clip.y) || !Number.isFinite(clip.width) || !Number.isFinite(clip.height) || clip.width <= 0 || clip.height <= 0)
-        return { captured: false, reason: 'INVALID_GEOMETRY' };
-    const fits = (data) => Buffer.byteLength(JSON.stringify({ data }), 'utf8') <= MAX_BYTES - 4_096;
+    if (!clip || ![clip.x, clip.y, clip.width, clip.height].every(Number.isFinite) || clip.width <= 0 || clip.height <= 0)
+        return { reason: 'INVALID_GEOMETRY' };
+    return clip;
+}
+/** Whether base64 image data stays under the response ceiling. */
+export const fitsImage = (data, limit = MAX_BYTES - 4_096) => Buffer.byteLength(JSON.stringify({ data }), 'utf8') <= Math.min(limit, MAX_BYTES - 4_096);
+export async function captureNode(page, uuid, maxBytes) {
+    const clip = await visibleClip(page, uuid);
+    if ('reason' in clip)
+        return { captured: false, reason: clip.reason };
+    const fits = (data) => fitsImage(data, maxBytes);
     const size = { width: Math.round(clip.width), height: Math.round(clip.height) };
     // Device-pixel PNG, then CSS-pixel JPEG quality steps.
     const attempts = [{ type: 'png', scale: 'device' }, ...[80, 60, 40].map(quality => ({ type: 'jpeg', quality, scale: 'css' }))];
@@ -40,11 +49,8 @@ export async function captureNode(page, uuid) {
     return { captured: false, reason: 'RESPONSE_LIMIT' };
 }
 export async function nodeCenter(page, uuid) {
-    const result = await page.evaluate(inspectCocos, { action: 'getNodeBounds', uuid });
-    if (!result.available || !result.visible)
-        return { reason: result.reason ?? 'OUTSIDE_VIEWPORT' };
-    const clip = result.clippedViewport;
-    return { x: clip.x + clip.width / 2, y: clip.y + clip.height / 2 };
+    const clip = await visibleClip(page, uuid);
+    return 'reason' in clip ? clip : { x: clip.x + clip.width / 2, y: clip.y + clip.height / 2 };
 }
 // Under touch emulation Chrome turns mouse input into touch and never acknowledges Playwright's mouse calls, so send touch directly.
 function pointer(page) {
@@ -108,6 +114,26 @@ export async function typeText(page, uuid, text, submit) {
     const after = typeof properties?.string === 'string' ? { string: properties.string } : { redacted: true };
     return { typed: true, target: { nodeUuid: uuid }, length: text.length, submitted: submit, after, runtimeOnly: true };
 }
+// Keys the press tools accept: Playwright names, which native maps to Android key codes.
+export const namedKeys = ['Enter', 'Escape', 'Tab', 'Backspace', 'Delete', 'Space', 'ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight', 'Home', 'End', 'PageUp', 'PageDown'];
+export const keyPattern = new RegExp(`^(?:${namedKeys.join('|')}|[a-zA-Z0-9])$`);
+// Real keydown/keyup for game keyboard handlers (cc.Input KEY_DOWN/KEY_UP); cocos_type_text is the path for EditBox text.
+// The engine listens for keys on the GameCanvas element, so focus it first unless a DOM input (an open EditBox) already has focus.
+export async function pressKey(page, key) {
+    await page.evaluate(() => {
+        const active = document.activeElement;
+        if (active instanceof HTMLInputElement || active instanceof HTMLTextAreaElement)
+            return;
+        const canvas = document.getElementById('GameCanvas');
+        if (canvas) {
+            if (!canvas.hasAttribute('tabindex'))
+                canvas.tabIndex = -1;
+            canvas.focus();
+        }
+    });
+    await page.keyboard.press(key === 'Space' ? ' ' : key);
+    return { pressed: true, key, runtimeOnly: true };
+}
 const IOS_UA = 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1';
 const IPAD_UA = 'Mozilla/5.0 (iPad; CPU OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1';
 const androidUa = (model) => `Mozilla/5.0 (Linux; Android 14; ${model}) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Mobile Safari/537.36`;
@@ -236,7 +262,7 @@ export function inspectCocos(request) {
         throw new Error('Cocos Creator 3.x runtime not found');
     const scene = cc.director?.getScene?.();
     if (!scene)
-        throw new Error('Active Cocos scene not found');
+        throw new Error(`Active Cocos scene not found (${cc.director ? 'director has no scene yet' : 'no director'}); the game may still be booting or loading a scene, retry shortly`);
     const sensitiveParts = ['token', 'cookie', 'authorization', 'password', 'secret', 'credential', 'storage', 'jwt', 'apikey', 'privatekey', 'accesskey', 'signingkey', 'authheader'];
     const isSensitiveKey = (key) => {
         const normalized = key.toLowerCase().replace(/[^a-z]/g, '');
@@ -276,8 +302,26 @@ export function inspectCocos(request) {
         activeInHierarchy: node?.activeInHierarchy !== false,
         componentTypes: components(node).slice(0, 100).map(componentName),
     });
+    const truncatePath = (path) => path.length <= 10_000 ? path : `${path.slice(0, 9_999)}…`;
+    const utf8Bytes = (text) => {
+        let bytes = 0;
+        for (let index = 0; index < text.length; index++) {
+            const code = text.charCodeAt(index);
+            if (code < 0x80)
+                bytes++;
+            else if (code < 0x800)
+                bytes += 2;
+            else if (code >= 0xd800 && code <= 0xdbff && index + 1 < text.length && (text.charCodeAt(index + 1) & 0xfc00) === 0xdc00) {
+                bytes += 4;
+                index++;
+            }
+            else
+                bytes += 3;
+        }
+        return bytes;
+    };
     const walk = (visit, limit = 5_000) => {
-        const stack = [{ node: scene, path: `/${String(scene.name ?? '')}`, depth: 0 }];
+        const stack = [{ node: scene, path: truncatePath(`/${String(scene.name ?? '')}`), depth: 0 }];
         const seen = new Set();
         let count = 0;
         let truncated = false;
@@ -297,7 +341,7 @@ export function inspectCocos(request) {
                 const child = next[index];
                 const childName = String(child?.name ?? '').slice(0, 500);
                 const childPath = `${current.path}/${childName}`;
-                stack.push({ node: child, path: childPath.length <= 10_000 ? childPath : `${childPath.slice(0, 9_999)}…`, depth: current.depth + 1 });
+                stack.push({ node: child, path: truncatePath(childPath), depth: current.depth + 1 });
             }
         }
         return { truncated: truncated || stack.length > 0 };
@@ -311,7 +355,7 @@ export function inspectCocos(request) {
             }
         });
         if (!match)
-            throw new Error(traversal.truncated ? 'Node not found within traversal limit' : 'Node not found');
+            throw new Error(traversal.truncated ? 'Node not found within traversal limit' : `Node not found${/^(Node|Comp)\.\d+$/.test(uuid) ? '; Node.N ids are runtime-assigned and change on scene switch or reload, look the node up by path' : ''}`);
         return match;
     };
     const nodeBounds = (node) => {
@@ -625,6 +669,73 @@ export function inspectCocos(request) {
             ...(selection ? {} : { hint: 'Alt+click a node on the game canvas, then call again' }),
         };
     }
+    if (request.action === 'semanticSnapshot') {
+        const rootNode = request.uuid ? findByUuid(request.uuid) : scene;
+        const maxDepth = Math.min(Math.max(request.maxDepth ?? 6, 0), 20);
+        const maxNodes = Math.min(Math.max(request.maxNodes ?? 500, 1), 5_000);
+        // ponytail: normalized snapshots stop near 65 KB; increase only with a response-size-aware transport.
+        const budget = 65_000;
+        const reasons = new Set();
+        const nodes = [];
+        let bytes = 0;
+        const vector = (value, keys) => Object.fromEntries(keys.map(key => [key, Number(dataProperty(value ?? {}, key) ?? 0)]));
+        const collect = (node, path, depth) => {
+            if (nodes.length >= maxNodes) {
+                reasons.add('NODE_LIMIT');
+                return;
+            }
+            const item = {
+                uuid: String(dataProperty(node, 'uuid') ?? dataProperty(node, '_id') ?? ''),
+                name: String(dataProperty(node, 'name') ?? dataProperty(node, '_name') ?? '').slice(0, 500),
+                path,
+                active: (dataProperty(node, '_active') ?? dataProperty(node, 'active')) !== false,
+                position: vector(dataProperty(node, '_lpos') ?? dataProperty(node, '_position') ?? dataProperty(node, 'position'), ['x', 'y', 'z']),
+                rotation: vector(dataProperty(node, '_lrot') ?? dataProperty(node, '_rotation') ?? dataProperty(node, 'rotation'), ['x', 'y', 'z', 'w']),
+                scale: vector(dataProperty(node, '_lscale') ?? dataProperty(node, '_scale') ?? dataProperty(node, 'scale'), ['x', 'y', 'z']),
+            };
+            const transform = components(node).find(component => componentName(component) === 'UITransform');
+            const size = transform && dataProperty(transform, '_contentSize');
+            const anchor = transform && dataProperty(transform, '_anchorPoint');
+            if (size && anchor)
+                item.uiBounds = { x: -Number(dataProperty(size, 'width') ?? 0) * Number(dataProperty(anchor, 'x') ?? 0), y: -Number(dataProperty(size, 'height') ?? 0) * Number(dataProperty(anchor, 'y') ?? 0), width: Number(dataProperty(size, 'width') ?? 0), height: Number(dataProperty(size, 'height') ?? 0) };
+            const label = components(node).find(component => componentName(component) === 'Label');
+            if (label && typeof dataProperty(label, '_string') === 'string')
+                item.labelText = String(dataProperty(label, '_string')).slice(0, 2_000);
+            const button = components(node).find(component => componentName(component) === 'Button');
+            if (button && typeof dataProperty(button, '_interactable') === 'boolean')
+                item.buttonInteractable = dataProperty(button, '_interactable');
+            const encoded = utf8Bytes(JSON.stringify(item));
+            if (bytes + encoded > budget) {
+                reasons.add('RESPONSE_LIMIT');
+                return;
+            }
+            bytes += encoded;
+            nodes.push(item);
+            const next = children(node);
+            if (depth >= maxDepth) {
+                if (next.length)
+                    reasons.add('MAX_DEPTH');
+                return;
+            }
+            for (const child of next) {
+                if (nodes.length >= maxNodes) {
+                    reasons.add('NODE_LIMIT');
+                    break;
+                }
+                collect(child, truncatePath(`${path}/${String(dataProperty(child, 'name') ?? dataProperty(child, '_name') ?? '').slice(0, 500)}`), depth + 1);
+                if (reasons.has('RESPONSE_LIMIT'))
+                    break;
+            }
+        };
+        let rootPath = truncatePath(`/${String(dataProperty(scene, 'name') ?? dataProperty(scene, '_name') ?? '').slice(0, 500)}`);
+        if (request.uuid)
+            walk((node, path) => { if (node === rootNode) {
+                rootPath = path;
+                return false;
+            } });
+        collect(rootNode, rootPath, 0);
+        return { version, ...(typeof performance !== 'undefined' && Number.isFinite(performance.timeOrigin) ? { documentId: performance.timeOrigin } : {}), rootUuid: String(dataProperty(rootNode, 'uuid') ?? dataProperty(rootNode, '_id') ?? ''), nodes, nodeCount: nodes.length, truncated: reasons.size > 0, truncationReasons: [...reasons] };
+    }
     if (request.action === 'snapshotSubtree') {
         const rootNode = findByUuid(request.uuid);
         const maxDepth = Math.min(Math.max(request.maxDepth ?? 6, 0), 20);
@@ -642,7 +753,7 @@ export function inspectCocos(request) {
                 ...summary(node),
                 components: components(node).slice(0, 200).map(component => ({ type: componentName(component), uuid: String(component.uuid ?? ''), enabled: component.enabled !== false })),
             };
-            bytes += JSON.stringify(item).length;
+            bytes += utf8Bytes(JSON.stringify(item));
             if (bytes > 70_000) {
                 reasons.add('RESPONSE_LIMIT');
                 return undefined;
@@ -770,12 +881,12 @@ export function inspectCocos(request) {
         const node = findByUuid(request.uuid);
         const matches = request.componentType ? components(node).filter(component => componentName(component) === request.componentType) : [];
         if (matches.length > 1)
-            throw new Error('Ambiguous component type');
+            throw new Error(`Ambiguous component type ${request.componentType}; pass componentUuid: ${matches.map(component => component?.uuid).join(', ')}`);
         const selected = request.componentUuid
             ? components(node).find(component => component?.uuid === request.componentUuid)
             : request.componentType ? matches[0] : node;
         if (!selected)
-            throw new Error('Component not found');
+            throw new Error(`Component not found: ${request.componentUuid ?? request.componentType} on ${node.name}; components: ${components(node).map(component => `${componentName(component)} ${component?.uuid}`).join(', ').slice(0, 500)}`);
         const maxDepth = Math.min(Math.max(request.maxDepth ?? 3, 0), 6);
         const serializer = createSerializer(maxDepth);
         const { serialize, truncate } = serializer;
@@ -850,7 +961,7 @@ export function inspectCocos(request) {
     const componentByUuid = (node, uuid) => {
         const component = components(node).find(candidate => candidate?.uuid === uuid);
         if (!component)
-            throw new Error('Component not found');
+            throw new Error(`Component not found: ${uuid} on ${node?.name}; components: ${components(node).map(candidate => `${componentName(candidate)} ${candidate?.uuid}`).join(', ').slice(0, 500)}`);
         return component;
     };
     const directorState = () => {
@@ -1015,7 +1126,7 @@ export function inspectCocos(request) {
                     const names = [];
                     for (let current = node, depth = 0; current && depth < 100; current = current.parent, depth++)
                         names.unshift(String(current.name ?? '').slice(0, 200));
-                    return `/${names.join('/')}`.slice(0, 2_000);
+                    return truncatePath(`/${names.join('/')}`);
                 };
                 const reasons = {};
                 for (const batch of batches)
@@ -1138,7 +1249,7 @@ export function inspectCocos(request) {
         for (let depth = 0; owner && depth < 20 && !descriptor; depth++, owner = Object.getPrototypeOf(owner))
             descriptor = Object.getOwnPropertyDescriptor(owner, request.key);
         if (!descriptor || !('value' in descriptor))
-            invalidMutation('property is not a data property');
+            invalidMutation('property is not a data property (accessor or missing); only plain data properties are writable');
         const current = descriptor.value;
         const keys = current && typeof current === 'object'
             ? 'width' in current && 'height' in current ? ['width', 'height'] : 'r' in current && 'g' in current && 'b' in current ? ['r', 'g', 'b', 'a'] : ['x', 'y', ...('z' in current ? ['z'] : []), ...('w' in current ? ['w'] : [])]
@@ -1230,8 +1341,13 @@ export function inspectCocos(request) {
         let descriptor;
         for (let depth = 0; owner && owner !== Object.prototype && depth < 20 && !descriptor; depth++, owner = Object.getPrototypeOf(owner))
             descriptor = Object.getOwnPropertyDescriptor(owner, name);
-        if (!descriptor || typeof descriptor.value !== 'function')
-            return invalidMutation(`${name} is not a method of ${target === node ? 'Node' : componentName(target)}`);
+        if (!descriptor || typeof descriptor.value !== 'function') {
+            const hasMethod = (object) => { for (let owner = object, depth = 0; owner && owner !== Object.prototype && depth < 20; depth++, owner = Object.getPrototypeOf(owner))
+                if (typeof Object.getOwnPropertyDescriptor(owner, name)?.value === 'function')
+                    return true; return false; };
+            const owners = target === node ? components(node).filter(hasMethod).map(component => `${componentName(component)} ${component?.uuid}`) : [];
+            return invalidMutation(`${name} is not a method of ${target === node ? 'Node' : componentName(target)}${owners.length ? `; components with ${name}: ${owners.join(', ')} (pass componentUuid)` : ''}`);
+        }
         const resolve = (value, depth = 0) => {
             if (depth > 10)
                 invalidMutation('argument nesting is too deep');
@@ -1708,6 +1824,388 @@ export function inspectCocos(request) {
             truncationReasons: [...(items.length > limit || total > 50_000 ? ['NODE_LIMIT'] : []), ...(sceneTruncated ? ['NODE_LIMIT'] : [])].filter((value, index, all) => all.indexOf(value) === index),
         };
     }
+    const pathOf = (node) => {
+        const names = [];
+        for (let current = node, depth = 0; current && depth < 100; current = current.parent, depth++)
+            names.unshift(String(current.name ?? '').slice(0, 200));
+        return `/${names.join('/')}`;
+    };
+    const chainOf = (node) => {
+        const chain = [];
+        for (let current = node, depth = 0; current && depth < 100; current = current.parent, depth++)
+            chain.push(current);
+        return chain;
+    };
+    const finiteOr = (value, fallback = 0) => Number.isFinite(Number(value)) ? Number(value) : fallback;
+    const sizeOf = (node) => {
+        const transform = components(node).find(component => componentName(component) === 'UITransform');
+        const size = transform && dataProperty(transform, '_contentSize');
+        const anchor = transform && dataProperty(transform, '_anchorPoint');
+        return size ? { width: finiteOr(size.width), height: finiteOr(size.height), ...(anchor ? { anchor: { x: finiteOr(anchor.x), y: finiteOr(anchor.y) } } : {}) } : undefined;
+    };
+    if (request.action === 'explainVisibility') {
+        // Reads backing fields (_active, _layer, _color, _opacity, _visibility) so no getter runs; mirrors what the renderer checks, without rendering.
+        const target = findByUuid(request.uuid);
+        const chain = chainOf(target);
+        const reasons = [];
+        const warnings = [];
+        const add = (list, code, node, detail) => list.push({ code, ...(node ? { node: String(node.name ?? '').slice(0, 200), nodeUuid: String(node.uuid ?? '') } : {}), ...(detail ? { detail } : {}) });
+        if (target.activeInHierarchy === false) {
+            const off = chain.find(node => dataProperty(node, '_active') === false) ?? target;
+            add(reasons, 'INACTIVE', off, off === target ? 'the node itself is inactive' : 'an ancestor is inactive');
+        }
+        const rendererTypes = ['Sprite', 'Label', 'RichText', 'Graphics', 'Skeleton', 'ArmatureDisplay', 'MeshRenderer', 'SkinnedMeshRenderer', 'ParticleSystem2D', 'ParticleSystem', 'TiledMap', 'MotionStreak', 'UIMeshRenderer', 'VideoPlayer', 'WebView'];
+        const renderers = components(target).filter(component => rendererTypes.includes(componentName(component)));
+        if (!renderers.length)
+            add(warnings, 'NO_RENDERER', target, 'no Sprite, Label, Graphics, or other renderer component on this node; it draws nothing itself');
+        for (const renderer of renderers) {
+            const type = componentName(renderer);
+            if (dataProperty(renderer, '_enabled') === false)
+                add(reasons, 'RENDERER_DISABLED', target, type);
+            if (type === 'Sprite' && !dataProperty(renderer, '_spriteFrame'))
+                add(reasons, 'NO_SPRITE_FRAME', target, 'Sprite has no spriteFrame');
+            if (type === 'Label' && dataProperty(renderer, '_string') === '')
+                add(reasons, 'EMPTY_TEXT', target, 'Label string is empty');
+            const color = dataProperty(renderer, '_color');
+            if (color && finiteOr(color.a, 255) === 0)
+                add(reasons, 'TRANSPARENT_COLOR', target, `${type} color alpha is 0`);
+        }
+        let opacity = 1;
+        for (const node of chain) {
+            const ui = components(node).find(component => componentName(component) === 'UIOpacity');
+            const value = ui ? dataProperty(ui, '_opacity') : undefined;
+            if (typeof value === 'number') {
+                opacity *= value / 255;
+                if (value === 0)
+                    add(reasons, 'ZERO_OPACITY', node, 'UIOpacity is 0');
+            }
+            const scale = dataProperty(node, '_lscale');
+            if (scale && (finiteOr(scale.x, 1) === 0 || finiteOr(scale.y, 1) === 0))
+                add(reasons, 'ZERO_SCALE', node, 'local scale x or y is 0');
+        }
+        const size = sizeOf(target);
+        if (size && (size.width === 0 || size.height === 0))
+            add(reasons, 'ZERO_SIZE', target, `${size.width}x${size.height}`);
+        // Native (JSB) nodes keep _layer in C++ behind an accessor that data reads skip; fall back to the public layer getter, which returns a plain bitmask.
+        const layerData = dataProperty(target, '_layer');
+        const layer = Number(typeof layerData === 'number' ? layerData : target.layer);
+        const cameras = [];
+        walk(node => {
+            for (const component of components(node)) {
+                if (componentName(component) === 'Camera' && dataProperty(component, '_enabled') !== false && node.activeInHierarchy !== false)
+                    cameras.push({ node: String(node.name ?? '').slice(0, 200), visibility: finiteOr(dataProperty(component, '_visibility')) });
+            }
+        });
+        if (Number.isFinite(layer) && cameras.length) {
+            if (!cameras.some(camera => (camera.visibility & layer) !== 0))
+                add(reasons, 'LAYER_NOT_RENDERED', target, `node layer ${layer} is outside every active camera's visibility (${cameras.slice(0, 5).map(camera => `${camera.node}: ${camera.visibility}`).join(', ')})`);
+        }
+        else if (!cameras.length)
+            add(warnings, 'NO_ACTIVE_CAMERA', undefined, 'no active Camera found; cannot check layer visibility');
+        const bounds = nodeBounds(target);
+        if (bounds.available && bounds.outsideViewport)
+            add(reasons, 'OUTSIDE_VIEWPORT', target);
+        if (bounds.available) {
+            for (const ancestor of chain.slice(1)) {
+                const mask = components(ancestor).find(component => componentName(component) === 'Mask' && dataProperty(component, '_enabled') !== false);
+                if (!mask)
+                    continue;
+                const maskBounds = nodeBounds(ancestor);
+                if (!maskBounds.available)
+                    continue;
+                const a = bounds.viewport;
+                const b = maskBounds.viewport;
+                if (a.x >= b.x + b.width || b.x >= a.x + a.width || a.y >= b.y + b.height || b.y >= a.y + a.height)
+                    add(reasons, 'CLIPPED_BY_MASK', ancestor, 'the node lies entirely outside this Mask\'s box');
+            }
+            // ponytail: covering is judged by an opaque Sprite's box only; texture transparency and camera priority are ignored. Upgrade: sample the framebuffer.
+            if (!bounds.outsideViewport && target.activeInHierarchy !== false) {
+                const clip = bounds.clippedViewport;
+                let after = false;
+                let checked = 0;
+                const covering = [];
+                walk(node => {
+                    if (node === target) {
+                        after = true;
+                        return;
+                    }
+                    if (!after || checked >= 500 || covering.length >= 3 || node.activeInHierarchy === false || chainOf(node).includes(target))
+                        return;
+                    const sprite = components(node).find(component => componentName(component) === 'Sprite' && dataProperty(component, '_enabled') !== false && dataProperty(component, '_spriteFrame'));
+                    const color = sprite && dataProperty(sprite, '_color');
+                    if (!sprite || !color || finiteOr(color.a, 255) < 255)
+                        return;
+                    checked++;
+                    const other = nodeBounds(node);
+                    if (other.available && other.viewport.x <= clip.x && other.viewport.y <= clip.y && other.viewport.x + other.viewport.width >= clip.x + clip.width && other.viewport.y + other.viewport.height >= clip.y + clip.height)
+                        covering.push({ uuid: String(node.uuid ?? ''), name: String(node.name ?? '').slice(0, 200), path: pathOf(node) });
+                });
+                if (covering.length)
+                    warnings.push({ code: 'POSSIBLY_COVERED', detail: 'an opaque Sprite drawn later fully contains this node\'s box', coveredBy: covering });
+            }
+        }
+        return {
+            version,
+            target: summary(target),
+            visible: reasons.length === 0,
+            reasons,
+            warnings,
+            effectiveOpacity: Math.round(opacity * 1000) / 1000,
+            ...(Number.isFinite(layer) ? { layer } : {}),
+            bounds: bounds.available ? { viewport: bounds.viewport, clippedViewport: bounds.clippedViewport } : { reason: bounds.reason },
+        };
+    }
+    if (request.action === 'explainLayout') {
+        // Reads Widget, Layout, Label, and Sprite backing fields to say which of them drives this node's size and position.
+        const target = findByUuid(request.uuid);
+        const parent = target.parent;
+        const explanations = [];
+        const note = (code, detail, extra = {}) => explanations.push({ code, detail, ...extra });
+        const own = components(target);
+        const find = (node, type) => components(node).find(component => componentName(component) === type);
+        const alignModes = ['ONCE', 'ON_WINDOW_RESIZE', 'ALWAYS'];
+        const widget = find(target, 'Widget');
+        let widgetInfo;
+        if (widget) {
+            const flags = finiteOr(dataProperty(widget, '_alignFlags'));
+            const edge = (flag, field, abs) => flags & flag ? { value: finiteOr(dataProperty(widget, field)), unit: dataProperty(widget, abs) === false ? 'percent' : 'px' } : undefined;
+            const edges = { top: edge(1, '_top', '_isAbsTop'), bottom: edge(4, '_bottom', '_isAbsBottom'), left: edge(8, '_left', '_isAbsLeft'), right: edge(32, '_right', '_isAbsRight'), horizontalCenter: edge(16, '_horizontalCenter', '_isAbsHorizontalCenter'), verticalCenter: edge(2, '_verticalCenter', '_isAbsVerticalCenter') };
+            const alignMode = alignModes[finiteOr(dataProperty(widget, '_alignMode'), -1)] ?? 'UNKNOWN';
+            const reference = dataProperty(widget, '_target');
+            widgetInfo = { enabled: dataProperty(widget, '_enabled') !== false, alignMode, ...(reference ? { target: { uuid: String(reference.uuid ?? ''), name: String(reference.name ?? '').slice(0, 200) } } : {}), edges: Object.fromEntries(Object.entries(edges).filter(([, value]) => value)) };
+            if (dataProperty(widget, '_enabled') === false)
+                note('WIDGET_DISABLED', 'Widget is disabled, so it does not constrain this node');
+            else {
+                if (flags & 8 && flags & 32)
+                    note('WIDGET_STRETCHES_WIDTH', 'left and right edges are both aligned, so the width is the reference width minus both offsets');
+                if (flags & 1 && flags & 4)
+                    note('WIDGET_STRETCHES_HEIGHT', 'top and bottom edges are both aligned, so the height is the reference height minus both offsets');
+                if (flags & 15 && !(flags & 8 && flags & 32) || flags & 63)
+                    note('WIDGET_SETS_POSITION', 'Widget positions the node against ' + (reference ? 'its target' : 'its parent') + ' edges');
+                if (alignMode === 'ONCE')
+                    note('WIDGET_ALIGN_ONCE', 'alignMode ONCE aligns when enabled and not again, so a later resize or parent change leaves the node where it was');
+            }
+        }
+        const parentLayout = parent ? find(parent, 'Layout') : undefined;
+        const layoutTypes = ['NONE', 'HORIZONTAL', 'VERTICAL', 'GRID'];
+        const resizeModes = ['NONE', 'CONTAINER', 'CHILDREN'];
+        const describeLayout = (layout) => ({ type: layoutTypes[finiteOr(dataProperty(layout, '_layoutType'), -1)] ?? 'UNKNOWN', resizeMode: resizeModes[finiteOr(dataProperty(layout, '_resizeMode'), -1)] ?? 'UNKNOWN', spacingX: finiteOr(dataProperty(layout, '_spacingX')), spacingY: finiteOr(dataProperty(layout, '_spacingY')), padding: { left: finiteOr(dataProperty(layout, '_paddingLeft')), right: finiteOr(dataProperty(layout, '_paddingRight')), top: finiteOr(dataProperty(layout, '_paddingTop')), bottom: finiteOr(dataProperty(layout, '_paddingBottom')) }, affectedByScale: dataProperty(layout, '_affectedByScale') === true, enabled: dataProperty(layout, '_enabled') !== false });
+        let parentLayoutInfo;
+        if (parentLayout) {
+            parentLayoutInfo = describeLayout(parentLayout);
+            if (parentLayoutInfo.enabled && parentLayoutInfo.type !== 'NONE')
+                note('LAYOUT_CONTROLS_POSITION', `the parent's ${parentLayoutInfo.type} Layout places its children; a manual position is overwritten the next time it updates`);
+            if (parentLayoutInfo.enabled && parentLayoutInfo.resizeMode === 'CHILDREN')
+                note('LAYOUT_CONTROLS_SIZE', 'the parent Layout resizes its children');
+        }
+        const ownLayout = find(target, 'Layout');
+        let ownLayoutInfo;
+        if (ownLayout) {
+            ownLayoutInfo = describeLayout(ownLayout);
+            if (ownLayoutInfo.enabled && ownLayoutInfo.resizeMode === 'CONTAINER')
+                note('LAYOUT_FITS_CONTAINER_TO_CHILDREN', 'resizeMode CONTAINER sizes this node to fit its children');
+        }
+        const label = find(target, 'Label');
+        if (label && [0, 3].includes(finiteOr(dataProperty(label, '_overflow'), -1)))
+            note('LABEL_CONTROLS_SIZE', `Label overflow ${finiteOr(dataProperty(label, '_overflow')) === 0 ? 'NONE' : 'RESIZE_HEIGHT'} sets the size from its text`);
+        const sprite = find(target, 'Sprite');
+        if (sprite && finiteOr(dataProperty(sprite, '_sizeMode'), 0) !== 0)
+            note('SPRITE_CONTROLS_SIZE', `Sprite sizeMode ${finiteOr(dataProperty(sprite, '_sizeMode')) === 1 ? 'TRIMMED' : 'RAW'} takes the size from its spriteFrame`);
+        let ancestorScale = { x: 1, y: 1 };
+        for (const node of chainOf(target).slice(1)) {
+            const scale = dataProperty(node, '_lscale');
+            if (scale)
+                ancestorScale = { x: ancestorScale.x * finiteOr(scale.x, 1), y: ancestorScale.y * finiteOr(scale.y, 1) };
+        }
+        if (ancestorScale.x !== 1 || ancestorScale.y !== 1)
+            note('SCALED_BY_ANCESTOR', `ancestors scale this node by ${Math.round(ancestorScale.x * 1000) / 1000} x ${Math.round(ancestorScale.y * 1000) / 1000}`);
+        if (!find(target, 'UITransform'))
+            note('NO_UI_TRANSFORM', 'the node has no UITransform, so it has no size, anchor, or Widget/Layout participation');
+        const position = dataProperty(target, '_lpos');
+        const bounds = nodeBounds(target);
+        return {
+            version,
+            target: summary(target),
+            size: sizeOf(target) ?? null,
+            localPosition: position ? { x: finiteOr(position.x), y: finiteOr(position.y), z: finiteOr(position.z) } : null,
+            parent: parent ? { uuid: String(parent.uuid ?? ''), name: String(parent.name ?? '').slice(0, 200), size: sizeOf(parent) ?? null } : null,
+            ...(widgetInfo ? { widget: widgetInfo } : {}),
+            ...(parentLayoutInfo ? { parentLayout: parentLayoutInfo } : {}),
+            ...(ownLayoutInfo ? { layout: ownLayoutInfo } : {}),
+            ancestorScale,
+            explanations,
+            viewport: bounds.available ? bounds.viewport : { reason: bounds.reason },
+            componentTypes: own.slice(0, 50).map(componentName),
+        };
+    }
+    if (request.action === 'animationReport') {
+        // Reads Animation states, Spine/DragonBones fields, and the tween manager's hash by data property; nothing is played or stopped.
+        const limit = Math.min(Math.max(request.limit ?? 100, 1), 500);
+        const animations = [];
+        let playing = 0;
+        let total = 0;
+        const finiteJson = (value) => typeof value === 'number' ? (Number.isFinite(value) ? value : String(value)) : value;
+        const traversal = walk((node, path) => {
+            for (const component of components(node)) {
+                const type = componentName(component);
+                if (!['Animation', 'Skeleton', 'ArmatureDisplay'].includes(type))
+                    continue;
+                total++;
+                const base = { uuid: String(node.uuid ?? ''), node: String(node.name ?? '').slice(0, 200), path, type, enabled: dataProperty(component, '_enabled') !== false, activeInHierarchy: node.activeInHierarchy !== false };
+                if (type === 'Animation') {
+                    const states = Object.values(dataProperty(component, '_nameToState') ?? {});
+                    const active = states.filter(state => dataProperty(state, '_isPlaying') === true);
+                    playing += active.length;
+                    if (animations.length < limit)
+                        animations.push({ ...base, stateCount: states.length, playing: active.length, states: states.filter(state => dataProperty(state, '_isPlaying') === true).slice(0, 20).map(state => ({ name: String(dataProperty(state, '_name') ?? '').slice(0, 120), paused: dataProperty(state, '_isPaused') === true, speed: finiteJson(dataProperty(state, '_speed')), wrapMode: dataProperty(state, '_wrapMode'), repeatCount: finiteJson(dataProperty(state, '_repeatCount')), time: finiteJson(dataProperty(state, 'time')) })) });
+                }
+                else {
+                    const animation = dataProperty(component, '_animationName');
+                    if (animation)
+                        playing++;
+                    if (animations.length < limit)
+                        animations.push({ ...base, animation: animation ? String(animation).slice(0, 120) : null, loop: finiteJson(dataProperty(component, 'loop') ?? dataProperty(component, '_loop')), timeScale: finiteJson(dataProperty(component, '_timeScale')), paused: dataProperty(component, '_paused') === true ? true : undefined });
+                }
+            }
+        });
+        const systems = (dataProperty(cc.director ?? {}, '_systems') ?? []);
+        const hash = dataProperty(dataProperty(systems.find(system => system && dataProperty(system, 'actionMgr')) ?? {}, 'actionMgr') ?? {}, '_hashTargets');
+        const tweens = [];
+        let tweenTotal = 0;
+        let tweenActions = 0;
+        if (hash instanceof Map) {
+            for (const [owner, element] of hash) {
+                const actions = Array.isArray(element?.actions) ? element.actions.length : 0;
+                tweenTotal++;
+                tweenActions += actions;
+                if (tweens.length >= limit)
+                    continue;
+                const isNode = !!owner && typeof owner === 'object' && typeof dataProperty(owner, '_id') === 'string';
+                tweens.push({ target: isNode ? { uuid: String(owner.uuid ?? ''), name: String(owner.name ?? '').slice(0, 200), path: pathOf(owner) } : { type: String(dataProperty(owner ?? {}, 'constructor')?.name ?? typeof owner).slice(0, 80) }, actions, paused: element?.paused === true });
+            }
+        }
+        return {
+            version,
+            counts: { animationComponents: total, playingStates: playing, tweenTargets: tweenTotal, tweenActions },
+            animations,
+            tweens,
+            ...(hash instanceof Map ? {} : { unavailableMetrics: { tweens: 'UNSUPPORTED_PUBLIC_API' } }),
+            truncated: traversal.truncated || animations.length >= limit || tweens.length >= limit,
+            truncationReasons: traversal.truncated || animations.length >= limit || tweens.length >= limit ? ['NODE_LIMIT'] : [],
+        };
+    }
+    if (request.action === 'frameProfile') {
+        // Measures wall-clock time between consecutive AFTER_DRAW events, so GC pauses and long frames show; reads draw stats the same frame.
+        const wanted = Math.min(Math.max(Math.floor(request.frames ?? 120), 2), 600);
+        const timeoutMs = Math.min(Math.max(request.timeoutMs ?? 10_000, 100), 30_000);
+        const director = cc.director;
+        if (typeof director?.on !== 'function' || typeof director?.off !== 'function' || !cc.Director?.EVENT_AFTER_DRAW)
+            invalidMutation('director events are unavailable');
+        if (typeof director.isPaused === 'function' && director.isPaused())
+            return { version, sampled: 0, reason: 'DIRECTOR_PAUSED' };
+        const now = () => typeof root.performance?.now === 'function' ? root.performance.now() : Date.now();
+        const renderRoot = dataProperty(director, '_root');
+        const device = renderRoot && typeof renderRoot === 'object' ? dataProperty(renderRoot, '_device') : undefined;
+        const read = (owner, key) => { const value = owner && typeof owner === 'object' ? dataProperty(owner, key) : undefined; return typeof value === 'number' && Number.isFinite(value) ? value : undefined; };
+        const samples = [];
+        return new Promise(resolve => {
+            let last;
+            let finished = false;
+            let timer;
+            const finish = (timedOut) => {
+                if (finished)
+                    return;
+                finished = true;
+                director.off(cc.Director.EVENT_AFTER_DRAW, onFrame);
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                const sorted = samples.map(sample => sample.ms).sort((a, b) => a - b);
+                const at = (fraction) => sorted.length ? sorted[Math.min(sorted.length - 1, Math.floor(fraction * sorted.length))] : 0;
+                const round = (value) => Math.round(value * 100) / 100;
+                const median = at(0.5);
+                const stat = (key) => { const values = samples.map(sample => sample[key]).filter((value) => value !== undefined); return values.length ? { min: Math.min(...values), avg: Math.round(values.reduce((sum, value) => sum + value, 0) / values.length), max: Math.max(...values) } : undefined; };
+                resolve({
+                    version,
+                    sampled: samples.length,
+                    ...(timedOut ? { timedOut: true } : {}),
+                    frameMs: samples.length ? { avg: round(sorted.reduce((sum, value) => sum + value, 0) / sorted.length), p50: round(median), p95: round(at(0.95)), max: round(sorted[sorted.length - 1]) } : undefined,
+                    fps: samples.length && median > 0 ? round(1_000 / median) : undefined,
+                    // A spike is a frame over twice the median and over 33 ms: slow enough to be felt, not ordinary jitter.
+                    spikes: samples.filter(sample => sample.ms > median * 2 && sample.ms > 33).length,
+                    worstFrames: samples.map((sample, index) => ({ index, ms: round(sample.ms) })).sort((a, b) => b.ms - a.ms).slice(0, 5),
+                    drawCalls: stat('drawCalls'),
+                    triangles: stat('triangles'),
+                });
+            };
+            const onFrame = () => {
+                const at = now();
+                if (last !== undefined)
+                    samples.push({ ms: at - last, drawCalls: read(device, '_numDrawCalls'), triangles: read(device, '_numTris') });
+                last = at;
+                if (samples.length >= wanted)
+                    finish(false);
+            };
+            director.on(cc.Director.EVENT_AFTER_DRAW, onFrame);
+            timer = setTimeout(() => finish(true), timeoutMs);
+        });
+    }
+    if (request.action === 'eventTrace') {
+        // Wraps Node.prototype.emit for a bounded window and counts calls per event and node. Arguments are never recorded; the original runs unchanged.
+        const durationMs = Math.min(Math.max(request.durationMs ?? 2_000, 100), 10_000);
+        const limit = Math.min(Math.max(request.limit ?? 50, 1), 200);
+        if (root.__cocosWebInspectorEventTrace)
+            invalidMutation('an event trace is already running');
+        const proto = cc.Node?.prototype;
+        if (!proto || typeof proto.emit !== 'function')
+            invalidMutation('Node.prototype.emit is unavailable');
+        const original = proto.emit;
+        const hadOwn = Object.prototype.hasOwnProperty.call(proto, 'emit');
+        const groups = new Map();
+        let total = 0;
+        let droppedGroups = 0;
+        const startedAt = Date.now();
+        root.__cocosWebInspectorEventTrace = true;
+        proto.emit = function (type, ...rest) {
+            try {
+                total++;
+                const event = String(typeof type === 'string' || typeof type === 'number' ? type : 'unknown').slice(0, 120);
+                const name = String(dataProperty(this, '_name') ?? '').slice(0, 200);
+                const uuid = String(dataProperty(this, '_id') ?? '');
+                const key = `${event}|${uuid}`;
+                const group = groups.get(key);
+                if (group)
+                    group.count++;
+                else if (groups.size < 1_000)
+                    groups.set(key, { event, node: name, nodeUuid: uuid, count: 1 });
+                else
+                    droppedGroups++;
+            }
+            catch { /* tracing must never break the game */ }
+            return original.call(this, type, ...rest);
+        };
+        return new Promise(resolve => setTimeout(() => {
+            if (hadOwn)
+                proto.emit = original;
+            else
+                delete proto.emit;
+            root.__cocosWebInspectorEventTrace = undefined;
+            const seconds = Math.max((Date.now() - startedAt) / 1_000, 0.001);
+            const top = [...groups.values()].sort((a, b) => b.count - a.count);
+            const perEvent = new Map();
+            for (const group of top)
+                perEvent.set(group.event, (perEvent.get(group.event) ?? 0) + group.count);
+            resolve({
+                version,
+                durationMs: Date.now() - startedAt,
+                totalEmits: total,
+                emitsPerSecond: Math.round(total / seconds),
+                byEvent: [...perEvent.entries()].sort((a, b) => b[1] - a[1]).slice(0, limit).map(([event, count]) => ({ event, count })),
+                top: top.slice(0, limit).map(group => ({ ...group, perSecond: Math.round(group.count / seconds) })),
+                truncated: top.length > limit || droppedGroups > 0,
+                truncationReasons: top.length > limit || droppedGroups > 0 ? ['NODE_LIMIT'] : [],
+            });
+        }, durationMs));
+    }
     if (request.action === 'getNodeBounds')
         return { version, uuid: request.uuid, ...nodeBounds(findByUuid(request.uuid)) };
     if (request.action !== 'highlightNode')