extension 3.8.11 → 3.8.13

package/README.md

@@ -137,45 +137,6 @@ npx extension@latest dev --chromium-binary "/Applications/Google Chrome.app/Cont
 npx extension@latest dev --gecko-binary "/Applications/Firefox.app/Contents/MacOS/firefox"
 ```
 
-### Managed browser binaries
-
-Use Extension.js commands to install/remove managed browser binaries:
-
-```bash
-# Install into Extension.js managed cache
-npx extension@latest install --browser=chromium
-npx extension@latest install --browser=firefox
-
-# Show managed cache root
-npx extension@latest install --where
-
-# Show managed path for a specific browser
-npx extension@latest install --where --browser=firefox
-
-# Remove one browser binary
-npx extension@latest uninstall chromium
-
-# Remove all managed browser binaries
-npx extension@latest uninstall --all
-
-# Show managed cache root
-npx extension@latest uninstall --where
-
-# Show managed path(s) for target browser(s)
-npx extension@latest uninstall --where --browser=chromium
-```
-
-`uninstall` only removes binaries from the Extension.js managed cache root (or `EXT_BROWSERS_CACHE_DIR` when set). It does not remove browser installations that were installed elsewhere (for example, system browsers or custom paths outside the managed cache).
-
-`edge` note for Linux: Playwright channel installs may require a privileged interactive session (`sudo` prompt). If channel install cannot proceed but a system Edge binary is already present, Extension.js will use that existing binary. Otherwise, install Edge system-wide first and then run Extension.js with `--browser=edge` (or use `chromium`).
-
-Default managed cache locations are stable and human-readable:
-- macOS: `~/Library/Caches/extension.js/browsers`
-- Linux: `~/.cache/extension.js/browsers` (or `$XDG_CACHE_HOME/extension.js/browsers`)
-- Windows: `%LOCALAPPDATA%\\extension.js\\browsers`
-
-If you want a custom path, set `EXT_BROWSERS_CACHE_DIR` to a clean location (for example, `EXT_BROWSERS_CACHE_DIR=/tmp/extension.js/browsers-dev`).
-
 ## Sponsors
 
 <div align="center">

package/dist/cli.cjs

@@ -160,6 +160,7 @@ Source Inspection (dev command)
   - When provided without a URL, falls back to ${messages_arg('--starting-url')} or ${messages_arg('https://example.com')}
   - For ${code('extension dev')}, watch mode is enabled by default when ${code('--source')} is present
 - ${messages_arg('Note:')} ${code('extension preview')} and ${code('extension start')} do not run source inspection in run-only preview mode.
+- ${messages_arg('Automation sync:')} when using ${code('extension dev --no-browser')} or ${code('extension start --no-browser')}, run ${code('extension <dev|start> --wait --browser=<browser>')} in a second process to gate on ${code('ready.json')} (add ${code('--wait-format=json')} for machine-readable output).
 - ${code('--watch-source')} ${messages_arg('[boolean]')}       Re-print HTML on rebuilds or file changes
 - ${code('--source-format')} ${messages_arg('<pretty|json|ndjson>')} Output format for page HTML (defaults to ${code('--log-format')} when present)
 - ${code('--source-summary')} ${messages_arg('[boolean]')}     Output a compact summary instead of full HTML
@@ -336,6 +337,7 @@ Source Inspection & Real-Time Monitoring
 - Useful for debugging content script behavior and style injection
 - Example: ${code('extension dev --source=' + messages_arg('https://example.com'))}
 - ${messages_arg('Note:')} ${code('preview/start')} run in run-only mode and do not perform source inspection.
+- For machine synchronization with ${code('--no-browser')}, use ${code('extension dev --wait --browser=<browser>')} or ${code('extension start --wait --browser=<browser>')} in a second process (use ${code('--wait-format=json')} when a parser consumes stdout).
 
 Non-Destructive Testing in CI
 - Prefer ${code('EXTENSION_AUTHOR_MODE=development')} to copy local templates and avoid network.
@@ -470,6 +472,8 @@ Cross-Browser Compatibility
                 'extension --ai-help --format json',
                 'extension dev ./my-ext --source https://example.com --source-format json',
                 'extension dev ./my-ext --logs=info --log-format=json',
+                'extension dev ./my-ext --wait --browser=chromium --wait-format=json',
+                'extension start ./my-ext --wait --browser=chromium --wait-format=json',
                 'extension install chromium',
                 'extension install --where',
                 'extension uninstall --where',
@@ -905,6 +909,105 @@ Cross-Browser Compatibility
             }
         });
     }
+    function isHttpUrl(value) {
+        if (!value) return false;
+        return /^https?:\/\//i.test(value);
+    }
+    function resolveProjectPath(pathOrRemoteUrl) {
+        if (!pathOrRemoteUrl) return process.cwd();
+        return external_node_path_namespaceObject.isAbsolute(pathOrRemoteUrl) ? pathOrRemoteUrl : external_node_path_namespaceObject.join(process.cwd(), pathOrRemoteUrl);
+    }
+    function parseWaitTimeoutMs(value) {
+        const fallback = 60000;
+        if ('number' == typeof value && Number.isFinite(value) && value > 0) return Math.floor(value);
+        if ('string' == typeof value && value.trim()) {
+            const parsed = parseInt(value, 10);
+            if (Number.isFinite(parsed) && parsed > 0) return parsed;
+        }
+        return fallback;
+    }
+    function parseWaitFormat(value) {
+        return 'json' === value ? 'json' : 'pretty';
+    }
+    function isProcessLikelyAlive(pid) {
+        if ('number' != typeof pid || !Number.isInteger(pid) || pid <= 0) return true;
+        try {
+            process.kill(pid, 0);
+            return true;
+        } catch  {
+            return false;
+        }
+    }
+    function isFreshContractPayload(payload, maxAgeMs) {
+        const candidates = [
+            payload.ts,
+            payload.compiledAt,
+            payload.startedAt
+        ];
+        for (const candidate of candidates){
+            if (!candidate) continue;
+            const stamp = Date.parse(candidate);
+            if (Number.isFinite(stamp)) return Date.now() - stamp <= maxAgeMs;
+        }
+        return false;
+    }
+    async function waitForReadyContract(options) {
+        const readyPath = external_node_path_namespaceObject.join(options.projectPath, 'dist', 'extension-js', options.browser, 'ready.json');
+        const start = Date.now();
+        while(Date.now() - start < options.timeoutMs){
+            if (external_node_fs_namespaceObject.existsSync(readyPath)) try {
+                const payload = JSON.parse(external_node_fs_namespaceObject.readFileSync(readyPath, 'utf8'));
+                const isLive = isProcessLikelyAlive(payload.pid);
+                if (payload.command !== options.command) {
+                    await new Promise((resolve)=>setTimeout(resolve, 250));
+                    continue;
+                }
+                if (!isLive) {
+                    if ('start' !== options.command || !isFreshContractPayload(payload, options.timeoutMs)) {
+                        await new Promise((resolve)=>setTimeout(resolve, 250));
+                        continue;
+                    }
+                }
+                if ('ready' === payload.status) return payload;
+                if ('error' === payload.status) {
+                    const detail = payload.message || payload.errors?.[0] || 'unknown error';
+                    throw new Error(String(detail));
+                }
+            } catch (error) {
+                if (error instanceof Error) throw error;
+                throw new Error(String(error));
+            }
+            await new Promise((resolve)=>setTimeout(resolve, 250));
+        }
+        throw new Error(`Timed out waiting for ready contract at ${readyPath} (${options.timeoutMs} ms)`);
+    }
+    async function runWaitMode(options) {
+        if (isHttpUrl(options.pathOrRemoteUrl)) throw new Error('--wait requires a local project path (remote URLs are not supported)');
+        const projectPath = resolveProjectPath(options.pathOrRemoteUrl);
+        const timeoutMs = parseWaitTimeoutMs(options.waitTimeout);
+        const format = parseWaitFormat(options.waitFormat);
+        const results = [];
+        for (const browser of options.browsers){
+            const payload = await waitForReadyContract({
+                command: options.command,
+                projectPath,
+                browser,
+                timeoutMs
+            });
+            results.push({
+                ...payload,
+                browser
+            });
+        }
+        return {
+            projectPath,
+            command: options.command,
+            timeoutMs,
+            format,
+            browsers: options.browsers,
+            results
+        };
+    }
     function normalizeSourceOption(source, startingUrl) {
         if (!source) return;
         const hasExplicitSourceString = 'string' == typeof source && 'true' !== String(source).trim().toLowerCase();
@@ -1012,7 +1115,7 @@ Cross-Browser Compatibility
     }
     const dev_require = (0, external_module_namespaceObject.createRequire)(__rslib_import_meta_url__);
     function registerDevCommand(program, telemetry) {
-        program.command('dev').arguments('[project-path|remote-url]').usage('dev [project-path|remote-url] [options]').description(commandDescriptions.dev).addHelpText('after', '\nAdditional option:\n  --no-browser    do not launch the browser (dev server still starts)\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 <chrome | chromium | edge | firefox | chromium-based | gecko-based | firefox-based>', '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('--polyfill [boolean]', 'whether or not to apply the cross-browser polyfill. Defaults to `false`').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('--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('--source [url]', "[experimental] opens the provided URL in Chrome and prints the full, live HTML of the page after content scripts are injected").option('--watch-source [boolean]', '[experimental] re-print HTML on rebuilds or file changes (defaults to true when --source is present)', parseOptionalBoolean).option('--source-format <pretty|json|ndjson>', '[experimental] output format for source HTML (defaults to --log-format when present, otherwise JSON when --source is used)').option('--source-summary [boolean]', '[experimental] output a compact summary instead of full HTML', parseOptionalBoolean).option('--source-meta [boolean]', '[experimental] output page metadata (readyState, viewport, frames)', parseOptionalBoolean).option('--source-probe <selectors>', '[experimental] comma-separated CSS selectors to probe').option('--source-tree <off|root-only>', '[experimental] output a compact extension root tree').option('--source-console [boolean]', '[experimental] output console summary (best-effort)', parseOptionalBoolean).option('--source-dom [boolean]', '[experimental] output DOM snapshots and diffs (default: true when watch is enabled)', parseOptionalBoolean).option('--source-max-bytes <bytes>', '[experimental] limit HTML output size in bytes (0 disables truncation)').option('--source-redact <off|safe|strict>', '[experimental] redact sensitive content in HTML output (default: safe for JSON/NDJSON)').option('--source-include-shadow <off|open-only|all>', '[experimental] control Shadow DOM inclusion in HTML output (default: open-only)').option('--source-diff [boolean]', '[experimental] include diff metadata on watch updates (default: true when watch is enabled)', parseOptionalBoolean).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('--author, --author-mode', '[internal] enable maintainer diagnostics (does not affect user runtime logs)').action(async function(pathOrRemoteUrl, { browser = 'chromium', ...devOptions }) {
+        program.command('dev').arguments('[project-path|remote-url]').usage('dev [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  --wait          wait for ready contract and exit\n  --wait-format   pretty|json output for wait mode\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 <chrome | chromium | edge | firefox | chromium-based | gecko-based | firefox-based>', '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('--polyfill [boolean]', 'whether or not to apply the cross-browser polyfill. Defaults to `false`').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('--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('--source [url]', "[experimental] opens the provided URL in Chrome and prints the full, live HTML of the page after content scripts are injected").option('--watch-source [boolean]', '[experimental] re-print HTML on rebuilds or file changes (defaults to true when --source is present)', parseOptionalBoolean).option('--source-format <pretty|json|ndjson>', '[experimental] output format for source HTML (defaults to --log-format when present, otherwise JSON when --source is used)').option('--source-summary [boolean]', '[experimental] output a compact summary instead of full HTML', parseOptionalBoolean).option('--source-meta [boolean]', '[experimental] output page metadata (readyState, viewport, frames)', parseOptionalBoolean).option('--source-probe <selectors>', '[experimental] comma-separated CSS selectors to probe').option('--source-tree <off|root-only>', '[experimental] output a compact extension root tree').option('--source-console [boolean]', '[experimental] output console summary (best-effort)', parseOptionalBoolean).option('--source-dom [boolean]', '[experimental] output DOM snapshots and diffs (default: true when watch is enabled)', parseOptionalBoolean).option('--source-max-bytes <bytes>', '[experimental] limit HTML output size in bytes (0 disables truncation)').option('--source-redact <off|safe|strict>', '[experimental] redact sensitive content in HTML output (default: safe for JSON/NDJSON)').option('--source-include-shadow <off|open-only|all>', '[experimental] control Shadow DOM inclusion in HTML output (default: open-only)').option('--source-diff [boolean]', '[experimental] include diff metadata on watch updates (default: true when watch is enabled)', parseOptionalBoolean).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('--wait-format <pretty|json>', 'output format for --wait results (default: pretty)').option('--author, --author-mode', '[internal] enable maintainer diagnostics (does not affect user runtime logs)').action(async function(pathOrRemoteUrl, { browser = 'chromium', ...devOptions }) {
             if (devOptions.author || devOptions['authorMode']) {
                 process.env.EXTENSION_AUTHOR_MODE = 'true';
                 if (!process.env.EXTENSION_VERBOSE) process.env.EXTENSION_VERBOSE = '1';
@@ -1030,6 +1133,29 @@ Cross-Browser Compatibility
             validateVendorsOrExit(list, (invalid, supported)=>{
                 console.error(unsupportedBrowserFlag(invalid, supported));
             });
+            if (devOptions.wait) {
+                const waitResult = await runWaitMode({
+                    command: 'dev',
+                    pathOrRemoteUrl,
+                    browsers: list,
+                    waitTimeout: devOptions.waitTimeout,
+                    waitFormat: devOptions.waitFormat
+                });
+                if ('json' === waitResult.format) console.log(JSON.stringify({
+                    ok: true,
+                    mode: 'wait',
+                    command: 'dev',
+                    browsers: waitResult.browsers,
+                    results: waitResult.results
+                }));
+                telemetry.track('cli_command_finish', {
+                    command: 'dev',
+                    duration_ms: Date.now() - cmdStart,
+                    success: true,
+                    exit_code: 0
+                });
+                return;
+            }
             const normalizedSource = normalizeSourceOption(devOptions.source, devOptions.startingUrl);
             if (normalizedSource) {
                 devOptions.source = normalizedSource;
@@ -1111,7 +1237,7 @@ Cross-Browser Compatibility
     }
     const start_require = (0, external_module_namespaceObject.createRequire)(__rslib_import_meta_url__);
     function registerStartCommand(program, telemetry) {
-        program.command('start').arguments('[project-path|remote-url]').usage('start [project-path|remote-url] [options]').description(commandDescriptions.start).addHelpText('after', '\nAdditional option:\n  --no-browser    do not launch the browser (build still runs)\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 <chrome | chromium | edge | firefox | chromium-based | gecko-based | firefox-based>', 'specify a browser/engine to run. Defaults to `chromium`').option('--polyfill [boolean]', 'whether or not to apply the cross-browser polyfill. Defaults to `true`').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('--source [url]', "[experimental] opens the provided URL in Chrome and prints the full, live HTML of the page after content scripts are injected").option('--watch-source [boolean]', '[experimental] re-print HTML on rebuilds or file changes', parseOptionalBoolean).option('--source-format <pretty|json|ndjson>', '[experimental] output format for source HTML (defaults to --log-format when present, otherwise JSON when --source is used)').option('--source-summary [boolean]', '[experimental] output a compact summary instead of full HTML', parseOptionalBoolean).option('--source-meta [boolean]', '[experimental] output page metadata (readyState, viewport, frames)', parseOptionalBoolean).option('--source-probe <selectors>', '[experimental] comma-separated CSS selectors to probe').option('--source-tree <off|root-only>', '[experimental] output a compact extension root tree').option('--source-console [boolean]', '[experimental] output console summary (best-effort)', parseOptionalBoolean).option('--source-dom [boolean]', '[experimental] output DOM snapshots and diffs (default: true when watch is enabled)', parseOptionalBoolean).option('--source-max-bytes <bytes>', '[experimental] limit HTML output size in bytes (0 disables truncation)').option('--source-redact <off|safe|strict>', '[experimental] redact sensitive content in HTML output (default: safe for JSON/NDJSON)').option('--source-include-shadow <off|open-only|all>', '[experimental] control Shadow DOM inclusion in HTML output (default: open-only)').option('--source-diff [boolean]', '[experimental] include diff metadata on watch updates (default: true when watch is enabled)', parseOptionalBoolean).option('--extensions <list>', 'comma-separated list of companion extensions or store URLs to load').option('--install [boolean]', '[experimental] install project dependencies when missing', parseOptionalBoolean).option('--author, --author-mode', '[experimental] enable maintainer diagnostics (does not affect user runtime logs)').action(async function(pathOrRemoteUrl, { browser = 'chromium', ...startOptions }) {
+        program.command('start').arguments('[project-path|remote-url]').usage('start [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\n  --wait-format   pretty|json output for wait mode\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 <chrome | chromium | edge | firefox | chromium-based | gecko-based | firefox-based>', 'specify a browser/engine to run. Defaults to `chromium`').option('--polyfill [boolean]', 'whether or not to apply the cross-browser polyfill. Defaults to `true`').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('--source [url]', "[experimental] opens the provided URL in Chrome and prints the full, live HTML of the page after content scripts are injected").option('--watch-source [boolean]', '[experimental] re-print HTML on rebuilds or file changes', parseOptionalBoolean).option('--source-format <pretty|json|ndjson>', '[experimental] output format for source HTML (defaults to --log-format when present, otherwise JSON when --source is used)').option('--source-summary [boolean]', '[experimental] output a compact summary instead of full HTML', parseOptionalBoolean).option('--source-meta [boolean]', '[experimental] output page metadata (readyState, viewport, frames)', parseOptionalBoolean).option('--source-probe <selectors>', '[experimental] comma-separated CSS selectors to probe').option('--source-tree <off|root-only>', '[experimental] output a compact extension root tree').option('--source-console [boolean]', '[experimental] output console summary (best-effort)', parseOptionalBoolean).option('--source-dom [boolean]', '[experimental] output DOM snapshots and diffs (default: true when watch is enabled)', parseOptionalBoolean).option('--source-max-bytes <bytes>', '[experimental] limit HTML output size in bytes (0 disables truncation)').option('--source-redact <off|safe|strict>', '[experimental] redact sensitive content in HTML output (default: safe for JSON/NDJSON)').option('--source-include-shadow <off|open-only|all>', '[experimental] control Shadow DOM inclusion in HTML output (default: open-only)').option('--source-diff [boolean]', '[experimental] include diff metadata on watch updates (default: true when watch is enabled)', parseOptionalBoolean).option('--extensions <list>', 'comma-separated list of companion extensions or store URLs to load').option('--install [boolean]', '[experimental] 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('--wait-format <pretty|json>', 'output format for --wait results (default: pretty)').option('--author, --author-mode', '[experimental] enable maintainer diagnostics (does not affect user runtime logs)').action(async function(pathOrRemoteUrl, { browser = 'chromium', ...startOptions }) {
             const hasSourceInspectionFlags = void 0 !== startOptions.source || void 0 !== startOptions.watchSource || void 0 !== startOptions.sourceFormat || void 0 !== startOptions.sourceSummary || void 0 !== startOptions.sourceMeta || void 0 !== startOptions.sourceProbe || void 0 !== startOptions.sourceTree || void 0 !== startOptions.sourceConsole || void 0 !== startOptions.sourceDom || void 0 !== startOptions.sourceMaxBytes || void 0 !== startOptions.sourceRedact || void 0 !== startOptions.sourceIncludeShadow || void 0 !== startOptions.sourceDiff;
             if (hasSourceInspectionFlags) {
                 console.error(sourceInspectionNotSupported('start'));
@@ -1131,6 +1257,29 @@ Cross-Browser Compatibility
             validateVendorsOrExit(list, (invalid, supported)=>{
                 console.error(unsupportedBrowserFlag(invalid, supported));
             });
+            if (startOptions.wait) {
+                const waitResult = await runWaitMode({
+                    command: 'start',
+                    pathOrRemoteUrl,
+                    browsers: list,
+                    waitTimeout: startOptions.waitTimeout,
+                    waitFormat: startOptions.waitFormat
+                });
+                if ('json' === waitResult.format) console.log(JSON.stringify({
+                    ok: true,
+                    mode: 'wait',
+                    command: 'start',
+                    browsers: waitResult.browsers,
+                    results: waitResult.results
+                }));
+                telemetry.track('cli_command_finish', {
+                    command: 'start',
+                    duration_ms: Date.now() - cmdStart,
+                    success: true,
+                    exit_code: 0
+                });
+                return;
+            }
             const normalizedSource = normalizeSourceOption(startOptions.source, startOptions.startingUrl);
             if (normalizedSource) startOptions.source = normalizedSource;
             const sourceEnabled = Boolean(startOptions.source || startOptions.watchSource);

package/dist/commands/dev-wait.d.ts

@@ -0,0 +1,37 @@
+export type WaitFormat = 'pretty' | 'json';
+export type WaitCommand = 'dev' | 'start';
+export type ReadyContractPayload = {
+    status?: string;
+    message?: string;
+    errors?: string[];
+    code?: string;
+    command?: string;
+    browser?: string;
+    runId?: string;
+    startedAt?: string;
+    distPath?: string;
+    manifestPath?: string;
+    port?: number | null;
+    pid?: number;
+    ts?: string;
+    compiledAt?: string | null;
+};
+export type RunWaitModeOptions = {
+    command: WaitCommand;
+    pathOrRemoteUrl?: string;
+    browsers: string[];
+    waitTimeout?: string | number;
+    waitFormat?: string;
+};
+export type RunWaitModeResult = {
+    projectPath: string;
+    command: WaitCommand;
+    timeoutMs: number;
+    format: WaitFormat;
+    browsers: string[];
+    results: Array<ReadyContractPayload & {
+        browser: string;
+    }>;
+};
+export declare function runWaitMode(options: RunWaitModeOptions): Promise<RunWaitModeResult>;
+export declare function runDevWaitMode(options: Omit<RunWaitModeOptions, 'command'>): Promise<RunWaitModeResult>;

package/package.json

@@ -33,7 +33,7 @@
     "extension": "./bin/extension.cjs"
   },
   "name": "extension",
-  "version": "3.8.11",
+  "version": "3.8.13",
   "description": "Create cross-browser extensions with no build configuration.",
   "homepage": "https://extension.js.org/",
   "bugs": {
@@ -90,9 +90,9 @@
     "@types/chrome": "^0.1.33",
     "@types/node": "^25.2.0",
     "@types/webextension-polyfill": "0.12.4",
-    "extension-create": "3.8.11",
-    "extension-develop": "3.8.11",
-    "extension-install": "3.8.11",
+    "extension-create": "3.8.13",
+    "extension-develop": "3.8.13",
+    "extension-install": "3.8.13",
     "commander": "^14.0.3",
     "pintor": "0.3.0",
     "semver": "^7.7.3",