extension 4.0.15 → 4.0.16

package/dist/cli.cjs

@@ -85,6 +85,14 @@ var __webpack_modules__ = {
             if (fromBrowserSpecificSettings) return fromBrowserSpecificSettings;
             return toNormalizedId(manifest?.applications?.gecko?.id);
         }
+        function expectedChromiumExtensionId(outPath) {
+            try {
+                const manifest = JSON.parse(node_fs__rspack_import_1.readFileSync(node_path__rspack_import_2.join(outPath, 'manifest.json'), 'utf-8'));
+                const fromKey = deriveChromiumExtensionIdFromManifest(manifest);
+                if (fromKey) return fromKey;
+            } catch  {}
+            return deriveChromiumExtensionIdFromPath(outPath);
+        }
         function resolveExtensionId(args) {
             const fromInfo = toNormalizedId(args.info?.extensionId);
             if (fromInfo) return fromInfo;
@@ -210,7 +218,8 @@ var __webpack_modules__ = {
         }
         __webpack_require__.d(__webpack_exports__, {
             MK: ()=>printProdBannerOnce,
-            ai: ()=>printDevBannerOnce
+            ai: ()=>printDevBannerOnce,
+            vy: ()=>expectedChromiumExtensionId
         });
     },
     "./browsers/browsers-lib/browser-family.ts" (__unused_rspack_module, __webpack_exports__, __webpack_require__) {
@@ -476,6 +485,12 @@ var __webpack_modules__ = {
         function chromiumManifestLoadBlockers(extensionPath, blockers) {
             return `${getLoggingPrefix('warn')} ${pintor__rspack_import_8_default().brightYellow('This manifest declares shapes Chrome refuses, the whole extension will not load.')}\n${pintor__rspack_import_8_default().gray('PATH')} ${pintor__rspack_import_8_default().underline(extensionPath)}\n` + blockers.map((blocker)=>`${pintor__rspack_import_8_default().gray('REASON')} ${pintor__rspack_import_8_default().red(blocker)}\n`).join('') + "Chrome rejects the extension at load, so no service worker or content script ever runs. Fix these in the source manifest.";
         }
+        function chromiumExtensionLoadRefused(extensionPath, reason) {
+            return `${getLoggingPrefix('error')} ${pintor__rspack_import_8_default().red('The browser refused to load this extension, so it is NOT running.')}\n${pintor__rspack_import_8_default().gray('PATH')} ${pintor__rspack_import_8_default().underline(extensionPath)}\n` + (reason ? `${pintor__rspack_import_8_default().gray('REASON')} ${pintor__rspack_import_8_default().red(reason)}\n` : '') + "No service worker, content script, or page from this extension will run, and no Extension ID was assigned. Fix the reason above and save. If the browser does not pick it up, restart the dev session.";
+        }
+        function geckoAddonLoadRefused(addonPath, reason) {
+            return `${getLoggingPrefix('error')} ${pintor__rspack_import_8_default().red('The browser refused to load this add-on, so it is NOT running.')}\n${pintor__rspack_import_8_default().gray('PATH')} ${pintor__rspack_import_8_default().underline(addonPath)}\n` + (reason ? `${pintor__rspack_import_8_default().gray('REASON')} ${pintor__rspack_import_8_default().red(reason)}\n` : '') + "No background script, content script, or page from this add-on will run, and no Extension ID was assigned. Fix the reason above and save. If the browser does not pick it up, restart the dev session.";
+        }
         function devChannelSnapshotInUse(binaryPath) {
             return `${getLoggingPrefix('warn')} ${pintor__rspack_import_8_default().brightYellow('Running a Chromium tip-of-tree snapshot (dev channel, not a stable release).')}\n${pintor__rspack_import_8_default().gray('PATH')} ${pintor__rspack_import_8_default().underline(binaryPath)}\nBehavior may differ from stable Chrome. Install a stable browser or remove the snapshot to stop using it.`;
         }
@@ -835,6 +850,7 @@ var __webpack_modules__ = {
             Cs: ()=>safariToolchainMissing,
             Dh: ()=>invalidGeckoBinaryPath,
             E8: ()=>chromiumDryRunFlags,
+            EE: ()=>geckoAddonLoadRefused,
             EI: ()=>firefoxRdpClientConnected,
             F1: ()=>cdpClientBrowserConnectionEstablished,
             F4: ()=>enhancedProcessManagementUncaughtException,
@@ -852,6 +868,7 @@ var __webpack_modules__ = {
             L: ()=>chromiumManifestLoadBlockers,
             LD: ()=>firefoxDryRunBinary,
             M3: ()=>cdpClientConnected,
+            M6: ()=>chromiumExtensionLoadRefused,
             MG: ()=>prettyPuppeteerInstallGuidance,
             MQ: ()=>firefoxFailedToStart,
             MS: ()=>errorConnectingToBrowser,
@@ -1224,6 +1241,21 @@ var __webpack_modules__ = {
                 node_fs__rspack_import_0.writeFileSync(readyPath, JSON.stringify(ready, null, 2));
             } catch  {}
         }
+        function stampReadyExtensionLoadRefused(extensionOutputPath, reason) {
+            try {
+                if (!extensionOutputPath) return;
+                const readyPath = readyPathFor(extensionOutputPath);
+                if (!node_fs__rspack_import_0.existsSync(readyPath)) return;
+                const ready = JSON.parse(node_fs__rspack_import_0.readFileSync(readyPath, 'utf-8'));
+                ready.status = 'error';
+                ready.code = 'extension_load_refused';
+                const browserLabel = String(ready.browser || 'the browser');
+                ready.message = `${browserLabel.charAt(0).toUpperCase() + browserLabel.slice(1)} refused to load the extension at ${extensionOutputPath}${reason ? `: ${reason}` : ''}`;
+                ready.extensionLoadRefusedAt = new Date().toISOString();
+                if (reason) ready.extensionLoadRefusedReason = reason;
+                node_fs__rspack_import_0.writeFileSync(readyPath, JSON.stringify(ready, null, 2));
+            } catch  {}
+        }
         function stampReadyBrowserExited(extensionOutputPath, code) {
             try {
                 if (!extensionOutputPath) return;
@@ -1241,8 +1273,9 @@ var __webpack_modules__ = {
             } catch  {}
         }
         __webpack_require__.d(__webpack_exports__, {
-            W: ()=>stampReadyBrowserExited,
-            _: ()=>stampReadyRdpPort
+            Wi: ()=>stampReadyBrowserExited,
+            __: ()=>stampReadyRdpPort,
+            sf: ()=>stampReadyExtensionLoadRefused
         });
     },
     "./browsers/browsers-lib/resolve-profile.ts" (__unused_rspack_module, __webpack_exports__, __webpack_require__) {
@@ -1448,6 +1481,9 @@ var __webpack_modules__ = {
         function parseEnvBrowserFlags(raw) {
             return String(raw || '').split(/\s+/).map((flag)=>flag.trim()).filter(Boolean);
         }
+        function isHeadlessGuardRequested(env = process.env) {
+            return /^(1|true)$/i.test(String(env.EXTENSION_HEADLESS || '').trim());
+        }
         function mergeChromiumFeatureSwitches(flags) {
             const merged = [];
             const featureValues = {
@@ -1608,6 +1644,7 @@ var __webpack_modules__ = {
             Py: ()=>mergeChromiumFeatureSwitches,
             RE: ()=>markManagedEphemeralProfile,
             W0: ()=>parseEnvBrowserFlags,
+            ZO: ()=>isHeadlessGuardRequested,
             aY: ()=>findAvailablePortNear,
             jl: ()=>deriveDebugPortWithInstance,
             ov: ()=>filterBrowserFlags,
@@ -1688,6 +1725,20 @@ var __webpack_modules__ = {
             let cdpController;
             if (enableCdp) cdpController = ctx.getController?.();
             return {
+                getExtensionLoadRefusal () {
+                    return launcher.getExtensionLoadRefusal();
+                },
+                async retryExtensionLoad () {
+                    if (!cdpController?.verifyGuestLoaded) return {
+                        status: 'unknown'
+                    };
+                    const outcome = await cdpController.verifyGuestLoaded();
+                    if ('loaded' === outcome.status) {
+                        launcher.clearExtensionLoadRefusal();
+                        await launcher.printBannerOnRecovery();
+                    }
+                    return outcome;
+                },
                 async enableUnifiedLogging (logOpts) {
                     if (cdpController?.enableUnifiedLogging) await cdpController.enableUnifiedLogging({
                         level: logOpts.level,
@@ -1719,7 +1770,8 @@ var __webpack_modules__ = {
                 logTimestamps: opts.logTimestamps,
                 logColor: opts.logColor,
                 logUrl: opts.logUrl,
-                logTab: opts.logTab
+                logTab: opts.logTab,
+                logSink: opts.logSink
             };
             const pluginOptions = {
                 extension: opts.extensionsToLoad,
@@ -1747,6 +1799,15 @@ var __webpack_modules__ = {
             await launcher.runOnce(compilationLike, launchRequest);
             const rdpController = ctx.getController?.();
             return {
+                getExtensionLoadRefusal () {
+                    return firefoxOpts.extensionLoadRefused || null;
+                },
+                async retryExtensionLoad () {
+                    if (!firefoxOpts.retryAddonInstall) return {
+                        status: 'unknown'
+                    };
+                    return await firefoxOpts.retryAddonInstall();
+                },
                 async enableUnifiedLogging (logOpts) {
                     if (!rdpController?.enableUnifiedLogging) return;
                     await rdpController.enableUnifiedLogging({
@@ -2093,6 +2154,7 @@ var __webpack_modules__ = {
         var output_binaries_resolver = __webpack_require__("./browsers/browsers-lib/output-binaries-resolver.ts");
         var process_teardown = __webpack_require__("./browsers/browsers-lib/process-teardown.ts");
         var ready_message = __webpack_require__("./browsers/browsers-lib/ready-message.ts");
+        var ready_stamp = __webpack_require__("./browsers/browsers-lib/ready-stamp.ts");
         var runtime_options = __webpack_require__("./browsers/browsers-lib/runtime-options.ts");
         var shared_utils = __webpack_require__("./browsers/browsers-lib/shared-utils.ts");
         var discovery = __webpack_require__("./browsers/run-chromium/cdp/discovery.ts");
@@ -2325,6 +2387,7 @@ var __webpack_modules__ = {
                 ...configOptions.browserFlags || [],
                 ...(0, shared_utils.W0)(process.env.EXTENSION_BROWSER_FLAGS)
             ];
+            if ((0, shared_utils.ZO)() && !baseFlags.some((flag)=>flag.startsWith('--headless'))) baseFlags.push('--headless=new');
             return (0, shared_utils.Py)(baseFlags);
         }
         function logChromiumDryRun(browserBinaryLocation, chromiumConfig) {
@@ -2505,7 +2568,6 @@ var __webpack_modules__ = {
                 throw error;
             }
         }
-        var ready_stamp = __webpack_require__("./browsers/browsers-lib/ready-stamp.ts");
         function _define_property(obj, key, value) {
             if (key in obj) Object.defineProperty(obj, key, {
                 value: value,
@@ -2536,6 +2598,15 @@ var __webpack_modules__ = {
             });
         }
         class ChromiumLaunchPlugin {
+            getExtensionLoadRefusal() {
+                return this.extensionLoadRefused || null;
+            }
+            clearExtensionLoadRefusal() {
+                this.extensionLoadRefused = void 0;
+            }
+            async printBannerOnRecovery() {
+                await this.bannerOnRecovery?.();
+            }
             async runOnce(compilation, opts) {
                 if (!this.logger) this.logger = {
                     info: (...a)=>console.log(...a),
@@ -2560,7 +2631,7 @@ var __webpack_modules__ = {
                         if (this.didLaunch) return;
                         await this.launchChromium(stats.compilation);
                         this.didLaunch = true;
-                        if (!this.didReportReady) console.log((0, ready_message.G)(stats.compilation.options.mode, this.options.browser));
+                        if (!this.didReportReady && !this.extensionLoadRefused) console.log((0, ready_message.G)(stats.compilation.options.mode, this.options.browser));
                     } catch (error) {
                         try {
                             this.logger.error(messages._D(this.options.browser, error));
@@ -2927,10 +2998,13 @@ var __webpack_modules__ = {
                     }
                     if (!portReady && 'true' === process.env.EXTENSION_AUTHOR_MODE) this.logger.warn?.(`[browser] Debug port ${selectedPort} not bound after spawn. CDP may fail`);
                 }
-                if ('development' === compilation.options.mode && !this.didReportReady) {
+                const reportReady = ()=>{
+                    if ('development' !== compilation.options.mode) return;
+                    if (this.didReportReady || this.extensionLoadRefused) return;
                     console.log((0, ready_message.G)(compilation.options.mode, this.options.browser));
                     this.didReportReady = true;
-                }
+                };
+                if (!enableCdp) reportReady();
                 try {
                     const mode = compilation?.options?.mode || 'development';
                     try {
@@ -2962,12 +3036,18 @@ var __webpack_modules__ = {
                             mod.setupCdpAfterLaunch(compilation, cdpConfig, chromiumConfig, pipeStreams),
                             new Promise((_, reject)=>setTimeout(()=>reject(new Error(`CDP setup did not complete within ${CDP_SETUP_TIMEOUT_MS / 1000}s. Chrome likely rejected the extension at launch, open chrome://extensions in the dev browser window for the exact error. Common causes: MV3 content_security_policy with 'unsafe-inline', manifest keys Chrome does not support, or manifest references to files missing from the output. Reload/HMR cannot attach until this is fixed.`)), CDP_SETUP_TIMEOUT_MS).unref?.())
                         ]);
+                        if (cdpConfig.extensionLoadRefused) {
+                            this.extensionLoadRefused = cdpConfig.extensionLoadRefused;
+                            this.bannerOnRecovery = cdpConfig.printBannerOnRecovery;
+                        }
                         if (cdpConfig.cdpController) this.ctx.setController(cdpConfig.cdpController);
                     }
+                    reportReady();
                 } catch (error) {
                     const message = String(error && error.message);
                     const hint = /timed out|did not complete/i.test(message) ? " Chrome likely rejected the extension at launch, open chrome://extensions in the dev browser window for the exact error. Common causes: MV3 content_security_policy with 'unsafe-inline', manifest keys Chrome does not support, or manifest references to missing files. Reload/HMR cannot attach until this is fixed." : '';
                     console.error(`[browser] ${message}${hint}`);
+                    reportReady();
                 }
             }
             async launchWithDirectSpawn(binary, chromeFlags, usePipe = false) {
@@ -3018,7 +3098,7 @@ var __webpack_modules__ = {
                         if ('true' === process.env.EXTENSION_AUTHOR_MODE) this.logger.info(messages.nn(code || 0));
                         if (!(0, process_teardown.Op)(child)) {
                             this.logger.error(this.closeHandlerContext?.isDevMode ? `[browser] ${this.options.browser} exited mid-session (code ${code ?? 'unknown'}). The dev server is still running but reloads cannot be delivered, restart "extension dev" to relaunch the browser.` : `[browser] ${this.options.browser} exited (code ${code ?? 'unknown'}); the preview session is over.`);
-                            (0, ready_stamp.W)(this.closeHandlerContext?.extensionOutputPath, code);
+                            (0, ready_stamp.Wi)(this.closeHandlerContext?.extensionOutputPath, code);
                         }
                         disposeSignalHandlers?.();
                         const userDataDir = launchArgs.find((arg)=>arg.startsWith('--user-data-dir='))?.slice('--user-data-dir='.length).replace(/^"|"$/g, '');
@@ -3053,6 +3133,8 @@ var __webpack_modules__ = {
                 _define_property(this, "ctx", void 0);
                 _define_property(this, "didLaunch", void 0);
                 _define_property(this, "didReportReady", void 0);
+                _define_property(this, "extensionLoadRefused", void 0);
+                _define_property(this, "bannerOnRecovery", void 0);
                 _define_property(this, "logger", void 0);
                 _define_property(this, "closeHandlerContext", void 0);
                 this.options = options;
@@ -3243,7 +3325,7 @@ var __webpack_modules__ = {
             } : null;
         }
         function isFirefoxHeadlessRequested(env = process.env) {
-            return /^(1|true)$/i.test(String(env.MOZ_HEADLESS || '').trim());
+            return /^(1|true)$/i.test(String(env.MOZ_HEADLESS || '').trim()) || (0, shared_utils.ZO)(env);
         }
         class FirefoxBinaryDetector {
             static generateFirefoxArgs(binaryPath, profilePath, debugPort, additionalArgs = [], headless = false) {
@@ -3265,7 +3347,9 @@ var __webpack_modules__ = {
                             '-start-debugger-server',
                             String(debugPort)
                         ] : [],
-                        '--foreground',
+                        ...headless ? [] : [
+                            '--foreground'
+                        ],
                         ...additionalArgs
                     ];
                     return {
@@ -3286,7 +3370,9 @@ var __webpack_modules__ = {
                         '-start-debugger-server',
                         String(debugPort)
                     ] : [],
-                    '--foreground',
+                    ...headless ? [] : [
+                        '--foreground'
+                    ],
                     ...additionalArgs
                 ];
                 return {
@@ -3529,6 +3615,22 @@ var __webpack_modules__ = {
             if (external_node_fs_.existsSync(external_node_path_.join(distFirefox, 'manifest.json'))) return distFirefox;
             return candidate;
         }
+        function classifyAddonInstallFailure(error) {
+            if (error instanceof Error) return {
+                status: 'unknown'
+            };
+            const reply = error;
+            if (!reply || 'object' != typeof reply || !reply.error) return {
+                status: 'unknown'
+            };
+            const reason = String(reply.message || '').trim();
+            return reason ? {
+                status: 'refused',
+                reason
+            } : {
+                status: 'unknown'
+            };
+        }
         async function getAddonsActorWithRetry(client, cached, tries = 40, delayMs = 250) {
             if (cached) return cached;
             let addonsActor;
@@ -4185,6 +4287,9 @@ var __webpack_modules__ = {
         const RETRY_INTERVAL = constants.FQ;
         const RETRY_LOG_EVERY_N_ATTEMPTS = 10;
         class RemoteFirefox {
+            getAddonInstallRefusalReason() {
+                return this.addonInstallRefusalReason || null;
+            }
             selectPrimaryAddonPath(compilation, candidateAddonPaths) {
                 const normalizedOutputPath = String(compilation?.options?.output?.path || '').replace(/\\/g, '/');
                 if (normalizedOutputPath) {
@@ -4274,6 +4379,8 @@ var __webpack_modules__ = {
                         if (primaryAddonPath && String(addonPath) === String(primaryAddonPath) && maybeId) primaryUserAddonId = maybeId;
                         if (isManager) await waitForManagerWelcome(client);
                     } catch (err) {
+                        const outcome = classifyAddonInstallFailure(err);
+                        if ('refused' === outcome.status) this.addonInstallRefusalReason = outcome.reason;
                         const message = requestErrorToMessage(err);
                         throw new Error(messages.WV(this.options.browser, message));
                     }
@@ -4321,6 +4428,7 @@ var __webpack_modules__ = {
                 remote_firefox_define_property(this, "cachedAddonsActor", void 0);
                 remote_firefox_define_property(this, "lastInstalledAddonPath", void 0);
                 remote_firefox_define_property(this, "derivedExtensionId", void 0);
+                remote_firefox_define_property(this, "addonInstallRefusalReason", void 0);
                 this.options = configOptions;
             }
         }
@@ -4338,6 +4446,9 @@ var __webpack_modules__ = {
             async ensureLoaded(compilation) {
                 await this.remote.installAddons(compilation);
             }
+            getAddonInstallRefusalReason() {
+                return this.remote.getAddonInstallRefusalReason();
+            }
             async enableUnifiedLogging(opts) {
                 await this.remote.enableUnifiedLogging(opts);
             }
@@ -4370,6 +4481,7 @@ var __webpack_modules__ = {
                     return await fn();
                 } catch (error) {
                     lastError = error;
+                    if (controller.getAddonInstallRefusalReason()) break;
                     if ('true' === process.env.EXTENSION_AUTHOR_MODE) try {
                         const msg = error?.message || String(error);
                         console.warn(`[browser] Firefox RDP setup retry ${i + 1}/${attempts}: ${msg}`);
@@ -4379,10 +4491,19 @@ var __webpack_modules__ = {
                 }
                 throw lastError;
             };
-            if (plugin.rdpController) await retry(()=>plugin.rdpController.ensureLoaded?.(compilation) || Promise.resolve());
-            else {
-                await retry(()=>controller.ensureLoaded(compilation));
-                plugin.rdpController = controller;
+            const withRefusalReason = (error)=>{
+                const reason = controller.getAddonInstallRefusalReason();
+                if (reason && error && 'object' == typeof error) error.extensionLoadRefusedReason = reason;
+                return error;
+            };
+            try {
+                if (plugin.rdpController) await retry(()=>plugin.rdpController.ensureLoaded?.(compilation) || Promise.resolve());
+                else {
+                    await retry(()=>controller.ensureLoaded(compilation));
+                    plugin.rdpController = controller;
+                }
+            } catch (error) {
+                throw withRefusalReason(error);
             }
             return controller;
         }
@@ -4465,8 +4586,8 @@ var __webpack_modules__ = {
                     error: (...a)=>console.error(...a),
                     debug: (...a)=>console?.debug?.(...a)
                 };
-                if ('development' === options.mode) this.ctx.logger?.info?.((0, ready_message.G)(options.mode, this.host.browser));
                 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));
                 this.ctx.didLaunch = true;
             }
             apply(compiler) {
@@ -4486,8 +4607,8 @@ var __webpack_modules__ = {
                             return;
                         }
                         if (this.ctx.didLaunch) return void done();
-                        if ('development' === stats.compilation.options.mode) console.log((0, ready_message.G)(stats.compilation.options.mode, this.host.browser));
                         await this.launch(stats.compilation, (0, runtime_options.zU)(this.host, stats.compilation.options.mode));
+                        if ('development' === stats.compilation.options.mode && !this.host.extensionLoadRefused) console.log((0, ready_message.G)(stats.compilation.options.mode, this.host.browser));
                         this.ctx.didLaunch = true;
                     } catch (error) {
                         this.ctx.logger?.error?.(messages.MQ(error));
@@ -4648,10 +4769,24 @@ var __webpack_modules__ = {
                         (0, shared_utils.sW)(profilePath);
                     });
                     this.wireChildLifecycle();
-                    const ctrl = await setupRdpAfterLaunch(this.host, compilation, debugPort);
+                    let ctrl;
+                    try {
+                        ctrl = await setupRdpAfterLaunch(this.host, compilation, debugPort);
+                    } catch (error) {
+                        const reason = error?.extensionLoadRefusedReason;
+                        if (!reason) {
+                            (0, ready_stamp.__)(this.extensionOutputPath, debugPort);
+                            throw error;
+                        }
+                        this.reportAddonLoadRefused(reason);
+                        this.host.retryAddonInstall = ()=>this.retryAddonInstall(compilation, debugPort);
+                        (0, ready_stamp.__)(this.extensionOutputPath, debugPort);
+                        this.scheduleWatchTimeout();
+                        return;
+                    }
                     this.host.rdpController = ctrl;
                     this.ctx.setController(ctrl);
-                    (0, ready_stamp._)(this.extensionOutputPath, debugPort);
+                    (0, ready_stamp.__)(this.extensionOutputPath, debugPort);
                     this.scheduleWatchTimeout();
                     try {
                         if ('true' === process.env.EXTENSION_AUTHOR_MODE) {
@@ -4672,12 +4807,14 @@ var __webpack_modules__ = {
                         ...'win32' === process.platform ? [
                             '-wait-for-browser'
                         ] : [],
-                        '--foreground',
+                        ...isFirefoxHeadlessRequested() ? [] : [
+                            '--foreground'
+                        ],
                         ...firefoxArgs
                     ];
                     this.child = await this.spawnFirefoxChild(binaryPath, args, wslFallbackBinary);
                     this.wireChildLifecycle();
-                    if (debugPort > 0) (0, ready_stamp._)(this.extensionOutputPath, debugPort);
+                    if (debugPort > 0) (0, ready_stamp.__)(this.extensionOutputPath, debugPort);
                     this.scheduleWatchTimeout();
                 }
             }
@@ -4730,7 +4867,7 @@ var __webpack_modules__ = {
                     if ('true' === process.env.EXTENSION_AUTHOR_MODE) this.ctx.logger?.info?.(messages.Th(this.host.browser));
                     if (!(0, process_teardown.Op)(child)) {
                         this.ctx.logger?.error?.(`[browser] ${this.host.browser} exited (code ${code ?? 'unknown'}) without being asked to. The add-on may have been rejected or the browser crashed; the session cannot be driven.`);
-                        (0, ready_stamp.W)(this.extensionOutputPath, code);
+                        (0, ready_stamp.Wi)(this.extensionOutputPath, code);
                     }
                     this.cleanupInstance().catch((err)=>{
                         if ('true' === process.env.EXTENSION_AUTHOR_MODE) this.ctx.logger?.error?.(`[browser] Cleanup error on child close: ${err?.message || err}`);
@@ -4740,6 +4877,36 @@ var __webpack_modules__ = {
                 this.pipeChildOutput(child);
                 disposeProcessHandlers = setupFirefoxProcessHandlers(this.host.browser, ()=>this.child, ()=>this.cleanupInstance());
             }
+            async retryAddonInstall(compilation, debugPort) {
+                try {
+                    const ctrl = await setupRdpAfterLaunch(this.host, compilation, debugPort);
+                    this.host.rdpController = ctrl;
+                    this.ctx.setController(ctrl);
+                    this.host.extensionLoadRefused = void 0;
+                    return {
+                        status: 'loaded'
+                    };
+                } catch (error) {
+                    const reason = error?.extensionLoadRefusedReason;
+                    return reason ? {
+                        status: 'refused',
+                        reason
+                    } : {
+                        status: 'unknown'
+                    };
+                }
+            }
+            reportAddonLoadRefused(reason) {
+                const refusedPath = this.extensionOutputPath || '';
+                console.error(messages.EE(refusedPath, reason));
+                this.host.logSink?.({
+                    level: 'error',
+                    text: `extension_load_refused: ${refusedPath}${reason ? ` - ${reason}` : ''}`,
+                    source: 'browser'
+                });
+                (0, ready_stamp.sf)(this.extensionOutputPath, reason);
+                this.host.extensionLoadRefused = reason;
+            }
             async cleanupInstance() {
                 (0, process_teardown.Df)(this.child, this.host.browser);
             }

package/dist/extension/browsers/browsers-lib/banner.d.ts

@@ -10,6 +10,7 @@ type HostPort = {
     host?: string;
     port?: number | string;
 };
+export declare function expectedChromiumExtensionId(outPath: string): string;
 export declare function printDevBannerOnce(opts: {
     browser: BrowserType;
     outPath: string;

package/dist/extension/browsers/browsers-lib/messages.d.ts

@@ -20,6 +20,8 @@ export declare function mv3BackgroundScriptsNotSupportedByChromium(extensionPath
 export declare function unsupportedManifestVersionOnChromium(extensionPath: string, declared: unknown): string;
 export declare function chromiumInvalidMatchPatterns(extensionPath: string, patterns: string[]): string;
 export declare function chromiumManifestLoadBlockers(extensionPath: string, blockers: string[]): string;
+export declare function chromiumExtensionLoadRefused(extensionPath: string, reason: string): string;
+export declare function geckoAddonLoadRefused(addonPath: string, reason: string): string;
 export declare function devChannelSnapshotInUse(binaryPath: string): string;
 export declare function browserLaunchError(browser: Browser, error: unknown): string;
 export declare function enhancedProcessManagementCleanup(browser: Browser): string;

package/dist/extension/browsers/browsers-lib/ready-stamp.d.ts

@@ -1,2 +1,3 @@
 export declare function stampReadyRdpPort(extensionOutputPath: string | undefined, rdpPort: number): void;
+export declare function stampReadyExtensionLoadRefused(extensionOutputPath: string | undefined, reason: string): void;
 export declare function stampReadyBrowserExited(extensionOutputPath: string | undefined, code: number | null): void;

package/dist/extension/browsers/browsers-lib/shared-utils.d.ts

@@ -15,6 +15,7 @@ export declare function chooseChromiumBinaryPreferringStable(opts: {
     preferManagedSnapshot?: boolean;
 }): ChromiumBinaryChoice;
 export declare function parseEnvBrowserFlags(raw: string | undefined | null): string[];
+export declare function isHeadlessGuardRequested(env?: NodeJS.ProcessEnv): boolean;
 export declare function mergeChromiumFeatureSwitches(flags: string[]): string[];
 export declare function findAvailablePortNear(startPort: number, maxAttempts?: number, host?: string): Promise<number>;
 export declare function prepareChromiumProfileForLaunch(profilePath: string): {

package/dist/extension/browsers/browsers-types.d.ts

@@ -185,6 +185,11 @@ export interface BrowserLogSinkEvent {
 }
 /** Host-provided sink for {@link BrowserLogSinkEvent}s. Must never throw. */
 export type BrowserLogSink = (event: BrowserLogSinkEvent) => void;
+export interface ExtensionLoadRetryResult {
+    status: 'loaded' | 'refused' | 'unknown';
+    reason?: string;
+    extensionId?: string;
+}
 export interface Controller {
     enableUnifiedLogging: (opts: {
         level?: string;
@@ -199,4 +204,5 @@ export interface Controller {
         method?: string;
         params?: unknown;
     }) => void) => void;
+    verifyGuestLoaded?: () => Promise<ExtensionLoadRetryResult>;
 }

package/dist/extension/browsers/index.d.ts

@@ -1,4 +1,4 @@
-import type { BrowserLogSink, BrowserType } from './browsers-types';
+import type { BrowserLogSink, BrowserType, ExtensionLoadRetryResult } from './browsers-types';
 export type { BrowserType, CompilationLike, Controller } from './browsers-types';
 /**
  * Options for launching a browser with an extension loaded.
@@ -49,6 +49,7 @@ export interface BrowserLaunchOptions {
  * (`setupFirefoxProcessHandlers` / Chromium equivalents). The controller is
  * deliberately not responsible for teardown, so there is no `close()`.
  */
+export type { ExtensionLoadRetryResult };
 export interface BrowserController {
     enableUnifiedLogging(opts: {
         level?: string;
@@ -59,6 +60,10 @@ export interface BrowserController {
         urlFilter?: string;
         tabFilter?: number | string;
     }): Promise<void>;
+    /** The browser's refusal reason for this session, or null when it loaded. */
+    getExtensionLoadRefusal?(): string | null;
+    /** Re-offer the current dist. Only ever called while the session is refused. */
+    retryExtensionLoad?(): Promise<ExtensionLoadRetryResult>;
 }
 /**
  * Launch a browser with the given extension(s) loaded.

package/dist/extension/browsers/run-chromium/cdp/cdp-extension-controller/ensure.d.ts

@@ -1,5 +1,16 @@
 import type { CDPClient } from '../cdp-client';
 export declare function uninstallStaleUnpackedLoads(cdp: CDPClient, profilePath: string | undefined, outPath: string): Promise<string[]>;
+export declare function declaresBackgroundContext(outPath: string): boolean;
+export type LoadUnpackedOutcome = {
+    status: 'loaded';
+    extensionId: string;
+} | {
+    status: 'refused';
+    reason: string;
+} | {
+    status: 'unknown';
+};
+export declare function loadUnpacked(cdp: CDPClient, outPath: string): Promise<LoadUnpackedOutcome>;
 export declare function loadUnpackedIfNeeded(cdp: CDPClient, outPath: string): Promise<string | null>;
 export declare function readManifestInfo(outPath: string): {
     name?: string;

package/dist/extension/browsers/run-chromium/cdp/cdp-extension-controller/index.d.ts

@@ -1,6 +1,7 @@
 import type { Readable, Writable } from 'node:stream';
 import type { BrowserLogSink } from '../../../browsers-types';
 import type { CdpProtocolMessage } from '../../chromium-types';
+import { type LoadUnpackedOutcome } from './ensure';
 interface ExtensionInfoResult {
     extensionId: string;
     name?: string;
@@ -16,6 +17,7 @@ export declare class CDPExtensionController {
     private readonly logSink?;
     private cdp;
     private extensionId;
+    private loadRefusalReason;
     constructor(args: {
         outPath: string;
         browser: 'chrome' | 'edge' | 'chromium-based';
@@ -28,6 +30,9 @@ export declare class CDPExtensionController {
     });
     connect(): Promise<void>;
     openTab(url: string): Promise<void>;
+    verifyGuestLoaded(): Promise<LoadUnpackedOutcome>;
+    getLoadRefusalReason(): string | null;
+    private waitForExtensionTarget;
     ensureLoaded(): Promise<ExtensionInfoResult>;
     private deriveExtensionIdFromTargets;
     private classifyOwnership;

package/dist/extension/browsers/run-chromium/chromium-launch/index.d.ts

@@ -1,7 +1,7 @@
+import { stampReadyBrowserExited } from '../../browsers-lib/ready-stamp';
 import type { CompilationLike } from '../../browsers-types';
 import type { ChromiumContext } from '../chromium-context';
 import type { ChromiumLaunchOptions } from '../chromium-types';
-import { stampReadyBrowserExited } from '../../browsers-lib/ready-stamp';
 export { stampReadyBrowserExited };
 /**
  * ChromiumLaunchPlugin
@@ -17,6 +17,11 @@ export declare class ChromiumLaunchPlugin {
     private readonly ctx;
     private didLaunch;
     private didReportReady;
+    private extensionLoadRefused;
+    getExtensionLoadRefusal(): string | null;
+    clearExtensionLoadRefusal(): void;
+    printBannerOnRecovery(): Promise<void>;
+    private bannerOnRecovery;
     private logger;
     private closeHandlerContext;
     constructor(options: ChromiumLaunchOptions, ctx: ChromiumContext);

package/dist/extension/browsers/run-chromium/chromium-types.d.ts

@@ -41,6 +41,8 @@ export interface ChromiumPluginRuntime extends ChromiumLaunchOptions {
     bannerPrintedOnce?: boolean;
     cdpController?: Controller;
     browserVersionLine?: string;
+    extensionLoadRefused?: string;
+    printBannerOnRecovery?: () => Promise<void>;
 }
 export interface ChromiumLogger {
     level?: LogLevel | 'off' | string;

package/dist/extension/browsers/run-firefox/firefox-launch/index.d.ts

@@ -26,6 +26,8 @@ export declare class FirefoxLaunchPlugin {
     private spawnFirefoxChild;
     private pipeChildOutput;
     private wireChildLifecycle;
+    private retryAddonInstall;
+    private reportAddonLoadRefused;
     private cleanupInstance;
     private scheduleWatchTimeout;
     private printInstallHint;

package/dist/extension/browsers/run-firefox/firefox-types.d.ts

@@ -1,4 +1,4 @@
-import type { PluginInterface } from '../browsers-types';
+import type { BrowserLogSink, ExtensionLoadRetryResult, PluginInterface } from '../browsers-types';
 import type { FirefoxRDPController } from './rdp/rdp-extension-controller';
 export type FirefoxPluginLike = Pick<PluginInterface, 'extension' | 'browserFlags' | 'profile' | 'persistProfile' | 'keepProfileChanges' | 'copyFromProfile' | 'preferences' | 'startingUrl' | 'geckoBinary' | 'instanceId' | 'port' | 'logLevel' | 'logContexts' | 'logFormat' | 'logTimestamps' | 'logColor' | 'logUrl' | 'logTab' | 'dryRun'> & {
     browser: PluginInterface['browser'];
@@ -6,4 +6,7 @@ export type FirefoxPluginLike = Pick<PluginInterface, 'extension' | 'browserFlag
 export interface FirefoxPluginRuntime extends FirefoxPluginLike {
     rdpController?: FirefoxRDPController;
     browserVersionLine?: string;
+    logSink?: BrowserLogSink;
+    extensionLoadRefused?: string;
+    retryAddonInstall?: () => Promise<ExtensionLoadRetryResult>;
 }