dsh-browser-plus 0.5.0 → 0.5.1

package/lib/tool-browser/index.js

@@ -233,6 +233,86 @@ function formatSnapshot(snapshot) {
         : '';
     return `${header}\n\n${body}${tail}${banner}${user}`;
 }
+/**
+ * The snapshot shape both `browser_open` and `browser_snapshot` return.
+ *
+ * Shared on purpose: a tool output schema rejects unknown properties, so a
+ * field declared on only one of the two schemas is silently dropped before the
+ * model ever sees it — which is exactly what happened to `frames` and the
+ * element `frame` index when iframe support landed (declared on browser_open,
+ * missing from browser_snapshot, and dropped from browser_open's own mapper).
+ */
+const SNAPSHOT_OUTPUT_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        snapshotId: { type: 'string', required: true },
+        url: { type: 'string', required: true },
+        title: { type: 'string' },
+        truncated: { type: 'boolean' },
+        frames: {
+            type: 'array',
+            description: 'Every iframe on the page; readable:false marks the cross-origin ones whose contents cannot be read.',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    index: { type: 'number', required: true },
+                    url: { type: 'string', required: true },
+                    readable: { type: 'boolean', required: true },
+                },
+            },
+        },
+        elements: {
+            type: 'array',
+            required: true,
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    ref: { type: 'number', required: true },
+                    kind: { type: 'string', required: true },
+                    label: { type: 'string', required: true },
+                    x: { type: 'number', required: true },
+                    y: { type: 'number', required: true },
+                    loc: { type: 'string', required: true },
+                    frame: { type: 'number', description: 'Index into frames when this element lives inside an iframe.' },
+                },
+            },
+        },
+        challenge: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                blocked: { type: 'boolean', required: true },
+                kind: { type: 'string' },
+                reason: { type: 'string' },
+            },
+        },
+        userControlling: { type: 'boolean' },
+    },
+};
+/** Project a provider snapshot onto that shared model-facing shape. */
+function snapshotOutput(snapshot) {
+    return {
+        snapshotId: snapshot.snapshotId,
+        url: snapshot.url,
+        ...snapshot.title !== undefined ? { title: snapshot.title } : {},
+        ...snapshot.frames !== undefined ? { frames: snapshot.frames.map(frame => ({ index: frame.index, url: frame.url, readable: frame.readable })) } : {},
+        elements: snapshot.elements.map(el => ({
+            ref: el.ref,
+            kind: el.kind,
+            label: el.label,
+            x: el.x,
+            y: el.y,
+            loc: el.loc,
+            ...el.frame !== undefined ? { frame: el.frame } : {},
+        })),
+        truncated: snapshot.truncated,
+        ...snapshot.challenge !== undefined ? { challenge: snapshot.challenge } : {},
+        ...snapshot.userControlling !== undefined ? { userControlling: snapshot.userControlling } : {},
+    };
+}
 /** Register all browser tools with `ctx.tools`. */
 export function apply(ctx, config = {}) {
     const timeoutMs = config.timeoutMs ?? 60_000;
@@ -261,42 +341,7 @@ export function apply(ctx, config = {}) {
             space: { type: 'string', description: 'Optional browser-task label shown in the task manager and active window title.' },
         },
         output: {
-            schema: {
-                type: 'object',
-                additionalProperties: false,
-                properties: {
-                    snapshotId: { type: 'string', required: true },
-                    url: { type: 'string', required: true },
-                    title: { type: 'string' },
-                    truncated: { type: 'boolean' },
-                    elements: {
-                        type: 'array',
-                        required: true,
-                        items: {
-                            type: 'object',
-                            additionalProperties: false,
-                            properties: {
-                                ref: { type: 'number', required: true },
-                                kind: { type: 'string', required: true },
-                                label: { type: 'string', required: true },
-                                x: { type: 'number', required: true },
-                                y: { type: 'number', required: true },
-                                loc: { type: 'string', required: true },
-                            },
-                        },
-                    },
-                    challenge: {
-                        type: 'object',
-                        additionalProperties: false,
-                        properties: {
-                            blocked: { type: 'boolean', required: true },
-                            kind: { type: 'string' },
-                            reason: { type: 'string' },
-                        },
-                    },
-                    userControlling: { type: 'boolean' },
-                },
-            },
+            schema: SNAPSHOT_OUTPUT_SCHEMA,
             render: (_args, value) => [{ type: 'text', text: formatSnapshot(value) }],
         },
         timeoutMs,
@@ -313,15 +358,7 @@ export function apply(ctx, config = {}) {
                     ...args.newTab === true ? { newTab: true } : {},
                 }, exec.signal);
                 const snapshot = await browser.snapshot(session, {}, exec.signal);
