extension 4.1.12 → 4.1.13

package/dist/cli.cjs

@@ -642,12 +642,6 @@ var __webpack_modules__ = {
         function firefoxLaunchCalled() {
             return `${getLoggingPrefix('debug')} browser  launch browser=firefox`;
         }
-        function firefoxBinaryArgsExtracted(args) {
-            return `${getLoggingPrefix('debug')} browser  args="${args}"`;
-        }
-        function firefoxNoBinaryArgsFound() {
-            return `${getLoggingPrefix('debug')} browser  args=none`;
-        }
         function firefoxFailedToStart(error) {
             return `${getLoggingPrefix('error')} Firefox failed to start.\n${pintor__rspack_import_8_default().red(errorDetail(error))}`;
         }
@@ -657,8 +651,8 @@ var __webpack_modules__ = {
         function firefoxDryRunBinary(path) {
             return `${getLoggingPrefix('info')} ${pintor__rspack_import_8_default().gray('PATH')} ${pintor__rspack_import_8_default().underline(path)}`;
         }
-        function firefoxDryRunConfig(cfg) {
-            return `${getLoggingPrefix('info')} ${pintor__rspack_import_8_default().gray('CONFIG')} ${pintor__rspack_import_8_default().gray(cfg)}`;
+        function firefoxDryRunArgs(args) {
+            return `${getLoggingPrefix('info')} ${pintor__rspack_import_8_default().gray('ARGS')} ${pintor__rspack_import_8_default().gray(args)}`;
         }
         function safariBuildCalled() {
             return `${getLoggingPrefix('debug')} browser  build browser=safari`;
@@ -958,7 +952,6 @@ var __webpack_modules__ = {
             bv: ()=>cdpUnifiedExtensionLog,
             cD: ()=>targetActorHasActiveRequestError,
             cF: ()=>safariRebuilt,
-            dN: ()=>firefoxNoBinaryArgsFound,
             dk: ()=>generalBrowserError,
             dw: ()=>devFirefoxProfilePath,
             e_: ()=>runningInDevelopment,
@@ -969,14 +962,13 @@ var __webpack_modules__ = {
             fw: ()=>safariOpening,
             hE: ()=>cdpClientConnectionClosed,
             io: ()=>emptyLine,
-            iv: ()=>firefoxBinaryArgsExtracted,
             jP: ()=>rdpInvalidRequestPayload,
             jR: ()=>safariBuilding,
             jc: ()=>safariProjectStale,
             jk: ()=>requireGeckoBinaryForGeckoBased,
-            k6: ()=>firefoxDryRunConfig,
             kK: ()=>preferringSystemBrowserOverSnapshot,
             l9: ()=>parsingPacketError,
+            lO: ()=>firefoxDryRunArgs,
             l_: ()=>safariConverted,
             ne: ()=>requireChromiumBinaryForChromiumBased,
             nn: ()=>chromeProcessExited,
@@ -999,6 +991,22 @@ var __webpack_modules__ = {
             yc: ()=>safariDryRunNotBuilding
         });
     },
+    "./browsers/browsers-lib/newtab-override.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");
+        function manifestDeclaresNewtabOverride(outPath) {
+            try {
+                const manifest = JSON.parse(node_fs__rspack_import_0.readFileSync(node_path__rspack_import_1.join(outPath, 'manifest.json'), 'utf-8'));
+                const overrides = manifest?.chrome_url_overrides || manifest?.['chromium:chrome_url_overrides'] || manifest?.['chrome:chrome_url_overrides'] || manifest?.['gecko:chrome_url_overrides'] || manifest?.['firefox:chrome_url_overrides'];
+                return Boolean(overrides && 'string' == typeof overrides.newtab && overrides.newtab.trim().length > 0);
+            } catch  {
+                return false;
+            }
+        }
+        __webpack_require__.d(__webpack_exports__, {
+            c: ()=>manifestDeclaresNewtabOverride
+        });
+    },
     "./browsers/browsers-lib/output-binaries-resolver.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");
@@ -1474,6 +1482,7 @@ var __webpack_modules__ = {
         }
         function resolveProfileConfig(input) {
             const { managedBaseDir, useSystemProfile, persistProfile, keepProfileChanges, copyFromProfile, resolveExplicit } = input;
+            const provision = false !== input.provision;
             const rawProfile = normalizeProfileOption(input.rawProfile);
             if (false === rawProfile || useSystemProfile) return {
                 kind: 'system',
@@ -1504,6 +1513,14 @@ var __webpack_modules__ = {
                 profilePath = external_node_path_.join(managedBaseDir, human);
             }
             const isFreshTarget = !external_node_fs_.existsSync(profilePath) || 0 === external_node_fs_.readdirSync(profilePath).length;
+            if (!provision) return {
+                kind: 'managed',
+                profilePath,
+                persisted,
+                ...hasCopyFrom(copyFromProfile) && isFreshTarget ? {
+                    seededFrom: copyFromProfile.trim()
+                } : {}
+            };
             external_node_fs_.mkdirSync(profilePath, {
                 recursive: true
             });
@@ -1976,6 +1993,7 @@ var __webpack_modules__ = {
                 preferences: opts.preferences,
                 browserFlags: opts.browserFlags,
                 startingUrl: opts.startingUrl,
+                noOpen: opts.noOpen,
                 geckoBinary: opts.geckoBinary,
                 instanceId: opts.instanceId,
                 port: opts.port,
@@ -2170,6 +2188,38 @@ var __webpack_modules__ = {
         var messaging = __webpack_require__("./helpers/messaging.ts");
         var banner = __webpack_require__("./browsers/browsers-lib/banner.ts");
         var instance_registry = __webpack_require__("./browsers/browsers-lib/instance-registry.ts");
+        const MSG_REFERENCE = /__MSG_([A-Za-z0-9_@]+?)__/g;
+        function collectMsgReferences(value) {
+            const found = [];
+            const seen = new Set();
+            const visit = (node)=>{
+                if ('string' == typeof node) {
+                    MSG_REFERENCE.lastIndex = 0;
+                    let match = MSG_REFERENCE.exec(node);
+                    while(null !== match){
+                        const name = match[1];
+                        if (name && !name.startsWith('@@') && !seen.has(name)) {
+                            seen.add(name);
+                            found.push(name);
+                        }
+                        match = MSG_REFERENCE.exec(node);
+                    }
+                    return;
+                }
+                if (Array.isArray(node)) {
+                    for (const item of node)visit(item);
+                    return;
+                }
+                if (node && 'object' == typeof node) for (const item of Object.values(node))visit(item);
+            };
+            visit(value);
+            return found;
+        }
+        function findUndefinedMsgReferences(value, catalogKeys) {
+            const lower = new Set();
+            for (const key of catalogKeys)lower.add(String(key).toLowerCase());
+            return collectMsgReferences(value).filter((name)=>!lower.has(name.toLowerCase()));
+        }
         function diagnoseChromiumManifestRefusal(manifest) {
             const m = manifest;
             if (2 === Number(m?.manifest_version)) return 'mv2';
@@ -2304,7 +2354,7 @@ var __webpack_modules__ = {
                     if (external_node_fs_.existsSync(catalogPath)) try {
                         const raw = external_node_fs_.readFileSync(catalogPath, 'utf8').replace(/^\uFEFF/, '');
                         const catalog = JSON.parse(raw);
-                        catalogKeys = new Set(Object.keys(catalog || {}).map((key)=>key.toLowerCase()));
+                        catalogKeys = new Set(Object.keys(catalog || {}));
                     } catch  {
                         blockers.push(`default_locale: _locales/${defaultLocale}/messages.json is not valid JSON, Chrome refuses the whole extension.`);
                     }
@@ -2312,11 +2362,7 @@ var __webpack_modules__ = {
                 } catch  {
                     return blockers;
                 }
-                if (catalogKeys) {
-                    const refs = new Set();
-                    collectMsgRefs(m, refs);
-                    for (const ref of refs)if (!catalogKeys.has(ref.toLowerCase())) blockers.push(`__MSG_${ref}__: used in the manifest but not defined in _locales/${defaultLocale}/messages.json, Chrome refuses the whole extension.`);
-                }
+                if (catalogKeys) for (const ref of findUndefinedMsgReferences(m, catalogKeys))blockers.push(`__MSG_${ref}__: used in the manifest but not defined in _locales/${defaultLocale}/messages.json, Chrome refuses the whole extension.`);
             } else try {
                 if (external_node_fs_.existsSync(localesDir)) {
                     const hasCatalog = external_node_fs_.readdirSync(localesDir).some((entry)=>external_node_fs_.existsSync(external_node_path_.join(localesDir, entry, 'messages.json')));
@@ -2337,13 +2383,6 @@ var __webpack_modules__ = {
             } catch  {}
             return [];
         }
-        function collectMsgRefs(value, out) {
-            if ('string' == typeof value) {
-                const match = /^__MSG_(.+)__$/.exec(value.trim());
-                if (match && !match[1].startsWith('@@')) out.add(match[1]);
-            } else if (Array.isArray(value)) for (const item of value)collectMsgRefs(item, out);
-            else if (value && 'object' == typeof value) for (const item of Object.values(value))collectMsgRefs(item, out);
-        }
         function isValidDottedVersion(version) {
             if (!version) return false;
             const parts = version.split('.');
@@ -2524,7 +2563,19 @@ var __webpack_modules__ = {
             });
             external_node_fs_.writeFileSync(preferencesPath, JSON.stringify(mergedPreferences), 'utf8');
         }
-        function browserConfig(compilation, configOptions) {
+        function chromiumLaunchPlan(binary, chromiumConfig, startingUrl) {
+            return {
+                binary,
+                args: startingUrl ? [
+                    ...chromiumConfig,
+                    startingUrl
+                ] : [
+                    ...chromiumConfig
+                ]
+            };
+        }
+        function browserConfig(compilation, configOptions, mode = {}) {
+            const provision = false !== mode.provision;
             const extensionsToLoad = (0, runtime_options.fT)(configOptions.extension);
             const devWantsCDP = compilation?.options?.mode === 'development';
             const rawProfile = configOptions.profile;
@@ -2548,17 +2599,18 @@ var __webpack_modules__ = {
                 persistProfile: configOptions.persistProfile,
                 keepProfileChanges: configOptions.keepProfileChanges,
                 copyFromProfile: configOptions.copyFromProfile,
-                resolveExplicit: (trimmedProfile)=>external_node_path_.isAbsolute(trimmedProfile) ? trimmedProfile : external_node_path_.resolve(contextDir, trimmedProfile)
+                resolveExplicit: (trimmedProfile)=>external_node_path_.isAbsolute(trimmedProfile) ? trimmedProfile : external_node_path_.resolve(contextDir, trimmedProfile),
+                provision
             });
             const userProfilePath = resolved.profilePath;
-            if ('managed' === resolved.kind) {
+            if ('managed' === resolved.kind && provision) {
                 if ((0, messaging._o)()) (0, messaging._w)(messages.sY(shownPath(userProfilePath)));
                 if (!resolved.persisted) try {
                     const maxAgeHours = parseInt(String(process.env.EXTENSION_TMP_PROFILE_MAX_AGE_HOURS || ''), 10);
                     (0, shared_utils.CW)(managedBaseDir, external_node_path_.basename(userProfilePath), Number.isFinite(maxAgeHours) ? maxAgeHours : 12);
                 } catch  {}
             }
-            if (userProfilePath) {
+            if (userProfilePath && provision) {
                 external_node_fs_.mkdirSync(userProfilePath, {
                     recursive: true
                 });
@@ -2879,7 +2931,10 @@ var __webpack_modules__ = {
                         process.exit(1);
                     }
                 }
-                if (this.options?.dryRun || process.env.VITEST || process.env.VITEST_WORKER_ID) return void logChromiumDryRun(this.options?.chromiumBinary ? (0, wsl_support.f7)(String(this.options.chromiumBinary)) : 'chromium-mock-binary', []);
+                const inTestRunner = Boolean(process.env.VITEST || process.env.VITEST_WORKER_ID);
+                const dryRun = Boolean(this.options?.dryRun);
+                if (inTestRunner && !dryRun) return void logChromiumDryRun(this.options?.chromiumBinary ? (0, wsl_support.f7)(String(this.options.chromiumBinary)) : 'chromium-mock-binary', []);
+                if (inTestRunner && dryRun && !this.options?.chromiumBinary) return void this.printDryRunPlan(compilation, 'chromium-mock-binary');
                 const browser = this.options?.browser;
                 let browserBinaryLocation = null;
                 let printedGuidance = false;
@@ -3188,6 +3243,8 @@ var __webpack_modules__ = {
                         instanceId: this.options.instanceId,
                         extension: extensionsToLoad,
                         logLevel: this.options.logLevel
+                    }, {
+                        provision: !dryRun
                     });
                 } catch (error) {
                     if (shared_utils.ci(error)) (0, ready_stamp.iD)((0, extension_output_path.W)(compilation, void 0), {
@@ -3220,7 +3277,7 @@ var __webpack_modules__ = {
                         enableCdp
                     });
                 } catch  {}
-                if (this.options.dryRun) return void logChromiumDryRun(browserBinaryLocation, chromiumConfig);
+                if (dryRun) return void this.printDryRunPlan(compilation, browserBinaryLocation, chromiumConfig);
                 const usePipe = chromiumConfig.includes('--remote-debugging-pipe');
                 this.closeHandlerContext = {
                     isDevMode: 'development' === compilation.options.mode,
@@ -3290,14 +3347,18 @@ var __webpack_modules__ = {
                     reportReady();
                 }
             }
+            printDryRunPlan(compilation, binary, chromiumConfig) {
+                const flags = chromiumConfig ?? browserConfig(compilation, {
+                    ...this.options
+                }, {
+                    provision: false
+                });
+                const plan = chromiumLaunchPlan(binary, flags, this.options?.startingUrl);
+                logChromiumDryRun(plan.binary, plan.args);
+            }
             async launchWithDirectSpawn(binary, chromeFlags, usePipe = false) {
                 if ((0, messaging._o)()) this.logger.info(messages.xy());
-                const launchArgs = this.options?.startingUrl ? [
-                    ...chromeFlags,
-                    this.options.startingUrl
-                ] : [
-                    ...chromeFlags
-                ];
+                const { args: launchArgs } = chromiumLaunchPlan(binary, chromeFlags, this.options?.startingUrl);
                 const stdio = usePipe ? [
                     'ignore',
                     'ignore',
@@ -3570,6 +3631,29 @@ var __webpack_modules__ = {
             return /^(1|true)$/i.test(String(env.MOZ_HEADLESS || '').trim()) || (0, shared_utils.ZO)(env);
         }
         class FirefoxBinaryDetector {
+            static launchPlan(input) {
+                if (input.profilePath) return FirefoxBinaryDetector.generateFirefoxArgs(input.binaryPath, input.profilePath, input.debugPort, input.binaryArgs, input.headless);
+                const args = [
+                    ...input.headless ? [
+                        '-headless'
+                    ] : [],
+                    ...input.debugPort > 0 ? [
+                        '-start-debugger-server',
+                        String(input.debugPort)
+                    ] : [],
+                    ...'win32' === process.platform ? [
+                        '-wait-for-browser'
+                    ] : [],
+                    ...input.headless ? [] : [
+                        '--foreground'
+                    ],
+                    ...input.binaryArgs
+                ];
+                return {
+                    binary: input.binaryPath,
+                    args
+                };
+            }
             static generateFirefoxArgs(binaryPath, profilePath, debugPort, additionalArgs = [], headless = false) {
                 const headlessArgs = headless ? [
                     '-headless'
@@ -3699,7 +3783,8 @@ var __webpack_modules__ = {
                 ...customPrefs
             };
         }
-        async function browserConfig(compilation, configOptions) {
+        async function resolveFirefoxLaunchConfig(compilation, configOptions, mode = {}) {
+            const provision = false !== mode.provision;
             const { browser, profile, browserFlags = [] } = configOptions;
             const binaryArgs = [];
             const excludeFlags = configOptions.excludeBrowserFlags || [];
@@ -3727,17 +3812,18 @@ var __webpack_modules__ = {
                 persistProfile: configOptions.persistProfile,
                 keepProfileChanges: configOptions.keepProfileChanges,
                 copyFromProfile: configOptions.copyFromProfile,
-                resolveExplicit: (trimmedProfile)=>external_node_path_.isAbsolute(trimmedProfile) ? trimmedProfile : external_node_path_.resolve(contextDir, trimmedProfile)
+                resolveExplicit: (trimmedProfile)=>external_node_path_.isAbsolute(trimmedProfile) ? trimmedProfile : external_node_path_.resolve(contextDir, trimmedProfile),
+                provision
             });
             const profilePath = resolved.profilePath;
-            if ('managed' === resolved.kind) {
+            if ('managed' === resolved.kind && provision) {
                 if ((0, messaging._o)()) (0, messaging._w)(messages.sY(shownPath(profilePath)));
                 if (!resolved.persisted) try {
                     const maxAgeHours = parseInt(String(process.env.EXTENSION_TMP_PROFILE_MAX_AGE_HOURS || ''), 10);
                     (0, shared_utils.CW)(managedBaseDir, external_node_path_.basename(profilePath), Number.isFinite(maxAgeHours) ? maxAgeHours : 12);
                 } catch  {}
             }
-            if (profilePath) {
+            if (profilePath && provision) {
                 try {
                     external_node_fs_.mkdirSync(profilePath, {
                         recursive: true
@@ -3750,7 +3836,7 @@ var __webpack_modules__ = {
                     });
                 } catch  {}
             }
-            if (profilePath) try {
+            if (profilePath && provision) try {
                 const prefs = getPreferences(configOptions?.preferences || {});
                 function serializeValue(value) {
                     if ('string' == typeof value) return JSON.stringify(value);
@@ -3770,13 +3856,17 @@ var __webpack_modules__ = {
             ];
             if (binaryArgs.length > 0) parts.unshift(`--binary-args="${binaryArgs.join(' ')}"`);
             if (profilePath) parts.splice(1, 0, `--profile="${profilePath}"`);
-            return parts.join(' ');
+            return {
+                profilePath,
+                binaryArgs,
+                config: parts.join(' ')
+            };
         }
-        function logFirefoxDryRun(browserBinaryLocation, firefoxConfig) {
+        function logFirefoxDryRun(browserBinaryLocation, launchArgs) {
             if ((0, messaging._o)()) (0, messaging._w)(messages.A9());
             (0, messaging._w)(messages.qn());
             (0, messaging._w)(messages.LD(browserBinaryLocation));
-            (0, messaging._w)(messages.k6(firefoxConfig));
+            (0, messaging._w)(messages.lO(launchArgs.join(' ')));
         }
         const activeInstances = new Set();
         let globalHandlersInstalled = false;
@@ -3841,6 +3931,7 @@ var __webpack_modules__ = {
                 activeInstances.delete(instance);
             };
         }
+        var newtab_override = __webpack_require__("./browsers/browsers-lib/newtab-override.ts");
         var constants = __webpack_require__("./browsers/browsers-lib/constants.ts");
         var manifest_readiness = __webpack_require__("./browsers/run-chromium/manifest-readiness.ts");
         function resolveAddonDirectory(baseDir, inputPath) {
@@ -4094,6 +4185,110 @@ var __webpack_modules__ = {
                 } catch  {}
             });
         }
+        const MANAGER_ADDON_ID = 'devtools@extension.js';
+        const OPEN_NEW_TAB_EXPRESSION = "(function () { var api = globalThis.browser || globalThis.chrome; api.tabs.create({active: true}); return true;})()";
+        const TARGET_WAIT_MS = 2000;
+        function reportStep(step, detail) {
+            if (!(0, messaging._o)()) return;
+            const reason = detail instanceof Error ? detail.message : void 0 === detail ? '' : ` ${JSON.stringify(detail).slice(0, 300)}`;
+            (0, messaging.mR)(`[browser] Firefox new-tab courtesy: ${step}${reason}`);
+        }
+        async function findManagerAddon(client) {
+            const reply = await client.request({
+                to: 'root',
+                type: 'listAddons'
+            });
+            return (reply?.addons || []).find((addon)=>addon?.id === MANAGER_ADDON_ID);
+        }
+        function manager_tab_unsubscribe(client, listener) {
+            if ('function' == typeof client.off) client.off('message', listener);
+            else client.removeListener?.('message', listener);
+        }
+        function isBackgroundPage(target) {
+            return /_generated_background_page\.html|\/background/.test(String(target?.url || ''));
+        }
+        async function resolveConsoleActorViaWatcher(client, descriptorActor) {
+            const watcher = await client.request({
+                to: descriptorActor,
+                type: 'getWatcher',
+                isServerTargetSwitchingEnabled: true
+            });
+            const noop = ()=>{};
+            if (!watcher?.actor) return {
+                release: noop
+            };
+            const watcherActor = watcher.actor;
+            const release = ()=>{
+                client.request({
+                    to: watcherActor,
+                    type: 'unwatchTargets',
+                    targetType: 'frame'
+                }).catch(()=>{});
+            };
+            const targets = [];
+            const collect = (message)=>{
+                const event = message;
+                if (event?.type === 'target-available-form' && event.target) targets.push(event.target);
+            };
+            client.on('message', collect);
+            try {
+                collect(await client.request({
+                    to: watcherActor,
+                    type: 'watchTargets',
+                    targetType: 'frame'
+                }));
+                const deadline = Date.now() + TARGET_WAIT_MS;
+                while(Date.now() < deadline){
+                    const background = targets.find((target)=>target.consoleActor && isBackgroundPage(target));
+                    if (background) return {
+                        consoleActor: background.consoleActor,
+                        release
+                    };
+                    await new Promise((resolve)=>setTimeout(resolve, 50));
+                }
+                return {
+                    consoleActor: targets.find((target)=>target.consoleActor)?.consoleActor,
+                    release
+                };
+            } finally{
+                manager_tab_unsubscribe(client, collect);
+            }
+        }
+        async function resolveConsoleActor(client, addon) {
+            if (addon.consoleActor) return {
+                consoleActor: addon.consoleActor,
+                release: ()=>{}
+            };
+            if (!addon.actor) return {
+                release: ()=>{}
+            };
+            return await resolveConsoleActorViaWatcher(client, addon.actor);
+        }
+        async function openManagerNewTab(client) {
+            try {
+                const addon = await findManagerAddon(client);
+                if (!addon) {
+                    reportStep('manager add-on not listed');
+                    return false;
+                }
+                const { consoleActor, release } = await resolveConsoleActor(client, addon);
+                if (!consoleActor) {
+                    release();
+                    reportStep('no console actor for the manager background page');
+                    return false;
+                }
+                try {
+                    const result = await client.evaluate(consoleActor, OPEN_NEW_TAB_EXPRESSION);
+                    reportStep('tabs.create evaluated', result);
+                } finally{
+                    release();
+                }
+                return true;
+            } catch (error) {
+                reportStep('failed', error);
+                return false;
+            }
+        }
         function requestErrorToMessage(error) {
             if (error instanceof Error) return String(error);
             try {
@@ -4282,21 +4477,33 @@ var __webpack_modules__ = {
             const raw = parseInt(String(process.env.EXTENSION_RDP_REQUEST_TIMEOUT_MS || ''), 10);
             return Number.isFinite(raw) && raw > 0 ? raw : 30000;
         }
+        function surfaceTransportError(emitter, error) {
+            if (emitter.listenerCount('error') > 0) return void emitter.emit('error', error);
+            (0, messaging.Gg)(error instanceof Error ? error.message : String(error));
+        }
         class RdpTransport extends external_node_events_default() {
             async connect(port, host = '127.0.0.1') {
                 await new Promise((resolve, reject)=>{
+                    let connected = false;
                     try {
                         const c = external_node_net_default().createConnection({
                             host,
                             port
                         }, ()=>{
+                            connected = true;
                             if ((0, messaging._o)()) (0, messaging._w)(messages.EI(host, port));
                             resolve();
                         });
                         this.conn = c;
+                        this.lost = false;
                         c.on('data', this.onData.bind(this));
-                        c.on('error', reject);
-                        c.on('end', this.onEnd.bind(this));
+                        c.on('error', (err)=>{
+                            if (connected) return;
+                            this.conn = void 0;
+                            reject(err);
+                        });
+                        c.on('end', this.onConnectionLost.bind(this));
+                        c.on('close', this.onConnectionLost.bind(this));
                         c.on('timeout', this.onTimeout.bind(this));
                     } catch (err) {
                         reject(err);
@@ -4304,11 +4511,15 @@ var __webpack_modules__ = {
                 });
             }
             disconnect() {
-                if (!this.conn) return;
-                this.conn.removeAllListeners();
-                this.conn.end();
-                const err = new Error(messages.qN('firefox'));
-                this.rejectAll(err);
+                const c = this.conn;
+                if (!c) return;
+                this.conn = void 0;
+                this.lost = true;
+                this.incoming = Buffer.alloc(0);
+                c.removeAllListeners();
+                c.on('error', ()=>{});
+                c.end();
+                this.rejectAll(new Error(messages.qN('firefox')));
             }
             rejectAll(error) {
                 for (const entry of this.active.values()){
@@ -4380,8 +4591,8 @@ var __webpack_modules__ = {
                 const { remainingData, parsedMessage, error, fatal } = parseRdpFrame(this.incoming);
                 this.incoming = remainingData;
                 if (error) {
-                    this.emit('error', new Error(messages.l9('firefox', error)));
-                    if (fatal) this.disconnect();
+                    surfaceTransportError(this, new Error(messages.l9('firefox', error)));
+                    if (fatal) this.onConnectionLost();
                     return !fatal;
                 }
                 if (!parsedMessage) return false;
@@ -4389,10 +4600,11 @@ var __webpack_modules__ = {
                 return true;
             }
             handleMessage(message) {
-                if (!message.from) return void this.emit('error', new Error(messages.HH('firefox', message)));
-                const entry = this.active.get(message.from);
+                const from = message.from;
+                if (!from) return void surfaceTransportError(this, new Error(messages.HH('firefox', message)));
+                const entry = this.active.get(from);
                 if (entry) {
-                    this.active.delete(message.from);
+                    this.active.delete(from);
                     if (entry.timer) clearTimeout(entry.timer);
                     if (message.error) entry.deferred.reject(message);
                     else entry.deferred.resolve(message);
@@ -4401,7 +4613,17 @@ var __webpack_modules__ = {
                 }
                 this.emit('message', message);
             }
-            onEnd() {
+            onConnectionLost() {
+                if (this.lost) return;
+                this.lost = true;
+                const c = this.conn;
+                this.conn = void 0;
+                this.incoming = Buffer.alloc(0);
+                if (c) {
+                    c.removeAllListeners();
+                    c.on('error', ()=>{});
+                    c.destroy();
+                }
                 this.rejectAll(new Error(messages.qN('firefox')));
                 this.emit('end');
             }
@@ -4409,7 +4631,7 @@ var __webpack_modules__ = {
                 this.emit('timeout');
             }
             constructor(...args){
-                super(...args), _define_property(this, "conn", void 0), _define_property(this, "incoming", Buffer.alloc(0)), _define_property(this, "active", new Map()), _define_property(this, "pending", []);
+                super(...args), _define_property(this, "conn", void 0), _define_property(this, "incoming", Buffer.alloc(0)), _define_property(this, "active", new Map()), _define_property(this, "pending", []), _define_property(this, "lost", false);
             }
         }
         function messaging_client_define_property(obj, key, value) {
@@ -4422,15 +4644,20 @@ var __webpack_modules__ = {
             else obj[key] = value;
             return obj;
         }
+        const RECONNECT_MAX_ATTEMPTS = 5;
+        const RECONNECT_RETRY_DELAY_MS = 1000;
         class MessagingClient extends external_node_events_default() {
             async connect(port) {
-                this.lastPort = port;
                 this.disconnectedByUser = false;
+                await this.openTransport(port);
+            }
+            async openTransport(port) {
+                this.lastPort = port;
                 await this.transport.connect(port);
                 if (!this.forwardingSetup) {
                     this.forwardingSetup = true;
                     this.transport.on('message', (message)=>this.emit('message', message));
-                    this.transport.on('error', (error)=>this.emit('error', error));
+                    this.transport.on('error', (error)=>surfaceTransportError(this, error));
                     this.transport.on('end', ()=>{
                         this.emit('end');
                         this.attemptReconnect();
@@ -4445,20 +4672,21 @@ var __webpack_modules__ = {
             async attemptReconnect() {
                 if (this.disconnectedByUser || this.reconnecting || !this.lastPort) return;
                 this.reconnecting = true;
-                const maxAttempts = 5;
-                const retryDelay = 1000;
-                for(let i = 0; i < maxAttempts; i++){
-                    await new Promise((r)=>setTimeout(r, retryDelay));
-                    try {
-                        this.transport = new RdpTransport();
-                        this.forwardingSetup = false;
-                        await this.connect(this.lastPort);
-                        this.reconnecting = false;
-                        this.emit('reconnected');
-                        return;
-                    } catch  {}
+                try {
+                    for(let i = 0; i < RECONNECT_MAX_ATTEMPTS; i++){
+                        await new Promise((r)=>setTimeout(r, RECONNECT_RETRY_DELAY_MS));
+                        if (this.disconnectedByUser) return;
+                        try {
+                            this.transport = new RdpTransport();
+                            this.forwardingSetup = false;
+                            await this.openTransport(this.lastPort);
+                            this.emit('reconnected');
+                            return;
+                        } catch  {}
+                    }
+                } finally{
+                    this.reconnecting = false;
                 }
-                this.reconnecting = false;
             }
             async request(requestProps) {
                 if ('string' == typeof requestProps) return await this.transport.request({
@@ -4647,6 +4875,10 @@ var __webpack_modules__ = {
                 });
                 if (!bannerPrinted) throw new Error(messages.WV(this.options.browser, 'Failed to print runningInDevelopment banner; add-on may not be installed.'));
             }
+            async openNewTab() {
+                if (!this.client) return false;
+                return await openManagerNewTab(this.client);
+            }
             async enableUnifiedLogging(opts) {
                 try {
                     if (this.loggingAttached) return;
@@ -4700,6 +4932,9 @@ var __webpack_modules__ = {
             getAddonInstallRefusalReason() {
                 return this.remote.getAddonInstallRefusalReason();
             }
+            async openNewTab() {
+                return await this.remote.openNewTab();
+            }
             getExtensionId() {
                 return this.remote.getDerivedExtensionId();
             }
@@ -4762,6 +4997,14 @@ var __webpack_modules__ = {
             } catch (error) {
                 throw withRefusalReason(error);
             }
+            try {
+                const outPath = String(compilation?.options?.output?.path || '');
+                if (!plugin.startingUrl && !plugin.noOpen && (0, newtab_override.c)(outPath)) {
+                    const live = plugin.rdpController || controller;
+                    const opened = await live.openNewTab?.();
+                    if (!opened && (0, messaging._o)()) (0, messaging.mR)('[browser] Firefox: could not open the new-tab override page.');
+                }
+            } catch  {}
             return controller;
         }
         var external_node_child_process_ = __webpack_require__("node:child_process");
@@ -4844,7 +5087,7 @@ var __webpack_modules__ = {
                     debug: (...a)=>console?.debug?.(...a)
                 };
                 await this.launch(compilation, options);
-                if ('development' === options.mode && !this.host.extensionLoadRefused) this.ctx.logger?.info?.((0, ready_message.G)(options.mode, this.host.browser));
+                if (options?.mode === 'development' && !this.host.extensionLoadRefused) this.ctx.logger?.info?.((0, ready_message.G)(options.mode, this.host.browser));
                 this.ctx.didLaunch = true;
             }
             apply(compiler) {
@@ -4909,12 +5152,10 @@ var __webpack_modules__ = {
                     if (process.env.VITEST || process.env.VITEST_WORKER_ID) throw new Error('Firefox not installed or binary path not found');
                     process.exit(1);
                 };
-                if (this.host.dryRun || process.env.VITEST || process.env.VITEST_WORKER_ID) {
-                    try {
-                        logFirefoxDryRun('firefox-mock-binary', '--binary-args=""');
-                    } catch  {}
-                    return;
-                }
+                const inTestRunner = Boolean(process.env.VITEST || process.env.VITEST_WORKER_ID);
+                const dryRun = Boolean(this.host.dryRun);
+                if (inTestRunner && !dryRun) return void logFirefoxDryRun('firefox-mock-binary', []);
+                if (inTestRunner && dryRun && !this.host.geckoBinary) return void await this.printDryRunPlan(compilation, options, 'firefox-mock-binary');
                 let browserBinaryLocation = resolveManagedBinary();
                 let skipDetection = Boolean(browserBinaryLocation);
                 const engineBased = 'gecko-based' === this.host.browser || 'firefox-based' === this.host.browser;
@@ -5008,25 +5249,25 @@ var __webpack_modules__ = {
                     rdpPort: debugPort
                 });
                 const effectiveInstanceId = this.host.instanceId;
-                let firefoxCfg;
-                firefoxCfg = await browserConfig(compilation, {
+                const launchConfig = await resolveFirefoxLaunchConfig(compilation, {
                     ...options,
                     profile: this.host.profile,
                     preferences: this.host.preferences || {},
                     instanceId: effectiveInstanceId
+                }, {
+                    provision: !dryRun
+                });
+                const { profilePath, binaryArgs: firefoxArgs } = launchConfig;
+                const plan = FirefoxBinaryDetector.launchPlan({
+                    binaryPath,
+                    profilePath,
+                    debugPort,
+                    binaryArgs: firefoxArgs,
+                    headless: isFirefoxHeadlessRequested()
                 });
-                if (this.host.dryRun) return void logFirefoxDryRun(binaryPath, firefoxCfg);
-                const firefoxArgs = [];
-                const binaryArgsMatch = firefoxCfg.match(/--binary-args="([^"]*)"/);
-                if (binaryArgsMatch) {
-                    const rawArgs = String(binaryArgsMatch[1] || '').trim();
-                    if (rawArgs) firefoxArgs.push(...rawArgs.split(' ').filter((arg)=>arg.trim().length > 0));
-                    if ((0, messaging._o)()) this.ctx.logger?.info?.(messages.iv(binaryArgsMatch[1]));
-                } else if ((0, messaging._o)()) this.ctx.logger?.info?.(messages.dN());
-                const profileMatch = firefoxCfg.match(/--profile="([^"]*)"/);
-                if (profileMatch) {
-                    const profilePath = profileMatch[1];
-                    const { binary, args } = FirefoxBinaryDetector.generateFirefoxArgs(binaryPath, profilePath, debugPort, firefoxArgs, isFirefoxHeadlessRequested());
+                if (dryRun) return void logFirefoxDryRun(plan.binary, plan.args);
+                if (profilePath) {
+                    const { binary, args } = plan;
                     this.host.launchProfilePath = profilePath;
                     this.child = await this.spawnFirefoxChild(binary, args, wslFallbackBinary);
                     (0, ready_stamp.M)(this.extensionOutputPath, {
@@ -5066,23 +5307,7 @@ var __webpack_modules__ = {
                     } catch  {}
                 } else {
                     if ((0, messaging._o)()) this.ctx.logger?.warn?.('[browser] Firefox profile not set; skipping RDP add-on install.');
-                    const args = [
-                        ...isFirefoxHeadlessRequested() ? [
-                            '-headless'
-                        ] : [],
-                        ...debugPort > 0 ? [
-                            '-start-debugger-server',
-                            String(debugPort)
-                        ] : [],
-                        ...'win32' === process.platform ? [
-                            '-wait-for-browser'
-                        ] : [],
-                        ...isFirefoxHeadlessRequested() ? [] : [
-                            '--foreground'
-                        ],
-                        ...firefoxArgs
-                    ];
-                    this.child = await this.spawnFirefoxChild(binaryPath, args, wslFallbackBinary);
+                    this.child = await this.spawnFirefoxChild(plan.binary, plan.args, wslFallbackBinary);
                     (0, ready_stamp.M)(this.extensionOutputPath, {
                         browserPid: this.child?.pid,
                         extensionId: this.extensionOutputPath ? (0, banner.MT)(this.extensionOutputPath) : void 0
@@ -5092,6 +5317,24 @@ var __webpack_modules__ = {
                     this.scheduleWatchTimeout();
                 }
             }
+            async printDryRunPlan(compilation, options, binaryPath) {
+                const launchConfig = await resolveFirefoxLaunchConfig(compilation, {
+                    ...options,
+                    profile: this.host.profile,
+                    preferences: this.host.preferences || {},
+                    instanceId: this.host.instanceId
+                }, {
+                    provision: false
+                });
+                const plan = FirefoxBinaryDetector.launchPlan({
+                    binaryPath,
+                    profilePath: launchConfig.profilePath,
+                    debugPort: (0, shared_utils.jl)(this.host.port, this.host.instanceId),
+                    binaryArgs: launchConfig.binaryArgs,
+                    headless: isFirefoxHeadlessRequested()
+                });
+                logFirefoxDryRun(plan.binary, plan.args);
+            }
             resolveSpawnStdio() {
                 if ('win32' !== process.platform) return [
                     'pipe',
@@ -5305,6 +5548,7 @@ var __webpack_modules__ = {
                 preferences: pluginOptions.preferences,
                 browserFlags: pluginOptions.browserFlags,
                 startingUrl: pluginOptions.startingUrl,
+                noOpen: pluginOptions.noOpen,
                 geckoBinary: pluginOptions.geckoBinary,
                 instanceId: pluginOptions.instanceId,
                 port: pluginOptions.port,
@@ -6617,257 +6861,6 @@ var __webpack_modules__ = {
             if (!Number.isFinite(n)) return min;
             return Math.min(Math.max(n, min), max);
         }
-        const KNOWN_COMMANDS = new Set([
-            'create',
-            'dev',
-            'start',
-            'preview',
-            'build',
-            'install',
-            'uninstall',
-            'telemetry',
-            'unknown'
-        ]);
-        function detectInvokedCommand(argv) {
-            for(let i = 2; i < argv.length; i += 1){
-                const arg = argv[i];
-                if (!(!arg || arg.startsWith('-'))) {
-                    if (KNOWN_COMMANDS.has(arg)) return arg;
-                    break;
-                }
-            }
-            return 'unknown';
-        }
-        function readArgValue(argv, names) {
-            for(let i = 2; i < argv.length; i += 1){
-                const arg = argv[i];
-                if (arg) for (const name of names){
-                    if (arg === name) {
-                        const next = argv[i + 1];
-                        return next && !next.startsWith('-') ? next : void 0;
-                    }
-                    if (arg.startsWith(`${name}=`)) return arg.slice(name.length + 1);
-                }
-            }
-        }
-        function telemetryCommandContext(command, argv = process.argv) {
-            if ('create' !== command) return {};
-            return {
-                template: readArgValue(argv, [
-                    '--template',
-                    '-t'
-                ]),
-                source: readArgValue(argv, [
-                    '--source'
-                ]) || 'cli'
-            };
-        }
-        const consent = resolveTelemetryConsent(process.argv);
-        const invoked = detectInvokedCommand(process.argv);
-        const telemetry_cli_version = String(getCliPackageJson().version || '0.0.0');
-        const telemetry = new Telemetry({
-            app: 'extension',
-            version: telemetry_cli_version,
-            disabled: !consent.enabled
-        });
-        function getTelemetryConsent() {
-            return consent;
-        }
-        function setTelemetryConsent(value) {
-            const ok = writeConsent(value);
-            const storage = resolveTelemetryStorage();
-            return {
-                ok,
-                path: storage?.consentFile ?? null
-            };
-        }
-        let tracked = false;
-        function markTracked() {
-            if (tracked) return false;
-            tracked = true;
-            return true;
-        }
-        function markCommandSuccess(command = invoked) {
-            if (!markTracked()) return;
-            telemetry.track('command_executed', {
-                command,
-                success: true,
-                version: telemetry_cli_version,
-                ...telemetryCommandContext(command)
-            });
-        }
-        function markCommandFailure(command = invoked) {
-            if (!markTracked()) return;
-            telemetry.track('command_failed', {
-                command,
-                success: false,
-                version: telemetry_cli_version,
-                ...telemetryCommandContext(command)
-            });
-        }
-        function printOptOutNoticeIfFirstRun() {
-            if (!consent.enabled || 'default' !== consent.source) return;
-            const storage = resolveTelemetryStorage();
-            if (!storage) return;
-            const written = writeConsent('enabled');
-            if (!written) return;
-            console.error(`${external_pintor_default().gray('⏵⏵⏵')} Extension.js collects anonymous, opt-out telemetry (two events: ${external_pintor_default().cyan('command_executed')} + ${external_pintor_default().cyan('command_failed')}). Disable with ${external_pintor_default().cyan('extension telemetry disable')}, ${external_pintor_default().cyan('EXTENSION_TELEMETRY=0')}, or ${external_pintor_default().cyan('--no-telemetry')}. See docs/TELEMETRY.md.`);
-        }
-        if (consent.enabled) {
-            printOptOutNoticeIfFirstRun();
-            process.on('beforeExit', async ()=>{
-                if (!tracked) if ((process.exitCode ?? 0) === 0) markCommandSuccess();
-                else markCommandFailure();
-                await telemetry.flush();
-            });
-            process.on('uncaughtException', ()=>{
-                markCommandFailure();
-            });
-            process.on('unhandledRejection', ()=>{
-                markCommandFailure();
-            });
-        }
-        const TELEMETRY_FLUSH_TIMEOUT_MS = 500;
-        async function exitAfterDrain(code) {
-            try {
-                await Promise.race([
-                    telemetry.flush(),
-                    new Promise((resolve)=>setTimeout(resolve, TELEMETRY_FLUSH_TIMEOUT_MS).unref?.())
-                ]);
-            } catch  {}
-            await Promise.all([
-                process.stdout,
-                process.stderr
-            ].map((stream)=>new Promise((resolve)=>{
-                    if (0 === stream.writableLength) return resolve();
-                    stream.write('', ()=>resolve());
-                })));
-            process.exit(code);
-        }
-        var external_node_module_ = __webpack_require__("node:module");
-        const external_node_url_namespaceObject = require("node:url");
-        const extension_develop_runtime_require = (0, external_node_module_.createRequire)(__rslib_import_meta_url__);
-        function parseJsonSafe(filePath) {
-            return JSON.parse(external_node_fs_default().readFileSync(filePath, 'utf8'));
-        }
-        function resolveDevelopRootFromDir(dir) {
-            try {
-                const packageJsonPath = external_node_path_default().join(dir, 'package.json');
-                if (!external_node_fs_default().existsSync(packageJsonPath)) return;
-                const pkg = parseJsonSafe(packageJsonPath);
-                return pkg?.name === 'extension-develop' ? dir : void 0;
-            } catch  {
-                return;
-            }
-        }
-        function resolveWorkspaceDevelopRoot(startDir) {
-            let currentDir = external_node_path_default().resolve(startDir);
-            if (currentDir.split(external_node_path_default().sep).includes('node_modules')) return;
-            for(let depth = 0; depth < 8; depth += 1){
-                const candidate = external_node_path_default().join(currentDir, 'programs', 'develop');
-                const resolved = resolveDevelopRootFromDir(candidate);
-                if (resolved) return resolved;
-                const parent = external_node_path_default().dirname(currentDir);
-                if (parent === currentDir) break;
-                currentDir = parent;
-            }
-        }
-        function resolveInstalledDevelopRoot() {
-            try {
-                const packageJsonPath = extension_develop_runtime_require.resolve('extension-develop/package.json');
-                return resolveDevelopRootFromDir(external_node_path_default().dirname(packageJsonPath));
-            } catch  {
-                try {
-                    const entryPath = extension_develop_runtime_require.resolve('extension-develop');
-                    return resolveDevelopRootFromDir(external_node_path_default().dirname(external_node_path_default().dirname(entryPath)));
-                } catch  {
-                    return;
-                }
-            }
-        }
-        function resolvePreferredDevelopRoot(startDir) {
-            const workspaceRoot = resolveWorkspaceDevelopRoot(startDir);
-            if (workspaceRoot) return {
-                root: workspaceRoot,
-                source: 'workspace'
-            };
-            const envRoot = process.env.EXTENSION_DEVELOP_ROOT ? resolveDevelopRootFromDir(external_node_path_default().resolve(process.env.EXTENSION_DEVELOP_ROOT)) : void 0;
-            if (envRoot) return {
-                root: envRoot,
-                source: 'env'
-            };
-            const installedRoot = resolveInstalledDevelopRoot();
-            if (installedRoot) return {
-                root: installedRoot,
-                source: 'installed'
-            };
-            return {
-                root: void 0,
-                source: 'missing'
-            };
-        }
-        function resolveDevelopDistEntry(root, name = 'module') {
-            const base = external_node_path_default().join(root, 'dist', name);
-            const candidates = [
-                `${base}.mjs`,
-                `${base}.cjs`,
-                `${base}.js`,
-                base
-            ];
-            for (const candidate of candidates)if (external_node_fs_default().existsSync(candidate)) return candidate;
-        }
-        function resolveExtensionDevelopRoot(startDir = __dirname) {
-            const { root, source } = resolvePreferredDevelopRoot(startDir);
-            if (!root) throw new Error('Unable to locate the extension-develop runtime.');
-            process.env.EXTENSION_DEVELOP_ROOT = root;
-            if ('workspace' === source) process.env.EXTENSION_CREATE_DEVELOP_ROOT = root;
-            return root;
-        }
-        function resolveExtensionDevelopVersion(startDir = __dirname, fallbackVersion) {
-            try {
-                const root = resolveExtensionDevelopRoot(startDir);
-                const packageJsonPath = external_node_path_default().join(root, 'package.json');
-                const pkg = parseJsonSafe(packageJsonPath);
-                return pkg?.version || fallbackVersion || '0.0.0';
-            } catch  {
-                return fallbackVersion || '0.0.0';
-            }
-        }
-        async function importModule(filePath) {
-            const mod = await import((0, external_node_url_namespaceObject.pathToFileURL)(filePath).href);
-            return mod?.default && 'object' == typeof mod.default ? {
-                ...mod.default,
-                ...mod
-            } : mod;
-        }
-        async function loadExtensionDevelopModule(startDir = __dirname) {
-            const root = resolveExtensionDevelopRoot(startDir);
-            const { source } = resolvePreferredDevelopRoot(startDir);
-            const distEntry = resolveDevelopDistEntry(root);
-            if (distEntry) return importModule(distEntry);
-            if ('workspace' === source) throw new Error(`Local extension-develop runtime is not built at ${external_node_path_default().join(root, 'dist')}. Run \`pnpm --filter extension-develop compile\` before invoking the local CLI.`);
-            return await import("extension-develop");
-        }
-        async function loadExtensionDevelopPreviewModule(startDir = __dirname) {
-            const root = resolveExtensionDevelopRoot(startDir);
-            const { source } = resolvePreferredDevelopRoot(startDir);
-            const previewEntry = resolveDevelopDistEntry(root, 'preview');
-            if (previewEntry) return importModule(previewEntry);
-            const fullEntry = resolveDevelopDistEntry(root);
-            if (fullEntry) return importModule(fullEntry);
-            if ('workspace' === source) throw new Error(`Local extension-develop runtime is not built at ${external_node_path_default().join(root, 'dist')}. Run \`pnpm --filter extension-develop compile\` before invoking the local CLI.`);
-            return await import("extension-develop/preview");
-        }
-        async function loadExtensionDevelopBridgeModule(startDir = __dirname) {
-            const root = resolveExtensionDevelopRoot(startDir);
-            const { source } = resolvePreferredDevelopRoot(startDir);
-            const bridgeEntry = resolveDevelopDistEntry(root, 'bridge');
-            if (bridgeEntry) return importModule(bridgeEntry);
-            if ('workspace' === source) throw new Error(`Local extension-develop runtime is not built at ${external_node_path_default().join(root, 'dist')}. Run \`pnpm --filter extension-develop compile\` before invoking the local CLI.`);
-            const bridgeSpecifier = 'extension-develop/bridge';
-            return await import(bridgeSpecifier);
-        }
-        var messaging = __webpack_require__("./helpers/messaging.ts");
         const TEMPLATE_CORPUS_REPO = 'extension-js/examples';
         const TEMPLATE_CORPUS_REF = 'cb6a25377bd9516a1e55447a2010537019851ab2';
         const TEMPLATE_CORPUS_SLUGS = [
@@ -6931,7 +6924,7 @@ var __webpack_modules__ = {
             "typescript",
             'vue'
         ];
-        const DEFAULT_TEMPLATE = "javascript";
+        const DEFAULT_TEMPLATE = "typescript";
         const BUNDLED_TEMPLATES = [
             "javascript"
         ];
@@ -7093,6 +7086,9 @@ var __webpack_modules__ = {
         function listTemplates() {
             return TEMPLATE_GROUPS.flatMap((group)=>group.templates);
         }
+        function templateAliasFor(name) {
+            return TEMPLATE_ALIASES.find((alias)=>alias.name === name);
+        }
         function wrapSlugs(slugs, indent, width) {
             const lines = [];
             let current = '';
@@ -7124,32 +7120,290 @@ var __webpack_modules__ = {
                 lines.push(`  ${title('Aliases')}`);
                 for (const alias of TEMPLATE_ALIASES)lines.push(`    ${slug(alias.name)} ${dim(`still works, ${alias.note}`)}`);
             }
-            return lines.join('\n');
+            return lines.join('\n');
+        }
+        function renderCreateTemplateHelp() {
+            const total = listTemplates().length;
+            const dim = (text)=>external_pintor_default().gray(text);
+            const defaultIsBundled = BUNDLED_TEMPLATES.includes(DEFAULT_TEMPLATE);
+            return [
+                '',
+                external_pintor_default().underline(external_pintor_default().blue(`Templates (${total})`)),
+                renderTemplateList(),
+                '',
+                `  ${external_pintor_default().green('Default')}`,
+                `    ${external_pintor_default().blue(DEFAULT_TEMPLATE)} ${dim('is used when --template is omitted.')}`,
+                ...defaultIsBundled ? [
+                    dim('    It ships inside the CLI, so it scaffolds with no network.')
+                ] : [
+                    dim('    It downloads the catalog archive like every other name.')
+                ],
+                '',
+                `  ${external_pintor_default().green('Everything else')}`,
+                dim('    downloads the catalog archive at create time, so it needs the'),
+                dim('    network and takes longer. A GitHub URL or a ZIP URL also works.'),
+                `    ${external_pintor_default().blue(TEMPLATE_CATALOG_URL)}`,
+                ''
+            ].join('\n');
+        }
+        const KNOWN_COMMANDS = new Set([
+            'create',
+            'dev',
+            'start',
+            'preview',
+            'build',
+            'install',
+            'uninstall',
+            'telemetry',
+            'unknown'
+        ]);
+        function detectInvokedCommand(argv) {
+            for(let i = 2; i < argv.length; i += 1){
+                const arg = argv[i];
+                if (!(!arg || arg.startsWith('-'))) {
+                    if (KNOWN_COMMANDS.has(arg)) return arg;
+                    break;
+                }
+            }
+            return 'unknown';
+        }
+        function readArgValue(argv, names) {
+            for(let i = 2; i < argv.length; i += 1){
+                const arg = argv[i];
+                if (arg) for (const name of names){
+                    if (arg === name) {
+                        const next = argv[i + 1];
+                        return next && !next.startsWith('-') ? next : void 0;
+                    }
+                    if (arg.startsWith(`${name}=`)) return arg.slice(name.length + 1);
+                }
+            }
+        }
+        function advertisedTemplateName(value) {
+            if (!value) return;
+            const name = value.trim();
+            if (!name) return;
+            if (listTemplates().includes(name)) return name;
+            if (templateAliasFor(name)) return name;
+        }
+        function telemetryCommandContext(command, argv = process.argv) {
+            if ('create' !== command) return {};
+            return {
+                template: advertisedTemplateName(readArgValue(argv, [
+                    '--template',
+                    '-t'
+                ])),
+                source: readArgValue(argv, [
+                    '--source'
+                ]) || 'cli'
+            };
+        }
+        const consent = resolveTelemetryConsent(process.argv);
+        const invoked = detectInvokedCommand(process.argv);
+        const telemetry_cli_version = String(getCliPackageJson().version || '0.0.0');
+        const telemetry = new Telemetry({
+            app: 'extension',
+            version: telemetry_cli_version,
+            disabled: !consent.enabled
+        });
+        function getTelemetryConsent() {
+            return consent;
+        }
+        function setTelemetryConsent(value) {
+            const ok = writeConsent(value);
+            const storage = resolveTelemetryStorage();
+            return {
+                ok,
+                path: storage?.consentFile ?? null
+            };
+        }
+        let tracked = false;
+        function markTracked() {
+            if (tracked) return false;
+            tracked = true;
+            return true;
+        }
+        function markCommandSuccess(command = invoked) {
+            if (!markTracked()) return;
+            telemetry.track('command_executed', {
+                command,
+                success: true,
+                version: telemetry_cli_version,
+                ...telemetryCommandContext(command)
+            });
+        }
+        function markCommandFailure(command = invoked) {
+            if (!markTracked()) return;
+            telemetry.track('command_failed', {
+                command,
+                success: false,
+                version: telemetry_cli_version,
+                ...telemetryCommandContext(command)
+            });
+        }
+        function printOptOutNoticeIfFirstRun() {
+            if (!consent.enabled || 'default' !== consent.source) return;
+            const storage = resolveTelemetryStorage();
+            if (!storage) return;
+            const written = writeConsent('enabled');
+            if (!written) return;
+            console.error(`${external_pintor_default().gray('⏵⏵⏵')} Extension.js collects anonymous, opt-out telemetry (two events: ${external_pintor_default().cyan('command_executed')} + ${external_pintor_default().cyan('command_failed')}). Disable with ${external_pintor_default().cyan('extension telemetry disable')}, ${external_pintor_default().cyan('EXTENSION_TELEMETRY=0')}, or ${external_pintor_default().cyan('--no-telemetry')}. See docs/TELEMETRY.md.`);
+        }
+        if (consent.enabled) {
+            printOptOutNoticeIfFirstRun();
+            process.on('beforeExit', async ()=>{
+                if (!tracked) if ((process.exitCode ?? 0) === 0) markCommandSuccess();
+                else markCommandFailure();
+                await telemetry.flush();
+            });
+            process.on('uncaughtException', ()=>{
+                markCommandFailure();
+            });
+            process.on('unhandledRejection', ()=>{
+                markCommandFailure();
+            });
+        }
+        const TELEMETRY_FLUSH_TIMEOUT_MS = 500;
+        async function exitAfterDrain(code) {
+            try {
+                await Promise.race([
+                    telemetry.flush(),
+                    new Promise((resolve)=>setTimeout(resolve, TELEMETRY_FLUSH_TIMEOUT_MS).unref?.())
+                ]);
+            } catch  {}
+            await Promise.all([
+                process.stdout,
+                process.stderr
+            ].map((stream)=>new Promise((resolve)=>{
+                    if (0 === stream.writableLength) return resolve();
+                    stream.write('', ()=>resolve());
+                })));
+            process.exit(code);
+        }
+        var external_node_module_ = __webpack_require__("node:module");
+        const external_node_url_namespaceObject = require("node:url");
+        const extension_develop_runtime_require = (0, external_node_module_.createRequire)(__rslib_import_meta_url__);
+        function parseJsonSafe(filePath) {
+            return JSON.parse(external_node_fs_default().readFileSync(filePath, 'utf8'));
+        }
+        function resolveDevelopRootFromDir(dir) {
+            try {
+                const packageJsonPath = external_node_path_default().join(dir, 'package.json');
+                if (!external_node_fs_default().existsSync(packageJsonPath)) return;
+                const pkg = parseJsonSafe(packageJsonPath);
+                return pkg?.name === 'extension-develop' ? dir : void 0;
+            } catch  {
+                return;
+            }
+        }
+        function resolveWorkspaceDevelopRoot(startDir) {
+            let currentDir = external_node_path_default().resolve(startDir);
+            if (currentDir.split(external_node_path_default().sep).includes('node_modules')) return;
+            for(let depth = 0; depth < 8; depth += 1){
+                const candidate = external_node_path_default().join(currentDir, 'programs', 'develop');
+                const resolved = resolveDevelopRootFromDir(candidate);
+                if (resolved) return resolved;
+                const parent = external_node_path_default().dirname(currentDir);
+                if (parent === currentDir) break;
+                currentDir = parent;
+            }
+        }
+        function resolveInstalledDevelopRoot() {
+            try {
+                const packageJsonPath = extension_develop_runtime_require.resolve('extension-develop/package.json');
+                return resolveDevelopRootFromDir(external_node_path_default().dirname(packageJsonPath));
+            } catch  {
+                try {
+                    const entryPath = extension_develop_runtime_require.resolve('extension-develop');
+                    return resolveDevelopRootFromDir(external_node_path_default().dirname(external_node_path_default().dirname(entryPath)));
+                } catch  {
+                    return;
+                }
+            }
+        }
+        function resolvePreferredDevelopRoot(startDir) {
+            const workspaceRoot = resolveWorkspaceDevelopRoot(startDir);
+            if (workspaceRoot) return {
+                root: workspaceRoot,
+                source: 'workspace'
+            };
+            const envRoot = process.env.EXTENSION_DEVELOP_ROOT ? resolveDevelopRootFromDir(external_node_path_default().resolve(process.env.EXTENSION_DEVELOP_ROOT)) : void 0;
+            if (envRoot) return {
+                root: envRoot,
+                source: 'env'
+            };
+            const installedRoot = resolveInstalledDevelopRoot();
+            if (installedRoot) return {
+                root: installedRoot,
+                source: 'installed'
+            };
+            return {
+                root: void 0,
+                source: 'missing'
+            };
+        }
+        function resolveDevelopDistEntry(root, name = 'module') {
+            const base = external_node_path_default().join(root, 'dist', name);
+            const candidates = [
+                `${base}.mjs`,
+                `${base}.cjs`,
+                `${base}.js`,
+                base
+            ];
+            for (const candidate of candidates)if (external_node_fs_default().existsSync(candidate)) return candidate;
+        }
+        function resolveExtensionDevelopRoot(startDir = __dirname) {
+            const { root, source } = resolvePreferredDevelopRoot(startDir);
+            if (!root) throw new Error('Unable to locate the extension-develop runtime.');
+            process.env.EXTENSION_DEVELOP_ROOT = root;
+            if ('workspace' === source) process.env.EXTENSION_CREATE_DEVELOP_ROOT = root;
+            return root;
+        }
+        function resolveExtensionDevelopVersion(startDir = __dirname, fallbackVersion) {
+            try {
+                const root = resolveExtensionDevelopRoot(startDir);
+                const packageJsonPath = external_node_path_default().join(root, 'package.json');
+                const pkg = parseJsonSafe(packageJsonPath);
+                return pkg?.version || fallbackVersion || '0.0.0';
+            } catch  {
+                return fallbackVersion || '0.0.0';
+            }
         }
-        function renderCreateTemplateHelp() {
-            const total = listTemplates().length;
-            const dim = (text)=>external_pintor_default().gray(text);
-            const defaultIsBundled = BUNDLED_TEMPLATES.includes(DEFAULT_TEMPLATE);
-            return [
-                '',
-                external_pintor_default().underline(external_pintor_default().blue(`Templates (${total})`)),
-                renderTemplateList(),
-                '',
-                `  ${external_pintor_default().green('Default')}`,
-                `    ${external_pintor_default().blue(DEFAULT_TEMPLATE)} ${dim('is used when --template is omitted.')}`,
-                ...defaultIsBundled ? [
-                    dim('    It ships inside the CLI, so it scaffolds with no network.')
-                ] : [
-                    dim('    It downloads the catalog archive like every other name.')
-                ],
-                '',
-                `  ${external_pintor_default().green('Everything else')}`,
-                dim('    downloads the catalog archive at create time, so it needs the'),
-                dim('    network and takes longer. A GitHub URL or a ZIP URL also works.'),
-                `    ${external_pintor_default().blue(TEMPLATE_CATALOG_URL)}`,
-                ''
-            ].join('\n');
+        async function importModule(filePath) {
+            const mod = await import((0, external_node_url_namespaceObject.pathToFileURL)(filePath).href);
+            return mod?.default && 'object' == typeof mod.default ? {
+                ...mod.default,
+                ...mod
+            } : mod;
+        }
+        async function loadExtensionDevelopModule(startDir = __dirname) {
+            const root = resolveExtensionDevelopRoot(startDir);
+            const { source } = resolvePreferredDevelopRoot(startDir);
+            const distEntry = resolveDevelopDistEntry(root);
+            if (distEntry) return importModule(distEntry);
+            if ('workspace' === source) throw new Error(`Local extension-develop runtime is not built at ${external_node_path_default().join(root, 'dist')}. Run \`pnpm --filter extension-develop compile\` before invoking the local CLI.`);
+            return await import("extension-develop");
+        }
+        async function loadExtensionDevelopPreviewModule(startDir = __dirname) {
+            const root = resolveExtensionDevelopRoot(startDir);
+            const { source } = resolvePreferredDevelopRoot(startDir);
+            const previewEntry = resolveDevelopDistEntry(root, 'preview');
+            if (previewEntry) return importModule(previewEntry);
+            const fullEntry = resolveDevelopDistEntry(root);
+            if (fullEntry) return importModule(fullEntry);
+            if ('workspace' === source) throw new Error(`Local extension-develop runtime is not built at ${external_node_path_default().join(root, 'dist')}. Run \`pnpm --filter extension-develop compile\` before invoking the local CLI.`);
+            return await import("extension-develop/preview");
+        }
+        async function loadExtensionDevelopBridgeModule(startDir = __dirname) {
+            const root = resolveExtensionDevelopRoot(startDir);
+            const { source } = resolvePreferredDevelopRoot(startDir);
+            const bridgeEntry = resolveDevelopDistEntry(root, 'bridge');
+            if (bridgeEntry) return importModule(bridgeEntry);
+            if ('workspace' === source) throw new Error(`Local extension-develop runtime is not built at ${external_node_path_default().join(root, 'dist')}. Run \`pnpm --filter extension-develop compile\` before invoking the local CLI.`);
+            const bridgeSpecifier = 'extension-develop/bridge';
+            return await import(bridgeSpecifier);
         }
+        var messaging = __webpack_require__("./helpers/messaging.ts");
         function getLoggingPrefix(type) {
             return (0, messaging.Pl)(type);
         }
@@ -7856,9 +8110,135 @@ Cross-browser compatibility
         function deprecatedOutputAlias(flag) {
             return `${getLoggingPrefix('warn')} ${messages_code(flag)} is deprecated and maps to ${messages_code('--output')}.\nPass ${messages_code('--output')} ${messages_arg('<pretty|json>')} instead.`;
         }
+        const OPEN_SURFACE_NOUN = {
+            popup: 'popup',
+            sidebar: 'side panel',
+            action: 'action popup'
+        };
+        function openSurfaceNoun(surface) {
+            return OPEN_SURFACE_NOUN[surface] || surface;
+        }
+        function openSurfaceGestureStep(surface) {
+            return `Click the extension's toolbar entry, or its row in the extensions menu, to open the ${openSurfaceNoun(surface)}.`;
+        }
+        function openSurfaceNeedsGesturePlain(surface) {
+            return `Chromium opens the ${openSurfaceNoun(surface)} only in response to a user gesture, so extension open ${surface} can't open it from the command line.`;
+        }
+        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 sessionOnPort(browser, port) {
+            return port ? `for ${browser} on port ${port}` : `for ${browser}`;
+        }
+        function controlDisabledInSessionPlain(browser, port, flag) {
+            return `The dev session ${sessionOnPort(browser, port)} refused the controller because control is off in that session. Restart the dev session with ${flag} to turn it on, or run extension doctor when a session started with ${flag} still answers this way.`;
+        }
+        function controlDisabledInSession(browser, port, flag) {
+            return `${getLoggingPrefix('error')} The dev session ${sessionOnPort(browser, port)} refused the controller because control is off in that session.\nRestart the dev session with ${messages_code(flag)} to turn it on, or run ${messages_code('extension doctor')} when a session started with ${messages_code(flag)} still answers this way.`;
+        }
         function noBrowserNotSupportedForCommand(command) {
             return `${getLoggingPrefix('error')} ${messages_code('--no-browser')} is only supported for ${messages_code('dev')}, ${messages_code('start')}, and ${messages_code('preview')}.\n${messaging.Sc.label('GOT')} ${messages_code(command || '(none)')}`;
         }
+        let warnedDeprecatedAlias = false;
+        function warnDeprecatedOutputAlias(flag) {
+            if (warnedDeprecatedAlias) return;
+            warnedDeprecatedAlias = true;
+            console.error(deprecatedOutputAlias(flag));
+        }
+        function normalizeOutputFormat(value) {
+            const v = String(value ?? '').trim().toLowerCase();
+            return 'pretty' === v || 'json' === v ? v : void 0;
+        }
+        const normalize = normalizeOutputFormat;
+        function isJsonOutput(opts) {
+            return 'json' === resolveOutputFormat(opts);
+        }
+        function resolveOutputFormat(opts) {
+            const direct = normalize(opts.output);
+            if (direct) return direct;
+            const aliases = [
+                [
+                    '--format',
+                    opts.format
+                ],
+                [
+                    '--wait-format',
+                    opts.waitFormat
+                ]
+            ];
+            for (const [flag, value] of aliases){
+                const resolved = normalize(value);
+                if (resolved) {
+                    warnDeprecatedOutputAlias(flag);
+                    return resolved;
+                }
+            }
+            return 'pretty';
+        }
+        function resolveSessionProjectPath(bridge, pathArg) {
+            const inputPath = external_node_path_default().resolve(pathArg || process.cwd());
+            const resolve = bridge?.resolveSessionProjectRoot;
+            if ('function' != typeof resolve) return inputPath;
+            try {
+                const resolved = resolve(inputPath);
+                return 'string' == typeof resolved && resolved ? resolved : inputPath;
+            } catch  {
+                return inputPath;
+            }
+        }
+        function sessionFilePath(bridge, exportName, projectPath, browser, fileName) {
+            const fn = bridge?.[exportName];
+            if ('function' == typeof fn) try {
+                const resolved = fn(projectPath, browser);
+                if ('string' == typeof resolved && resolved) return resolved;
+            } catch  {}
+            return external_node_path_default().join(projectPath, 'dist', 'extension-js', browser, fileName);
+        }
+        function sessionReadyPath(bridge, projectPath, browser) {
+            return sessionFilePath(bridge, 'readyContractPath', projectPath, browser, 'ready.json');
+        }
+        function sessionLogsPath(bridge, projectPath, browser) {
+            return sessionFilePath(bridge, 'logsPath', projectPath, browser, 'logs.ndjson');
+        }
+        function parseLogSinceLocal(value) {
+            if (null == value || '' === value) return null;
+            if ('number' == typeof value) return Number.isFinite(value) ? {
+                seq: value
+            } : void 0;
+            const text = String(value).trim();
+            if (/^\d+(?:\.\d+)?$/.test(text)) return {
+                seq: Number(text)
+            };
+            const time = Date.parse(text);
+            return Number.isFinite(time) ? {
+                time
+            } : void 0;
+        }
+        function isAfterSinceLocal(event, since) {
+            if ('seq' in since) return !('number' == typeof event.seq && event.seq <= since.seq);
+            const raw = event.timestamp;
+            const time = 'number' == typeof raw ? raw : 'string' == typeof event.ts ? Date.parse(String(event.ts)) : NaN;
+            return !Number.isFinite(time) || time > since.time;
+        }
+        function sinceHelpersFrom(bridge) {
+            const candidate = bridge;
+            return {
+                parseLogSince: 'function' == typeof candidate?.parseLogSince ? candidate.parseLogSince : parseLogSinceLocal,
+                isAfterSince: 'function' == typeof candidate?.isAfterSince ? candidate.isAfterSince : isAfterSinceLocal
+            };
+        }
+        function parseLogLine(line) {
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            } catch  {
+                return null;
+            }
+            return isLogEventLike(parsed) ? parsed : null;
+        }
+        function isLogEventLike(value) {
+            return Boolean(value) && 'object' == typeof value && !Array.isArray(value);
+        }
         const LEVEL_ORDER = [
             'error',
             'warn',
@@ -7887,10 +8267,9 @@ Cross-browser compatibility
                 return candidates.some((c)=>re ? re.test(c) : c.includes(pattern));
             };
         }
-        function makeFilter(opts) {
+        function makeFilter(opts, since, helpers) {
             const minLevel = String(opts.level || 'all').toLowerCase();
             const contexts = opts.context && 'all' !== opts.context.toLowerCase() ? new Set(opts.context.split(',').map((c)=>c.trim())) : null;
-            const sinceSeq = null != opts.since ? Number(opts.since) : null;
             const urlMatches = opts.url ? makeUrlMatcher(opts.url) : null;
             const tabId = null != opts.tab && '' !== opts.tab ? Number(opts.tab) : null;
             return (event)=>{
@@ -7901,14 +8280,15 @@ Cross-browser compatibility
                 if ('all' !== minLevel && 'off' !== minLevel) {
                     if (levelRank(String(event.level || '')) > levelRank(minLevel)) return false;
                 }
-                if (null != sinceSeq && Number.isFinite(sinceSeq) && 'number' == typeof event.seq && event.seq <= sinceSeq) return false;
+                if (since && !helpers.isAfterSince(event, since)) return false;
                 if (urlMatches && !urlMatches(event)) return false;
                 if (null != tabId && Number.isFinite(tabId) && event.tabId !== tabId) return false;
                 return true;
             };
         }
         function resolveFormat(opts) {
-            if (opts.output) return opts.output;
+            const requested = String(opts.output ?? '').trim().toLowerCase();
+            if ('pretty' === requested || 'json' === requested || 'ndjson' === requested) return requested;
             return process.stdout.isTTY ? 'pretty' : 'ndjson';
         }
         function printEvent(event, format) {
@@ -7929,18 +8309,28 @@ Cross-browser compatibility
                 console.log(JSON.stringify(frame));
             }
         }
-        function logsFilePath(projectPath, browser) {
-            return external_node_path_default().resolve(projectPath, 'dist', 'extension-js', browser, 'logs.ndjson');
-        }
         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').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 projectPath = external_node_path_default().resolve(projectPathArg || process.cwd());
+            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)=>{
+                const bridge = await loadExtensionDevelopBridgeModule();
+                const projectPath = resolveSessionProjectPath(bridge, projectPathArg);
                 const browser = options.browser || 'chromium';
                 const format = resolveFormat(options);
-                const matches = makeFilter(options);
+                const helpers = sinceHelpersFrom(bridge);
+                const since = helpers.parseLogSince(options.since);
+                if (null != options.since && '' !== options.since && void 0 === since) {
+                    const message = `extension logs --since expects a sequence number or an ISO timestamp, got: ${options.since}`;
+                    console.error(message);
+                    if ('pretty' !== format) writeFrame(messaging.Pr.fail('logs', 'usage', {
+                        code: messaging.Lp.E_INVALID_OPTION,
+                        message,
+                        name: 'CliError'
+                    }));
+                    process.exit(1);
+                }
+                const matches = makeFilter(options, since ?? null, helpers);
                 if (options.signalsOnly) console.error("extension logs --signals-only: no signals emitter ships in this build, so dev sessions record no dx.signal events and this filter will print nothing.");
                 if (options.follow) return void await followLogs(projectPath, browser, format, matches);
-                const file = logsFilePath(projectPath, browser);
+                const file = sessionLogsPath(bridge, projectPath, browser);
                 if (!external_node_fs_default().existsSync(file)) {
                     const message = `No logs found at ${file}. Start a dev session (extension dev) first, or pass --browser to match it.`;
                     console.error(message);
@@ -7953,21 +8343,17 @@ Cross-browser compatibility
                 }
                 const lines = external_node_fs_default().readFileSync(file, 'utf-8').split('\n').filter(Boolean);
                 for (const line of lines){
-                    let event;
-                    try {
-                        event = JSON.parse(line);
-                    } catch  {
-                        continue;
-                    }
-                    if (matches(event)) printEvent(event, format);
+                    const event = parseLogLine(line);
+                    if (event && matches(event)) printEvent(event, format);
                 }
             });
         }
         async function followLogs(projectPath, browser, format, matches) {
-            const { BridgeConsumer, readReadyContract } = await loadExtensionDevelopBridgeModule();
+            const bridge = await loadExtensionDevelopBridgeModule();
+            const { BridgeConsumer, readReadyContract } = bridge;
             const ready = readReadyContract(projectPath, browser);
             if (!ready) {
-                const message = `No active dev session control channel found for ${browser}. Run \`extension dev --browser=${browser}\` first.`;
+                const message = `No active dev session control channel found for ${browser}. Looked at ${sessionReadyPath(bridge, projectPath, browser)}. Run \`extension dev --browser=${browser}\` first.`;
                 console.error(message);
                 if ('pretty' !== format) writeFrame(messaging.Pr.fail('logs', 'not-found', {
                     code: messaging.Lp.E_SESSION_NOT_FOUND,
@@ -7976,6 +8362,19 @@ Cross-browser compatibility
                 }));
                 process.exit(1);
             }
+            let settle = ()=>{};
+            const settled = new Promise((resolve)=>{
+                settle = resolve;
+            });
+            const refusals = new Set([
+                bridge.CLOSE_BAD_INSTANCE,
+                bridge.CLOSE_BAD_HELLO,
+                bridge.CLOSE_CONTROL_UNAVAILABLE
+            ].filter((code)=>'number' == typeof code));
+            const sessionStillNamed = ()=>{
+                const current = readReadyContract(projectPath, browser);
+                return Boolean(current) && 'stopped' !== current.status && current.instanceId === ready.instanceId && current.controlPort === ready.controlPort;
+            };
             const consumer = new BridgeConsumer({
                 controlPort: ready.controlPort,
                 instanceId: ready.instanceId,
@@ -7985,6 +8384,18 @@ Cross-browser compatibility
                 },
                 onGap: (gap)=>{
                     console.error(`… ${gap.dropped} event(s) dropped (${gap.reason}), stream is behind`);
+                },
+                onClose: (close)=>{
+                    if (!refusals.has(close.code) && sessionStillNamed()) return;
+                    consumer.close();
+                    const why = close.reason ? `${close.code}, ${close.reason}` : close.code;
+                    console.error(`extension logs --follow: the control channel closed (${why}) and the dev session is over.`);
+                    if ('pretty' !== format) console.log(JSON.stringify(messaging.Pr.ok('logs', 'closed', {
+                        closeCode: close.code,
+                        reason: close.reason,
+                        follow: true
+                    })));
+                    settle();
                 }
             });
             const shutdown = (signal)=>{
@@ -7998,7 +8409,7 @@ Cross-browser compatibility
             process.on('SIGINT', ()=>shutdown('SIGINT'));
             process.on('SIGTERM', ()=>shutdown('SIGTERM'));
             consumer.start();
-            await new Promise(()=>{});
+            await settled;
         }
         function readRecentConsole(projectPath, browser, target, limit) {
             const file = external_node_path_default().resolve(projectPath, 'dist', 'extension-js', browser, 'logs.ndjson');
@@ -8098,15 +8509,54 @@ Cross-browser compatibility
         }
         function fail(message, frame) {
             console.error(message);
-            if (frame && 'json' === frame.output) act_writeFrame(messaging.Pr.fail(frame.command, statusForCode(frame.code), {
+            if (frame && 'json' === normalizeOutputFormat(frame.output)) act_writeFrame(messaging.Pr.fail(frame.command, statusForCode(frame.code), {
                 code: frame.code,
-                message,
-                name: 'CliError'
+                message: frame.plain ?? message,
+                name: 'CliError',
+                ...frame.hint ? {
+                    hint: frame.hint
+                } : {}
             }));
             process.exit(1);
         }
+        function isChromiumFamily(browser) {
+            return !/firefox|gecko|safari|webkit/i.test(browser);
+        }
+        function readSessionManifest(bridge, projectPath, browser) {
+            const candidates = [];
+            const readDocument = bridge?.readReadyContractDocument;
+            if ('function' == typeof readDocument) try {
+                const doc = readDocument(projectPath, browser);
+                if (doc && 'string' == typeof doc.distPath) candidates.push(external_node_path_default().join(doc.distPath, 'manifest.json'));
+                if (doc && 'string' == typeof doc.manifestPath) candidates.push(doc.manifestPath);
+            } catch  {}
+            candidates.push(external_node_path_default().join(projectPath, 'manifest.json'));
+            for (const file of candidates)try {
+                const parsed = JSON.parse(external_node_fs_default().readFileSync(file, 'utf-8'));
+                if (parsed && 'object' == typeof parsed && !Array.isArray(parsed)) return parsed;
+            } catch  {}
+        }
+        function manifestDeclaresPopup(manifest) {
+            for (const [key, value] of Object.entries(manifest)){
+                if (!/(?:^|:)(?:action|browser_action)$/.test(key)) continue;
+                const popup = value?.default_popup;
+                if ('string' == typeof popup && popup.trim()) return true;
+            }
+            return false;
+        }
+        function gestureRefusal(surface, bridge, projectPath, browser) {
+            if (!isChromiumFamily(browser)) return;
+            const gated = 'popup' === surface || 'sidebar' === surface || 'action' === surface && manifestDeclaresPopup(readSessionManifest(bridge, projectPath, browser) ?? {});
+            if (!gated) return;
+            return {
+                message: openSurfaceNeedsGesture(surface),
+                plain: openSurfaceNeedsGesturePlain(surface),
+                code: messaging.Lp.E_USER_GESTURE_REQUIRED,
+                hint: openSurfaceGestureStep(surface)
+            };
+        }
         function printResult(result, output, command) {
-            if ('json' === output) return void console.log(JSON.stringify(buildActEnvelope(command, result)));
+            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));
@@ -8125,16 +8575,24 @@ Cross-browser compatibility
             console.error(`${err.name}: ${err.message}${err.engine ? ` (engine: ${err.engine})` : ''}`);
         }
         async function runCommand(input) {
-            const projectPath = external_node_path_default().resolve(input.projectPathArg || process.cwd());
+            const bridge = await loadExtensionDevelopBridgeModule();
+            const projectPath = resolveSessionProjectPath(bridge, input.projectPathArg);
             const browser = input.opts.browser || 'chromium';
-            const { BridgeController, readReadyContract, readControlToken } = await loadExtensionDevelopBridgeModule();
+            const { BridgeController, readReadyContract, readControlToken } = bridge;
             const outputFrame = {
                 command: input.command,
                 output: input.opts.output
             };
             const unlockFlag = 'eval' === input.op ? '--allow-eval' : '--allow-control';
+            const refusal = input.preflight?.(bridge, projectPath, browser);
+            if (refusal) fail(refusal.message, {
+                ...outputFrame,
+                code: refusal.code,
+                plain: refusal.plain,
+                hint: refusal.hint
+            });
             const ready = readReadyContract(projectPath, browser);
-            if (!ready) fail(`No active control channel found for ${browser}. Run \`extension dev --browser=${browser} ${unlockFlag}\` first.`, {
+            if (!ready) fail(`No active control channel found for ${browser}. Looked at ${sessionReadyPath(bridge, projectPath, browser)}. Run \`extension dev --browser=${browser} ${unlockFlag}\` first.`, {
                 ...outputFrame,
                 code: messaging.Lp.E_SESSION_NOT_FOUND
             });
@@ -8150,6 +8608,12 @@ Cross-browser compatibility
             } catch (err) {
                 controller.close();
                 const message = err?.message || 'could not connect to the control channel';
+                const closeCode = err?.closeCode;
+                if (4003 === closeCode || /code 4003\b/.test(message)) fail(controlDisabledInSession(browser, ready.controlPort, unlockFlag), {
+                    ...outputFrame,
+                    code: messaging.Lp.E_CONTROL_DENIED,
+                    plain: controlDisabledInSessionPlain(browser, ready.controlPort, unlockFlag)
+                });
                 fail(message, {
                     ...outputFrame,
                     code: /code 40\d\d/.test(message) ? messaging.Lp.E_CONTROL_DENIED : messaging.Lp.E_CONTROL_UNAVAILABLE
@@ -8321,13 +8785,25 @@ Cross-browser compatibility
                         context
                     },
                     args,
-                    opts
+                    opts,
+                    preflight: (bridge, projectPath, browser)=>gestureRefusal(surface, bridge, projectPath, browser)
                 });
             });
         }
         var safari_launch = __webpack_require__("./browsers/run-safari/safari-launch/index.ts");
         var safari_config = __webpack_require__("./browsers/run-safari/safari-launch/safari-config.ts");
         var safari_packager = __webpack_require__("./browsers/run-safari/safari-packager.ts");
+        async function resolveConfigBrowser(projectPath, command) {
+            try {
+                const develop = await loadExtensionDevelopModule();
+                if ('function' != typeof develop.loadCommandConfig) return;
+                const config = await develop.loadCommandConfig(projectPath, command);
+                const browser = config?.browser;
+                return 'string' == typeof browser && browser.length > 0 ? browser : void 0;
+            } catch  {
+                return;
+            }
+        }
         function parseLogContexts(raw) {
             if (!raw || 0 === String(raw).trim().length) return;
             if ('all' === String(raw).trim().toLowerCase()) return;
@@ -8438,7 +8914,8 @@ Cross-browser compatibility
             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('--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 = 'chromium', ...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('--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 })=>{
+                const browser = cliBrowser ?? await resolveConfigBrowser(pathOrRemoteUrl || process.cwd(), 'build') ?? 'chromium';
                 if (buildOptions.debug || buildOptions.author || buildOptions.authorMode) {
                     process.env.EXTENSION_DEBUG = '1';
                     process.env.EXTENSION_AUTHOR_MODE = 'true';
@@ -8502,7 +8979,7 @@ Cross-browser compatibility
                     }
                 }
                 const { extensionBuild } = await loadExtensionDevelopModule();
-                const asJson = 'json' === buildOptions.output;
+                const asJson = isJsonOutput(buildOptions);
                 if (asJson) process.env.EXTENSION_OUTPUT = 'json';
                 const built = [];
                 const summaries = [];
@@ -8601,7 +9078,9 @@ Cross-browser compatibility
         }
         function registerCreateCommand(program) {
             program.command('create').arguments('<project-name|project-path>').usage('<project-name|project-path> [options]').description(commandDescriptions.create).option('-t, --template <template-name>', `catalog name, GitHub URL, or ZIP URL to scaffold from; every catalog name is listed below (default: ${DEFAULT_TEMPLATE})`).option('--install [boolean]', 'whether or not to install the dependencies after creating the project (disabled by default, pass --install to opt in)', parseOptionalBoolean, false).option('--source <source>', 'attribution tag for where this create was initiated (e.g. cli, templates); recorded in anonymous telemetry only').option('--output <pretty|json>', 'result format. Use json for a schema-1 envelope on stdout').addHelpText('after', renderCreateTemplateHelp()).action(async (pathOrRemoteUrl, { template, install, output })=>{
-                const asJson = 'json' === output;
+                const asJson = isJsonOutput({
+                    output
+                });
                 if (!process.env.EXTENSION_CREATE_DEVELOP_ROOT) try {
                     process.env.EXTENSION_CREATE_DEVELOP_ROOT = resolveExtensionDevelopRoot();
                 } catch  {
@@ -8672,6 +9151,59 @@ Cross-browser compatibility
                 ].includes(normalized)) return true;
             }
         }
+        function scanArgvValue(argv, flag) {
+            const equalArg = argv.find((arg)=>arg.startsWith(`${flag}=`));
+            if (equalArg) return equalArg.slice(flag.length + 1);
+            const flagIndex = argv.indexOf(flag);
+            if (flagIndex >= 0) return argv[flagIndex + 1] || '';
+        }
+        function collectValuedLongFlags(program) {
+            const flags = new Set();
+            const visit = (command)=>{
+                for (const option of command.options)if (option.long && (option.required || option.optional)) flags.add(option.long);
+                for (const sub of command.commands)visit(sub);
+            };
+            visit(program);
+            return flags;
+        }
+        function resolveCommandFromArgv(argv, valuedFlags = new Set()) {
+            for(let i = 2; i < argv.length; i += 1){
+                const arg = argv[i];
+                if (arg.startsWith('-')) {
+                    if (valuedFlags.has(arg)) i += 1;
+                    continue;
+                }
+                return arg;
+            }
+        }
+        function rewriteOutputAliasArgv(argv, valuedFlags = new Set()) {
+            const index = argv.findIndex((arg)=>'--format' === arg || arg.startsWith('--format='));
+            if (index < 0) return {
+                argv,
+                rewritten: false
+            };
+            const next = [
+                ...argv
+            ];
+            const tokens = [];
+            if (next[index].startsWith('--format=')) {
+                tokens.push(`--output=${next[index].slice(9)}`);
+                next.splice(index, 1);
+            } else {
+                tokens.push('--output');
+                const value = next[index + 1];
+                next.splice(index, void 0 === value || value.startsWith('-') ? 1 : 2);
+                if (void 0 !== value && !value.startsWith('-')) tokens.push(value);
+            }
+            const command = resolveCommandFromArgv(next, valuedFlags);
+            const commandIndex = command ? next.indexOf(command, 2) : -1;
+            if (commandIndex >= index) next.splice(commandIndex + 1, 0, ...tokens);
+            else next.splice(index, 0, ...tokens);
+            return {
+                argv: next,
+                rewritten: true
+            };
+        }
         const FRAMED_FLAG = 'extensionEnvelopePrinted';
         function markErrorFramed(err) {
             if (err && 'object' == typeof err) try {
@@ -8682,11 +9214,7 @@ Cross-browser compatibility
             return Boolean(err && 'object' == typeof err && true === err[FRAMED_FLAG]);
         }
         function wantsJsonOutput(argv) {
-            const equalArg = argv.find((arg)=>arg.startsWith('--output='));
-            if (equalArg) return 'json' === equalArg.slice(9).trim().toLowerCase();
-            const flagIndex = argv.indexOf('--output');
-            if (flagIndex >= 0) return 'json' === String(argv[flagIndex + 1] || '').trim().toLowerCase();
-            return false;
+            return 'json' === normalizeOutputFormat(scanArgvValue(argv, '--output'));
         }
         function isCommanderError(err) {
             return Boolean(err && 'object' == typeof err && 'string' == typeof err.code && String(err.code).startsWith('commander.'));
@@ -8784,16 +9312,14 @@ Cross-browser compatibility
                 console.log(JSON.stringify(frame));
             }
         }
-        async function resolveConfigBrowser(projectPath, command) {
-            try {
-                const develop = await loadExtensionDevelopModule();
-                if ('function' != typeof develop.loadCommandConfig) return;
-                const config = await develop.loadCommandConfig(projectPath, command);
-                const browser = config?.browser;
-                return 'string' == typeof browser && browser.length > 0 ? browser : void 0;
-            } catch  {
-                return;
-            }
+        function geckoBinaryOption() {
+            return new external_commander_namespaceObject.Option('--gecko-binary <path-to-binary>', 'specify a path to the Gecko binary (alias: --firefox-binary). This option overrides the --browser setting. Defaults to the system default');
+        }
+        function firefoxBinaryAliasOption() {
+            return new external_commander_namespaceObject.Option('--firefox-binary <path-to-binary>').hideHelp();
+        }
+        function cliGeckoBinary(opts) {
+            return opts.geckoBinary ?? opts.firefoxBinary;
         }
         async function resolveNoBrowser(projectPath, command) {
             if ('1' === process.env.EXTENSION_CLI_NO_BROWSER) return true;
@@ -8806,38 +9332,6 @@ Cross-browser compatibility
                 return false;
             }
         }
-        let warnedDeprecatedAlias = false;
-        function warnDeprecatedOutputAlias(flag) {
-            if (warnedDeprecatedAlias) return;
-            warnedDeprecatedAlias = true;
-            console.error(deprecatedOutputAlias(flag));
-        }
-        function normalize(value) {
-            const v = String(value ?? '').trim().toLowerCase();
-            return 'pretty' === v || 'json' === v ? v : void 0;
-        }
-        function resolveOutputFormat(opts) {
-            const direct = normalize(opts.output);
-            if (direct) return direct;
-            const aliases = [
-                [
-                    '--format',
-                    opts.format
-                ],
-                [
-                    '--wait-format',
-                    opts.waitFormat
-                ]
-            ];
-            for (const [flag, value] of aliases){
-                const resolved = normalize(value);
-                if (resolved) {
-                    warnDeprecatedOutputAlias(flag);
-                    return resolved;
-                }
-            }
-            return 'pretty';
-        }
         const POLL_INTERVAL_MS = 2000;
         const HARD_EXIT_GRACE_MS = 5000;
         function isProcessAlive(pid) {
@@ -8897,9 +9391,17 @@ Cross-browser compatibility
             if (!value) return false;
             return /^https?:\/\//i.test(value);
         }
-        function resolveProjectPath(pathOrRemoteUrl) {
-            if (!pathOrRemoteUrl) return process.cwd();
-            return external_node_path_.isAbsolute(pathOrRemoteUrl) ? pathOrRemoteUrl : external_node_path_.join(process.cwd(), pathOrRemoteUrl);
+        async function resolveProjectPath(pathOrRemoteUrl) {
+            let bridge;
+            try {
+                bridge = await loadExtensionDevelopBridgeModule();
+            } catch  {
+                bridge = void 0;
+            }
+            return {
+                projectPath: resolveSessionProjectPath(bridge, pathOrRemoteUrl),
+                bridge
+            };
         }
         function parseWaitTimeoutMs(value) {
             const fallback = 60000;
@@ -8911,7 +9413,7 @@ Cross-browser compatibility
             return fallback;
         }
         function parseWaitFormat(value) {
-            return 'json' === value ? 'json' : 'pretty';
+            return normalizeOutputFormat(value) ?? 'pretty';
         }
         class WaitModeError extends Error {
             constructor(message, code){
@@ -8966,7 +9468,7 @@ Cross-browser compatibility
             return false;
         }
         async function waitForReadyContract(options) {
-            const readyPath = external_node_path_.join(options.projectPath, 'dist', 'extension-js', options.browser, 'ready.json');
+            const readyPath = sessionReadyPath(options.bridge, options.projectPath, options.browser);
             const start = Date.now();
             while(Date.now() - start < options.timeoutMs){
                 if (external_node_fs_.existsSync(readyPath)) try {
@@ -9002,7 +9504,7 @@ Cross-browser compatibility
         }
         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);
-            const projectPath = resolveProjectPath(options.pathOrRemoteUrl);
+            const { projectPath, bridge } = await resolveProjectPath(options.pathOrRemoteUrl);
             const timeoutMs = parseWaitTimeoutMs(options.waitTimeout);
             const format = parseWaitFormat(options.waitFormat);
             const results = [];
@@ -9010,6 +9512,7 @@ Cross-browser compatibility
                 const payload = await waitForReadyContract({
                     command: options.command,
                     projectPath,
+                    bridge,
                     browser,
                     timeoutMs
                 });
@@ -9041,7 +9544,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    do not launch the browser (dev server still starts)\n  --no-reload     emit a dev-mode dist without the content-script reload runtime; tabs need manual reload to see changes\n  --wait          wait for ready contract and exit; pair with --output json for machine output\n").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').option('--gecko-binary, --firefox-binary <path-to-binary>', 'specify a path to the Gecko binary. This option overrides the --browser setting. Defaults to the system default').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', 'do not open the browser automatically (default: open)').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    do not launch the browser (dev server still starts)\n  --no-reload     emit a dev-mode dist without the content-script reload runtime; tabs need manual reload to see changes\n  --wait          wait for ready contract and exit; pair with --output json for machine output\n").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', 'do not open the browser automatically (default: open)').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) {
@@ -9175,7 +9678,7 @@ Cross-browser compatibility
                         profile: (0, resolve_profile.Md)(devOptions.profile),
                         browser: vendor,
                         chromiumBinary: devOptions.chromiumBinary,
-                        geckoBinary: devOptions.geckoBinary,
+                        geckoBinary: cliGeckoBinary(devOptions),
                         polyfill: explicitCliValue(command, 'polyfill', explicitOptionalBoolean(devOptions.polyfill)),
                         noOpen: explicitNoOpen,
                         macOsOnly: opts.macosOnly,
@@ -9244,13 +9747,12 @@ Cross-browser compatibility
                 return [];
             }
         }
-        function resolveDoctorBrowser(projectPathArg, optsBrowser) {
+        function resolveDoctorBrowser(projectPath, optsBrowser) {
             if (optsBrowser) return {
                 browser: optsBrowser,
                 sessionBrowsers: []
             };
-            const projectPath = external_node_path_default().resolve(projectPathArg || process.cwd());
-            const sessionBrowsers = listSessionBrowsers(projectPath);
+            const sessionBrowsers = listSessionBrowsers(external_node_path_default().resolve(projectPath || process.cwd()));
             if (1 === sessionBrowsers.length) return {
                 browser: sessionBrowsers[0],
                 sessionBrowsers
@@ -9269,8 +9771,9 @@ Cross-browser compatibility
             };
         }
         async function runDoctor(projectPathArg, opts) {
-            const projectPath = external_node_path_default().resolve(projectPathArg || process.cwd());
-            const { browser, sessionBrowsers } = resolveDoctorBrowser(projectPathArg, opts.browser);
+            const bridge = await loadExtensionDevelopBridgeModule();
+            const projectPath = resolveSessionProjectPath(bridge, projectPathArg);
+            const { browser, sessionBrowsers } = resolveDoctorBrowser(projectPath, opts.browser);
             const results = [];
             if (sessionBrowsers.length > 1) results.push({
                 check: 'session-resolution',
@@ -9285,13 +9788,13 @@ Cross-browser compatibility
                     detail: `skipped: blocked by ${blockedBy}`
                 });
             };
-            const { BridgeController, readReadyContract, readControlToken, readPersistedControlPort, controlPortFilePath } = await loadExtensionDevelopBridgeModule();
+            const { BridgeController, readReadyContract, readControlToken, readPersistedControlPort, controlPortFilePath } = bridge;
             const ready = readReadyContract(projectPath, browser);
             if (!ready) {
                 results.push({
                     check: 'ready-contract',
                     status: 'fail',
-                    detail: `no ready contract at dist/extension-js/${browser}/ready.json`,
+                    detail: `no ready contract at ${sessionReadyPath(bridge, projectPath, browser)}`,
                     remediation: `Start a dev session first: extension dev --browser=${browser} --allow-control (add --allow-eval for the eval verb)`
                 });
                 for (const check of [
@@ -9392,7 +9895,7 @@ Cross-browser compatibility
                         detail = 'refused: ready.json instanceId no longer matches the live server';
                         remediation = "A newer session overwrote the contract, or this dist belongs to another session, re-read ready.json or restart the dev session";
                     } else if ('4003' === code) {
-                        detail = 'refused: session was not started with --allow-control';
+                        detail = 'refused: control is off in the session that answered';
                         remediation = `Restart with control enabled: extension dev --browser=${browser} --allow-control`;
                     }
                     results.push({
@@ -9513,8 +10016,8 @@ Cross-browser compatibility
             browser: messaging.Lp.E_BROWSER_LAUNCH
         };
         function registerDoctorCommand(program) {
-            program.command('doctor').argument('[project-path]', 'path to the extension project root').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)=>{
-                const asJson = 'json' === opts.output;
+            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)=>{
+                const asJson = isJsonOutput(opts);
                 let results;
                 try {
                     results = await runDoctor(projectPathArg, opts);
@@ -9596,7 +10099,7 @@ Cross-browser compatibility
         }
         function registerInstallCommand(program) {
             program.command('install').arguments('[browser-name]').usage('[browser-name] [options]').description(commandDescriptions.install).option(`--browser <${MANAGED_INSTALL_TARGETS_HELP}>`, 'override the positional browser name. Supports comma-separated values and `all`.').option('--where', 'print the resolved managed browser cache root').option('--output <pretty|json>', 'result format. Use json for a schema-1 envelope on stdout').action(async (browserArg, options)=>{
-                const asJson = 'json' === options.output;
+                const asJson = isJsonOutput(options);
                 const named = Boolean(options.browser || browserArg);
                 const selectedBrowser = options.browser || browserArg || 'chromium';
                 const browserList = installTargets(selectedBrowser);
@@ -9636,7 +10139,9 @@ Cross-browser compatibility
                 }));
             });
             program.command('uninstall').usage('<browser-name> | --all | --where').description(commandDescriptions.uninstall).option(`--browser <${MANAGED_INSTALL_TARGETS_HELP}>`, 'browser(s) to uninstall. Supports comma-separated values and `all`.').option('--all', 'remove all managed browser binaries').option('--where', 'print the resolved managed browser cache root').option('--output <pretty|json>', 'result format. Use json for a schema-1 envelope on stdout').argument('[browser-name]').action(async (browserArg, { browser, all, where, output })=>{
-                const asJson = 'json' === output;
+                const asJson = isJsonOutput({
+                    output
+                });
                 const named = Boolean(browserArg || browser);
                 const selected = all || 'all' === browserArg || 'all' === browser ? 'all' : browser || browserArg;
                 const { extensionUninstall, getManagedBrowsersCacheRoot, getManagedBrowserInstallDir } = await import("extension-install");
@@ -9704,14 +10209,15 @@ Cross-browser compatibility
             'Manifest file not found'
         ];
         function registerPreviewCommand(program) {
-            program.command('preview').arguments('[project-name]').usage('[path-to-remote-extension] [options]').description(commandDescriptions.preview).addHelpText('after', '\nAdditional option:\n  --no-browser    do not launch the browser\n').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(`--browser <${NO_SAFARI_BROWSER_TARGETS_HELP}>`, 'specify a browser/engine to run. Defaults to `chromium`').option('--chromium-binary <path-to-binary>', 'specify a path to the Chromium binary. This option overrides the --browser setting. Defaults to the system default').option('--gecko-binary, --firefox-binary <path-to-binary>', 'specify a path to the Gecko binary. This option overrides the --browser setting. Defaults to the system default').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('--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('--output-path <dir>', 'path to an existing unpacked extension directory. Defaults to dist/<browser> when available').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, options, command)=>{
-                const { browser = 'chromium', ...previewOptions } = options;
+            program.command('preview').arguments('[project-name]').usage('[path-to-remote-extension] [options]').description(commandDescriptions.preview).addHelpText('after', '\nAdditional option:\n  --no-browser    do not launch the browser\n').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(`--browser <${NO_SAFARI_BROWSER_TARGETS_HELP}>`, 'specify a browser/engine to run. Defaults to `chromium`').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('--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('--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('--output-path <dir>', 'path to an existing unpacked extension directory. Defaults to dist/<browser> when available').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, options, command)=>{
+                const { browser: cliBrowser, ...previewOptions } = options;
+                const browser = cliBrowser ?? await resolveConfigBrowser(pathOrRemoteUrl || process.cwd(), 'preview') ?? 'chromium';
                 if (previewOptions.debug || previewOptions.author || previewOptions.authorMode) {
                     process.env.EXTENSION_DEBUG = '1';
                     process.env.EXTENSION_AUTHOR_MODE = 'true';
                     if (!process.env.EXTENSION_VERBOSE) process.env.EXTENSION_VERBOSE = '1';
                 }
-                const asJson = 'json' === previewOptions.output;
+                const asJson = isJsonOutput(previewOptions);
                 if (asJson) process.env.EXTENSION_OUTPUT = 'json';
                 const emit = (frame)=>{
                     console.log(JSON.stringify(frame));
@@ -9756,7 +10262,7 @@ Cross-browser compatibility
                             profile: (0, resolve_profile.Md)(previewOptions.profile),
                             browser: vendor,
                             chromiumBinary: previewOptions.chromiumBinary,
-                            geckoBinary: previewOptions.geckoBinary,
+                            geckoBinary: cliGeckoBinary(previewOptions),
                             startingUrl: previewOptions.startingUrl,
                             port: previewOptions.port,
                             noBrowser: await resolveNoBrowser(pathOrRemoteUrl || process.cwd(), 'preview'),
@@ -9882,7 +10388,7 @@ Cross-browser compatibility
         }
         function registerPublishCommand(program) {
             program.command('publish').arguments('[project-path]').usage('[project-path] [options]').description(commandDescriptions.publish).option('--token <token>', 'platform access token (or EXTENSION_DEV_TOKEN, or the stored login)').option('--api <url>', 'platform base URL (or EXTENSION_DEV_API_URL)').option('--ttl <hours>', 'share-link lifetime in hours (1–168, default 24)').option('--build-sha <sha>', 'pin the share URL to a specific build').option('--project <slug>', 'name the project this publish is for, when it is not the directory you are in').option('--output <pretty|json>', 'output format (default pretty)').action(async (projectPathArg, opts)=>{
-                const asJson = 'json' === opts.output;
+                const asJson = isJsonOutput(opts);
                 const failWith = async (status, error, prose, hint)=>{
                     if (asJson) console.log(JSON.stringify(messaging.Pr.fail('publish', status, error, hint ? {
                         hint
@@ -9968,8 +10474,9 @@ Cross-browser compatibility
             return Number.isFinite(parsed) && parsed >= 0 ? Math.floor(parsed) : 8080;
         }
         function registerStartCommand(program) {
-            program.command('start').arguments('[project-path|remote-url]').usage('[project-path|remote-url] [options]').description(commandDescriptions.start).addHelpText('after', '\nAdditional options:\n  --no-browser    do not launch the browser (build still runs)\n  --wait          wait for ready contract and exit; pair with --output json for machine output\n').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(`--browser <${NO_SAFARI_BROWSER_TARGETS_HELP}>`, 'specify a browser/engine to run. Defaults to `chromium`').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('--chromium-binary <path-to-binary>', 'specify a path to the Chromium binary. This option overrides the --browser setting. Defaults to the system default').option('--gecko-binary, --firefox-binary <path-to-binary>', 'specify a path to the Gecko binary. This option overrides the --browser setting. Defaults to the system default').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()).action(async (pathOrRemoteUrl, options, command)=>{
-                const { browser = 'chromium', ...startOptions } = options;
+            program.command('start').arguments('[project-path|remote-url]').usage('[project-path|remote-url] [options]').description(commandDescriptions.start).addHelpText('after', '\nAdditional options:\n  --no-browser    do not launch the browser (build still runs)\n  --wait          wait for ready contract and exit; pair with --output json for machine output\n').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(`--browser <${NO_SAFARI_BROWSER_TARGETS_HELP}>`, 'specify a browser/engine to run. Defaults to `chromium`').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('--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('--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()).action(async (pathOrRemoteUrl, options, command)=>{
+                const { browser: cliBrowser, ...startOptions } = options;
+                const browser = cliBrowser ?? await resolveConfigBrowser(pathOrRemoteUrl || process.cwd(), 'start') ?? 'chromium';
                 if (startOptions.debug || startOptions.author || startOptions.authorMode) {
                     process.env.EXTENSION_DEBUG = '1';
                     process.env.EXTENSION_AUTHOR_MODE = 'true';
@@ -10069,7 +10576,7 @@ Cross-browser compatibility
                         profile: (0, resolve_profile.Md)(startOptions.profile),
                         browser: vendor,
                         chromiumBinary: startOptions.chromiumBinary,
-                        geckoBinary: startOptions.geckoBinary,
+                        geckoBinary: cliGeckoBinary(startOptions),
                         startingUrl: startOptions.startingUrl,
                         port: startOptions.port,
                         host: startOptions.host,
@@ -10090,7 +10597,7 @@ Cross-browser compatibility
         function registerTelemetryCommand(program) {
             program.command('telemetry').argument('[action]', 'enable | disable | status (default: status)').description(commandDescriptions.telemetry).option('--output <pretty|json>', 'result format. Use json for a schema-1 envelope on stdout').action(async (action, opts = {})=>{
                 const normalized = String(action || 'status').trim().toLowerCase();
-                const asJson = 'json' === opts.output;
+                const asJson = isJsonOutput(opts);
                 const emit = (frame)=>{
                     console.log(JSON.stringify(frame));
                 };
@@ -10165,12 +10672,6 @@ Cross-browser compatibility
             return resolveExtensionDevelopVersion(__dirname, index_cliPackageJson.version);
         }
         process.env.EXTENSION_DEVELOP_VERSION = developVersion();
-        function scanArgvValue(argv, flag) {
-            const equalArg = argv.find((arg)=>arg.startsWith(`${flag}=`));
-            if (equalArg) return equalArg.slice(flag.length + 1);
-            const flagIndex = argv.indexOf(flag);
-            if (flagIndex >= 0) return argv[flagIndex + 1] || '';
-        }
         function resolveAIHelpFormatFromArgv(argv) {
             const direct = scanArgvValue(argv, '--output');
             if (void 0 !== direct) return direct;
@@ -10181,29 +10682,21 @@ Cross-browser compatibility
             }
             return 'pretty';
         }
-        function resolveCommandFromArgv(argv) {
-            for(let i = 2; i < argv.length; i += 1){
-                const arg = argv[i];
-                if (!arg.startsWith('-')) return arg;
-            }
+        let valuedLongFlags = new Set();
+        function index_resolveCommandFromArgv(argv) {
+            return resolveCommandFromArgv(argv, valuedLongFlags);
         }
         function failBeforeParse(argv, humanMessage, code, plainMessage, flag) {
             console.error(humanMessage);
-            if (wantsJsonOutput(argv)) writeStdoutFrame(earlyExitEnvelope(resolveCommandFromArgv(argv) || 'extension', code, plainMessage, {
+            if (wantsJsonOutput(argv)) writeStdoutFrame(earlyExitEnvelope(index_resolveCommandFromArgv(argv) || 'extension', code, plainMessage, {
                 flag
             }));
             process.exit(1);
         }
         function applyOutputAliasArgvShim(argv) {
-            const index = argv.findIndex((arg)=>'--format' === arg || arg.startsWith('--format='));
-            if (index < 0) return argv;
             if (argv.includes('--ai-help')) return argv;
-            const next = [
-                ...argv
-            ];
-            if (next[index].startsWith('--format=')) next[index] = `--output=${next[index].slice(9)}`;
-            else next[index] = '--output';
-            warnDeprecatedOutputAlias('--format');
+            const { argv: next, rewritten } = rewriteOutputAliasArgv(argv, valuedLongFlags);
+            if (rewritten) warnDeprecatedOutputAlias('--format');
             return next;
         }
         function applyNoBrowserArgvShim(argv) {
@@ -10212,7 +10705,7 @@ Cross-browser compatibility
             let nextArgv = argv;
             const hasNoReload = nextArgv.includes('--no-reload');
             if (hasNoReload) {
-                const command = resolveCommandFromArgv(nextArgv);
+                const command = index_resolveCommandFromArgv(nextArgv);
                 if ('dev' !== command) {
                     const message = `--no-reload is only supported on \`extension dev\` (got: ${command || 'no command'}).`;
                     failBeforeParse(nextArgv, message, messaging.Lp.E_FLAG_NOT_SUPPORTED_HERE, message, '--no-reload');
@@ -10222,7 +10715,7 @@ Cross-browser compatibility
             }
             const hasNoBrowser = nextArgv.includes('--no-browser');
             if (!hasNoBrowser) return nextArgv;
-            const command = resolveCommandFromArgv(nextArgv);
+            const command = index_resolveCommandFromArgv(nextArgv);
             const supportsNoBrowser = 'dev' === command || 'start' === command || 'preview' === command;
             if (!supportsNoBrowser) failBeforeParse(nextArgv, noBrowserNotSupportedForCommand(command), messaging.Lp.E_FLAG_NOT_SUPPORTED_HERE, command ? `--no-browser is not supported on \`extension ${command}\`.` : '--no-browser needs a command that launches a browser.', '--no-browser');
             process.env.EXTENSION_CLI_NO_BROWSER = '1';
@@ -10249,6 +10742,7 @@ Cross-browser compatibility
         registerTelemetryCommand(extensionJs);
         registerDoctorCommand(extensionJs);
         registerCapabilitiesCommand(extensionJs);
+        valuedLongFlags = collectValuedLongFlags(extensionJs);
         function runAIHelp() {
             const format = resolveAIHelpFormatFromArgv(process.argv).trim().toLowerCase();
             if ('json' === format) {
@@ -10272,7 +10766,7 @@ Cross-browser compatibility
         else {
             const argv = applyNoBrowserArgvShim(applyOutputAliasArgvShim(process.argv));
             const asJson = wantsJsonOutput(argv);
-            const commandName = resolveCommandFromArgv(argv) || 'extension';
+            const commandName = index_resolveCommandFromArgv(argv) || 'extension';
             (async ()=>{
                 try {
                     await extensionJs.parseAsync(argv);