extension 4.1.20 → 4.1.21

package/dist/cli.cjs

@@ -750,7 +750,7 @@ var __webpack_modules__ = {
             return `${getLoggingPrefix('warn')} safari-web-extension-converter reported ${pintor__rspack_import_8_default().yellow(String(warnings.length))} ${1 === warnings.length ? 'warning' : 'warnings'}, some manifest keys/APIs may not be supported by Safari:\n` + warnings.map((line)=>`  ${pintor__rspack_import_8_default().gray('•')} ${line}`).join('\n') + (kept.length ? `\nExtension.js kept ${1 === kept.length ? 'one of these keys' : 'some of these keys'} on purpose:\n${keptLines}` : '');
         }
         function safariDefaultBundleIdNote(bundleId) {
-            return `${getLoggingPrefix('warn')} The bundle id ${pintor__rspack_import_8_default().gray(bundleId)} is generated from the app name.\nEvery project built from the same source shares this id, and the first team to register it takes it.\nSet your own with ${pintor__rspack_import_8_default().blue('--bundle-id')} before your first submission.\nAfter a submission, a new id is a new extension with none of your users.`;
+            return `${getLoggingPrefix('info')} Bundle id ${pintor__rspack_import_8_default().gray(bundleId)} (generated, set ${pintor__rspack_import_8_default().blue('--bundle-id')} to own it).`;
         }
         function safariOpenHint(appPath, appName) {
             return `${getLoggingPrefix('info')} Launch it once to register with Safari: ${pintor__rspack_import_8_default().blue('open')} ${pintor__rspack_import_8_default().underline(`"${appPath}"`)}\nThen turn on ${pintor__rspack_import_8_default().yellow(appName)} in Safari ▸ Settings ▸ Extensions.`;
@@ -772,6 +772,9 @@ var __webpack_modules__ = {
         function safariRegistered(appName) {
             return `${getLoggingPrefix('success')} Safari recognizes ${pintor__rspack_import_8_default().yellow(appName)}, finish enabling it with the steps above.`;
         }
+        function safariPidUnresolved(appName) {
+            return `${getLoggingPrefix('warn')} Opened ${pintor__rspack_import_8_default().yellow(appName)} but could not find its process id.\nThe session's ready.json names the app and the extension without a ${pintor__rspack_import_8_default().gray('browserPid')}.`;
+        }
         function safariNotYetRegistered(appName) {
             return `${getLoggingPrefix('info')} Safari hasn't picked up ${pintor__rspack_import_8_default().yellow(appName)} yet.\nOpen the app once, then check Safari ▸ Settings ▸ Extensions.`;
         }
@@ -1033,6 +1036,7 @@ var __webpack_modules__ = {
             jR: ()=>safariBuilding,
             jc: ()=>safariProjectStale,
             jk: ()=>requireGeckoBinaryForGeckoBased,
+            jn: ()=>safariPidUnresolved,
             kK: ()=>preferringSystemBrowserOverSnapshot,
             l9: ()=>parsingPacketError,
             lO: ()=>firefoxDryRunArgs,
@@ -1405,6 +1409,7 @@ var __webpack_modules__ = {
     "./browsers/browsers-lib/ready-stamp.ts" (__unused_rspack_module, __webpack_exports__, __webpack_require__) {
         var node_fs__rspack_import_0 = __webpack_require__("node:fs");
         var node_path__rspack_import_1 = __webpack_require__("node:path");
+        var _write_json_atomic__rspack_import_2 = __webpack_require__("./browsers/browsers-lib/write-json-atomic.ts");
         function readyPathFor(extensionOutputPath) {
             return node_path__rspack_import_1.join(node_path__rspack_import_1.dirname(extensionOutputPath), 'extension-js', node_path__rspack_import_1.basename(extensionOutputPath), 'ready.json');
         }
@@ -1416,7 +1421,7 @@ var __webpack_modules__ = {
                 const ready = JSON.parse(node_fs__rspack_import_0.readFileSync(readyPath, 'utf-8'));
                 if (ready.rdpPort === rdpPort) return;
                 ready.rdpPort = rdpPort;
-                node_fs__rspack_import_0.writeFileSync(readyPath, JSON.stringify(ready, null, 2));
+                (0, _write_json_atomic__rspack_import_2.Z)(readyPath, ready);
             } catch  {}
         }
         function stampReadyBrowserLaunch(extensionOutputPath, details) {
@@ -1434,7 +1439,7 @@ var __webpack_modules__ = {
                 if (binary) ready.binary = binary;
                 const provenance = String(details?.binaryProvenance || '').trim();
                 if (provenance) ready.binaryProvenance = provenance;
-                node_fs__rspack_import_0.writeFileSync(readyPath, JSON.stringify(ready, null, 2));
+                (0, _write_json_atomic__rspack_import_2.Z)(readyPath, ready);
             } catch  {}
         }
         function stampReadyExtensionId(extensionOutputPath, extensionId) {
@@ -1446,7 +1451,7 @@ var __webpack_modules__ = {
                 const ready = JSON.parse(node_fs__rspack_import_0.readFileSync(readyPath, 'utf-8'));
                 if (ready.extensionId === id) return;
                 ready.extensionId = id;
-                node_fs__rspack_import_0.writeFileSync(readyPath, JSON.stringify(ready, null, 2));
+                (0, _write_json_atomic__rspack_import_2.Z)(readyPath, ready);
             } catch  {}
         }
         function stampReadyExtensionLoadRefused(extensionOutputPath, reason) {
@@ -1461,7 +1466,7 @@ var __webpack_modules__ = {
                 ready.message = `${browserLabel.charAt(0).toUpperCase() + browserLabel.slice(1)} refused to load the extension at ${extensionOutputPath}${reason ? `: ${reason}` : ''}`;
                 ready.extensionLoadRefusedAt = new Date().toISOString();
                 if (reason) ready.extensionLoadRefusedReason = reason;
-                node_fs__rspack_import_0.writeFileSync(readyPath, JSON.stringify(ready, null, 2));
+                (0, _write_json_atomic__rspack_import_2.Z)(readyPath, ready);
             } catch  {}
         }
         function stampReadyProfileLocked(extensionOutputPath, details) {
@@ -1475,7 +1480,7 @@ var __webpack_modules__ = {
                 ready.message = String(details?.message || '').trim() || 'the browser profile is already in use by another session';
                 ready.profileLockedAt = new Date().toISOString();
                 if (details?.owner) ready.profileLockOwner = details.owner;
-                node_fs__rspack_import_0.writeFileSync(readyPath, JSON.stringify(ready, null, 2));
+                (0, _write_json_atomic__rspack_import_2.Z)(readyPath, ready);
             } catch  {}
         }
         function stampReadyBrowserExited(extensionOutputPath, code) {
@@ -1491,7 +1496,7 @@ var __webpack_modules__ = {
                     ready.code = 'browser_exited';
                     ready.message = `the ${ready.browser || 'browser'} process exited (code ${code ?? 'unknown'}); nothing is running`;
                 }
-                node_fs__rspack_import_0.writeFileSync(readyPath, JSON.stringify(ready, null, 2));
+                (0, _write_json_atomic__rspack_import_2.Z)(readyPath, ready);
             } catch  {}
         }
         __webpack_require__.d(__webpack_exports__, {
@@ -1955,6 +1960,27 @@ var __webpack_modules__ = {
             yO: ()=>probeChromiumBinaryVersion
         });
     },
+    "./browsers/browsers-lib/write-json-atomic.ts" (__unused_rspack_module, __webpack_exports__, __webpack_require__) {
+        var node_fs__rspack_import_0 = __webpack_require__("node:fs");
+        function writeJsonAtomic(filePath, value) {
+            const tmpPath = `${filePath}.tmp-${process.pid}`;
+            try {
+                node_fs__rspack_import_0.writeFileSync(tmpPath, JSON.stringify(value, null, 2), 'utf-8');
+                node_fs__rspack_import_0.renameSync(tmpPath, filePath);
+                return true;
+            } catch  {
+                try {
+                    node_fs__rspack_import_0.rmSync(tmpPath, {
+                        force: true
+                    });
+                } catch  {}
+                return false;
+            }
+        }
+        __webpack_require__.d(__webpack_exports__, {
+            Z: ()=>writeJsonAtomic
+        });
+    },
     "./browsers/browsers-lib/wsl-support.ts" (__unused_rspack_module, __webpack_exports__, __webpack_require__) {
         __webpack_require__.d(__webpack_exports__, {
             qc: ()=>external_wsl_support_namespaceObject.hasGuiDisplay,
@@ -5807,7 +5833,6 @@ var __webpack_modules__ = {
             QW: ()=>safariBuildPreflight,
             iF: ()=>safariPreflightError
         });
-        var external_node_child_process_ = __webpack_require__("node:child_process");
         var external_node_fs_ = __webpack_require__("node:fs");
         var messaging = __webpack_require__("./helpers/messaging.ts");
         var banner = __webpack_require__("./browsers/browsers-lib/banner.ts");
@@ -5821,6 +5846,7 @@ var __webpack_modules__ = {
             (0, messaging._w)(messages.Aj(xcodebuildCmd));
         }
         var safari_config = __webpack_require__("./browsers/run-safari/safari-launch/safari-config.ts");
+        var external_node_child_process_ = __webpack_require__("node:child_process");
         function isMacOS() {
             return 'darwin' === process.platform;
         }
@@ -5878,20 +5904,6 @@ var __webpack_modules__ = {
                 ok: Boolean(converter && xcodebuild)
             };
         }
-        function fallbackLogger() {
-            return {
-                info: (...a)=>(0, messaging._w)(...a),
-                warn: (...a)=>(0, messaging.mR)(...a),
-                error: (...a)=>(0, messaging.Gg)(...a),
-                debug: (...a)=>console?.debug?.(...a)
-            };
-        }
-        function isTestEnv() {
-            return Boolean(process.env.VITEST || process.env.VITEST_WORKER_ID);
-        }
-        function delay(ms) {
-            return new Promise((resolve)=>setTimeout(resolve, ms));
-        }
         const TOOL_TAIL_LINES = 50;
         const TOOL_TAIL_BYTES = 8192;
         function toolOutputTail(output) {
@@ -5930,6 +5942,60 @@ var __webpack_modules__ = {
                     }));
             });
         }
