extension 4.1.19 → 4.1.21

package/dist/cli.cjs

@@ -741,16 +741,19 @@ var __webpack_modules__ = {
             const tail = outputTail.trim().length ? `\n${pintor__rspack_import_8_default().gray('── last output ──')}\n${outputTail}` : `\n${pintor__rspack_import_8_default().gray('(no output captured)')}`;
             return `${getLoggingPrefix('error')} Safari packaging tool ${pintor__rspack_import_8_default().underline(tool)} failed (${pintor__rspack_import_8_default().red(code)}).${tail}`;
         }
+        const SAFARI_KEPT_ON_PURPOSE = {
+            world: 'Safari has honored the MAIN world since Safari 18, so the key stays'
+        };
         function safariConverterWarnings(warnings) {
-            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');
+            const kept = warnings.map((line)=>line.trim()).filter((line)=>line in SAFARI_KEPT_ON_PURPOSE);
+            const keptLines = kept.map((line)=>`  ${pintor__rspack_import_8_default().yellow(line)} ${pintor__rspack_import_8_default().gray(SAFARI_KEPT_ON_PURPOSE[line])}`).join('\n');
+            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, signed) {
-            const launch = `${getLoggingPrefix('info')} Launch it once to register with Safari: ${pintor__rspack_import_8_default().blue('open')} ${pintor__rspack_import_8_default().underline(`"${appPath}"`)}\n`;
-            if (signed) return launch + `Then turn on ${pintor__rspack_import_8_default().yellow(appName)} in Safari ▸ Settings ▸ Extensions.`;
-            return launch + `Then enable ${pintor__rspack_import_8_default().yellow(appName)} via Safari ▸ Develop ▸ ` + `${pintor__rspack_import_8_default().yellow('Allow Unsigned Extensions')} and Safari ▸ Settings ▸ Extensions.`;
+        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.`;
         }
         function safariDryRunNotBuilding() {
             return `${getLoggingPrefix('info')} Dry run: skip the Safari app build.`;
@@ -762,17 +765,21 @@ var __webpack_modules__ = {
             return `${getLoggingPrefix('info')} xcodebuild: ${pintor__rspack_import_8_default().gray(cmd)}.`;
         }
         function safariNextSteps(appName, signed) {
-            if (signed) return `${getLoggingPrefix('info')} One-time setup to load ${pintor__rspack_import_8_default().yellow(appName)} in Safari:\n  ${pintor__rspack_import_8_default().gray('1.')} Safari ▸ Settings ▸ Extensions ▸ turn on ${pintor__rspack_import_8_default().yellow(appName)}\n  ${pintor__rspack_import_8_default().gray('→')} Signed with your team id, so this survives a restart.`;
-            return `${getLoggingPrefix('info')} One-time setup to load ${pintor__rspack_import_8_default().yellow(appName)} in Safari:\n  ${pintor__rspack_import_8_default().gray('1.')} Safari ▸ Settings ▸ Advanced ▸ check ${pintor__rspack_import_8_default().yellow('“Show features for web developers”')}\n  ${pintor__rspack_import_8_default().gray('2.')} Safari ▸ Develop ▸ ${pintor__rspack_import_8_default().yellow('Allow Unsigned Extensions')} ${pintor__rspack_import_8_default().gray('(resets each launch)')}\n  ${pintor__rspack_import_8_default().gray('3.')} Safari ▸ Settings ▸ Extensions ▸ turn on ${pintor__rspack_import_8_default().yellow(appName)}\n  ${pintor__rspack_import_8_default().gray('→')} The app window that just opened can also take you there.`;
+            const steps = `${getLoggingPrefix('info')} One-time setup to load ${pintor__rspack_import_8_default().yellow(appName)} in Safari:\n  ${pintor__rspack_import_8_default().gray('1.')} Safari ▸ Settings ▸ Extensions ▸ turn on ${pintor__rspack_import_8_default().yellow(appName)}\n`;
+            if (signed) return steps + `  ${pintor__rspack_import_8_default().gray('→')} Signed with your team id, so the identity is stable for distribution.`;
+            return steps + `  ${pintor__rspack_import_8_default().gray('→')} Ad-hoc signed, so it stays enabled across restarts.`;
         }
         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.`;
         }
         function safariRebuilt(appName) {
-            return `${getLoggingPrefix('success')} Rebuilt ${pintor__rspack_import_8_default().yellow(appName)}, reload the page (or toggle the extension) in Safari to see changes.`;
+            return `${getLoggingPrefix('success')} Rebuilt ${pintor__rspack_import_8_default().yellow(appName)}.`;
         }
         function safariProjectStale() {
             return `${getLoggingPrefix('info')} Regenerating the Xcode project, manifest.json or identity options changed since it was generated.`;
@@ -1029,6 +1036,7 @@ var __webpack_modules__ = {
             jR: ()=>safariBuilding,
             jc: ()=>safariProjectStale,
             jk: ()=>requireGeckoBinaryForGeckoBased,
+            jn: ()=>safariPidUnresolved,
             kK: ()=>preferringSystemBrowserOverSnapshot,
             l9: ()=>parsingPacketError,
             lO: ()=>firefoxDryRunArgs,
@@ -1401,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');
         }
@@ -1412,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) {
@@ -1430,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) {
@@ -1442,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) {
@@ -1457,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) {
@@ -1471,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) {
@@ -1487,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__, {
@@ -1951,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,
@@ -5803,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");
@@ -5817,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;
         }
@@ -5874,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) {
@@ -5926,18 +5942,85 @@ 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) {
-            return output.split(/\r?\n/).filter((line)=>/warning/i.test(line)).map((line)=>line.trim()).filter((line)=>line.length > 0);
+            const lines = output.split(/\r?\n/);
+            const collected = [];
+            let inWarning = false;
+            for (const line of lines){
+                const trimmed = line.trim();
+                if (/warning/i.test(line)) {
+                    inWarning = true;
+                    if (trimmed.length > 0) collected.push(trimmed);
+                    continue;
+                }
+                const isContinuation = inWarning && /^\s/.test(line) && trimmed.length > 0;
+                if (isContinuation) {
+                    collected.push(trimmed);
+                    continue;
+                }
+                inWarning = false;
+            }
+            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;
@@ -5952,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);
@@ -5975,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)({
@@ -6010,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);
@@ -6043,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));
@@ -6058,9 +6125,9 @@ var __webpack_modules__ = {
                 if (preservedKeys.length > 0) logger.info?.(messages.oB(preservedKeys));
                 (0, safari_config.x7)(config);
                 logger.info?.(messages.l_(config.projectLocation));
-            } else logger.info?.(messages.oM());
+            } 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));
@@ -6073,32 +6140,28 @@ var __webpack_modules__ = {
             }
             logger.info?.(messages.Rl(appPath));
             if (!config.open) {
-                logger.info?.(messages.aO(appPath, config.appName, isSigned));
+                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 = {
@@ -6218,36 +6281,56 @@ var __webpack_modules__ = {
         function manifestFingerprintPath(config) {
             return node_path__rspack_import_1.join(config.projectLocation, '.manifest-fingerprint');
         }
-        function stableStringify(obj) {
-            if (null == obj) return JSON.stringify(obj);
-            if ('object' != typeof obj) return JSON.stringify(obj);
-            if (Array.isArray(obj)) return `[${obj.map(stableStringify).join(',')}]`;
-            const keys = Object.keys(obj).sort();
-            return `{${keys.map((k)=>`${JSON.stringify(k)}:${stableStringify(obj[k])}`).join(',')}}`;
-        }
-        function readManifestRaw(extensionDir) {
+        const HOT_UPDATE_DIR = 'hot';
+        function topLevelEntries(extensionDir) {
             try {
-                return node_fs__rspack_import_0.readFileSync(node_path__rspack_import_1.join(extensionDir, 'manifest.json'), 'utf8');
+                return node_fs__rspack_import_0.readdirSync(extensionDir).filter((entry)=>entry !== HOT_UPDATE_DIR).sort();
             } catch  {
-                return '';
+                return [];
             }
         }
-        function normalizeManifest(raw) {
+        function iconsFingerprint(extensionDir) {
             try {
-                return stableStringify(JSON.parse(raw));
+                const raw = node_fs__rspack_import_0.readFileSync(node_path__rspack_import_1.join(extensionDir, 'manifest.json'), 'utf8');
+                const icons = JSON.parse(raw).icons;
+                if (!icons || 'object' != typeof icons) return '';
+                return Object.keys(icons).sort().map((size)=>`${size}:${String(icons[size])}`).join(',');
             } catch  {
-                return raw;
+                return '';
+            }
+        }
+        function asRecord(value) {
+            return value && 'object' == typeof value && !Array.isArray(value) ? value : {};
+        }
+        function judgedManifestSurface(extensionDir) {
+            const manifest = readManifest(extensionDir);
+            const parts = [
+                Object.keys(manifest).sort().join(',')
+            ];
+            for (const listName of [
+                'permissions',
+                'optional_permissions'
+            ]){
+                const list = manifest[listName];
+                const names = Array.isArray(list) ? list.filter((entry)=>'string' == typeof entry).sort() : [];
+                parts.push(`${listName}:${names.join(',')}`);
             }
+            const contentScripts = manifest.content_scripts;
+            if (Array.isArray(contentScripts)) parts.push(contentScripts.map((entry)=>Object.keys(asRecord(entry)).sort().join('+')).join(';'));
+            parts.push(Object.keys(asRecord(manifest.options_ui)).sort().join(','));
+            return parts.join('|');
         }
         function composeProjectFingerprint(config) {
             return JSON.stringify({
-                v: 2,
+                v: 4,
                 identity: {
                     appName: config.appName,
                     bundleId: config.bundleIdentifier,
                     macOsOnly: config.macOsOnly
                 },
-                manifest: normalizeManifest(readManifestRaw(config.extensionDir))
+                entries: topLevelEntries(config.extensionDir),
+                icons: iconsFingerprint(config.extensionDir),
+                judged: judgedManifestSurface(config.extensionDir)
             });
         }
         function saveManifestFingerprint(config) {
@@ -6330,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
@@ -6338,6 +6421,7 @@ var __webpack_modules__ = {
                     browser,
                     noOpen,
                     dryRun,
+                    tools,
                     ...withoutUndefined(identity),
                     ...withoutUndefined(overrides)
                 }, distPath, logger, mode);
@@ -6663,23 +6747,62 @@ var __webpack_modules__ = {
     "./index.ts" (__unused_rspack_module, __unused_rspack___webpack_exports__, __webpack_require__) {
         const MIN_NODE_MAJOR = 22;
         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'
+        ];
+        function meetsFloor(version, major, minor) {
+            const [actualMajor, actualMinor] = version.split('.').map((part)=>parseInt(part, 10));
+            if (!Number.isFinite(actualMajor)) return true;
+            if (actualMajor !== major) return actualMajor > major;
+            return (Number.isFinite(actualMinor) ? actualMinor : 0) >= minor;
+        }
         function isSupportedNodeVersion(version) {
-            const [major, minor] = version.split('.').map((part)=>parseInt(part, 10));
-            if (!Number.isFinite(major)) return true;
-            if (major !== MIN_NODE_MAJOR) return major > MIN_NODE_MAJOR;
-            return (Number.isFinite(minor) ? minor : 0) >= MIN_NODE_MINOR;
+            return meetsFloor(version, MIN_NODE_MAJOR, MIN_NODE_MINOR);
+        }
+        function isSupportedDenoVersion(version) {
+            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;
         }
-        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 detectDenoVersion(versions = process.versions) {
+            const denoVersion = versions.deno;
+            return 'string' == typeof denoVersion && denoVersion.length > 0 ? denoVersion : void 0;
+        }
+        function unsupportedDenoVersionMessage(version) {
+            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 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()) {
-            if (!bunVersion && isSupportedNodeVersion(version)) return;
-            console.error(unsupportedNodeVersionMessage(version, bunVersion));
+        function enforceSupportedNodeVersion(version = process.versions.node, bunVersion = detectBunVersion(), denoVersion = detectDenoVersion()) {
+            if (denoVersion) {
+                if (isSupportedDenoVersion(denoVersion)) return;
+                console.error(unsupportedDenoVersionMessage(denoVersion));
+                process.exit(1);
+                return;
+            }
+            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();
@@ -7075,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 = 'e552f6db6f2862093ba9d7026e0d376f002d95cc';
+        const TEMPLATE_CORPUS_REF = '06d33e35894516a460409dca06d1614e291e6252';
         const TEMPLATE_CORPUS_SLUGS = [
             'action',
             'action-locales',
@@ -8066,7 +8189,7 @@ AI assistants
             return `${getLoggingPrefix('error')} Can't use ${messages_code(bundleId)} as a bundle identifier.\nUse reverse-DNS form: dot-separated segments of letters, digits and hyphens, each starting with a letter (e.g. ${messages_code('com.example.my-extension')}).`;
         }
         function safariCommandNotSupported(command) {
-            return `${getLoggingPrefix('error')} ${messages_code(command)} can't load an extension into Safari automatically.\nSafari extensions ship inside a signed app and are enabled by hand, so there's no live browser session to load into, unlike Chromium and Firefox.\nBuild the Safari app instead: ${messages_code('extension build --browser safari')}\nThen open the generated app and enable it in Safari → Settings → Extensions.`;
+            return `${getLoggingPrefix('error')} ${messages_code(command)} can't load an extension into Safari.\nSafari loads an extension only from an app it has registered, and that app is enabled by hand once installed.\nIts automation route can load a folder but grants no website access, so content scripts never run.\nRun a live Safari session: ${messages_code('extension dev --browser safari')}\nOr package the app and open it: ${messages_code('extension build --browser safari --open')}\nBoth need macOS with Xcode, and Safari takes the enable gesture once in Safari ▸ Settings ▸ Extensions.`;
         }
         function programAIHelp() {
             return `\n${getLoggingPrefix('info')} ${external_pintor_default().gray('Development tips for extension developers and AI assistants')}
@@ -8188,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
@@ -8361,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'
                         ]
                     }
@@ -8392,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)}.`;
         }
@@ -8407,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}`;
         }
@@ -8483,6 +8650,96 @@ Cross-browser compatibility
         function sessionLogsPath(bridge, projectPath, browser) {
             return sessionFilePath(bridge, 'logsPath', projectPath, browser, 'logs.ndjson');
         }
+        function isSafariVendor(value) {
+            return 'safari' === value || 'webkit-based' === value;
+        }
+        const SUPPORTED_BROWSER_TARGETS = [
+            'chrome',
+            'chromium',
+            'edge',
+            'firefox',
+            'brave',
+            'opera',
+            'vivaldi',
+            'yandex',
+            'waterfox',
+            'librewolf',
+            'chromium-based',
+            'gecko-based',
+            'firefox-based',
+            'safari',
+            'webkit-based'
+        ];
+        const BROWSER_TARGETS_HELP = SUPPORTED_BROWSER_TARGETS.join(' | ');
+        const SESSION_BROWSER_TARGETS_HELP = "chrome | chromium | edge | firefox | safari";
+        const NO_SAFARI_BROWSER_TARGETS_HELP = SUPPORTED_BROWSER_TARGETS.filter((target)=>!isSafariVendor(target)).join(' | ');
+        function parseOptionalBoolean(value) {
+            if (void 0 === value) return true;
+            const normalized = String(value).trim().toLowerCase();
+            return ![
+                'false',
+                '0',
+                'no',
+                'off'
+            ].includes(normalized);
+        }
+        const vendors = (browser)=>{
+            const value = browser ?? 'chromium';
+            return 'all' === value ? [
+                'chrome',
+                'edge',
+                'firefox'
+            ] : String(value).split(',').map((part)=>part.trim()).filter(Boolean);
+        };
+        const MANAGED_INSTALL_TARGETS = [
+            'chrome',
+            'chromium',
+            'edge',
+            'firefox',
+            'chromium-based',
+            'gecko-based',
+            'firefox-based'
+        ];
+        const MANAGED_INSTALL_TARGETS_HELP = [
+            ...MANAGED_INSTALL_TARGETS,
+            'all'
+        ].join(' | ');
+        const MANAGED_INSTALL_BINARIES = [
+            'chrome',
+            'chromium',
+            'edge',
+            'firefox'
+        ];
+        const installTargets = (browser)=>'all' === browser ? [
+                ...MANAGED_INSTALL_BINARIES
+            ] : vendors(browser);
+        function validateVendors(vendorsList, onInvalid) {
+            const supported = SUPPORTED_BROWSER_TARGETS;
+            for (const v of vendorsList)if (!supported.includes(v)) {
+                onInvalid(v, supported);
+                return false;
+            }
+            return true;
+        }
+        const MANAGED_INSTALL_TARGET_SET = new Set(MANAGED_INSTALL_TARGETS);
+        const SUPPORTED_BROWSER_TARGET_SET = new Set(SUPPORTED_BROWSER_TARGETS);
+        function classifyManagedInstallTarget(name) {
+            const value = String(name || '').trim().toLowerCase();
+            if (!value) return 'unknown';
+            if (MANAGED_INSTALL_TARGET_SET.has(value)) return 'managed';
+            if (SUPPORTED_BROWSER_TARGET_SET.has(value)) return 'not-installable';
+            return 'unknown';
+        }
+        function firstNonManagedInstallTarget(targetsList) {
+            for (const name of targetsList){
+                const kind = classifyManagedInstallTarget(name);
+                if ('managed' !== kind) return {
+                    name,
+                    kind
+                };
+            }
+            return null;
+        }
         function parseLogSinceLocal(value) {
             if (null == value || '' === value) return null;
             if ('number' == typeof value) return Number.isFinite(value) ? {
@@ -8579,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 {
@@ -8593,7 +8859,7 @@ Cross-browser compatibility
             }
         }
         function registerLogsCommand(program) {
-            program.command('logs').arguments('[project-path]').usage('[project-path] [options]').description(commandDescriptions.logs).option('--browser <chrome | chromium | edge | firefox>', 'which dist/extension-js/<browser> to read. Defaults to `chromium`').option('--follow', 'stream live via the control channel instead of printing and exiting').option('--context <list>', 'comma-separated contexts (background, content, popup, options, sidebar, devtools, page)').option('--level <off|error|warn|info|debug|trace|all>', 'minimum severity to show. Defaults to `all`').option('--signals-only', '[experimental] show only structured dx.signal diagnostics. No emitter ships yet, so this currently prints nothing').option('--since <seq|iso>', 'only show events after this sequence number or ISO timestamp').option('--url <glob|substring>', 'only events whose url/hostname matches (glob with * or plain substring)').option('--tab <id>', 'only events from this tab id').option('--output <pretty|json|ndjson>', 'output format. Defaults to pretty on a TTY, ndjson when piped').action(async (projectPathArg, options)=>{
+            program.command('logs').arguments('[project-path]').usage('[project-path] [options]').description(commandDescriptions.logs).option(`--browser <${SESSION_BROWSER_TARGETS_HELP}>`, 'which dist/extension-js/<browser> to read. Defaults to `chromium`').option('--follow', 'stream live via the control channel instead of printing and exiting').option('--context <list>', 'comma-separated contexts (background, content, popup, options, sidebar, devtools, page)').option('--level <off|error|warn|info|debug|trace|all>', 'minimum severity to show. Defaults to `all`').option('--signals-only', '[experimental] show only structured dx.signal diagnostics. No emitter ships yet, so this currently prints nothing').option('--since <seq|iso>', 'only show events after this sequence number or ISO timestamp').option('--url <glob|substring>', 'only events whose url/hostname matches (glob with * or plain substring)').option('--tab <id>', 'only events from this tab id').option('--output <pretty|json|ndjson>', 'output format. Defaults to pretty on a TTY, ndjson when piped').action(async (projectPathArg, options)=>{
                 const bridge = await loadExtensionDevelopBridgeModule();
                 const projectPath = resolveSessionProjectPath(bridge, projectPathArg);
                 const browser = options.browser || 'chromium';
@@ -8666,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;
@@ -8838,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)');
@@ -8851,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'
@@ -8924,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') {
@@ -8936,7 +9229,7 @@ Cross-browser compatibility
             if (null != opts.tab && '' !== opts.tab) target.tabId = Number(opts.tab);
             return target;
         }
-        const commonOptions = (cmd)=>cmd.option('--browser <chrome | chromium | edge | firefox>', 'which session to target (default chromium)').option('--timeout <ms>', 'command timeout in milliseconds (default 5000)').option('--output <pretty|json>', 'output format (default pretty)');
+        const commonOptions = (cmd)=>cmd.option(`--browser <${SESSION_BROWSER_TARGETS_HELP}>`, 'which session to target (default chromium)').option('--timeout <ms>', 'command timeout in milliseconds (default 5000)').option('--output <pretty|json>', 'output format (default pretty)');
         function registerActCommands(program) {
             commonOptions(program.command('eval').arguments('<expression> [project-path]').description(commandDescriptions.eval).option('--context <background|popup|options|sidebar|devtools|newtab|history|bookmarks|content|page>', 'target context (default background). Extension pages (popup/options/sidebar/devtools/newtab/history/bookmarks) answer via their own in-page relay and must be open').option('--url <glob|substring>', 'for content/page: document to target (resolved to its tab)').option('--tab <id>', 'for content/page: a specific tab (default: the --url match, else the active tab)')).action(async (expression, projectPathArg, opts)=>{
                 await runCommand({
@@ -9069,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)
+                    }
                 });
             });
         }
@@ -9107,97 +9404,8 @@ Cross-browser compatibility
             const values = String(raw).split(',').map((value)=>value.trim()).filter((value)=>value.length > 0);
             return values.length > 0 ? values : void 0;
         }
-        function isSafariVendor(value) {
-            return 'safari' === value || 'webkit-based' === value;
-        }
-        const SUPPORTED_BROWSER_TARGETS = [
-            'chrome',
-            'chromium',
-            'edge',
-            'firefox',
-            'brave',
-            'opera',
-            'vivaldi',
-            'yandex',
-            'waterfox',
-            'librewolf',
-            'chromium-based',
-            'gecko-based',
-            'firefox-based',
-            'safari',
-            'webkit-based'
-        ];
-        const BROWSER_TARGETS_HELP = SUPPORTED_BROWSER_TARGETS.join(' | ');
-        const NO_SAFARI_BROWSER_TARGETS_HELP = SUPPORTED_BROWSER_TARGETS.filter((target)=>!isSafariVendor(target)).join(' | ');
-        function parseOptionalBoolean(value) {
-            if (void 0 === value) return true;
-            const normalized = String(value).trim().toLowerCase();
-            return ![
-                'false',
-                '0',
-                'no',
-                'off'
-            ].includes(normalized);
-        }
-        const vendors = (browser)=>{
-            const value = browser ?? 'chromium';
-            return 'all' === value ? [
-                'chrome',
-                'edge',
-                'firefox'
-            ] : String(value).split(',').map((part)=>part.trim()).filter(Boolean);
-        };
-        const MANAGED_INSTALL_TARGETS = [
-            'chrome',
-            'chromium',
-            'edge',
-            'firefox',
-            'chromium-based',
-            'gecko-based',
-            'firefox-based'
-        ];
-        const MANAGED_INSTALL_TARGETS_HELP = [
-            ...MANAGED_INSTALL_TARGETS,
-            'all'
-        ].join(' | ');
-        const MANAGED_INSTALL_BINARIES = [
-            'chrome',
-            'chromium',
-            'edge',
-            'firefox'
-        ];
-        const installTargets = (browser)=>'all' === browser ? [
-                ...MANAGED_INSTALL_BINARIES
-            ] : vendors(browser);
-        function validateVendors(vendorsList, onInvalid) {
-            const supported = SUPPORTED_BROWSER_TARGETS;
-            for (const v of vendorsList)if (!supported.includes(v)) {
-                onInvalid(v, supported);
-                return false;
-            }
-            return true;
-        }
-        const MANAGED_INSTALL_TARGET_SET = new Set(MANAGED_INSTALL_TARGETS);
-        const SUPPORTED_BROWSER_TARGET_SET = new Set(SUPPORTED_BROWSER_TARGETS);
-        function classifyManagedInstallTarget(name) {
-            const value = String(name || '').trim().toLowerCase();
-            if (!value) return 'unknown';
-            if (MANAGED_INSTALL_TARGET_SET.has(value)) return 'managed';
-            if (SUPPORTED_BROWSER_TARGET_SET.has(value)) return 'not-installable';
-            return 'unknown';
-        }
-        function firstNonManagedInstallTarget(targetsList) {
-            for (const name of targetsList){
-                const kind = classifyManagedInstallTarget(name);
-                if ('managed' !== kind) return {
-                    name,
-                    kind
-                };
-            }
-            return null;
-        }
         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 treats as unsigned: the extension then needs Develop \u25b8 Allow Unsigned Extensions re-ticked on every launch. A signed build is listed and stays enabled across restarts').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';
@@ -9759,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);
@@ -9833,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; no live reload)').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 treats as unsigned: the extension then needs Develop \u25b8 Allow Unsigned Extensions re-ticked on every launch. A signed build is listed and stays enabled across restarts').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) {
@@ -10289,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,
@@ -10313,7 +10529,7 @@ Cross-browser compatibility
             browser: messaging.Lp.E_BROWSER_LAUNCH
         };
         function registerDoctorCommand(program) {
-            program.command('doctor').argument('[project-path]', 'path to the extension project root or the folder holding its manifest').option('--browser <chrome | chromium | edge | firefox>', 'which session to diagnose (defaults to the single live session, else chromium)').option('--output <pretty|json>', 'result format. Use json for a schema-1 envelope on stdout').description(commandDescriptions.doctor).action(async (projectPathArg, opts)=>{
+            program.command('doctor').argument('[project-path]', 'path to the extension project root or the folder holding its manifest').option(`--browser <${SESSION_BROWSER_TARGETS_HELP}>`, 'which session to diagnose (defaults to the single live session, else chromium)').option('--output <pretty|json>', 'result format. Use json for a schema-1 envelope on stdout').description(commandDescriptions.doctor).action(async (projectPathArg, opts)=>{
                 const asJson = isJsonOutput(opts);
                 let results;
                 try {