-                return {
-                    snapshotId: snapshot.snapshotId,
-                    url: snapshot.url,
-                    ...snapshot.title !== undefined ? { title: snapshot.title } : {},
-                    elements: snapshot.elements.map(el => ({ ref: el.ref, kind: el.kind, label: el.label, x: el.x, y: el.y, loc: el.loc })),
-                    truncated: snapshot.truncated,
-                    ...snapshot.challenge !== undefined ? { challenge: snapshot.challenge } : {},
-                    ...snapshot.userControlling !== undefined ? { userControlling: snapshot.userControlling } : {},
-                };
+                return snapshotOutput(snapshot);
             }, args.space);
         },
     }));
@@ -546,42 +583,7 @@ export function apply(ctx, config = {}) {
             limit: { type: 'number', description: 'Maximum number of elements to return (1-1000; default 60).' },
         },
         output: {
-            schema: {
-                type: 'object',
-                additionalProperties: false,
-                properties: {
-                    snapshotId: { type: 'string', required: true },
-                    url: { type: 'string', required: true },
-                    title: { type: 'string' },
-                    truncated: { type: 'boolean' },
-                    elements: {
-                        type: 'array',
-                        required: true,
-                        items: {
-                            type: 'object',
-                            additionalProperties: false,
-                            properties: {
-                                ref: { type: 'number', required: true },
-                                kind: { type: 'string', required: true },
-                                label: { type: 'string', required: true },
-                                x: { type: 'number', required: true },
-                                y: { type: 'number', required: true },
-                                loc: { type: 'string', required: true },
-                            },
-                        },
-                    },
-                    challenge: {
-                        type: 'object',
-                        additionalProperties: false,
-                        properties: {
-                            blocked: { type: 'boolean', required: true },
-                            kind: { type: 'string' },
-                            reason: { type: 'string' },
-                        },
-                    },
-                    userControlling: { type: 'boolean' },
-                },
-            },
+            schema: SNAPSHOT_OUTPUT_SCHEMA,
             render: (_args, value) => [{ type: 'text', text: formatSnapshot(value) }],
         },
         timeoutMs,
@@ -595,15 +597,7 @@ export function apply(ctx, config = {}) {
                 ...args.query !== undefined ? { query: args.query } : {},
                 ...args.limit !== undefined ? { limit: args.limit } : {},
             }, exec.signal));