+        async function resolvePidForBundle(bundleId) {
+            for(let attempt = 0; attempt < 10; attempt += 1){
+                const pid = await new Promise((resolve)=>{
+                    const child = (0, external_node_child_process_.spawn)("osascript", [
+                        '-e',
+                        `tell application "System Events" to get unix id of first process whose bundle identifier is "${bundleId}"`
+                    ]);
+                    let out = '';
+                    child.stdout.on('data', (d)=>out += String(d));
+                    child.on('error', ()=>resolve(null));
+                    child.on('close', ()=>{
+                        const n = Number(String(out).trim());
+                        resolve(Number.isFinite(n) && n > 0 ? n : null);
+                    });
+                });
+                if (pid) return pid;
+                await new Promise((r)=>setTimeout(r, 500));
+            }
+            return null;
+        }
+        function createSafariTools() {
+            return {
+                detectToolchain: ()=>detectSafariToolchain(),
+                runConverter: (args)=>runTool('xcrun', args),
+                runXcodebuild: (args)=>runTool('xcodebuild', args),
+                openApp: (target)=>runTool('open', [
+                        target
+                    ]),
+                openSafari: (binary)=>runTool('open', [
+                        '-a',
+                        binary
+                    ]),
+                resolvePid: (bundleId)=>resolvePidForBundle(bundleId),
+                pluginkitList: async ()=>{
+                    const { ok, output } = await runTool('pluginkit', [
+                        '-m'
+                    ], {
+                        quiet: true
+                    });
+                    return ok ? output : '';
+                }
+            };
+        }
+        function fallbackLogger() {
+            return {
+                info: (...a)=>(0, messaging._w)(...a),
+                warn: (...a)=>(0, messaging.mR)(...a),
+                error: (...a)=>(0, messaging.Gg)(...a),
+                debug: (...a)=>console?.debug?.(...a)
+            };
+        }
+        function delay(ms) {
+            return new Promise((resolve)=>setTimeout(resolve, ms));
+        }
         function converterWarnings(output) {
             const lines = output.split(/\r?\n/);
             const collected = [];
@@ -5950,15 +6016,11 @@ var __webpack_modules__ = {
             }
             return collected;
         }
