@angelky7/dsh-browser-control 1.3.0 → 1.4.0

package/README.en.md

@@ -64,8 +64,8 @@ In one line: **for "use MY browser" tasks (logged-in Bilibili, Zhihu, admin pane
 
 | File | Purpose |
 |---|---|
-| [DSH-Browser-Control-v1.3.0.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.3.0/DSH-Browser-Control-v1.3.0.zip) | Chrome extension (unzip and load; extension code is unchanged since 1.2.0 — no reinstall needed) |
-| [dsh-browser-control-plugin-v1.3.0.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.3.0/dsh-browser-control-plugin-v1.3.0.zip) | dsh plugin (offline fallback; online installs use Option A/B) |
+| [DSH-Browser-Control-v1.4.0.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.4.0/DSH-Browser-Control-v1.4.0.zip) | Chrome extension (unzip and load; navigation waiting is now event-driven — reinstall required) |
+| [dsh-browser-control-plugin-v1.4.0.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.4.0/dsh-browser-control-plugin-v1.4.0.zip) | dsh plugin (offline fallback; online installs use Option A/B) |
 
 ## Install the Chrome extension (30 seconds)
 
@@ -104,7 +104,7 @@ npm install @angelky7/dsh-browser-control
 
 ```bash
 # Straight from GitHub
-dsh plugin --profile web add "github:angelky7/dsh-browser-control#v1.3.0"
+dsh plugin --profile web add "github:angelky7/dsh-browser-control#v1.4.0"
 
 # Local checkout for debugging (note: the explicit file: prefix is required)
 dsh plugin --profile web add "file:D:\path\to\dsh-browser-control"

package/README.md

@@ -64,8 +64,8 @@ Chrome 扩展（CDP 驱动）
 
 | 文件 | 说明 |
 |---|---|
-| [DSH-Browser-Control-v1.3.0.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.3.0/DSH-Browser-Control-v1.3.0.zip) | Chrome 扩展（解压后加载；与 1.2.0 相比扩展代码无改动，已装 1.2.0 不必重装） |
-| [dsh-browser-control-plugin-v1.3.0.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.3.0/dsh-browser-control-plugin-v1.3.0.zip) | dsh 插件（离线兜底，在线装直接用方式 A/B） |
+| [DSH-Browser-Control-v1.4.0.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.4.0/DSH-Browser-Control-v1.4.0.zip) | Chrome 扩展（解压后加载；这一版扩展的导航等待换成事件驱动，**必须重装**） |
+| [dsh-browser-control-plugin-v1.4.0.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.4.0/dsh-browser-control-plugin-v1.4.0.zip) | dsh 插件（离线兜底，在线装直接用方式 A/B） |
 
 ## 安装 Chrome 扩展（30 秒）
 
@@ -104,7 +104,7 @@ npm install @angelky7/dsh-browser-control
 
 ```bash
 # 直接从 GitHub 安装
-dsh plugin --profile web add "github:angelky7/dsh-browser-control#v1.3.0"
+dsh plugin --profile web add "github:angelky7/dsh-browser-control#v1.4.0"
 
 # 本地目录调试（注意：必须显式 file: 前缀）
 dsh plugin --profile web add "file:D:\path\to\dsh-browser-control"

package/lib/index.js

@@ -942,6 +942,18 @@ function policyRefusal(command, flags, params) {
 /** Navigation wait ceiling (same as browser_wait); the bridge gets this plus BRIDGE_MARGIN_MS. */
 const NAV_MAX_MS = 12e4;
 /**
+* Same tier table as the extension's NAV_TIERS (extension/background.js). Both
+* literals must stay in lockstep — verify_nav_waituntil.mjs extracts the
+* extension's by regex and asserts the two agree (cross-side literals are wire
+* protocol: a value only one side knows is a lie on the other).
+*/
+const NAV_TIERS = {
+	none: 0,
+	commit: 4e3,
+	domcontentloaded: 4e3,
+	load: 15e3
+};
+/**
 * Extra time handed to the bridge on top of the navigation budget. Without it a
 * caller-requested budget longer than the bridge default (60s) would be beaten by
 * the bridge, and the model would get `command_timeout` (effect unknown) instead
@@ -1246,9 +1258,13 @@ function applyBrowserTools(ctx, controller) {
 				type: "number",
 				description: "Target tab; defaults to the active tab."
 			},
+			waitUntil: {
+				type: "string",
+				description: "When the navigation counts as arrived: \"load\" (default) waits for the page load event (15s budget), \"domcontentloaded\" returns once the DOM is parsed (async components may still be mounting — follow with browser_wait if an element is missing), \"commit\" once the new document's address lands, \"none\" returns immediately with no arrival check at all."
+			},
 			timeoutMs: {
 				type: "number",
-				description: `How long to wait for the page load to settle: defaults to 15000, capped at ${NAV_MAX_MS}. Raise it for slow pages instead of retrying; drop it to 3000-5000 when you do not need the page to finish loading and will read/wait afterwards.`
+				description: `How long to wait for the page load to settle: defaults to the waitUntil tier (load 15000, commit/domcontentloaded 4000), capped at ${NAV_MAX_MS}. An explicit value always wins over the tier.`
 			}
 		},
 		output: {
@@ -1264,7 +1280,10 @@ function applyBrowserTools(ctx, controller) {
 					title: { type: "string" },
 					pendingUrl: { type: "string" },
 					loadPending: { type: "boolean" },
-					siteUnreachable: { type: "boolean" }
+					siteUnreachable: { type: "boolean" },
+					waitUntil: { type: "string" },
+					waitedMs: { type: "number" },
+					readyState: { type: "string" }
 				}
 			},
 			render: (_args, value) => {
@@ -1298,17 +1317,26 @@ function applyBrowserTools(ctx, controller) {
 			kind: "other"
 		}),
 		async execute(args, exec) {
-			const params = { url: args.url };
+			const waitUntil = args.waitUntil === void 0 ? "load" : String(args.waitUntil);
+			if (!(waitUntil in NAV_TIERS)) throw new Error(`browser_navigate: waitUntil must be one of none, commit, domcontentloaded, load — got "${waitUntil}"`);
+			const params = {
+				url: args.url,
+				waitUntil
+			};
 			if (args.tabId !== void 0) params.tabId = args.tabId;
-			const budgetMs = typeof args.timeoutMs === "number" && Number.isFinite(args.timeoutMs) ? Math.min(NAV_MAX_MS, Math.max(100, Math.trunc(args.timeoutMs))) : 15e3;
-			params.timeoutMs = budgetMs;
-			const raw = await controller.execute("nav", params, exec.signal, budgetMs + BRIDGE_MARGIN_MS);
+			let budgetMs = NAV_TIERS[waitUntil];
+			if (typeof args.timeoutMs === "number" && Number.isFinite(args.timeoutMs)) budgetMs = Math.min(NAV_MAX_MS, Math.max(100, Math.trunc(args.timeoutMs)));
+			if (waitUntil !== "none") params.timeoutMs = budgetMs;
+			const raw = await controller.execute("nav", params, exec.signal, waitUntil === "none" ? void 0 : budgetMs + BRIDGE_MARGIN_MS);
 			const out = { tabId: raw.tabId };
 			if (typeof raw.url === "string") out.url = raw.url;
 			if (typeof raw.title === "string") out.title = raw.title;
 			if (typeof raw.pendingUrl === "string") out.pendingUrl = raw.pendingUrl;
 			if (raw.loadPending === true) out.loadPending = true;
 			if (raw.siteUnreachable === true || typeof raw.siteUnreachable === "object" && raw.siteUnreachable !== null) out.siteUnreachable = true;
+			if (typeof raw.waitUntil === "string") out.waitUntil = raw.waitUntil;
+			if (typeof raw.waitedMs === "number") out.waitedMs = raw.waitedMs;
+			if (typeof raw.readyState === "string" && raw.readyState.length > 0) out.readyState = raw.readyState;
 			return out;
 		}
 	}));
@@ -2011,6 +2039,14 @@ function applyBrowserTools(ctx, controller) {
 				type: "boolean",
 				description: "For open: put the new tab in the DSH tab group. Defaults to true; pass false to keep it loose."
 			},
+			waitUntil: {
+				type: "string",
+				description: "For open: when the new tab counts as arrived — same tiers as browser_navigate (load default / domcontentloaded / commit / none)."
+			},
+			timeoutMs: {
+				type: "number",
+				description: "For open: wait budget, overriding the waitUntil tier (load 15000, commit/domcontentloaded 4000)."
+			},
 			windowId: {
 				type: "number",
 				description: "For ungroup: only dissolve that window’s DSH group; omit to clear every window."
@@ -2036,10 +2072,19 @@ function applyBrowserTools(ctx, controller) {
 				case "list": return await controller.execute("tabs.list", {}, exec.signal);
 				case "open": {
 					if (typeof args.url !== "string" || args.url.length === 0) throw new Error("open requires url");
-					const params = { url: args.url };
+					const waitUntil = args.waitUntil === void 0 ? "load" : String(args.waitUntil);
+					if (!(waitUntil in NAV_TIERS)) throw new Error(`browser_tabs open: waitUntil must be one of none, commit, domcontentloaded, load — got "${waitUntil}"`);
+					const params = {
+						url: args.url,
+						waitUntil
+					};
 					if (args.active !== void 0) params.active = args.active;
 					if (args.group !== void 0) params.group = args.group;
-					return await controller.execute("tabs.open", params, exec.signal);
+					if (waitUntil === "none") return await controller.execute("tabs.open", params, exec.signal);
+					let budgetMs = NAV_TIERS[waitUntil];
+					if (typeof args.timeoutMs === "number" && Number.isFinite(args.timeoutMs)) budgetMs = Math.min(NAV_MAX_MS, Math.max(100, Math.trunc(args.timeoutMs)));
+					params.timeoutMs = budgetMs;
+					return await controller.execute("tabs.open", params, exec.signal, budgetMs + BRIDGE_MARGIN_MS);
 				}
 				case "close": {
 					const ids = closeTabIds(args);

package/lib/types/index.js

@@ -26,6 +26,13 @@ import { BridgeError, classify } from "./errors.js";
 import { policyRefusal } from "./policy.js";
 /** Navigation wait ceiling (same as browser_wait); the bridge gets this plus BRIDGE_MARGIN_MS. */
 const NAV_MAX_MS = 120_000;
+/**
+ * Same tier table as the extension's NAV_TIERS (extension/background.js). Both
+ * literals must stay in lockstep — verify_nav_waituntil.mjs extracts the
+ * extension's by regex and asserts the two agree (cross-side literals are wire
+ * protocol: a value only one side knows is a lie on the other).
+ */
+const NAV_TIERS = { none: 0, commit: 4_000, domcontentloaded: 4_000, load: 15_000 };
 /**
  * Extra time handed to the bridge on top of the navigation budget. Without it a
  * caller-requested budget longer than the bridge default (60s) would be beaten by
@@ -367,7 +374,8 @@ function applyBrowserTools(ctx, controller) {
         parameters: {
             url: { type: 'string', required: true, description: 'Absolute URL to open in the tab.' },
             tabId: { type: 'number', description: 'Target tab; defaults to the active tab.' },
-            timeoutMs: { type: 'number', description: `How long to wait for the page load to settle: defaults to 15000, capped at ${NAV_MAX_MS}. Raise it for slow pages instead of retrying; drop it to 3000-5000 when you do not need the page to finish loading and will read/wait afterwards.` },
+            waitUntil: { type: 'string', description: 'When the navigation counts as arrived: "load" (default) waits for the page load event (15s budget), "domcontentloaded" returns once the DOM is parsed (async components may still be mounting — follow with browser_wait if an element is missing), "commit" once the new document\'s address lands, "none" returns immediately with no arrival check at all.' },
+            timeoutMs: { type: 'number', description: `How long to wait for the page load to settle: defaults to the waitUntil tier (load 15000, commit/domcontentloaded 4000), capped at ${NAV_MAX_MS}. An explicit value always wins over the tier.` },
         },
         output: {
             schema: {
@@ -380,6 +388,9 @@ function applyBrowserTools(ctx, controller) {
                     pendingUrl: { type: 'string' },
                     loadPending: { type: 'boolean' },
                     siteUnreachable: { type: 'boolean' },
+                    waitUntil: { type: 'string' },
+                    waitedMs: { type: 'number' },
+                    readyState: { type: 'string' },
                 },
             },
             render: (_args, value) => {
@@ -404,14 +415,23 @@ function applyBrowserTools(ctx, controller) {
         isConcurrencySafe: () => false,
         presentCall: args => ({ card: 'generic', title: `Open ${args.url}`, kind: 'other' }),
         async execute(args, exec) {
-            const params = { url: args.url };
+            const waitUntil = args.waitUntil === undefined ? 'load' : String(args.waitUntil);
+            if (!(waitUntil in NAV_TIERS)) {
+                throw new Error(`browser_navigate: waitUntil must be one of none, commit, domcontentloaded, load — got "${waitUntil}"`);
+            }
+            const params = { url: args.url, waitUntil };
             if (args.tabId !== undefined)
                 params.tabId = args.tabId;
-            const budgetMs = typeof args.timeoutMs === 'number' && Number.isFinite(args.timeoutMs)
-                ? Math.min(NAV_MAX_MS, Math.max(100, Math.trunc(args.timeoutMs)))
-                : 15_000;
-            params.timeoutMs = budgetMs;
-            const raw = await controller.execute('nav', params, exec.signal, budgetMs + BRIDGE_MARGIN_MS);
+            // Explicit timeoutMs always wins over the tier; 'none' waits 0 and sends
+            // no budget at all. The bridge gets budget+2s so the extension's own
+            // "navigation did not arrive" always reports before the bridge's ceiling.
+            let budgetMs = NAV_TIERS[waitUntil];
+            if (typeof args.timeoutMs === 'number' && Number.isFinite(args.timeoutMs)) {
+                budgetMs = Math.min(NAV_MAX_MS, Math.max(100, Math.trunc(args.timeoutMs)));
+            }
+            if (waitUntil !== 'none')
+                params.timeoutMs = budgetMs;
+            const raw = await controller.execute('nav', params, exec.signal, waitUntil === 'none' ? undefined : budgetMs + BRIDGE_MARGIN_MS);
             // The declared schema is closed, so the fields describing a navigation that did
             // not arrive have to be carried over on purpose. The old shape check
             // (`siteUnreachable === true`) also missed the object the extension really
@@ -429,6 +449,12 @@ function applyBrowserTools(ctx, controller) {
                 || (typeof raw.siteUnreachable === 'object' && raw.siteUnreachable !== null);
             if (unreachable)
                 out.siteUnreachable = true;
+            if (typeof raw.waitUntil === 'string')
+                out.waitUntil = raw.waitUntil;
+            if (typeof raw.waitedMs === 'number')
+                out.waitedMs = raw.waitedMs;
+            if (typeof raw.readyState === 'string' && raw.readyState.length > 0)
+                out.readyState = raw.readyState;
             return out;
         },
     }));
@@ -836,6 +862,8 @@ function applyBrowserTools(ctx, controller) {
             tabIds: { type: 'array', items: { type: 'number' }, description: 'For close: every tab to close in one call. The result reports each id (closed / alreadyGone / failed) instead of stopping at the first failure.' },
             active: { type: 'boolean', description: 'Whether a newly opened tab becomes active; defaults to true.' },
             group: { type: 'boolean', description: 'For open: put the new tab in the DSH tab group. Defaults to true; pass false to keep it loose.' },
+            waitUntil: { type: 'string', description: 'For open: when the new tab counts as arrived — same tiers as browser_navigate (load default / domcontentloaded / commit / none).' },
+            timeoutMs: { type: 'number', description: 'For open: wait budget, overriding the waitUntil tier (load 15000, commit/domcontentloaded 4000).' },
             windowId: { type: 'number', description: 'For ungroup: only dissolve that window’s DSH group; omit to clear every window.' },
         },
         output: {
@@ -850,12 +878,24 @@ function applyBrowserTools(ctx, controller) {
                 case 'open': {
                     if (typeof args.url !== 'string' || args.url.length === 0)
                         throw new Error('open requires url');
-                    const params = { url: args.url };
+                    const waitUntil = args.waitUntil === undefined ? 'load' : String(args.waitUntil);
+                    if (!(waitUntil in NAV_TIERS)) {
+                        throw new Error(`browser_tabs open: waitUntil must be one of none, commit, domcontentloaded, load — got "${waitUntil}"`);
+                    }
+                    const params = { url: args.url, waitUntil };
                     if (args.active !== undefined)
                         params.active = args.active;
                     if (args.group !== undefined)
                         params.group = args.group;
-                    return await controller.execute('tabs.open', params, exec.signal);
+                    if (waitUntil === 'none') {
+                        return await controller.execute('tabs.open', params, exec.signal);
+                    }
+                    let budgetMs = NAV_TIERS[waitUntil];
+                    if (typeof args.timeoutMs === 'number' && Number.isFinite(args.timeoutMs)) {
+                        budgetMs = Math.min(NAV_MAX_MS, Math.max(100, Math.trunc(args.timeoutMs)));
+                    }
+                    params.timeoutMs = budgetMs;
+                    return await controller.execute('tabs.open', params, exec.signal, budgetMs + BRIDGE_MARGIN_MS);
                 }
                 case 'close': {
                     const ids = closeTabIds(args);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@angelky7/dsh-browser-control",
   "description": "Local WebSocket bridge between dsh and the DSH Browser Control browser extension, with model-facing browser_* tools and a Settings-managed on/off switch",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",
@@ -37,7 +37,7 @@
     "build": "tsc -p tsconfig.json && tsdown",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "check": "npm run typecheck && npm run build && publint",
-    "verify": "node verify/verify_config_patch.mjs && node verify/verify_peers.mjs && node verify/verify_surface.mjs && node verify/verify_tab_groups.mjs && node verify/verify_tabs_close_many.mjs && node verify/verify_cdp_retry.mjs && node verify/verify_snapshot_ax.mjs && node verify/verify_hard_lock.mjs && node verify/verify_policy.mjs && node verify/verify_cookies.mjs && node verify/verify_extension_e2e.mjs && node verify/verify_plugin.mjs legacy && node verify/verify_plugin.mjs conflict && node verify/verify_plugin.mjs new && node verify/verify_http.mjs && node verify/verify_errors.mjs && node verify/verify_hold.mjs && node verify/verify_protocol.mjs && node verify/verify_bundle_http.mjs && node verify/verify_nav_report.mjs && node verify/verify_nav_landing.mjs && node verify/verify_render_contract.mjs && node verify/verify_press_events.mjs && node verify/verify_nav_timeout.mjs"
+    "verify": "node verify/verify_config_patch.mjs && node verify/verify_peers.mjs && node verify/verify_surface.mjs && node verify/verify_tab_groups.mjs && node verify/verify_tabs_close_many.mjs && node verify/verify_cdp_retry.mjs && node verify/verify_snapshot_ax.mjs && node verify/verify_hard_lock.mjs && node verify/verify_policy.mjs && node verify/verify_cookies.mjs && node verify/verify_extension_e2e.mjs && node verify/verify_plugin.mjs legacy && node verify/verify_plugin.mjs conflict && node verify/verify_plugin.mjs new && node verify/verify_http.mjs && node verify/verify_errors.mjs && node verify/verify_hold.mjs && node verify/verify_protocol.mjs && node verify/verify_bundle_http.mjs && node verify/verify_nav_report.mjs && node verify/verify_nav_landing.mjs && node verify/verify_render_contract.mjs && node verify/verify_press_events.mjs && node verify/verify_nav_timeout.mjs && node verify/verify_nav_waituntil.mjs"
   },
   "publishConfig": {
     "access": "public",