-            return {
-                snapshotId: snapshot.snapshotId,
-                url: snapshot.url,
-                ...snapshot.title !== undefined ? { title: snapshot.title } : {},
-                elements: snapshot.elements.map(el => ({ ref: el.ref, kind: el.kind, label: el.label, x: el.x, y: el.y, loc: el.loc })),
-                truncated: snapshot.truncated,
-                ...snapshot.challenge !== undefined ? { challenge: snapshot.challenge } : {},
-                ...snapshot.userControlling !== undefined ? { userControlling: snapshot.userControlling } : {},
-            };
+            return snapshotOutput(snapshot);
         },
     }));
     ctx.tools.register(defineTool({
@@ -1171,9 +1165,11 @@ export function apply(ctx, config = {}) {
     }));
     ctx.tools.register(defineTool({
         name: 'browser_wait_for',
-        description: 'Wait until an element matching a CSS selector appears (and is visible), polling every 250ms. Use before interacting with dynamically-loaded content (SPA views, toasts, menus).',
+        description: 'Wait until a selector, some text, or both reaches a state, polling every 250ms. `state` is visible (default), attached, hidden or detached — hidden/detached are how you wait for something to go away. Use before clicking or reading, instead of sleeping.',
         parameters: {
-            selector: { type: 'string', required: true, description: 'CSS selector to wait for.' },
+            selector: { type: 'string', description: 'CSS selector to wait for. Omit to watch the document text (give `text`).' },
+            text: { type: 'string', description: 'Text that must be present: inside the matched element when a selector is given, otherwise anywhere in the document.' },
+            state: { type: 'string', enum: ['visible', 'attached', 'hidden', 'detached'], description: 'Which state to wait for. visible (default) needs a 4x4 px element that is not display:none / visibility:hidden; attached only needs it to exist; hidden and detached wait for it to go away.' },
             timeoutMs: { type: 'number', description: `Total budget in ms (default 15000), capped below this tool's ${String(timeoutMs)}ms budget.` },
             visible: { type: 'boolean', description: 'Require visibility (>4x4 px, not display:none). Default true.' },
         },
@@ -1183,12 +1179,18 @@ export function apply(ctx, config = {}) {
                 additionalProperties: false,
                 properties: {
                     found: { type: 'boolean', required: true },
+                    state: { type: 'string', required: true },
                     selector: { type: 'string', required: true },
                     tag: { type: 'string', required: true },
                     text: { type: 'string' },
                 },
             },
-            render: (_args, value) => [{ type: 'text', text: `Found <${value.tag}> ${value.selector}${value.text !== undefined ? ` — "${value.text.slice(0, 80)}"` : ''}.` }],
+            render: (_args, value) => [{
+                    type: 'text',
+                    text: value.selector === ''
+                        ? `Found text "${(value.text ?? '').slice(0, 80)}" (state "${value.state}").`
+                        : `Found <${value.tag}> ${value.selector}${value.text !== undefined ? ` — "${value.text.slice(0, 80)}"` : ''}.`,
+                }],
         },
         timeoutMs,
         isConcurrencySafe: () => true,
@@ -1198,11 +1200,13 @@ export function apply(ctx, config = {}) {
             if (browser === undefined)
                 throw new Error('tool-browser: browser service unavailable');
             const result = await withTaskAction(browser, taskKey(exec), 'wait for element', exec, session => browser.waitForElement(session, {
-                selector: args.selector,
+                ...args.selector !== undefined ? { selector: args.selector } : {},
+                ...args.text !== undefined ? { text: args.text } : {},
+                ...args.state !== undefined ? { state: args.state } : {},
                 timeoutMs: withinToolBudget(args.timeoutMs, 15_000),
                 ...args.visible !== undefined ? { visible: args.visible } : {},
             }, exec.signal));
-            return { found: true, selector: result.selector, tag: result.tag, text: result.text };
+            return { found: true, state: result.state, selector: result.selector, tag: result.tag, text: result.text };
         },
     }));
     ctx.tools.register(defineTool({
@@ -1441,6 +1445,97 @@ export function apply(ctx, config = {}) {
             };
         },
     }));
