dsh-browser-playwright-codex 0.8.0 → 0.8.2

package/lib/session.js

@@ -240,7 +240,12 @@ export class PlaywrightSession {
     }
     /** Element-level stability before a pointer/keyboard action, bounded. Returns true when stable. */
     async waitForElementStable(locator) {
-        const ok = await locator.evaluate(elementStabilityProbe, { frames: 2, timeoutMs: 1500 }).catch(() => false);
+        // locator.evaluate has no timeout of its own either: the probe runs page
+        // script, so a wedged main thread makes it hang before the action it is
+        // supposed to protect. Degrade to "not stable" and let the action's own
+        // Playwright timeout report the real problem (same contract as before, just
+        // no longer unbounded).
+        const ok = await withDeadline(locator.evaluate(elementStabilityProbe, { frames: 2, timeoutMs: 1500 }).catch(() => false), Math.max(3000, this.timeoutMs()), 'waiting for the element to hold still', this.currentSignal, 'resolve-undefined').catch(() => false);
         return ok === true;
     }
     /** Post-action settle: wait out a real navigation, then render-stabilize before snapshotting. */
@@ -579,7 +584,11 @@ export class PlaywrightSession {
                 if (page === undefined)
                     continue;
                 this.guardBlockedDialog(page);
-                out.push({ index, url: page.url(), title: await page.title(), active: index === activeIndex });
+                // page.title() is a page round trip with no timeout: one tab running a
+                // stuck script used to hang the whole tab list, and every tab after it.
+                // An unreadable title degrades to "" — the URL still identifies the tab.
+                const title = await withDeadline(page.title().catch(() => ''), Math.max(2000, Math.min(this.timeoutMs(), 5000)), 'reading the title of tab ' + String(index), this.currentSignal, 'resolve-undefined').catch(() => undefined);
+                out.push({ index, url: page.url(), title: title ?? '', active: index === activeIndex });
             }
             return out;
         });
@@ -623,7 +632,29 @@ export class PlaywrightSession {
         });
     }
     async pageData() {
-        return pageData(this);
+        // page.evaluate again: the extract walker is page script, so a stuck tab used
+        // to hang browser_extract exactly like a snapshot read. Same deadline, and on
+        // timeout the same cleanup — drop the handle and the page so the next call
+        // does not inherit a page that will never answer.
+        try {
+            return await withDeadline(pageData(this), this.timeoutMs(), 'reading the page content', this.currentSignal, 'reject', 'That page has been closed; anything typed into it but not submitted is lost.');
+        }
+        catch (error) {
+            if (isReadTimeout(error)) {
+                this.closed = true;
+                this.provider.invalidateOwner(this.owner);
+                let page;
+                try {
+                    page = this.currentPageSync();
+                }
+                catch {
+                    page = undefined;
+                }
+                if (page !== undefined)
+                    await this.discardStuckPage(page);
+            }
+            throw error;
+        }
     }
     async evaluate(expression, signal) {
         // The switch is enforced HERE, not only in the tool layer: browser_evaluate
@@ -639,14 +670,26 @@ export class PlaywrightSession {
             this.provider.touch(this.owner);
             const page = await this.ensurePage();
             const fn = new Function('return (' + expression + ')');
+            // page.evaluate takes no timeout: an expression with an infinite loop (a
+            // shader compile, a spin on a mutex) never returns and the tool call hangs
+            // forever. Bound it with the same budget the snapshot read uses, and on
+            // timeout drop this handle + the stuck page so the next call starts clean
+            // instead of inheriting a page that will never answer.
+            const once = async () => (await withDeadline(withAbort(page.evaluate(fn), signal), this.timeoutMs(), 'evaluating page JavaScript', undefined, 'reject', 'That page has been closed; anything typed into it but not submitted is lost, and the expression may have left the page unresponsive.'));
             try {
-                return await withAbort(page.evaluate(fn), signal);
+                return await once();
             }
             catch (error) {
+                if (isReadTimeout(error)) {
+                    this.closed = true;
+                    this.provider.invalidateOwner(this.owner);
+                    await this.discardStuckPage(page);
+                    throw error;
+                }
                 if (!isContextDestroyed(error) || signal?.aborted === true)
                     throw error;
                 await this.settleNavigation(page);
-                return withAbort(page.evaluate(fn), signal);
+                return once();
             }
         });
     }
