@aryanduntley/pwa-debug 0.1.6 → 0.1.8

package/README.md

@@ -29,6 +29,8 @@ The goal is to eliminate the "user is the AI's eyes and hands" loop. Today, debu
 > - **PWA Runtime Diagnostics** — service-worker lifecycle + versions, CacheStorage contents + age, installability gaps, a live capability matrix, IndexedDB/web-storage inspection, update-propagation / version-skew analysis, and a one-shot runtime-state snapshot.
 >
 > **Verified on Linux** (the full suite live-tested against a real PWA). macOS/Windows code paths are implemented with unit coverage but still need real-machine retest ([help wanted](#help-wanted-macos--windows-verification)). Firefox is not supported (it doesn't speak CDP).
+>
+> ⚠️ **macOS / Windows users, beware:** these platforms have **never been run on real hardware** — only unit-tested with injected fakes. Expect rough edges (browser detection, profile paths, native-messaging registration, system-default resolution). Please [open an issue](../../issues) with the failing command and its output — bug reports from real macOS/Windows machines are the single most useful contribution right now. See [Help wanted](#help-wanted-macos--windows-verification) for the specific things to try.
 
 ## How it differs from `chrome-devtools-mcp`
 

package/dist/main.js

@@ -12797,12 +12797,18 @@ const browserUrlFor = (port) => `http://127.0.0.1:${port}`;
  * Chromium flags for a fresh launch — shared by the exec-by-path and flatpak
  * builders so the two command forms differ ONLY in the command prefix, never in
  * the flag set. --no-first-run / --no-default-browser-check keep it non-interactive.
+ *
+ * `extraArgs` are caller-supplied Chromium startup flags (e.g.
+ * --enable-speech-dispatcher) appended AFTER the managed flags so the caller can
+ * override a non-essential default; they only matter on a cold spawn (this path),
+ * never on an attach.
  */
-const freshFlags = (port, userDataDir) => Object.freeze([
+const freshFlags = (port, userDataDir, extraArgs = []) => Object.freeze([
     `--remote-debugging-port=${port}`,
     `--user-data-dir=${userDataDir}`,
     '--no-first-run',
     '--no-default-browser-check',
+    ...extraArgs,
 ]);
 /**
  * Chromium flags for a sandbox launch (dedicated profile + preloaded extension).
@@ -12826,7 +12832,7 @@ const freshFlags = (port, userDataDir) => Object.freeze([
  * preloads pwa-debug, while the profile's other extensions stay enabled. No-op
  * under 'manual-guided' (the flag is already omitted there).
  */
-const sandboxFlags = (port, userDataDir, extensionPath, strategy, isolate) => {
+const sandboxFlags = (port, userDataDir, extensionPath, strategy, isolate, extraArgs = []) => {
     const extensionFlags = strategy === 'manual-guided'
         ? []
         : [
@@ -12844,6 +12850,7 @@ const sandboxFlags = (port, userDataDir, extensionPath, strategy, isolate) => {
         '--no-default-browser-check',
         '--disable-session-crashed-bubble',
         '--hide-crash-restore-bubble',
+        ...extraArgs,
     ]);
 };
 /**
@@ -12865,9 +12872,12 @@ const flatpakRun = (appId, browserFlags) => Object.freeze({
 /**
  * Fresh launch (sub-state c): bring up the debug port on the user's profile.
  */
-const buildFreshSpawnArgs = (execPath, port, userDataDir) => Object.freeze({ cmd: execPath, args: freshFlags(port, userDataDir) });
+const buildFreshSpawnArgs = (execPath, port, userDataDir, extraArgs = []) => Object.freeze({
+    cmd: execPath,
+    args: freshFlags(port, userDataDir, extraArgs),
+});
 /** Fresh launch for a flatpak browser: `flatpak run <app-id> <fresh flags>`. */
-const buildFreshFlatpakArgs = (appId, port, userDataDir) => flatpakRun(appId, freshFlags(port, userDataDir));
+const buildFreshFlatpakArgs = (appId, port, userDataDir, extraArgs = []) => flatpakRun(appId, freshFlags(port, userDataDir, extraArgs));
 /**
  * New-window launch (sub-state b): re-invoke the binary so it opens a window
  * in the already-running session via IPC. No debug port — that requires a full
@@ -12891,9 +12901,9 @@ const buildNewWindowFlatpakArgs = (appId) => flatpakRun(appId, Object.freeze(['-
  * Applied to sandbox modes only — an 'existing'-mode launch is the user's real
  * profile, where a genuine restore prompt should be left intact.
  */
-const buildSandboxSpawnArgs = (execPath, port, userDataDir, extensionPath, strategy, isolate = true) => Object.freeze({
+const buildSandboxSpawnArgs = (execPath, port, userDataDir, extensionPath, strategy, isolate = true, extraArgs = []) => Object.freeze({
     cmd: execPath,
-    args: sandboxFlags(port, userDataDir, extensionPath, strategy, isolate),
+    args: sandboxFlags(port, userDataDir, extensionPath, strategy, isolate, extraArgs),
 });
 /**
  * Sandbox launch for a flatpak browser: `flatpak run <app-id> <sandbox flags>`.
@@ -12902,7 +12912,7 @@ const buildSandboxSpawnArgs = (execPath, port, userDataDir, extensionPath, strat
  * (`flatpak override --user --filesystem=host <app-id>`) for these to resolve
  * inside the sandbox — the same prerequisite the NMH path documents.
  */
-const buildSandboxFlatpakArgs = (appId, port, userDataDir, extensionPath, strategy, isolate = true) => flatpakRun(appId, sandboxFlags(port, userDataDir, extensionPath, strategy, isolate));
+const buildSandboxFlatpakArgs = (appId, port, userDataDir, extensionPath, strategy, isolate = true, extraArgs = []) => flatpakRun(appId, sandboxFlags(port, userDataDir, extensionPath, strategy, isolate, extraArgs));
 
 /**
  * 'existing'-mode launch: the graceful-degradation triad orchestrated over the
@@ -12948,9 +12958,10 @@ const launchExisting = async (input, deps) => {
         });
     }
     // spawn-fresh
+    const extraArgs = input.extraArgs ?? [];
     const { cmd, args } = input.appId
-        ? buildFreshFlatpakArgs(input.appId, input.port, input.userDataDir)
-        : buildFreshSpawnArgs(input.execPath, input.port, input.userDataDir);
+        ? buildFreshFlatpakArgs(input.appId, input.port, input.userDataDir, extraArgs)
+        : buildFreshSpawnArgs(input.execPath, input.port, input.userDataDir, extraArgs);
     const { pid } = await deps.spawnBrowser(cmd, args);
     // Chromium 136+ ignores --remote-debugging-port on the default profile: the
     // browser comes up (pwa-debug extension still usable) but the port never
@@ -13012,9 +13023,10 @@ const launchSandbox = async (input, deps) => {
     await deps.seedDeveloperMode(input.userDataDir);
     // Default to isolation (clean-room) when unset; false lets other extensions coexist.
     const isolate = input.isolateExtensions ?? true;
+    const extraArgs = input.extraArgs ?? [];
     const { cmd, args } = input.appId
-        ? buildSandboxFlatpakArgs(input.appId, input.port, input.userDataDir, input.extensionPath, input.loadStrategy, isolate)
-        : buildSandboxSpawnArgs(input.execPath, input.port, input.userDataDir, input.extensionPath, input.loadStrategy, isolate);
+        ? buildSandboxFlatpakArgs(input.appId, input.port, input.userDataDir, input.extensionPath, input.loadStrategy, isolate, extraArgs)
+        : buildSandboxSpawnArgs(input.execPath, input.port, input.userDataDir, input.extensionPath, input.loadStrategy, isolate, extraArgs);
     const { pid } = await deps.spawnBrowser(cmd, args);
     if (input.mode === 'sandbox-temp') {
         deps.registerTempProfile(input.userDataDir);
@@ -14020,6 +14032,7 @@ const inputSchema$5 = {
     mode: enumType(MODES).optional(),
     packaging: enumType(PACKAGINGS).optional(),
     isolateExtensions: booleanType().optional(),
+    extraArgs: arrayType(stringType()).optional(),
 };
 const isSandboxMode = (mode) => mode === 'sandbox-persistent' || mode === 'sandbox-temp';
 /**
@@ -14214,6 +14227,7 @@ const launchBrowserCore = async (args, platform, env, deps) => {
             ...(args.isolateExtensions !== undefined
                 ? { isolateExtensions: args.isolateExtensions }
                 : {}),
+            ...(args.extraArgs !== undefined ? { extraArgs: args.extraArgs } : {}),
             ...(target.appId !== undefined ? { appId: target.appId } : {}),
             ...(snapPkg ? { snapPackage: snapPkg } : {}),
         });
@@ -14238,6 +14252,7 @@ const launchBrowserCore = async (args, platform, env, deps) => {
         userDataDir,
         debugPortBlockedOnDefaultProfile: portBlocked,
         ...(target.appId !== undefined ? { appId: target.appId } : {}),
+        ...(args.extraArgs !== undefined ? { extraArgs: args.extraArgs } : {}),
     });
     deps.recordLaunch(result, port);
     return launchOk(result, target, alternatives, args.packaging !== undefined);
@@ -14264,7 +14279,7 @@ const launchBrowserHandler = async (args, ctx) => launchBrowserCore(args, proces
 });
 const launchBrowserTool = Object.freeze({
     name: 'pdl_launch_browser',
-    description: "Launch or attach to a Chromium-family browser with a live remote-debugging port, for use alongside chrome-devtools-mcp. Modes: mode='existing' (default) targets the user's normal profile and degrades gracefully — (a) port already live → attach; (b) running without a debug port → opens a NEW WINDOW in the existing session (never kills it), attached:false + degradation message; (c) not running → spawns fresh with --remote-debugging-port + --user-data-dir=<your profile>. mode='sandbox-persistent' spawns a dedicated, persistent dev profile at ~/.pwa-debug/profiles/<browser>/ beside your normal browser, with the pwa-debug extension PRELOADED (no reload needed); mode='sandbox-temp' is the same but in a throwaway mkdtemp profile cleaned up on host shutdown. Sandbox modes always work standalone (separate profile → no lock collision) and both pwa-debug + CDP tools are available. Args: browser? (chrome|chromium|edge|brave|vivaldi|opera; defaults to system-default), port? (default 9222), mode?, packaging? (native|snap|flatpak). When the same browser is installed under multiple packagings (e.g. snap AND flatpak chromium), pass packaging to pick one; without it the default preference is native > snap > flatpak and next_steps lists the alternatives so you can re-target. isolateExtensions? (sandbox modes only, default true): true pins the dedicated profile to ONLY the pwa-debug extension (clean room — every other extension is disabled); pass false to let other extensions coexist (pwa-debug still preloads, while extensions already in the persistent profile or Load-unpacked/installed after launch stay enabled) — use this to debug a PWA alongside other extensions or to test your own extension with pwa-debug. existing mode already keeps all your normal-profile extensions. Linux is first-class; macOS/Windows deferred. Follow next_steps[] — it carries the chrome-devtools-mcp registration snippet, the profile location, the flatpak onboarding steps, or the degradation guidance.",
+    description: "Launch or attach to a Chromium-family browser with a live remote-debugging port, for use alongside chrome-devtools-mcp. Modes: mode='existing' (default) targets the user's normal profile and degrades gracefully — (a) port already live → attach; (b) running without a debug port → opens a NEW WINDOW in the existing session (never kills it), attached:false + degradation message; (c) not running → spawns fresh with --remote-debugging-port + --user-data-dir=<your profile>. mode='sandbox-persistent' spawns a dedicated, persistent dev profile at ~/.pwa-debug/profiles/<browser>/ beside your normal browser, with the pwa-debug extension PRELOADED (no reload needed); mode='sandbox-temp' is the same but in a throwaway mkdtemp profile cleaned up on host shutdown. Sandbox modes always work standalone (separate profile → no lock collision) and both pwa-debug + CDP tools are available. Args: browser? (chrome|chromium|edge|brave|vivaldi|opera; defaults to system-default), port? (default 9222), mode?, packaging? (native|snap|flatpak). When the same browser is installed under multiple packagings (e.g. snap AND flatpak chromium), pass packaging to pick one; without it the default preference is native > snap > flatpak and next_steps lists the alternatives so you can re-target. isolateExtensions? (sandbox modes only, default true): true pins the dedicated profile to ONLY the pwa-debug extension (clean room — every other extension is disabled); pass false to let other extensions coexist (pwa-debug still preloads, while extensions already in the persistent profile or Load-unpacked/installed after launch stay enabled) — use this to debug a PWA alongside other extensions or to test your own extension with pwa-debug. existing mode already keeps all your normal-profile extensions. extraArgs? (string[]): extra Chromium startup flags appended after pwa-debug's managed flags — e.g. extraArgs=['--enable-speech-dispatcher'] to enable system TTS/speech-dispatcher, or any other --flag the browser needs at startup. Applied only on a COLD spawn (mode='existing' when the browser isn't already running, or either sandbox mode); they have no effect when attaching to an already-live port or opening a new window in a running session, since startup flags are read once at process start — fully quit the browser (or use a sandbox mode) for them to take effect. Linux is first-class; macOS/Windows deferred. Follow next_steps[] — it carries the chrome-devtools-mcp registration snippet, the profile location, the flatpak onboarding steps, or the degradation guidance.",
     inputSchema: inputSchema$5,
     handler: launchBrowserHandler,
 });
@@ -14856,6 +14871,90 @@ const registerChromeDevtoolsTool = Object.freeze({
     handler: registerChromeDevtoolsHandler,
 });
 
+// The SW waits up to timeout_ms (capped below) for the page to finish loading
+// before replying, so the IPC budget must comfortably exceed it.
+const NAV_MAX_LOAD_TIMEOUT_MS = 12_000;
+const NAV_IPC_TIMEOUT_MS = NAV_MAX_LOAD_TIMEOUT_MS + 3_000;
+const navigateInputSchema = {
+    extension_id: stringType().min(1).optional(),
+    tab_id: numberType().int().optional(),
+    url: stringType().min(1),
+    timeout_ms: numberType().int().positive().max(NAV_MAX_LOAD_TIMEOUT_MS).optional(),
+};
+const newTabInputSchema = {
+    extension_id: stringType().min(1).optional(),
+    url: stringType().min(1),
+    active: booleanType().optional(),
+    timeout_ms: numberType().int().positive().max(NAV_MAX_LOAD_TIMEOUT_MS).optional(),
+};
+/**
+ * Shared IPC round-trip for the navigation tools: resolve the target NMH, send a
+ * single request envelope to the SW, and normalize transport vs. handler errors.
+ * The SW handler (request_router) drives chrome.tabs and waits for load-complete.
+ */
+const sendNavRequest = async (ctx, extensionId, tool, payload, nextSteps) => {
+    const target = resolveTarget$1(ctx, extensionId);
+    if (!target.ok) {
+        return errorResponse(target.error, [
+            'Call host_status to see activeConnections. If empty, ensure host_register_extension has been called and the extension reloaded at chrome://extensions.',
+        ]);
+    }
+    const env = Object.freeze({
+        type: 'request',
+        requestId: randomUUID(),
+        tool,
+        extensionId: target.extensionId,
+        payload,
+    });
+    let response;
+    try {
+        response = await ctx.ipcServer.request(target.extensionId, env, {
+            timeoutMs: NAV_IPC_TIMEOUT_MS,
+        });
+    }
+    catch (err) {
+        return errorResponse(`${tool} failed: ${err.message}`, [
+            `IPC request did not complete. Confirm the SW is connected and the ${tool} handler is wired in the SW.`,
+        ]);
+    }
+    if (response.error) {
+        return errorResponse(`${tool} nmh error: ${response.error.message}`, [
+            'The SW rejected the navigation (invalid URL, no active tab, or chrome.tabs threw). Pass an explicit tab_id, or open a tab first.',
+        ]);
+    }
+    const data = {
+        extensionId: target.extensionId,
+        ...response.payload,
+    };
+    return okResponse(data, [...nextSteps]);
+};
+const navigateHandler = async (args, ctx) => sendNavRequest(ctx, args.extension_id, 'pdl_navigate', {
+    url: args.url,
+    ...(args.tab_id !== undefined ? { tab_id: args.tab_id } : {}),
+    ...(args.timeout_ms !== undefined ? { timeout_ms: args.timeout_ms } : {}),
+}, [
+    'Navigated the active (or given) tab. Returns { tabId, url, status }: status "complete" = page finished loading; "loading" = navigation happened but the load was still in flight when the wait elapsed (raise timeout_ms, or poll session_ping). pwa-debug capture/inspection tools now target the new page.',
+]);
+const newTabHandler = async (args, ctx) => sendNavRequest(ctx, args.extension_id, 'pdl_new_tab', {
+    url: args.url,
+    ...(args.active !== undefined ? { active: args.active } : {}),
+    ...(args.timeout_ms !== undefined ? { timeout_ms: args.timeout_ms } : {}),
+}, [
+    'Opened a new tab. Returns { tabId, url, status, created:true }. Pass the returned tabId to other pwa-debug tools (react_tree, console_tail, pdl_click, …) to target this tab; without tab_id they use the active tab.',
+]);
+const navigateTool = Object.freeze({
+    name: 'pdl_navigate',
+    description: "Navigate a browser tab to a URL, driven through the pwa-debug extension's service worker (chrome.tabs.update) — NO CDP, so it works on the user's real, logged-in profile without chrome-devtools-mcp being registered or attached. Targets the active tab in the last-focused window unless tab_id is given. The URL may omit the scheme (https:// is assumed); a javascript: URL is rejected. Waits for the page to reach document 'complete' (up to timeout_ms, default 10000, max 12000) before returning { extensionId, tabId, url, status, windowId? }, where status is 'complete' or 'loading' (load still in flight at timeout — the navigation still happened). Args: { url: non-empty string, tab_id?, timeout_ms?, extension_id? }. With no extension_id/tab_id, targets the single connected NMH and the active tab. CALL host_status FIRST to confirm a connection.",
+    inputSchema: navigateInputSchema,
+    handler: navigateHandler,
+});
+const newTabTool = Object.freeze({
+    name: 'pdl_new_tab',
+    description: "Open a NEW browser tab at a URL via the pwa-debug extension's service worker (chrome.tabs.create) — NO CDP, works on the user's real profile with no chrome-devtools-mcp dependency. The URL may omit the scheme (https:// is assumed); a javascript: URL is rejected. active? controls foreground vs. background (defaults to foreground). Waits for the page to reach document 'complete' (up to timeout_ms, default 10000, max 12000) before returning { extensionId, tabId, url, status, windowId?, created:true }. Pass the returned tabId to other pwa-debug tools to target this tab specifically. Args: { url: non-empty string, active?, timeout_ms?, extension_id? }. With no extension_id, targets the single connected NMH. CALL host_status FIRST to confirm a connection.",
+    inputSchema: newTabInputSchema,
+    handler: newTabHandler,
+});
+
 const ACTION_IPC_TIMEOUT_MS = 5000;
 // Locator + routing fields shared by every action tool.
 const locatorSchema = {
@@ -15026,6 +15125,8 @@ const TOOLS = Object.freeze([
     storageGetTool,
     idbListTool,
     idbQueryTool,
+    navigateTool,
+    newTabTool,
     launchBrowserTool,
     browserStatusTool,
     closeBrowserTool,

package/extension/service-worker.js

@@ -176,6 +176,110 @@ const dispatchToTabClassified = async (tabId, req, opts = {}) => {
     return { ok: true, response };
 };
 
+// SW-side navigation primitives — wraps chrome.tabs URL navigation so the request
+// router stays a thin orchestrator. SW-handled (NOT page-world): chrome.tabs is
+// only reachable in the extension service worker, and driving the tab to a new URL
+// is a browser action, not an in-page read. This is the pwa-debug counterpart to
+// chrome-devtools-mcp's navigate_page/new_page — it works through the loaded
+// extension on the user's real profile, with no CDP attach required.
+const DEFAULT_LOAD_TIMEOUT_MS = 10_000;
+// A bare javascript: URL would run script in the target page context on navigate;
+// reject it. Everything else (http(s), file:, about:, data:, chrome:, localhost
+// shorthand) is allowed — this is a debugging driver, not a sandbox.
+const JAVASCRIPT_SCHEME = /^javascript:/i;
+const HAS_SCHEME = /^[a-z][a-z0-9+.-]*:/i;
+/**
+ * Normalize a caller-supplied URL: trim, reject empty / javascript:, and assume
+ * https:// when no scheme is given (so `example.com` works). Returns null when the
+ * input is unusable so the caller can surface a clear error.
+ */
+const normalizeUrl = (raw) => {
+    const trimmed = raw.trim();
+    if (trimmed.length === 0)
+        return null;
+    if (JAVASCRIPT_SCHEME.test(trimmed))
+        return null;
+    return HAS_SCHEME.test(trimmed) ? trimmed : `https://${trimmed}`;
+};
+/** Active tab id in the last-focused window, or undefined when there is none. */
+const activeTabId = async () => {
+    const tabs = await chrome.tabs.query({ active: true, lastFocusedWindow: true });
+    return tabs[0]?.id;
+};
+/**
+ * Resolve once the tab reports document 'complete', or 'timeout' after timeoutMs.
+ * The onUpdated listener is added BEFORE the caller triggers the load so the
+ * 'complete' event can't be missed; it is always removed and the timer cleared.
+ */
+const waitForComplete = (tabId, timeoutMs) => new Promise((resolve) => {
+    let settled = false;
+    const settle = (outcome) => {
+        if (settled)
+            return;
+        settled = true;
+        chrome.tabs.onUpdated.removeListener(onUpdated);
+        clearTimeout(timer);
+        resolve(outcome);
+    };
+    const onUpdated = (id, info) => {
+        if (id === tabId && info.status === 'complete')
+            settle('complete');
+    };
+    const timer = setTimeout(() => settle('timeout'), timeoutMs);
+    chrome.tabs.onUpdated.addListener(onUpdated);
+});
+/**
+ * Navigate the active (or given) tab to url and wait for it to finish loading.
+ * Throws on an invalid url or when no tab can be resolved. The listener is armed
+ * before chrome.tabs.update so the fresh load's 'complete' is observed.
+ */
+const navigateTab = async (input) => {
+    const url = normalizeUrl(input.url);
+    if (url === null) {
+        throw new Error(`navigate: invalid or unsupported url: ${JSON.stringify(input.url)}`);
+    }
+    const tabId = input.tabId ?? (await activeTabId());
+    if (tabId === undefined) {
+        throw new Error('navigate: no active tab (open a tab or pass tab_id)');
+    }
+    const pending = waitForComplete(tabId, input.timeoutMs ?? DEFAULT_LOAD_TIMEOUT_MS);
+    const tab = await chrome.tabs.update(tabId, { url });
+    const outcome = await pending;
+    return {
+        tabId,
+        url,
+        ...(tab?.windowId !== undefined ? { windowId: tab.windowId } : {}),
+        status: outcome === 'complete' ? 'complete' : 'loading',
+    };
+};
+/**
+ * Open a new tab at url and wait for it to finish loading. active defaults to
+ * Chrome's behavior (foreground). Throws on an invalid url or when Chrome returns
+ * no tab id.
+ */
+const openNewTab = async (input) => {
+    const url = normalizeUrl(input.url);
+    if (url === null) {
+        throw new Error(`new_tab: invalid or unsupported url: ${JSON.stringify(input.url)}`);
+    }
+    const tab = await chrome.tabs.create({
+        url,
+        ...(input.active !== undefined ? { active: input.active } : {}),
+    });
+    const tabId = tab.id;
+    if (tabId === undefined) {
+        throw new Error('new_tab: chrome did not return a tab id');
+    }
+    const outcome = await waitForComplete(tabId, input.timeoutMs ?? DEFAULT_LOAD_TIMEOUT_MS);
+    return {
+        tabId,
+        url,
+        ...(tab.windowId !== undefined ? { windowId: tab.windowId } : {}),
+        status: outcome === 'complete' ? 'complete' : 'loading',
+        created: true,
+    };
+};
+
 const compilePatternList = (sources, fieldPathPrefix) => {
     if (sources === undefined || sources.length === 0) {
         return { ok: true, value: [] };
@@ -1610,6 +1714,50 @@ const handleSessionRecord = async (env) => {
     }
     return response.payload;
 };
+// --- Navigation tools (pdl_navigate / pdl_new_tab) ---------------------------
+// SW-handled, NOT page-world: chrome.tabs drives the browser to a URL. Forwarded
+// to the sw_navigation module, which validates the URL and waits for load.
+const readTimeoutMs = (r) => typeof r['timeout_ms'] === 'number' &&
+    Number.isInteger(r['timeout_ms']) &&
+    r['timeout_ms'] > 0
+    ? r['timeout_ms']
+    : undefined;
+const handleNavigate = async (env) => {
+    const raw = env.payload;
+    if (raw === null || typeof raw !== 'object') {
+        throw new Error('pdl_navigate: payload must be { url: non-empty string, tab_id?, timeout_ms? }');
+    }
+    const r = raw;
+    const url = r['url'];
+    if (typeof url !== 'string' || url.length === 0) {
+        throw new Error('pdl_navigate: payload must include { url: non-empty string }');
+    }
+    const tabId = readTabId(raw);
+    const timeoutMs = readTimeoutMs(r);
+    return navigateTab({
+        url,
+        ...(tabId !== undefined ? { tabId } : {}),
+        ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+    });
+};
+const handleNewTab = async (env) => {
+    const raw = env.payload;
+    if (raw === null || typeof raw !== 'object') {
+        throw new Error('pdl_new_tab: payload must be { url: non-empty string, active?, timeout_ms? }');
+    }
+    const r = raw;
+    const url = r['url'];
+    if (typeof url !== 'string' || url.length === 0) {
+        throw new Error('pdl_new_tab: payload must include { url: non-empty string }');
+    }
+    const active = typeof r['active'] === 'boolean' ? r['active'] : undefined;
+    const timeoutMs = readTimeoutMs(r);
+    return openNewTab({
+        url,
+        ...(active !== undefined ? { active } : {}),
+        ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+    });
+};
 // --- Path 7 interaction action tools (pdl_*) ---------------------------------
 // One generic handler per ACTION_TOOL_SPECS entry: extract tab_id for routing,
 // forward the locator + params payload to the page-world unchanged.
@@ -1643,6 +1791,8 @@ const makeActionRequestHandler = (tool) => async (env) => {
 const actionRequestHandlers = Object.freeze(Object.fromEntries(ACTION_TOOL_SPECS.map((s) => [s.tool, makeActionRequestHandler(s.tool)])));
 const HANDLERS = Object.freeze({
     ...actionRequestHandlers,
+    pdl_navigate: handleNavigate,
+    pdl_new_tab: handleNewTab,
     session_ping: handleSessionPing,
     recent_events: handleRecentEvents,
     evaluate: handleEvaluate,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aryanduntley/pwa-debug",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "private": false,
   "license": "MIT",
   "type": "module",
@@ -63,8 +63,8 @@
     "@types/winreg": "^1.2.36",
     "rollup": "^4.27.4",
     "tslib": "^2.8.1",
-    "@pwa-debug/extension": "0.1.6",
-    "@pwa-debug/shared": "0.1.6"
+    "@pwa-debug/extension": "0.1.8",
+    "@pwa-debug/shared": "0.1.8"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",