@aryanduntley/pwa-debug 0.1.5 → 0.1.7

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).
@@ -12818,13 +12824,20 @@ const freshFlags = (port, userDataDir) => Object.freeze([
  *    --load-extension, and --disable-extensions-except would additionally block
  *    the manual Load-unpack the user is steered to. The profile/port still come
  *    up; the extension is provisioned by hand afterward.
+ *
+ * `isolate` (default true) controls --disable-extensions-except, which pins the
+ * profile to ONLY pwa-debug — Chromium disables every other extension, including
+ * ones already in the persistent profile or Load-unpacked/installed after launch.
+ * Pass false to drop it so other extensions coexist: --load-extension still
+ * 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) => {
+const sandboxFlags = (port, userDataDir, extensionPath, strategy, isolate, extraArgs = []) => {
     const extensionFlags = strategy === 'manual-guided'
         ? []
         : [
             `--load-extension=${extensionPath}`,
-            `--disable-extensions-except=${extensionPath}`,
+            ...(isolate ? [`--disable-extensions-except=${extensionPath}`] : []),
             ...(strategy === 'load-flag-escape-hatch'
                 ? ['--disable-features=DisableLoadExtensionCommandLineSwitch']
                 : []),
@@ -12837,6 +12850,7 @@ const sandboxFlags = (port, userDataDir, extensionPath, strategy) => {
         '--no-default-browser-check',
         '--disable-session-crashed-bubble',
         '--hide-crash-restore-bubble',
+        ...extraArgs,
     ]);
 };
 /**
@@ -12858,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
@@ -12872,7 +12889,8 @@ const buildNewWindowFlatpakArgs = (appId) => flatpakRun(appId, Object.freeze(['-
 /**
  * Sandbox launch: dedicated profile + the pwa-debug extension preloaded BEFORE
  * any tab opens (so the content-script injection race cannot occur).
- * --disable-extensions-except pins the profile to only our extension.
+ * --disable-extensions-except pins the profile to only our extension when
+ * `isolate` is true (the default); pass false to let other extensions coexist.
  *
  * --disable-session-crashed-bubble + --hide-crash-restore-bubble suppress the
  * "Brave/Chrome didn't shut down correctly — restore tabs?" prompt on the NEXT
@@ -12883,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) => Object.freeze({
+const buildSandboxSpawnArgs = (execPath, port, userDataDir, extensionPath, strategy, isolate = true, extraArgs = []) => Object.freeze({
     cmd: execPath,
-    args: sandboxFlags(port, userDataDir, extensionPath, strategy),
+    args: sandboxFlags(port, userDataDir, extensionPath, strategy, isolate, extraArgs),
 });
 /**
  * Sandbox launch for a flatpak browser: `flatpak run <app-id> <sandbox flags>`.
@@ -12894,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) => flatpakRun(appId, sandboxFlags(port, userDataDir, extensionPath, strategy));
+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
@@ -12940,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
@@ -13002,9 +13021,12 @@ const launchSandbox = async (input, deps) => {
     // refuse the unpacked --load-extension (#318). Seed developer_mode=true into the
     // profile's Preferences before spawn so the extension loads with no manual step.
     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)
-        : buildSandboxSpawnArgs(input.execPath, input.port, input.userDataDir, input.extensionPath, input.loadStrategy);
+        ? 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);
@@ -14009,6 +14031,8 @@ const inputSchema$5 = {
     port: numberType().int().min(1).max(65535).optional(),
     mode: enumType(MODES).optional(),
     packaging: enumType(PACKAGINGS).optional(),
+    isolateExtensions: booleanType().optional(),
+    extraArgs: arrayType(stringType()).optional(),
 };
 const isSandboxMode = (mode) => mode === 'sandbox-persistent' || mode === 'sandbox-temp';
 /**
@@ -14200,6 +14224,10 @@ const launchBrowserCore = async (args, platform, env, deps) => {
             loadStrategy,
             mode,
             refreshExtension: refreshExtensionEnabled(mode, env),
+            ...(args.isolateExtensions !== undefined
+                ? { isolateExtensions: args.isolateExtensions }
+                : {}),
+            ...(args.extraArgs !== undefined ? { extraArgs: args.extraArgs } : {}),
             ...(target.appId !== undefined ? { appId: target.appId } : {}),
             ...(snapPkg ? { snapPackage: snapPkg } : {}),
         });
@@ -14224,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);
@@ -14250,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. 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,
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aryanduntley/pwa-debug",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "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.5",
-    "@pwa-debug/shared": "0.1.5"
+    "@pwa-debug/shared": "0.1.7",
+    "@pwa-debug/extension": "0.1.7"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",