@@ -688,13 +731,16 @@ export class PlaywrightSession {
                 // inside the driver, and the failure gets reported as a protocol error.
                 const session = this.cdpSession;
                 const send = session.send.bind(session);
-                return await withAbort(send(method, params ?? {}), signal);
+                // A CDP command has no timeout of its own either, and some of them
+                // (screenshots, layout dumps) run page script internally. Same budget as
+                // a page read; the CDP session itself stays usable, only this call dies.
+                return await withDeadline(withAbort(send(method, params ?? {}), signal), this.timeoutMs(), 'running CDP command ' + method, undefined, 'reject', 'The command was abandoned; the page may still be working on it. Take a fresh snapshot to see where it landed.');
             }
             catch (error) {
-                if (isAbortError(error))
+                // A deadline and a cancel both mean what they say: never relabel them as
+                // a protocol failure (the wrapping below only owns real CDP errors).
+                if (isAbortError(error) || isReadTimeout(error))
                     throw error;
-                // CDP protocol errors are already structured ("Protocol error
-                // (DOM.foo): ..."); wrap non-abort failures in a stable code.
                 const detail = error instanceof Error ? error.message : String(error);
                 if (/Protocol error/.test(detail)) {
                     const m = /\(([^)]+)\): ([\s\S]+)/.exec(detail);

package/lib/snapshot-aria.d.ts

@@ -48,26 +48,6 @@ export interface AriaParseResult {
     /** Content lines that could not be parsed — non-empty means format drift. */
     readonly unparsed: string[];
 }
-/**
- * Parse Playwright's official ariaSnapshot YAML into a semantic node tree.
- *
- * The real format (verified against playwright-core 1.62, 2026-09-30) is:
- *
- *   - generic [active] [ref=e1]:          ← trailing ':' = the node has children
- *     - link "One" [ref=e6] [cursor=pointer]:
- *       - /url: /one                       ← href rides a deeper child line
- *     - text: Name                         ← text content uses 'text: <value>'
- *
- * The first version of this parser assumed a hand-rolled dialect
- * (`- role "name" [flags] -> href`, nothing after the flags) that real output
- * never produces. Every container line ends in ':', so that regex matched none
- * of them: the whole hierarchy was dropped, links and their hrefs vanished, and
- * `captureAriaSnapshot` still reported success. Unreadable lines are now
- * collected in `unparsed` so the capture layer can refuse the tree and let the
- * provider fall back to the legacy engine.
- * @param yaml - the ariaSnapshot text.
- * @returns parsed roots plus any unreadable content lines.
- */
 export declare function parseAriaSnapshotWithStats(yaml: string): AriaParseResult;
 /**
  * Parse Playwright's ariaSnapshot YAML into a semantic node tree.

package/lib/snapshot-aria.js

@@ -54,12 +54,19 @@ export const ARIA_REF_SCRIPT = String.raw `
   window.__dshAriaRefsV = 2
   const INTERACTIVE = new Set(['button','link','checkbox','radio','menuitem','menuitemcheckbox','menuitemradio','tab','switch','combobox','listbox','option','textbox','searchbox','slider','spinbutton','row','gridcell'])
   const TAGS = new Set(['a','button','select','textarea','option','summary'])
-  const INPUT_ROLE = { checkbox:'checkbox', radio:'radio', button:'button', submit:'button', reset:'button', image:'button', range:'slider', search:'searchbox', hidden:'null' }
+  const INPUT_ROLE = { checkbox:'checkbox', radio:'radio', button:'button', submit:'button', reset:'button', image:'button', range:'slider', number:'spinbutton', search:'searchbox', hidden:'null' }
   const DOC_NONCE = String(Math.floor(Math.random() * 1e9)).padStart(9, '0')
   let refSeq = 0
   const roleOf = (el) => {
     const explicit = el.getAttribute && el.getAttribute('role')
-    if (explicit && explicit.trim()) return explicit.trim().toLowerCase()
+    const explicitRole = explicit && explicit.trim() ? explicit.trim().toLowerCase() : ''
+    // aria: an explicit role="presentation"/"none" is IGNORED on a focusable
+    // element — the tree still exposes its native role. jQuery-UI tabs do exactly
+    // this: <a href="#tabs-1" role="presentation"> shows up as a link in the aria
+    // tree (measured 2026-11-12 on MiniWoB click-tab).
+    const presentational = explicitRole === 'presentation' || explicitRole === 'none'
+    const focusableLink = el.tagName.toLowerCase() === 'a' && el.hasAttribute('href')
+    if (explicitRole !== '' && !(presentational && focusableLink)) return explicitRole
     const tag = el.tagName.toLowerCase()
     if (tag === 'input') return INPUT_ROLE[(el.getAttribute('type') || 'text').toLowerCase()] || 'textbox'
     if (tag === 'a') return 'link'
@@ -68,10 +75,34 @@ export const ARIA_REF_SCRIPT = String.raw `
     if (tag === 'textarea') return 'textarea'
     if (tag === 'option') return 'option'
     if (tag === 'summary') return 'summary'
+    // Implicit roles for the elements the accessibility tree annotates anyway.
+    // Without these the DOM side said "generic" for a <tr> while the tree said
+    // "row" (an actionable role), so the minted ref list and the tree disagreed
+    // and the whole page fell back (measured 2026-11-12: 6 of the 18 fallback
+    // MiniWoB pages were table/row tasks).
+    if (tag === 'tr') return 'row'
+    if (tag === 'td') return 'cell'
+    if (tag === 'th') return 'columnheader'
+    if (tag === 'li') return 'listitem'
+    if (tag === 'table') return 'table'
+    if (tag === 'ul' || tag === 'ol') return 'list'
+    if (tag === 'p') return 'paragraph'
+    if (tag === 'h1' || tag === 'h2' || tag === 'h3' || tag === 'h4' || tag === 'h5' || tag === 'h6') return 'heading'
+    if (tag === 'img') return 'img'
     return 'generic'
   }
   const isActionable = (el) => {
     if (!(el instanceof Element)) return false
+    // An explicit role of presentation / none tells the accessibility tree to drop
+    // the element's own semantics — EXCEPT on a focusable link, where the spec says
+    // the role is ignored (see roleOf). Skipping those here would mint one ref too
+    // few and put the lists out of step (measured 2026-11-12: the MiniWoB tab strips
+    // wrap each tab in <a href role="presentation">; 4 pages fell back).
+    const explicit = el.getAttribute('role')
+    const explicitRole = explicit && explicit.trim() ? explicit.trim().toLowerCase() : ''
+    const presentational = explicitRole === 'presentation' || explicitRole === 'none'
+    const focusableLink = el.tagName.toLowerCase() === 'a' && el.hasAttribute('href')
+    if (presentational && !focusableLink) return false
     const tag = el.tagName.toLowerCase()
     if (TAGS.has(tag)) return true
     const role = roleOf(el)
@@ -89,6 +120,17 @@ export const ARIA_REF_SCRIPT = String.raw `
       if (el.getAttribute('hidden') !== null || el.getAttribute('aria-hidden') === 'true') return false
       const style = getComputedStyle(el)
       if (style.display === 'none' || style.visibility === 'hidden') return false
+      // <option> has no layout box of its own inside a closed <select>, yet the
+      // accessibility tree lists it — so it must keep its slot here, or the two
+      // lists drift (measured 2026-11-12: choose-list minted 2 refs while the tree
+      // had 7 actionable nodes). Its <select> is the visibility signal: options of
+      // a display:none select are absent from the tree too.
+      if (el.tagName.toLowerCase() === 'option') {
+        const select = el.closest('select')
+        if (select === null) return false
+        const selectStyle = getComputedStyle(select)
+        return selectStyle.display !== 'none' && selectStyle.visibility !== 'hidden'
+      }
       // A 'display: contents' box has no rect of its own but lays its children
       // out normally — it belongs to the tree, so it keeps its slot.
       if (style.display === 'contents') return true
@@ -177,6 +219,29 @@ function readQuoted(text) {
  * @param yaml - the ariaSnapshot text.
  * @returns parsed roots plus any unreadable content lines.
  */
+/**
+ * Playwright quotes a whole node line when the name itself contains a double quote:
+ *   - 'tab "Section #1" [ref=e5]'
+ *   - 'link "Tab #1" [ref=e7] [cursor=pointer]':
+ * Strip the outer single quotes (and the optional trailing ':' that marks children),
+ * then parse the inner text like any other line. Measured 2026-11-12: 8 of 130
+ * MiniWoB pages fell back to the legacy engine purely over this shape (tab strips,
+ * collapsible sections), while the pages themselves read perfectly.
+ */
+function unwrapQuotedNodeBody(body) {
+    if (body.length < 3 || body[0] !== "'")
+        return body;
+    const close = body.lastIndexOf("'");
+    if (close <= 0)
+        return body;
+    const inside = body.slice(1, close);
+    const after = body.slice(close + 1).trim();
+    // Anything else after the closing quote is not the shape we know; leave it to
+    // the normal path so an unknown line is reported rather than silently accepted.
+    if (after !== '' && after !== ':')
+        return body;
+    return inside;
+}
 export function parseAriaSnapshotWithStats(yaml) {
     const roots = [];
     const stack = [];
@@ -206,7 +271,7 @@ export function parseAriaSnapshotWithStats(yaml) {
             continue;
         }
         const indent = Math.floor((m[1] ?? '').length / 2);
-        const body = m[2] ?? '';
+        const body = unwrapQuotedNodeBody(m[2] ?? '');
         // Attribute child lines describe the node declared above: '- /url: /one',
         // '- /placeholder: Search'. Playwright adds facts over time, and an attribute
         // line carries no tree structure — so an unknown one is safe to ignore.

package/lib/snapshot-render.js

@@ -42,6 +42,21 @@ const TRACKING_PARAMS = new Set([
 ]);
 /** Default cap for a rendered href, in characters. */
 export const MAX_HREF_LENGTH = 160;
+/**
+ * Path shapes that mark a redirect-wrapping URL — a link that does not point at
+ * its destination but at the site's own click-tracking endpoint, which forwards
+ * there. Search engines wrap every organic result this way (Bing `/ck/a?...`,
+ * Google `/url?q=...`, Facebook `l.php?u=...`). The real destination is encoded
+ * in a long query parameter, so the rendered href is 160 characters of base64
+ * that says nothing the link's own name does not — and it repeats for every
+ * result on the page.
+ *
+ * This is a generic category (a tracking endpoint on the same origin as the
+ * page), not a per-site special case. When one matches we render a short marker
+ * instead of the wrapped URL: the ref is what clicks, and the link's name plus
+ * any destination node already carry the meaning.
+ */
+const REDIRECT_WRAPPERS = [/\/ck\/a\?/i, /\/url\?q=/i, /l\.php\?u=/i];
 /** Clip a string to a display budget, marking the cut. */
 function clip(value, maxLength) {
     return value.length <= maxLength ? value : value.slice(0, maxLength - 1) + '…';
@@ -56,6 +71,13 @@ function clip(value, maxLength) {
  * @returns the shortened href
  */
 export function trimUrlForDisplay(href, maxLength = MAX_HREF_LENGTH) {
+    // A redirect-wrapping href (search-engine click tracker) is 160 characters of
+    // encoded destination that says nothing the link's name does not. Render a
+    // short marker instead; the ref is what clicks, so this never changes where a
+    // click lands — only what the model reads.
+    if (REDIRECT_WRAPPERS.some((re) => re.test(href))) {
+        return '→ (redirect wrapper)';
+    }
     const hashAt = href.indexOf('#');
     const hash = hashAt >= 0 ? href.slice(hashAt) : '';
     const head = hashAt >= 0 ? href.slice(0, hashAt) : href;
@@ -94,13 +116,14 @@ function isTransparentWrapper(node) {
         node.level === undefined &&
         node.checked === undefined &&
         node.selected === undefined &&
-        node.disabled === undefined);
+        node.disabled === undefined &&
+        node.value === undefined);
 }
 /** Render one node line into the accumulating line list. */
-function renderNode(node, depth, lines) {
+function renderNode(node, depth, lines, seenHrefs) {
     if (isTransparentWrapper(node)) {
         for (const child of node.children)
-            renderNode(child, depth, lines);
+            renderNode(child, depth, lines, seenHrefs);
         return;
     }
     const indent = '  '.repeat(depth);
@@ -116,15 +139,33 @@ function renderNode(node, depth, lines) {
         flags.push('selected');
     if (node.disabled === true)
         flags.push('disabled');
+    // The current value of a text entry field: without it the model cannot see
+    // what a fill actually left behind, which read as "no visible change".
+    if (node.value !== undefined && node.value !== '')
+        flags.push('value=' + node.value);
     if (node.ref !== undefined)
         flags.push('ref=' + node.ref);
     if (flags.length > 0)
         line += ' [' + flags.join(', ') + ']';
-    if (node.href !== undefined)
-        line += ' -> ' + trimUrlForDisplay(node.href);
+    if (node.href !== undefined) {
+        // Same href, second and later occurrence within ONE snapshot: the URL is
+        // already printed at its first occurrence, so repeat only a pointer to it.
+        // Every ref and element stays — this trims bytes, never click targets. Only
+        // absolute URLs are deduped (a bare "/docs" can name different pages).
+        const abs = /^https?:\/\//i.test(node.href);
+        const firstRef = abs ? seenHrefs.get(node.href) : undefined;
+        if (firstRef !== undefined && firstRef !== node.ref) {
+            line += ' -> (same as ' + firstRef + ')';
+        }
+        else {
+            line += ' -> ' + trimUrlForDisplay(node.href);
+            if (abs && node.ref !== undefined)
+                seenHrefs.set(node.href, node.ref);
+        }
+    }
     lines.push(line);
     for (const child of node.children)
-        renderNode(child, depth + 1, lines);
+        renderNode(child, depth + 1, lines, seenHrefs);
 }
 /**
  * Render a node tree as indented lines, one element per line.
@@ -133,8 +174,12 @@ function renderNode(node, depth, lines) {
  */
 export function renderSnapshotTree(nodes) {
     const lines = [];
+    // href -> ref of its first occurrence in THIS snapshot. Same href second and
+    // later renders as "(same as <ref>)" instead of repeating the URL. Scoped to
+    // one snapshot on purpose: a fresh snapshot after navigation re-prints URLs.
+    const seenHrefs = new Map();
     for (const node of nodes)
-        renderNode(node, 0, lines);
+        renderNode(node, 0, lines, seenHrefs);
     return lines.join('\n');
 }
 /**

package/lib/swarm-contract.d.ts

@@ -27,9 +27,11 @@
  * `assets/swarm-rebuild.upstream.js` 里逐条核对下面的每个名字是否真的存在 —— 上游换人、
  * 改名、删节点，这里第一个报错，而不是等某天浏览器里莫名其妙不播了。
  *
- * 法律面（别绕过它）：上游仓库根目录**没有 LICENSE**（默认保留所有权利），
- * issue #12 至今零回复。所以这段资产**不能 fork 成"我们自己的版本"** —— fork 不改变授权，
- * 只多出一份照样没有许可的副本。它只能留在本机自用、默认关闭、不随包分发。
+ * 法律面（0.8.1 起）：上游仓库根目录**仍然没有 LICENSE**（默认保留所有权利），
+ * 但 Dhvanil Patel 于 2026-11-11 邮件书面许可本项目**打包与修改**，Joel Califa 于
+ * 2026-11-08 书面许可并仅要求署名。所以资产可以随包分发，**但授权不是 MIT**：
+ * 它是邮件许可，只覆盖本项目，不给第三方通用许可。别把这份资产 fork 成
+ * "我们自己的版本" —— fork 不改变任何人拿到的权利，只会多出一份没有许可的副本。
  */
 /** 上游出处与入仓指纹。这三项之外的任何东西，都不该成为插件的依赖。 */
 export declare const SWARM_UPSTREAM: {
@@ -45,8 +47,12 @@ export declare const SWARM_UPSTREAM: {
     readonly sha256: "6a30f19daaa182d52673035feaeae775c398fa426655cc71a87a451fe00c7bfe";
     /** 补丁后的产出（**随包分发的那份**）。 */
     readonly patchedFile: "assets/swarm-rebuild.js";
-    /** 授权状态：`none` = 无许可证，默认保留所有权利。不是"宽松许可"。 */
-    readonly license: "none";
+    /**
+     * 授权状态：`none` = 仓库没有许可证；`permission` = 无许可证文本，但有作者的书面
+     * 邮件许可（本项目：Dhvanil 2026-11-11 打包 + 修改；Joel 2026-11-08 效果 + 署名）。
+     * 它不是"宽松许可"，第三方不能据此复用。
+     */
+    readonly license: "permission";
 };
 /**
  * Tier A —— 硬接口。上游官方句柄树，补丁完全没碰，插件主路径全走这里。

package/lib/swarm-contract.js

@@ -27,9 +27,11 @@
  * `assets/swarm-rebuild.upstream.js` 里逐条核对下面的每个名字是否真的存在 —— 上游换人、
  * 改名、删节点，这里第一个报错，而不是等某天浏览器里莫名其妙不播了。
  *
- * 法律面（别绕过它）：上游仓库根目录**没有 LICENSE**（默认保留所有权利），
- * issue #12 至今零回复。所以这段资产**不能 fork 成"我们自己的版本"** —— fork 不改变授权，
- * 只多出一份照样没有许可的副本。它只能留在本机自用、默认关闭、不随包分发。
+ * 法律面（0.8.1 起）：上游仓库根目录**仍然没有 LICENSE**（默认保留所有权利），
+ * 但 Dhvanil Patel 于 2026-11-11 邮件书面许可本项目**打包与修改**，Joel Califa 于
+ * 2026-11-08 书面许可并仅要求署名。所以资产可以随包分发，**但授权不是 MIT**：
+ * 它是邮件许可，只覆盖本项目，不给第三方通用许可。别把这份资产 fork 成
+ * "我们自己的版本" —— fork 不改变任何人拿到的权利，只会多出一份没有许可的副本。
  */
 /** 上游出处与入仓指纹。这三项之外的任何东西，都不该成为插件的依赖。 */
 export const SWARM_UPSTREAM = {
@@ -45,8 +47,12 @@ export const SWARM_UPSTREAM = {
     sha256: '6a30f19daaa182d52673035feaeae775c398fa426655cc71a87a451fe00c7bfe',
     /** 补丁后的产出（**随包分发的那份**）。 */
     patchedFile: 'assets/swarm-rebuild.js',
-    /** 授权状态：`none` = 无许可证，默认保留所有权利。不是"宽松许可"。 */
-    license: 'none',
+    /**
+     * 授权状态：`none` = 仓库没有许可证；`permission` = 无许可证文本，但有作者的书面
+     * 邮件许可（本项目：Dhvanil 2026-11-11 打包 + 修改；Joel 2026-11-08 效果 + 署名）。
+     * 它不是"宽松许可"，第三方不能据此复用。
+     */
+    license: 'permission',
 };
 /**
  * Tier A —— 硬接口。上游官方句柄树，补丁完全没碰，插件主路径全走这里。

package/lib/swarm-curtain.js

@@ -36,11 +36,11 @@ export function swarmBootScript() {
         asset = fs.readFileSync(fileURLToPath(new URL('../assets/swarm-rebuild.js', import.meta.url)), 'utf8');
     }
     catch {
-        // 资产不在（0.8.0 起 assets/ 不再随 npm 包分发）。这里**绝不能往外抛**：
+        // 资产读不到（0.8.1 起随包分发，理论上不会发生；手工删包时会）。这里**绝不能往外抛**：
         // 两个调用点都是 `await ctx.addInitScript({ content: swarmBootScript() })`，
         // 抛出去就是上下文创建失败、浏览器直接打不开 —— 把"动效没了"放大成"插件挂了"。
         // 返回一段空注释脚本，等于这次启动不注入任何东西，行为与"没开这个功能"一致。
-        return '/* dsh: swarm asset not shipped (0.8.0+) — nothing injected */\n';
+        return '/* dsh: swarm asset missing — nothing injected */\n';
     }
     return ('if (window.top === window && typeof window.name === "string" &&\n' +
         '    window.name.indexOf("' +

package/lib/swarm-intro.js

@@ -4,11 +4,13 @@
  * 这不是扩展。效果本体是 assets/swarm-rebuild.js，由 Playwright 直接注入当前
  * 页面执行，所以它跑在插件自己那个窗口里 —— 也就是用户已经登录的那个浏览器。
  *
- * **授权状态（发布前必须处理）**：那份脚本来自 Dhvanil Patel 的
- * github.com/DhvanilPatel/swarm-cursors，仓库当前**没有许可证**，README 明确
- * 写着「尚未授权，重用代码前请先问 Joel Califa」。底层的动效设计与编排又来自
- * Joel Califa 的 califa/swarm-site（同样没有许可证）。两人都点头之前，这个
- * 功能只能自己用，不能随公开版本分发。
+ * **授权状态（0.8.1 起已解决）**：那份脚本来自 Dhvanil Patel 的
+ * github.com/DhvanilPatel/swarm-cursors。2026-11-11 他邮件书面许可本项目
+ * **打包与修改**（"you are welcome to bundle and modify it as needed"），
+ * 所以资产重新随 npm 包分发；许可没有附 MIT 许可文本，也只覆盖本项目，
+ * 不给第三方通用许可。底层的动效设计与编排来自 Joel Califa 的
+ * califa/swarm-site，他 2026-11-08 已书面许可、唯一条件是署名。
+ * 功能仍然**默认关闭**（config.swarm.enabled），打开才播。
  *
  * 三个约束决定了这里的实现方式：
  *
@@ -727,7 +729,7 @@ export async function showWelcome(page, config) {
         return; // 页面还没准备好：留一张空白页也不影响任何事
     }
     const userChoice = runtimeState.getSwarm();
-    const enabled = userChoice ?? config?.swarm?.enabled ?? true;
+    const enabled = userChoice ?? config?.swarm?.enabled ?? false;
     if (!enabled)
         return;
     const tuning = runtimeState.getSwarmTuning();
@@ -754,7 +756,7 @@ export function willPlaySwarm(targetUrl, config, headless) {
         if (host === '')
             return false;
         const userChoice = runtimeState.getSwarm();
-        const enabled = userChoice ?? config?.swarm?.enabled ?? true;
+        const enabled = userChoice ?? config?.swarm?.enabled ?? false;
         if (!enabled)
             return false;
         const tuning = runtimeState.getSwarmTuning();
@@ -781,9 +783,9 @@ export function maybePlaySwarm(page, config, headless) {
             const host = new URL(url).hostname;
             if (host === '')
                 return;
-            // 用户的开关优先；没表态就用配置里的默认值（出厂是开）。
+            // 用户的开关优先；没表态就用配置里的默认值（出厂是关，与 config.ts 的 schema 一致）。
             const userChoice = runtimeState.getSwarm();
-            const enabled = userChoice ?? config?.swarm?.enabled ?? true;
+            const enabled = userChoice ?? config?.swarm?.enabled ?? false;
             if (!enabled) {
                 // 关着也要把可能已提前启动的引擎撤掉：标记可能是上一次导航残留的，
                 // 不清就会白屏卡住（2026-11-09 复核 find B）。

package/lib/tool-types.d.ts

@@ -46,6 +46,16 @@ export interface ChallengeNode {
     readonly name?: string;
     /** Accessible role. Both built-in engines provide one; it gates the wording tier. */
     readonly role?: string;
+    /** Whether a checkbox/radio is checked; present on toggles. */
+    readonly checked?: boolean;
+    /** Whether an option is selected; present on options. */
+    readonly selected?: boolean;
+    /**
+     * Current value of a textbox/textarea/select. The no-progress fingerprint
+     * includes it so that filling a field registers as change — otherwise a
+     * normal fill looks like "no visible change" and trips the anti-bot guess.
+     */
+    readonly value?: string;
     readonly children?: readonly ChallengeNode[];
 }
 /** The slice of a snapshot the challenge detector reads. */

package/lib/tool.js

@@ -1,7 +1,7 @@
 import z from '@deepseek-ai/schemastery';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { BlockAssembler, createUserMessage } from '@deepseek-ai/dsh-llm';
-import { BrowserError, cdpDisabled, evaluateDisabled } from "./errors.js";
+import { BrowserError, cdpDisabled, evaluateDisabled, normalizeEvaluateResult } from "./errors.js";
 import { registeredSuffixes } from "./contract.js";
 import { getEnabled, publishGates, publishLoginSites } from "./runtime-state.js";
 import { summarizeLoginSites } from "./login-sites.js";
@@ -563,6 +563,9 @@ export function apply(ctx, config) {
     registerMaybe('evaluate', defineTool({
         name: p('evaluate'),
         description: 'Evaluate one JavaScript expression in the page and return its JSON-serializable result. ' +
+            'Return value rules: an object, string, number, boolean or null comes back as-is; ' +
+            'a top-level ARRAY, undefined or a function is returned as a JSON string with a note saying it was converted ' +
+            '(wrap it yourself, e.g. {items: [...]} , if you need the array shape). ' +
             'Disabled by default; the deployment must enable allowEvaluate. ' +
             'IRON RULE: prefer read-only expressions to INSPECT state (value, outerHTML, checked, textContent) before ' +
             'concluding an interaction failed. If you write to the DOM directly (setting value/textContent), ' +
@@ -590,7 +593,8 @@ export function apply(ctx, config) {
                 throw evaluateDisabled();
             }
             const session = await acquire(exec);
-            return (await session.evaluate(args.expression, exec.signal));
+            const raw = await session.evaluate(args.expression, exec.signal);
+            return normalizeEvaluateResult(raw);
         },
     }));
     registerMaybe('cdp', defineTool({

package/lib/types.d.ts

@@ -21,6 +21,12 @@ export interface BrowserNode {
     readonly selected?: boolean;
     /** Whether the element is disabled. */
     readonly disabled?: boolean;
+    /**
+     * Current value of a textbox, textarea or select, clipped to the snapshot's
+     * text budget. Present so the model can see what a fill actually left behind
+     * and so the no-progress fingerprint registers a value change as change.
+     */
+    readonly value?: string;
     /** Href for links; present when the page is same-origin. */
     readonly href?: string;
     readonly children: readonly BrowserNode[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-browser-playwright-codex",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "Browser automation for DeepSeek Harness, one plugin: fill in forms, scrape lists and work across tabs in real pages, using the logins you already have. Runs in a visible window that stays quiet when minimised; native dialogs are parked instead of confirmed, CAPTCHA pages are flagged with a note that says stop and hand the page back, password / one-time-code / card fields are refused by browser_fill, and the Settings card (enable/disable, page-reading mode, capability gates) now lives inside this package.",
   "license": "MIT",
   "type": "module",
@@ -44,6 +44,8 @@
     "CHANGELOG.md",
     "SECURITY.md",
     "NOTICE.md",
+    "assets",
+    "!assets/swarm-rebuild.upstream.js",
     "locale",
     "scripts/doctor.mjs",
     "scripts/dsh-browser-verify.mjs"
@@ -63,26 +65,29 @@
     "format": "node node_modules/prettier/bin/prettier.cjs --write \"src/**/*.ts\" \"tests/**/*.ts\" \"scripts/**/*.mjs\"",
     "format:check": "node node_modules/prettier/bin/prettier.cjs --check \"src/**/*.ts\" \"tests/**/*.ts\" \"scripts/**/*.mjs\"",
     "prepublishOnly": "npm run build && npm run typecheck && npm test && npm run swarm:check && npm run verify && npm run preflight",
-    "preflight": "node scripts/preflight.mjs ."
+    "preflight": "node scripts/preflight.mjs .",
+    "test:toggle": "node --test tests/cross-repo/*.test.ts",
+    "coverage": "node scripts/coverage.mjs"
   },
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.4",
     "playwright-core": "~1.62.1"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": ">=4.0.4",
-    "@deepseek-ai/dsh-llm": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-tools": ">=0.2.0-rc.1"
+    "@deepseek-ai/cordis": ">=4.1.0",
+    "@deepseek-ai/dsh-llm": ">=0.2.2-rc.1",
+    "@deepseek-ai/dsh-tools": ">=0.2.2-rc.1"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "4.0.4",
-    "@deepseek-ai/dsh-agent": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-attachment": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-llm": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-session": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-system-prompt": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-tools": "0.2.0-rc.1",
-    "@deepseek-ai/schemastery": "3.18.4",
+    "@deepseek-ai/cordis": "4.1.0",
+    "@deepseek-ai/dsh-agent": "0.2.2-rc.1",
+    "@deepseek-ai/dsh-attachment": "0.2.2-rc.1",
+    "@deepseek-ai/dsh-llm": "0.2.2-rc.1",
+    "@deepseek-ai/dsh-session": "0.2.2-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "0.2.2-rc.1",
+    "@deepseek-ai/dsh-tools": "0.2.2-rc.1",
+    "@deepseek-ai/dsh-tool-executor-native": "0.2.2-rc.1",
+    "@deepseek-ai/schemastery": "3.19.0",
     "@types/node": "^24.13.3",
     "prettier": "^3.9.9",
     "tsx": "^4.20.0",