-        async function confirmRegisteredWithSafari(bundleIdentifier) {
+        async function confirmRegisteredWithSafari(tools, bundleIdentifier) {
             const needle = `${bundleIdentifier}.Extension`;
             for(let attempt = 0; attempt < 6; attempt += 1){
-                const { ok, output } = await runTool('pluginkit', [
-                    '-m'
-                ], {
-                    quiet: true
-                });
-                if (ok && output.includes(needle)) return true;
+                const listing = await tools.pluginkitList();
+                if (listing.includes(needle)) return true;
                 await delay(800);
             }
             return false;
@@ -5973,6 +6035,10 @@ var __webpack_modules__ = {
                 macOsOnly: config.macOsOnly
             };
         }
+        function completePackage(config, logger, mode) {
+            if ('full' === mode && config.bundleIdDerived) logger.info?.(messages.$q(config.bundleIdentifier));
+            return describePackage(config);
+        }
         function safariPreflightError() {
             const tc = detectSafariToolchain();
             if (!tc.platformOk) return messages.G3(process.platform);
@@ -5996,26 +6062,6 @@ var __webpack_modules__ = {
                 severity: 'ok'
             };
         }
-        async function resolvePidForBundle(bundleId) {
-            for(let attempt = 0; attempt < 10; attempt += 1){
-                const pid = await new Promise((resolve)=>{
-                    const child = (0, external_node_child_process_.spawn)("osascript", [
-                        '-e',
-                        `tell application "System Events" to get unix id of first process whose bundle identifier is "${bundleId}"`
-                    ]);
-                    let out = '';
-                    child.stdout.on('data', (d)=>out += String(d));
-                    child.on('error', ()=>resolve(null));
-                    child.on('close', ()=>{
-                        const n = Number(String(out).trim());
-                        resolve(Number.isFinite(n) && n > 0 ? n : null);
-                    });
-                });
-                if (pid) return pid;
-                await new Promise((r)=>setTimeout(r, 500));
-            }
-            return null;
-        }
         async function announceSafariDevSession(host, config, appPath) {
             try {
                 await (0, banner.ai)({
@@ -6031,16 +6077,16 @@ var __webpack_modules__ = {
             } catch  {}
         }
         async function runSafariPipeline(compilation, host, logger, mode) {
+            const tools = host.tools || createSafariTools();
             const config = (0, safari_config.F7)(compilation, host);
             const converterArgs = (0, safari_config.w7)(config);
             const xcodebuildArgs = (0, safari_config.vx)(config);
             const isSigned = Boolean(config.developmentTeam);
-            if ('full' === mode && config.bundleIdDerived) logger.warn?.(messages.$q(config.bundleIdentifier));
-            if (host.dryRun || isTestEnv()) {
+            if (host.dryRun) {
                 logSafariDryRun(`xcrun ${converterArgs.join(' ')}`, `xcodebuild ${xcodebuildArgs.join(' ')}`);
-                return describePackage(config);
+                return completePackage(config, logger, mode);
             }
-            const toolchain = detectSafariToolchain();
+            const toolchain = tools.detectToolchain();
             if (!toolchain.platformOk) {
                 logger.warn?.(messages.G3(process.platform));
                 return describePackage(config);
@@ -6064,7 +6110,7 @@ var __webpack_modules__ = {
                 }
                 const { saved, restore } = (0, safari_config._D)(config);
                 logger.info?.(messages.uK(config.extensionDir));
-                const converted = await runTool('xcrun', converterArgs);
+                const converted = await tools.runConverter(converterArgs);
                 if (!converted.ok) {
                     const tail = toolOutputTail(converted.output);
                     logger.error?.(messages.A('safari-web-extension-converter', converted.code, tail));
@@ -6081,7 +6127,7 @@ var __webpack_modules__ = {
                 logger.info?.(messages.l_(config.projectLocation));
             } else if ('full' === mode) logger.info?.(messages.oM());
             if ('full' === mode) logger.info?.(messages.jR((0, safari_config.aD)(config)));
-            const built = await runTool('xcodebuild', xcodebuildArgs);
+            const built = await tools.runXcodebuild(xcodebuildArgs);
             if (!built.ok) {
                 const tail = toolOutputTail(built.output);
                 logger.error?.(messages.A('xcodebuild', built.code, tail));
@@ -6096,30 +6142,26 @@ var __webpack_modules__ = {
             if (!config.open) {
                 logger.info?.(messages.aO(appPath, config.appName));
                 if (host.announceDevReady) await announceSafariDevSession(host, config, appPath);
-                return describePackage(config);
+                return completePackage(config, logger, mode);
             }
             const target = external_node_fs_.existsSync(appPath) ? appPath : (0, safari_config.Gi)(config);
             logger.info?.(messages.fw(target));
-            await runTool('open', [
-                target
-            ]);
-            if (config.safariBinary) await runTool('open', [
-                '-a',
-                config.safariBinary
-            ]);
+            await tools.openApp(target);
+            if (config.safariBinary) await tools.openSafari(config.safariBinary);
             const raisedBundleId = config.safariBinary ? 'com.apple.Safari' : config.bundleIdentifier;
-            const browserPid = await resolvePidForBundle(raisedBundleId);
-            if (browserPid) (0, ready_stamp.M)(config.extensionDir, {
-                browserPid,
+            const browserPid = await tools.resolvePid(raisedBundleId);
+            (0, ready_stamp.M)(config.extensionDir, {
+                browserPid: browserPid || void 0,
                 binary: config.safariBinary || appPath,
                 binaryProvenance: config.safariBinary ? 'pinned' : 'system',
                 extensionId: `${config.bundleIdentifier}.Extension`
             });
+            if (!browserPid) logger.warn?.(messages.jn(config.appName));
             logger.info?.(messages.fO(config.appName, isSigned));
-            if (await confirmRegisteredWithSafari(config.bundleIdentifier)) logger.info?.(messages.fd(config.appName));
+            if (await confirmRegisteredWithSafari(tools, config.bundleIdentifier)) logger.info?.(messages.fd(config.appName));
             else logger.info?.(messages.qY(config.appName));
             if (host.announceDevReady) await announceSafariDevSession(host, config, appPath);
-            return describePackage(config);
+            return completePackage(config, logger, mode);
         }
         async function packageSafariExtension(host, outputPath, logger, mode = 'full') {
             const compilation = {
@@ -6239,9 +6281,10 @@ var __webpack_modules__ = {
         function manifestFingerprintPath(config) {
             return node_path__rspack_import_1.join(config.projectLocation, '.manifest-fingerprint');
         }
+        const HOT_UPDATE_DIR = 'hot';
         function topLevelEntries(extensionDir) {
             try {
-                return node_fs__rspack_import_0.readdirSync(extensionDir).sort();
+                return node_fs__rspack_import_0.readdirSync(extensionDir).filter((entry)=>entry !== HOT_UPDATE_DIR).sort();
             } catch  {
                 return [];
             }
@@ -6370,7 +6413,7 @@ var __webpack_modules__ = {
             return Object.fromEntries(Object.entries(input).filter(([, value])=>void 0 !== value));
         }
         function createSafariPackager(options = {}) {
-            const { browser = 'safari', noOpen = true, dryRun = false, logger, ...identity } = options;
+            const { browser = 'safari', noOpen = true, dryRun = false, logger, tools, ...identity } = options;
             return async (distPath, mode = 'full', overrides)=>await (0, _safari_launch__rspack_import_0.Ah)({
                     extension: [
                         distPath
@@ -6378,6 +6421,7 @@ var __webpack_modules__ = {
                     browser,
                     noOpen,
                     dryRun,
+                    tools,
                     ...withoutUndefined(identity),
                     ...withoutUndefined(overrides)
                 }, distPath, logger, mode);
@@ -6705,6 +6749,8 @@ var __webpack_modules__ = {
         const MIN_NODE_MINOR = 12;
         const MIN_DENO_MAJOR = 2;
         const MIN_DENO_MINOR = 5;
+        const MIN_BUN_MAJOR = 1;
+        const MIN_BUN_MINOR = 2;
         const BLOCKED_DENO_VERSIONS = [
             '2.8.0'
         ];
@@ -6721,6 +6767,9 @@ var __webpack_modules__ = {
             if (BLOCKED_DENO_VERSIONS.includes(version)) return false;
             return meetsFloor(version, MIN_DENO_MAJOR, MIN_DENO_MINOR);
         }
+        function isSupportedBunVersion(version) {
+            return meetsFloor(version, MIN_BUN_MAJOR, MIN_BUN_MINOR);
+        }
         function detectBunVersion(versions = process.versions) {
             const bunVersion = versions.bun;
             return 'string' == typeof bunVersion && bunVersion.length > 0 ? bunVersion : void 0;
@@ -6733,8 +6782,10 @@ var __webpack_modules__ = {
             if (BLOCKED_DENO_VERSIONS.includes(version)) return `[Extension.js] Deno ${version} cannot load node:querystring inside the bundler, so every build fails on it. Deno fixed that in 2.8.1. Run deno upgrade to build the extension on Deno.`;
             return `[Extension.js] Requires Deno >= ${MIN_DENO_MAJOR}.${MIN_DENO_MINOR} (you are on ${version}). Run deno upgrade, or run the extension CLI on Node.js >= ${MIN_NODE_MAJOR}.${MIN_NODE_MINOR} instead.`;
         }
-        function unsupportedNodeVersionMessage(version, bunVersion) {
-            if (bunVersion) return `[Extension.js] The extension CLI runs on Node.js, not on the Bun runtime (Bun ${bunVersion}, reporting Node.js ${version}), so the Node.js you have installed is not the problem. Run it on Node.js instead: drop --bun from bunx or bun run, or unset run.bun in bunfig.toml, plain bunx runs the extension CLI on Node.js.`;
+        function unsupportedBunVersionMessage(version) {
+            return `[Extension.js] Requires Bun >= ${MIN_BUN_MAJOR}.${MIN_BUN_MINOR} (you are on ${version}). Run bun upgrade, or run the extension CLI on Node.js >= ${MIN_NODE_MAJOR}.${MIN_NODE_MINOR} instead.`;
+        }
+        function unsupportedNodeVersionMessage(version) {
             return `[Extension.js] Requires Node.js >= ${MIN_NODE_MAJOR}.${MIN_NODE_MINOR} (you are on ${version}). Upgrade Node.js to run the extension CLI.`;
         }
         function enforceSupportedNodeVersion(version = process.versions.node, bunVersion = detectBunVersion(), denoVersion = detectDenoVersion()) {
@@ -6744,8 +6795,14 @@ var __webpack_modules__ = {
                 process.exit(1);
                 return;
             }
-            if (!bunVersion && isSupportedNodeVersion(version)) return;
-            console.error(unsupportedNodeVersionMessage(version, bunVersion));
+            if (bunVersion) {
+                if (isSupportedBunVersion(bunVersion)) return;
+                console.error(unsupportedBunVersionMessage(bunVersion));
+                process.exit(1);
+                return;
+            }
+            if (isSupportedNodeVersion(version)) return;
+            console.error(unsupportedNodeVersionMessage(version));
             process.exit(1);
         }
         enforceSupportedNodeVersion();
@@ -7141,7 +7198,7 @@ var __webpack_modules__ = {
             return Math.min(Math.max(n, min), max);
         }
         const TEMPLATE_CORPUS_REPO = 'extension-js/examples';
-        const TEMPLATE_CORPUS_REF = '39448a235ea1b02516e6d555bcae409db2258b7f';
+        const TEMPLATE_CORPUS_REF = '06d33e35894516a460409dca06d1614e291e6252';
         const TEMPLATE_CORPUS_SLUGS = [
             'action',
             'action-locales',
@@ -8254,7 +8311,10 @@ Docker / Devcontainers / Codespaces
 - Use ${messages_code('--host 0.0.0.0')} to bind the dev server on all interfaces so HMR is reachable from the host.
 - Use ${messages_code('--no-browser')} inside the container and load the extension manually from ${messages_code('dist/<browser>/')} in your host browser.
 - Chromium sandbox flags (${messages_code('--no-sandbox')}) are added automatically when Docker, Podman, devcontainers, or Codespaces are detected.
-- File watching uses polling by default (1 s interval), which works across bind-mounted volumes.
+- File watching uses native file events by default, which keeps rebuilds fast.
+- Set ${messages_code(messages_arg('EXTENSION_WATCH_POLL=true'))} to poll instead when native events do not fire,
+  as in a container, a virtual machine, or a network or bind mount.
+  Tune it with ${messages_code(messages_arg('EXTENSION_WATCH_POLL_INTERVAL'))} (default 1000 ms).
 - Example: ${messages_code('extension dev ./my-ext --host 0.0.0.0 --no-browser --port 8080')}
 
 Flatpak Firefox
@@ -8427,7 +8487,9 @@ Cross-browser compatibility
                         ],
                         notes: [
                             'Use --no-browser inside the container and load dist/<browser>/ in the host browser',
-                            'File watching uses polling (1s interval) for bind-mount compatibility',
+                            'File watching uses native file events by default',
+                            'Set EXTENSION_WATCH_POLL=true to poll instead when native events do not fire, as in a container, a virtual machine, or a network or bind mount',
+                            'EXTENSION_WATCH_POLL_INTERVAL sets the poll interval in ms (default 1000)',
                             '--no-sandbox is added automatically when a container environment is detected'
                         ]
                     }
@@ -8458,12 +8520,45 @@ Cross-browser compatibility
         }
         const OPEN_SURFACE_NOUN = {
             popup: 'popup',
+            options: 'options page',
             sidebar: 'side panel',
             action: 'action popup'
         };
         function openSurfaceNoun(surface) {
             return OPEN_SURFACE_NOUN[surface] || surface;
         }
+        function openSurfaceAction(surface) {
+            return 'command' === surface ? 'trigger the command' : `open the ${openSurfaceNoun(surface)}`;
+        }
+        function asSentence(text) {
+            const trimmed = text.trim();
+            const capitalized = trimmed.charAt(0).toUpperCase() + trimmed.slice(1);
+            return capitalized.endsWith('.') ? capitalized : `${capitalized}.`;
+        }
+        function listenerCount(count, event) {
+            return `${count} ${event} ${1 === count ? 'listener' : 'listeners'}`;
+        }
+        function openedSurface(surface) {
+            return `${getLoggingPrefix('success')} Opened the ${openSurfaceNoun(surface)}.`;
+        }
+        function replayedActionClick(listeners) {
+            return `${getLoggingPrefix('success')} Replayed ${listenerCount(listeners, 'onClicked')} without a user gesture.`;
+        }
+        function replayedCommand(listeners, command) {
+            const name = command ? ` for ${messages_arg(command)}` : '';
+            return `${getLoggingPrefix('success')} Replayed ${listenerCount(listeners, 'onCommand')}${name} without a user gesture.`;
+        }
+        function openSurfaceWarning(warning) {
+            return `${getLoggingPrefix('warn')} ${asSentence(warning)}`;
+        }
+        function openSurfaceFailed(surface, reason, engine, remedy) {
+            const engineNote = engine ? messages_arg(` (engine ${engine})`) : '';
+            return [
+                `${getLoggingPrefix('error')} Can't ${openSurfaceAction(surface)}.`,
+                `${messaging.Sc.label('REASON')} ${messaging.Sc.val(reason)}${engineNote}`,
+                remedy
+            ].filter(Boolean).join('\n');
+        }
         function openSurfaceGestureStep(surface) {
             return `Click the extension's toolbar entry, or its row in the extensions menu, to open the ${openSurfaceNoun(surface)}.`;
         }
@@ -8473,6 +8568,12 @@ Cross-browser compatibility
         function openSurfaceNeedsGesture(surface) {
             return `${getLoggingPrefix('error')} Chromium opens the ${openSurfaceNoun(surface)} only in response to a user gesture, so ${messages_code(`extension open ${surface}`)} can't open it from the command line.\n` + openSurfaceGestureStep(surface);
         }
+        function doctorHeader(browser, passes, total) {
+            return `doctor (${browser}), ${passes}/${total} checks passed`;
+        }
+        function doctorRemedy(check, remediation) {
+            return `\n${check}: ${remediation}`;
+        }
         function sessionOnPort(browser, port) {
             return port ? `for ${browser} on port ${port}` : `for ${browser}`;
         }
@@ -8735,11 +8836,20 @@ Cross-browser compatibility
             if ('json' === format) return void console.log(JSON.stringify(event, null, 2));
             console.log(formatPrettyLogLine(event));
         }
+        function levelToken(level) {
+            const word = level.toUpperCase();
+            if ('error' === level) return external_pintor_default().red(word);
+            if ('warn' === level) return external_pintor_default().brightYellow(word);
+            if ('info' === level) return external_pintor_default().gray(word);
+            if ('debug' === level) return external_pintor_default().dim(external_pintor_default().gray(word));
+            return word;
+        }
         function formatPrettyLogLine(event) {
             const parts = Array.isArray(event.messageParts) ? event.messageParts.map((p)=>'string' == typeof p ? p : JSON.stringify(p)).join(' ') : '';
             const code = event.code ? ` ${event.code}` : '';
             const remediation = event.remediation ? `\n    ↳ ${event.remediation}` : '';
-            return `[${event.seq ?? '-'}] ${String(event.level || 'log').toUpperCase()} (${event.context})${code} ${parts}${remediation}`;
+            const level = String(event.level || 'log').toLowerCase();
+            return `[${event.seq ?? '-'}] ${levelToken(level)} ${external_pintor_default().dim(`(${event.context})`)}${code} ${parts}${remediation}`;
         }
         function writeFrame(frame) {
             try {
@@ -8822,7 +8932,7 @@ Cross-browser compatibility
                     if (matches(event)) printEvent(event, format);
                 },
                 onGap: (gap)=>{
-                    console.error(`… ${gap.dropped} event(s) dropped (${gap.reason}), stream is behind`);
+                    console.error(external_pintor_default().dim(external_pintor_default().gray(`… ${gap.dropped} event(s) dropped (${gap.reason}), stream is behind`)));
                 },
                 onClose: (close)=>{
                     if (!refusals.has(close.code) && sessionStillNamed()) return;
@@ -8994,11 +9104,33 @@ Cross-browser compatibility
                 hint: openSurfaceGestureStep(surface)
             };
         }
-        function printResult(result, output, command) {
+        function openResultLines(value) {
+            if (!value || 'object' != typeof value) return;
+            const reply = value;
+            if ('string' == typeof reply.opened) return [
+                openedSurface(reply.opened)
+            ];
+            if ('popup' === reply.triggered) return [
+                openedSurface('action')
+            ];
+            if ('number' != typeof reply.listeners) return;
+            const lines = [];
+            if ('onClicked' === reply.triggered) lines.push(replayedActionClick(reply.listeners));
+            else {
+                if ('command' !== reply.triggered) return;
+                lines.push(replayedCommand(reply.listeners, 'string' == typeof reply.command ? reply.command : void 0));
+            }
+            if ('string' == typeof reply.warning && reply.warning) lines.push(openSurfaceWarning(reply.warning));
+            return lines;
+        }
+        function printResult(result, output, command, pretty) {
             if ('json' === normalizeOutputFormat(output)) return void console.log(JSON.stringify(buildActEnvelope(command, result)));
             if (result.ok) {
                 const value = result.value;
-                console.log('string' == typeof value ? value : JSON.stringify(value, null, 2));
+                const lines = pretty?.value(value) ?? [
+                    'string' == typeof value ? value : JSON.stringify(value, null, 2)
+                ];
+                for (const line of lines)console.log(line);
                 const consoleRecords = result.console;
                 if (Array.isArray(consoleRecords)) {
                     if (0 === consoleRecords.length) console.log('(no console lines captured)');
@@ -9007,6 +9139,11 @@ Cross-browser compatibility
                 if (result.truncated) console.error('… result truncated (byte cap)');
                 return;
             }
+            if (pretty) {
+                const { error } = buildActEnvelope(command, result);
+                console.error(pretty.failure(error));
+                return;
+            }
             const err = result.error || {
                 name: 'Error',
                 message: 'command failed'
@@ -9080,7 +9217,7 @@ Cross-browser compatibility
             if (result?.ok && input.augment) try {
                 Object.assign(result, input.augment(projectPath, browser, result));
             } catch  {}
-            printResult(result, input.opts.output, input.command);
+            printResult(result, input.opts.output, input.command, input.pretty);
             await exitAfterDrain(result.ok ? 0 : 1);
         }
         function targetFrom(opts, fallback = 'background') {
@@ -9225,7 +9362,11 @@ Cross-browser compatibility
                     },
                     args,
                     opts,
-                    preflight: (bridge, projectPath, browser)=>gestureRefusal(surface, bridge, projectPath, browser)
+                    preflight: (bridge, projectPath, browser)=>gestureRefusal(surface, bridge, projectPath, browser),
+                    pretty: {
+                        value: openResultLines,
+                        failure: (error)=>openSurfaceFailed(surface, error.message, error.engine, error.hint)
+                    }
                 });
             });
         }
@@ -9264,7 +9405,7 @@ Cross-browser compatibility
             return values.length > 0 ? values : void 0;
         }
         function registerBuildCommand(program) {
-            program.command('build').arguments('[project-name]').usage('[path-to-remote-extension] [options]').description(commandDescriptions.build).option(`--browser <${BROWSER_TARGETS_HELP}>`, 'specify a browser/engine to run. Defaults to `chromium`. `safari` builds a Safari app via Xcode (macOS only)').option('--polyfill [boolean]', 'whether or not to apply the cross-browser polyfill. Defaults to `false`', parseOptionalBoolean).option('--no-polyfill', 'disable the cross-browser polyfill').option('--zip [boolean]', 'whether or not to compress the extension into a ZIP file. Defaults to `false`', parseOptionalBoolean).option('--zip-source [boolean]', 'whether or not to include the source files in the ZIP file. Defaults to `false`', parseOptionalBoolean).option('--zip-filename <string>', 'specify the name of the ZIP file. Defaults to the extension name and version').option('--silent [boolean]', 'suppress the build summary output. Defaults to `false`', parseOptionalBoolean).option('--addon-lint [boolean]', 'check Firefox builds against addons.mozilla.org rules with addons-linter when it is installed. Findings print as warnings. Defaults to `true`', parseOptionalBoolean).option('--no-addon-lint', 'skip the addons.mozilla.org lint of Firefox builds').option('--install [boolean]', '[internal] install project dependencies when missing', parseOptionalBoolean).option('--extensions <list>', 'comma-separated list of companion extensions or store URLs to load').option('--mode <development|production|none>', 'bundler mode override (also sets NODE_ENV). Defaults to `production`').option('--open [boolean]', 'open the built Safari app after packaging (safari targets only). Defaults to `false`', parseOptionalBoolean).option('--app-name <name>', 'override the Safari app name (safari targets only). Defaults to the manifest `name`').option('--bundle-id <reverse.dns>', 'set a user-owned Safari bundle identifier (safari targets only). Defaults to a generated dev.extensionjs.* id').option('--development-team <id>', 'sign the Safari app with an Apple Developer team id (safari targets only). Without it the build is ad-hoc signed, which Safari loads locally with no per-launch toggle. Use a team id for a stable identity you can distribute').option('--macos-only [boolean]', 'generate a macOS-only Safari Xcode project (safari targets only). Pass `false` for a universal macOS + iOS project. Defaults to `true`', parseOptionalBoolean).option('--force-regenerate', 'regenerate the Safari Xcode project even when up to date (safari targets only)').option('--output <pretty|json>', 'result format. Use json for a schema-1 envelope on stdout').addOption(new external_commander_namespaceObject.Option('--debug', 'print maintainer diagnostics alongside normal output')).addOption(new external_commander_namespaceObject.Option('--author, --author-mode', 'deprecated alias for --debug').hideHelp()).action(async (pathOrRemoteUrl, { browser: cliBrowser, ...buildOptions })=>{
+            program.command('build').arguments('[project-name]').usage('[path-to-remote-extension] [options]').description(commandDescriptions.build).option(`--browser <${BROWSER_TARGETS_HELP}>`, 'specify a browser/engine to run. Defaults to `chromium`. `safari` builds a Safari app via Xcode (macOS only)').option('--polyfill [boolean]', 'whether or not to apply the cross-browser polyfill. Defaults to `false`', parseOptionalBoolean).option('--no-polyfill', 'disable the cross-browser polyfill').option('--zip [boolean]', 'whether or not to compress the extension into a ZIP file. Defaults to `false`', parseOptionalBoolean).option('--zip-source [boolean]', 'whether or not to include the source files in the ZIP file. Defaults to `false`', parseOptionalBoolean).option('--zip-filename <string>', 'specify the name of the ZIP file. Defaults to the extension name and version').option('--silent [boolean]', 'suppress the build summary output. Defaults to `false`', parseOptionalBoolean).option('--addon-lint [boolean]', 'check Firefox builds against addons.mozilla.org rules with addons-linter when it is installed. Findings print as warnings. Defaults to `true`', parseOptionalBoolean).option('--no-addon-lint', 'skip the addons.mozilla.org lint of Firefox builds').option('--install [boolean]', '[internal] install project dependencies when missing', parseOptionalBoolean).option('--extensions <list>', 'comma-separated list of companion extensions or store URLs to load').option('--mode <development|production|none>', 'bundler mode override (also sets NODE_ENV). Defaults to `production`').option('--open [boolean]', 'open the built Safari app after packaging (safari targets only). Defaults to `false`', parseOptionalBoolean).option('--app-name <name>', 'override the Safari app name (safari targets only). Defaults to the manifest `name`').option('--bundle-id <reverse.dns>', 'set a user-owned Safari bundle identifier (safari targets only). Defaults to a generated dev.extensionjs.* id shared by every build of the same source, so set your own before the first submission').option('--development-team <id>', 'sign the Safari app with an Apple Developer team id (safari targets only). Without it the build is ad-hoc signed, which Safari loads locally with no per-launch toggle. Use a team id for a stable identity you can distribute').option('--macos-only [boolean]', 'generate a macOS-only Safari Xcode project (safari targets only). Pass `false` for a universal macOS + iOS project. Defaults to `true`', parseOptionalBoolean).option('--force-regenerate', 'regenerate the Safari Xcode project even when up to date (safari targets only)').option('--output <pretty|json>', 'result format. Use json for a schema-1 envelope on stdout').addOption(new external_commander_namespaceObject.Option('--debug', 'print maintainer diagnostics alongside normal output')).addOption(new external_commander_namespaceObject.Option('--author, --author-mode', 'deprecated alias for --debug').hideHelp()).action(async (pathOrRemoteUrl, { browser: cliBrowser, ...buildOptions })=>{
                 const browser = cliBrowser ?? await resolveConfigBrowser(pathOrRemoteUrl || process.cwd(), 'build') ?? 'chromium';
                 if (buildOptions.debug || buildOptions.author || buildOptions.authorMode) {
                     process.env.EXTENSION_DEBUG = '1';
@@ -9826,37 +9967,45 @@ Cross-browser compatibility
         async function waitForReadyContract(options) {
             const readyPath = sessionReadyPath(options.bridge, options.projectPath, options.browser);
             const start = Date.now();
+            let lastReadFailure = '';
             while(Date.now() - start < options.timeoutMs){
-                if (external_node_fs_.existsSync(readyPath)) try {
-                    const payload = JSON.parse(external_node_fs_.readFileSync(readyPath, 'utf8'));
-                    const isLive = isProcessLikelyAlive(payload.pid);
-                    const isFresh = isFreshContractPayload(payload);
-                    if (payload.command !== options.command) {
-                        await new Promise((resolve)=>setTimeout(resolve, 250));
-                        continue;
+                if (external_node_fs_.existsSync(readyPath)) {
+                    let payload = null;
+                    try {
+                        payload = JSON.parse(external_node_fs_.readFileSync(readyPath, 'utf8'));
+                        lastReadFailure = '';
+                    } catch (error) {
+                        payload = null;
+                        lastReadFailure = error instanceof Error ? error.message : String(error);
                     }
-                    if (!isLive) {
-                        if ('start' !== options.command || !isFresh) {
+                    if (payload) {
+                        const isLive = isProcessLikelyAlive(payload.pid);
+                        const isFresh = isFreshContractPayload(payload);
+                        if (payload.command !== options.command) {
                             await new Promise((resolve)=>setTimeout(resolve, 250));
                             continue;
                         }
-                    }
-                    if ('ready' === payload.status) return payload;
-                    if ('error' === payload.status) {
-                        if (!isLive && 'start' !== options.command) {
-                            await new Promise((resolve)=>setTimeout(resolve, 250));
-                            continue;
+                        if (!isLive) {
+                            if ('start' !== options.command || !isFresh) {
+                                await new Promise((resolve)=>setTimeout(resolve, 250));
+                                continue;
+                            }
+                        }
+                        if ('ready' === payload.status) return payload;
+                        if ('error' === payload.status) {
+                            if (!isLive && 'start' !== options.command) {
+                                await new Promise((resolve)=>setTimeout(resolve, 250));
+                                continue;
+                            }
+                            const detail = payload.message || payload.errors?.[0] || 'unknown error';
+                            throw new WaitModeError(String(detail), messaging.Lp.E_INTERNAL);
                         }
-                        const detail = payload.message || payload.errors?.[0] || 'unknown error';
-                        throw new WaitModeError(String(detail), messaging.Lp.E_INTERNAL);
                     }
-                } catch (error) {
-                    if (error instanceof Error) throw error;
-                    throw new Error(String(error));
                 }
                 await new Promise((resolve)=>setTimeout(resolve, 250));
             }
-            throw new WaitModeError(`Timed out waiting for ready contract at ${readyPath} (${options.timeoutMs} ms)`, messaging.Lp.E_READY_TIMEOUT);
+            const timeoutDetail = lastReadFailure ? `. The last read of the file failed to parse as JSON: ${lastReadFailure}` : '';
+            throw new WaitModeError(`Timed out waiting for ready contract at ${readyPath} (${options.timeoutMs} ms)${timeoutDetail}`, messaging.Lp.E_READY_TIMEOUT);
         }
         async function runWaitMode(options) {
             if (isHttpUrl(options.pathOrRemoteUrl)) throw new WaitModeError('--wait requires a local project path (remote URLs are not supported)', messaging.Lp.E_ARGS);
@@ -9900,7 +10049,7 @@ Cross-browser compatibility
             return Number.isFinite(parsed) && parsed >= 0 ? Math.floor(parsed) : 8080;
         }
         function registerDevCommand(program) {
-            program.command('dev').arguments('[project-path|remote-url]').usage('[project-path|remote-url] [options]').description(commandDescriptions.dev).addHelpText('after', "\nAdditional options:\n  --no-browser    stop the browser launch, the dev server still starts\n  --no-reload     emit a dev-mode dist without the content-script reload runtime, tabs need a manual reload to see changes\n  --wait          wait for ready contract and exit, pair with --output json for machine output\n" + BROWSER_LAUNCH_HELP_FOOTER).option('--profile <path-to-file | boolean>', 'what path to use for the browser profile. A boolean value of false sets the profile to the default user profile. Defaults to a fresh profile').option(`-b, --browser <${BROWSER_TARGETS_HELP}>`, 'specify a browser/engine to run. Defaults to `chromium`. `safari` builds and opens a Safari app via Xcode (macOS only)').option('--chromium-binary <path-to-binary>', 'specify a path to the Chromium binary. This option overrides the --browser setting. Defaults to the system default').addOption(geckoBinaryOption()).addOption(firefoxBinaryAliasOption()).option('--safari-binary <path-to-binary>', 'specify the Safari binary to open after packaging (safari targets only)').option('--app-name <name>', 'override the Safari app name (safari targets only). Defaults to the manifest `name`').option('--bundle-id <reverse.dns>', 'set a user-owned Safari bundle identifier (safari targets only). Defaults to a generated dev.extensionjs.* id').option('--development-team <id>', 'sign the Safari app with an Apple Developer team id (safari targets only). Without it the build is ad-hoc signed, which Safari loads locally with no per-launch toggle. Use a team id for a stable identity you can distribute').option('--macos-only [boolean]', 'generate a macOS-only Safari Xcode project (safari targets only). Pass `false` for a universal macOS + iOS project. Defaults to `true`', parseOptionalBoolean).option('--force-regenerate', 'regenerate the Safari Xcode project even when up to date (safari targets only)').option('--polyfill [boolean]', 'whether or not to apply the cross-browser polyfill. Defaults to `true`', parseOptionalBoolean).option('--no-polyfill', 'disable the cross-browser polyfill').option('--no-open', NO_OPEN_FLAG_DESCRIPTION).option('--starting-url <url>', 'specify the starting URL for the browser. Defaults to `undefined`').option('--port <port>', 'specify the port to use for the development server. Defaults to `8080`').option('--host <host>', 'specify the host to bind the dev server to. Use 0.0.0.0 for Docker/devcontainers. Defaults to `127.0.0.1`').option('--public-host <host>', 'connectable host the browser (HMR + reload bridge) dials when it differs from the bind host (e.g. a remote/devcontainer). Defaults to the bind host, or 127.0.0.1 when bound to 0.0.0.0').option('--log-context <list>', '[experimental] comma-separated contexts to include (background,content,page,sidebar,popup,options,devtools). Use `all` to include all contexts (default)').option('--logs <off|error|warn|info|debug|trace|all>', '[experimental] minimum centralized logger level to display in terminal (default: off)').option('--log-format <pretty|json|ndjson>', '[experimental] output format for logger events. Defaults to `pretty`').option('--no-log-timestamps', 'disable ISO timestamps in pretty output').option('--no-log-color', 'disable color in pretty output').option('--log-url <pattern>', '[experimental] only show logs where event.url matches this substring or regex (/re/i)').option('--log-tab <id>', 'only show logs for a specific tabId (number)').option('--extensions <list>', 'comma-separated list of companion extensions or store URLs to load').option('--install [boolean]', '[internal] install project dependencies when missing', parseOptionalBoolean).option('--wait [boolean]', 'wait for dist/extension-js/<browser>/ready.json and exit', parseOptionalBoolean).option('--wait-timeout <ms>', 'timeout in milliseconds when using --wait (default: 60000)').option('--output <pretty|json>', 'result format. Use json for a schema-1 envelope on stdout').addOption(new external_commander_namespaceObject.Option('--wait-format <pretty|json>').hideHelp()).addOption(new external_commander_namespaceObject.Option('--debug', 'print maintainer diagnostics alongside normal output')).addOption(new external_commander_namespaceObject.Option('--author, --author-mode', 'deprecated alias for --debug').hideHelp()).option('--allow-control', 'enable the agent-bridge control channel for bounded act (storage/reload/open): see `extension reload|storage|open`').option('--allow-eval', 'additionally enable `extension eval` (implies --allow-control, runs arbitrary code in a context, writes a 0600 session token)').option('--parent-pid <pid>', 'exit when the given process dies. For wrappers that spawn `extension dev`, so a leaked dev server can never outlive its owner').action(async (pathOrRemoteUrl, options, command)=>{
+            program.command('dev').arguments('[project-path|remote-url]').usage('[project-path|remote-url] [options]').description(commandDescriptions.dev).addHelpText('after', "\nAdditional options:\n  --no-browser    stop the browser launch, the dev server still starts\n  --no-reload     emit a dev-mode dist without the content-script reload runtime, tabs need a manual reload to see changes\n  --wait          wait for ready contract and exit, pair with --output json for machine output\n" + BROWSER_LAUNCH_HELP_FOOTER).option('--profile <path-to-file | boolean>', 'what path to use for the browser profile. A boolean value of false sets the profile to the default user profile. Defaults to a fresh profile').option(`-b, --browser <${BROWSER_TARGETS_HELP}>`, 'specify a browser/engine to run. Defaults to `chromium`. `safari` builds and opens a Safari app via Xcode (macOS only)').option('--chromium-binary <path-to-binary>', 'specify a path to the Chromium binary. This option overrides the --browser setting. Defaults to the system default').addOption(geckoBinaryOption()).addOption(firefoxBinaryAliasOption()).option('--safari-binary <path-to-binary>', 'specify the Safari binary to open after packaging (safari targets only)').option('--app-name <name>', 'override the Safari app name (safari targets only). Defaults to the manifest `name`').option('--bundle-id <reverse.dns>', 'set a user-owned Safari bundle identifier (safari targets only). Defaults to a generated dev.extensionjs.* id shared by every build of the same source, so set your own before the first submission').option('--development-team <id>', 'sign the Safari app with an Apple Developer team id (safari targets only). Without it the build is ad-hoc signed, which Safari loads locally with no per-launch toggle. Use a team id for a stable identity you can distribute').option('--macos-only [boolean]', 'generate a macOS-only Safari Xcode project (safari targets only). Pass `false` for a universal macOS + iOS project. Defaults to `true`', parseOptionalBoolean).option('--force-regenerate', 'regenerate the Safari Xcode project even when up to date (safari targets only)').option('--polyfill [boolean]', 'whether or not to apply the cross-browser polyfill. Defaults to `true`', parseOptionalBoolean).option('--no-polyfill', 'disable the cross-browser polyfill').option('--no-open', NO_OPEN_FLAG_DESCRIPTION).option('--starting-url <url>', 'specify the starting URL for the browser. Defaults to `undefined`').option('--port <port>', 'specify the port to use for the development server. Defaults to `8080`').option('--host <host>', 'specify the host to bind the dev server to. Use 0.0.0.0 for Docker/devcontainers. Defaults to `127.0.0.1`').option('--public-host <host>', 'connectable host the browser (HMR + reload bridge) dials when it differs from the bind host (e.g. a remote/devcontainer). Defaults to the bind host, or 127.0.0.1 when bound to 0.0.0.0').option('--log-context <list>', '[experimental] comma-separated contexts to include (background,content,page,sidebar,popup,options,devtools). Use `all` to include all contexts (default)').option('--logs <off|error|warn|info|debug|trace|all>', '[experimental] minimum centralized logger level to display in terminal (default: off)').option('--log-format <pretty|json|ndjson>', '[experimental] output format for logger events. Defaults to `pretty`').option('--no-log-timestamps', 'disable ISO timestamps in pretty output').option('--no-log-color', 'disable color in pretty output').option('--log-url <pattern>', '[experimental] only show logs where event.url matches this substring or regex (/re/i)').option('--log-tab <id>', 'only show logs for a specific tabId (number)').option('--extensions <list>', 'comma-separated list of companion extensions or store URLs to load').option('--install [boolean]', '[internal] install project dependencies when missing', parseOptionalBoolean).option('--wait [boolean]', 'wait for dist/extension-js/<browser>/ready.json and exit', parseOptionalBoolean).option('--wait-timeout <ms>', 'timeout in milliseconds when using --wait (default: 60000)').option('--output <pretty|json>', 'result format. Use json for a schema-1 envelope on stdout').addOption(new external_commander_namespaceObject.Option('--wait-format <pretty|json>').hideHelp()).addOption(new external_commander_namespaceObject.Option('--debug', 'print maintainer diagnostics alongside normal output')).addOption(new external_commander_namespaceObject.Option('--author, --author-mode', 'deprecated alias for --debug').hideHelp()).option('--allow-control', 'enable the agent-bridge control channel for bounded act (storage/reload/open): see `extension reload|storage|open`').option('--allow-eval', 'additionally enable `extension eval` (implies --allow-control, runs arbitrary code in a context, writes a 0600 session token)').option('--parent-pid <pid>', 'exit when the given process dies. For wrappers that spawn `extension dev`, so a leaked dev server can never outlive its owner').action(async (pathOrRemoteUrl, options, command)=>{
                 const { browser: cliBrowser, ...devOptions } = options;
                 const browser = cliBrowser ?? await resolveConfigBrowser(pathOrRemoteUrl || process.cwd(), 'dev') ?? 'chromium';
                 if (devOptions.debug || devOptions.author || devOptions.authorMode) {
@@ -10356,19 +10505,19 @@ Cross-browser compatibility
             });
             return results;
         }
+        function checkGlyph(status) {
+            if ('pass' === status) return external_pintor_default().green('✓');
+            if ('fail' === status) return external_pintor_default().red('✗');
+            if ('warn' === status) return external_pintor_default().brightYellow('!');
+            return external_pintor_default().gray('–');
+        }
         function printPretty(results, browser) {
             const passes = results.filter((r)=>'pass' === r.status).length;
-            const glyph = {
-                pass: '✓',
-                fail: '✗',
-                warn: '!',
-                skip: '–'
-            };
-            console.log(`doctor (${browser}), ${passes}/${results.length} checks passed`);
+            console.log(doctorHeader(browser, passes, results.length));
             const width = Math.max(...results.map((r)=>r.check.length));
-            for (const r of results)console.log(`  ${glyph[r.status]} ${r.check.padEnd(width)}  ${r.detail}`);
+            for (const r of results)console.log(`  ${checkGlyph(r.status)} ${r.check.padEnd(width)}  ${r.detail}`);
             const advisory = results.find((r)=>'fail' === r.status) ?? results.find((r)=>'warn' === r.status);
-            if (advisory?.remediation) console.log(`\n${advisory.check}: ${advisory.remediation}`);
+            if (advisory?.remediation) console.log(doctorRemedy(advisory.check, advisory.remediation));
         }
         const CHECK_CODES = {
             'ready-contract': messaging.Lp.E_SESSION_NOT_FOUND,