+    ctx.tools.register(defineTool({
+        name: 'browser_pdf',
+        description: 'Print the active tab to a PDF file — Chrome\'s "Save as PDF". The path must be inside the browser write roots. Returns the path and byte size.',
+        parameters: {
+            savePath: { type: 'string', required: true, description: 'Absolute path of the .pdf to write. Must be inside the browser write roots.' },
+            landscape: { type: 'boolean', description: 'Landscape orientation. Default portrait.' },
+            printBackground: { type: 'boolean', description: 'Include background colours and images. Default true — dark pages would otherwise print as white paper.' },
+            paperWidth: { type: 'number', description: 'Paper width in inches. Default 8.5.' },
+            paperHeight: { type: 'number', description: 'Paper height in inches. Default 11.' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    path: { type: 'string', required: true },
+                    bytes: { type: 'number', required: true },
+                },
+            },
+            render: (_args, value) => [{ type: 'text', text: `Wrote ${value.bytes} bytes to ${value.path}` }],
+        },
+        timeoutMs,
+        isConcurrencySafe: () => true,
+        async execute(args, exec) {
+            assertAllowed('browser_pdf', exec);
+            const browser = ctx.get('browser');
+            if (browser === undefined)
+                throw new Error('tool-browser: browser service unavailable');
+            const result = await withTaskAction(browser, taskKey(exec), 'print to pdf', exec, session => browser.pdf(session, {
+                savePath: args.savePath,
+                ...args.landscape !== undefined ? { landscape: args.landscape } : {},
+                ...args.printBackground !== undefined ? { printBackground: args.printBackground } : {},
+                ...args.paperWidth !== undefined ? { paperWidth: args.paperWidth } : {},
+                ...args.paperHeight !== undefined ? { paperHeight: args.paperHeight } : {},
+            }, exec.signal));
+            return { path: result.path, bytes: result.bytes };
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'browser_highlight',
+        description: 'Draw the DevTools-style highlight box over the first element matching a CSS selector, so a human watching the window can see what the Agent is about to touch. It goes through the CDP overlay, so the page DOM is never modified. Pass clear: true to remove it.',
+        parameters: {
+            selector: { type: 'string', description: 'CSS selector whose first match to highlight. Required unless clear is true.' },
+            clear: { type: 'boolean', description: 'Remove the highlight instead of drawing one.' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    matched: { type: 'boolean', required: true },
+                    cleared: { type: 'boolean', required: true },
+                    nodeId: { type: 'number' },
+                    box: {
+                        type: 'object',
+                        additionalProperties: false,
+                        properties: {
+                            x: { type: 'number', required: true },
+                            y: { type: 'number', required: true },
+                            width: { type: 'number', required: true },
+                            height: { type: 'number', required: true },
+                        },
+                    },
+                },
+            },
+            render: (_args, value) => [{
+                    type: 'text',
+                    text: value.matched
+                        ? `Highlighted node ${String(value.nodeId)} at ${Math.round(value.box?.x ?? 0)},${Math.round(value.box?.y ?? 0)} (${Math.round(value.box?.width ?? 0)}x${Math.round(value.box?.height ?? 0)})`
+                        : value.cleared ? 'Highlight cleared' : 'No element matched that selector',
+                }],
+        },
+        timeoutMs,
+        isConcurrencySafe: () => true,
+        async execute(args, exec) {
+            assertAllowed('browser_highlight', exec);
+            const browser = ctx.get('browser');
+            if (browser === undefined)
+                throw new Error('tool-browser: browser service unavailable');
+            const result = await withTaskAction(browser, taskKey(exec), 'highlight element', exec, session => browser.highlight(session, {
+                ...args.selector !== undefined ? { selector: args.selector } : {},
+                ...args.clear !== undefined ? { clear: args.clear } : {},
+            }, exec.signal));
+            return {
+                matched: result.matched,
+                cleared: result.cleared,
+                ...result.nodeId !== undefined ? { nodeId: result.nodeId } : {},
+                ...result.box !== undefined ? { box: result.box } : {},
+            };
+        },
+    }));
     if (config.tabTools !== false) {
         ctx.tools.register(defineTool({
             name: 'browser_list_tabs',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-browser-plus",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Enhanced shared browser for DeepSeek Harness: one visible window with isolated task views, a page task manager, non-stealing background tasks, built-in toolbar and operation trail, and pinned Electron 42.9.3 compositing.",
   "type": "module",
   "main": "lib/index.js",
@@ -22,6 +22,21 @@
       "types": "./lib/tool-browser/index.d.ts",
       "default": "./lib/tool-browser/index.js"
     },
+    "./command-browser": {
+      "types": "./lib/command-browser/index.d.ts",
+      "default": "./lib/command-browser/index.js"
+    },
+    "./http-browser": {
+      "types": "./lib/http-browser/index.d.ts",
+      "default": "./lib/http-browser/index.js"
+    },
+    "./task-todos": {
+      "types": "./lib/task-todos/index.d.ts",
+      "default": "./lib/task-todos/index.js"
+    },
+    "./client": {
+      "default": "./lib/client.js"
+    },
     "./host-main": {
       "default": "./lib/browser-electron/host-main.js"
     },
@@ -31,6 +46,7 @@
   "files": [
     "lib",
     "src",
+    "client",
     "docs",
     "assets",
     "scripts",
@@ -43,8 +59,9 @@
     "NOTICE.md"
   ],
   "scripts": {
-    "build": "npm run build:icons && tsc -p tsconfig.json",
+    "build": "npm run build:icons && tsc -p tsconfig.json && npm run build:client",
     "build:icons": "node scripts/build-icons.mjs",
+    "build:client": "node scripts/build-client.mjs",
     "pretest": "tsc -p tsconfig.json",
     "test": "node --test test/*.test.mjs",
     "test:only": "node --test test/*.test.mjs",
@@ -52,6 +69,7 @@
     "smoke:electron-host": "node scripts/smoke-electron-host.mjs",
     "smoke:browser-tools": "node scripts/smoke-browser-tools.mjs",
     "smoke:chrome-world": "node scripts/smoke-chrome-world.mjs",
+    "test:orb-drag": "node scripts/test-orb-drag.mjs",
     "prepack": "npm run build"
   },
   "keywords": [
@@ -89,6 +107,13 @@
   "dsh": {
     "bundle": {
       "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-slots",
+        "@deepseek-ai/dsh-client-ui-sidebar-right"
+      ],
+      "platform": "web"
     }
   },
   "optionalDependencies": {

package/scripts/build-client.mjs

@@ -0,0 +1,20 @@
+/**
+ * Build the browser bundle: copy the single-file client source to lib/client.js.
+ *
+ * The client-modules loader serves the package's \`./client\` export, and the
+ * bundle is one file that only requires platform modules (React), so there is
+ * nothing to bundle or minify — the copy keeps the shipped artifact identical to
+ * the reviewed source. Run by \`npm run build\` and by \`prepack\`.
+ */
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+
+const source = new URL('../client/index.js', import.meta.url)
+const output = new URL('../lib/client.js', import.meta.url)
+
+const body = await readFile(source, 'utf8')
+if (!body.includes('__ModuleLoader__.load')) {
+  throw new Error('client/index.js must register through window.__ModuleLoader__.load')
+}
+await mkdir(new URL('../lib/', import.meta.url), { recursive: true })
+await writeFile(output, body)
+process.stdout.write('built lib/client.js (' + String(body.length) + ' bytes)\n')

package/scripts/smoke-browser-tools.mjs

@@ -35,9 +35,14 @@ const check = async (name, fn) => {
   }
 }
 
-const host = new RemoteElectronViewHost(defaultHostMainPath())
+// 这套检查**探 chrome 的内部状态**（window.__dshTabs / __dshChromeMotion / __dshBookmarks…），
+// 而默认的 isolated 世界把这些放在 chrome 自己的世界里 —— 从页面世界读到的全是 undefined。
+// 所以行为套件显式跑 main；「隔离是否真的隔离、chrome 在隔离世界里能不能挂起来」由
+// `npm run smoke:chrome-world` 负责（它同时跑两种模式做 A/B）。
+const host = new RemoteElectronViewHost(defaultHostMainPath(), { chromeWorld: 'main' })
 const provider = new ElectronBrowserProvider(host, { writeRoots: [outDir], readRoots: [outDir] })
 
+
 try {
   const session = await provider.open()
   console.log('session', session)
@@ -63,6 +68,21 @@ try {
     return 'no error'
   })
   await check('waitForElement', async () => (await provider.waitForElement(session, { selector: 'body' })).tag)
+  // 纯文字等待：没有选择器可量，状态必须由「文字在不在」决定。
+  // 这一条曾经永远超时（脚本仍按 visibleNow(null) === false 判定）。
+  await check('waitForElement by text', async () => (await provider.waitForElement(session, { text: 'This domain is for use' })).state)
+  // 真机打印：Electron 的 debugger 没有 CDP Page.printToPDF，
+  // 所以这条只有走宿主的 webContents.printToPDF 才可能过。
+  await check('pdf', async () => {
+    const out = join(outDir, 'page.pdf')
+    const result = await provider.pdf(session, { savePath: out })
+    const bytes = readFileSync(out)
+    if (bytes.subarray(0, 5).toString() !== '%PDF-') throw new Error('not a PDF: ' + bytes.subarray(0, 8).toString())
+    if (bytes.length !== result.bytes) throw new Error('byte count mismatch: ' + String(bytes.length) + ' vs ' + String(result.bytes))
+    const pages = (bytes.toString('latin1').match(/\/Type\s*\/Page[^s]/g) ?? []).length
+    if (pages < 1) throw new Error('the printed document has no page objects')
+    return { bytes: bytes.length, pages }
+  })
   await check('scrape concurrent', async () => {
     const out = join(outDir, 'rows.jsonl')
     const started = await provider.startScrape(session, {
@@ -1801,6 +1821,69 @@ await check('a confirm dialog can be dismissed, not only accepted', async () =>
     await new Promise(resolve => setTimeout(resolve, 800))
   }
 })
+// 真机：同源子框架里的控件要能看到（元素带 frame 序号、坐标加上框架的矩形）；
+// 跨源框架的 contentDocument 读不到，必须明确记成 readable:false —— 不假装能读。
+await check('the snapshot sees into same-origin frames and names the cross-origin ones', async () => {
+  const size = await laidOut()
+  if (size === null) return { skipped: 'the view is not laid out in this run' }
+  const { createServer } = await import('node:http')
+  const page = (port) => '<!doctype html><title>frames</title>'
+    + '<button id="outer">Outer Button</button>'
+    + '<iframe id="same" src="/inner" style="width:220px;height:60px"></iframe>'
+    + '<iframe id="cross" src="http://127.0.0.1:' + String(port) + '/inner" style="width:220px;height:60px"></iframe>'
+  const innerPage = '<!doctype html><title>inner</title><button id="inside">Inner Button</button>'
+  const inner = createServer((_request, response) => {
+    response.writeHead(200, { 'content-type': 'text/html' })
+    response.end(innerPage)
+  })
+  await new Promise(resolve => inner.listen(0, '127.0.0.1', resolve))
+  // 路径要路由：主页面里的 src="/inner" 必须拿到内部页面，
+  // 否则框架里装的就是主页面自己（第一版就是这样，量出来才发现）。
+  const outerServer = createServer((request, response) => {
+    response.writeHead(200, { 'content-type': 'text/html' })
+    if (request.url === '/inner') {
+      response.end(innerPage)
+      return
+    }
+    response.end(page(inner.address().port))
+  })
+  await new Promise(resolve => outerServer.listen(0, '127.0.0.1', resolve))
+  try {
+    await provider.navigate(session, { url: 'http://127.0.0.1:' + String(outerServer.address().port) + '/' })
+    let snapshot = null
+    for (let i = 0; i < 25; i += 1) {
+      await new Promise(resolve => setTimeout(resolve, 150))
+      snapshot = await provider.snapshot(session, { limit: 50 })
+      if ((snapshot.frames ?? []).length >= 2) break
+    }
+    const frames = snapshot.frames ?? []
+    if (frames.length < 2) throw new Error('both iframes should be reported: ' + JSON.stringify(frames))
+    const inside = snapshot.elements.find(element => element.label === 'Inner Button')
+    if (inside === undefined) throw new Error('the same-origin frame content was not read: ' + JSON.stringify(snapshot.elements.map(e => e.label)))
+    if (inside.frame !== 0) throw new Error('the frame element did not carry its index: ' + String(inside.frame))
+    const outside = snapshot.elements.find(element => element.label === 'Outer Button')
+    if (outside === undefined || outside.frame !== undefined) throw new Error('a top-level element must not claim a frame')
+    const cross = frames.find(frame => frame.readable === false)
+    if (cross === undefined) throw new Error('the cross-origin frame must be reported unreadable: ' + JSON.stringify(frames))
+    const same = frames.find(frame => frame.readable === true)
+    if (same === undefined) throw new Error('the same-origin frame should be readable: ' + JSON.stringify(frames))
+    // 工具层也必须把这两样透出去。provider 有、工具层丢，才是这个 bug 的
+    // 真正形态：只测 provider 的冒烟一直是绿的。
+    // exec 不带 agent -> taskKey() 是 'default'，正好复用上面这个会话。
+    const viaTool = await call('browser_snapshot', { limit: 50 }, {})
+    const toolFrames = viaTool.frames ?? []
+    if (toolFrames.length < 2) throw new Error('the tool layer dropped frames: ' + JSON.stringify(viaTool.frames))
+    const toolInside = (viaTool.elements ?? []).find(element => element.label === 'Inner Button')
+    if (toolInside === undefined || toolInside.frame !== 0) {
+      throw new Error('the tool layer dropped the element frame index: ' + JSON.stringify(toolInside))
+    }
+    return { frames: frames.length, inside: inside.frame, cross: String(cross.url).slice(0, 34) }
+  } finally {
+    outerServer.close()
+    inner.close()
+  }
+})
+
 // 真机：页面自己的 console 输出和网络请求必须能被读到（这是「为什么没成功」的唯一线索）。
 await check('console and network capture what the page did', async () => {
   const size = await laidOut()

package/scripts/smoke-chrome-world.mjs

@@ -28,7 +28,7 @@ const probe = async (label, options) => {
     await view.sendCommand('Page.navigate', { url: 'https://example.com/' })
     await wait(2500)
     const reply = await view.sendCommand('Runtime.evaluate', {
-      expression: 'JSON.stringify({ chromeHost: document.getElementById("__dsh_browser_chrome_host__") !== null, binding: typeof window.__dshBrowserTaskAction, tasks: typeof window.__dshTasks, trail: typeof window.__dshTrail })',
+      expression: 'JSON.stringify({ chromeHost: document.getElementById("__dsh_browser_chrome_host__") !== null, painted: (() => { const h = document.getElementById("__dsh_browser_chrome_host__"); if (h === null) return 0; return Math.round(h.getBoundingClientRect().width) })(), binding: typeof window.__dshBrowserTaskAction, tasks: typeof window.__dshTasks, trail: typeof window.__dshTrail })',
       returnByValue: true,
     })
     const value = JSON.parse(reply?.result?.value ?? '{}')
@@ -42,8 +42,10 @@ const probe = async (label, options) => {
   }
 }
 
-const main = await probe('main (default)', {})
-const isolated = await probe('isolated', { chromeWorld: 'isolated' })
+// 两种模式都**显式**指定：默认值会变（2026-10-04 起默认 isolated），
+// 用 `{}` 表示「main」会让这条检查在默认值一变就静默失效。
+const isolated = await probe('isolated (default)', {})
+const main = await probe('main (opt-in)', { chromeWorld: 'main' })
 
 // Assert only what chromeWorld claims. window.__dshBrowserTaskAction is reported
 // but not asserted: it appears asynchronously after load, so a fixed wait
@@ -60,4 +62,4 @@ if (failures.length > 0) {
   console.log(JSON.stringify({ ok: false, failures }))
   process.exit(1)
 }
-console.log(JSON.stringify({ ok: true, note: 'the chrome mounts in both modes; only the default leaks its globals to the page' }))
+console.log(JSON.stringify({ ok: true, note: 'the chrome mounts in both modes; only main (the opt-in bisect path) leaks its globals to the page' }))