extension 3.5.1 → 3.6.0

package/dist/cli-lib/messages.d.ts

@@ -13,7 +13,6 @@ export declare const commandDescriptions: {
     readonly start: "Builds and starts the extension in production mode";
     readonly preview: "Previews the extension in production mode without building";
     readonly build: "Builds the extension for packaging/distribution";
-    readonly cleanup: "Cleans up orphaned instances and frees unused ports";
 };
 export declare function unhandledError(err: unknown): string;
 export declare function updateFailed(err: any): string;
@@ -31,3 +30,38 @@ export declare function unsupportedBrowserFlag(value: string, supported: string[
 export declare function invalidLogsOptionPipe(value: string): string;
 export declare function invalidLogsOptionValue(value: string, allowed: string[]): string;
 export declare function programAIHelp(): string;
+export type ProgramAIHelpJSON = {
+    version: string;
+    commands: Array<{
+        name: 'create' | 'dev' | 'start' | 'preview' | 'build';
+        summary: string;
+        supportsSourceInspection: boolean;
+    }>;
+    globalOptions: Array<{
+        name: '--ai-help' | '--format' | '--no-telemetry';
+        values?: string[];
+        default?: string;
+        description: string;
+    }>;
+    capabilities: {
+        sourceInspection: {
+            supportedIn: string[];
+            unsupportedIn: string[];
+            notes: string[];
+        };
+        logger: {
+            levels: string[];
+            formats: string[];
+            notes: string[];
+        };
+        managedDependencies: {
+            enforcement: string;
+            trigger: string;
+            action: string;
+        };
+    };
+    examples: string[];
+};
+export declare function programAIHelpJSON(version: string): ProgramAIHelpJSON;
+export declare function invalidAIHelpFormat(value: string): string;
+export declare function sourceInspectionNotSupported(command: 'start' | 'preview'): string;

package/dist/cli.cjs

@@ -57,7 +57,7 @@ var __webpack_exports__ = {};
         return external_pintor_default().green('►►►');
     }
     const code = (text)=>external_pintor_default().blue(text);
-    const arg = (text)=>external_pintor_default().gray(text);
+    const messages_arg = (text)=>external_pintor_default().gray(text);
     const fmt = {
         heading: (title)=>external_pintor_default().underline(external_pintor_default().blue(title)),
         label: (k)=>external_pintor_default().gray(k.toUpperCase()),
@@ -85,8 +85,7 @@ var __webpack_exports__ = {};
         dev: 'Starts the development server with hot reloading',
         start: 'Builds and starts the extension in production mode',
         preview: 'Previews the extension in production mode without building',
-        build: 'Builds the extension for packaging/distribution',
-        cleanup: 'Cleans up orphaned instances and frees unused ports'
+        build: 'Builds the extension for packaging/distribution'
     };
     function unhandledError(err) {
         const message = err instanceof Error ? err.stack || err.message : 'string' == typeof err ? err : fmt.truncate(err);
@@ -115,57 +114,70 @@ Example
 - ${code('extension create --help')} outputs information about the "create" command.
 
 Available Commands
-- ${code('extension create ' + arg('<project-name|project-path>'))}
+- ${code('extension create ' + messages_arg('<project-name|project-path>'))}
   ${commandDescriptions.create}
 
-- ${code('extension dev ' + arg('[project-path|remote-url]'))}
+- ${code('extension dev ' + messages_arg('[project-path|remote-url]'))}
   ${commandDescriptions.dev}
 
-- ${code('extension start ' + arg('[project-path|remote-url]'))}
+- ${code('extension start ' + messages_arg('[project-path|remote-url]'))}
   ${commandDescriptions.start}
 
-- ${code('extension preview ' + arg('[project-path|remote-url]'))}
+- ${code('extension preview ' + messages_arg('[project-path|remote-url]'))}
   ${commandDescriptions.preview}
 
-- ${code('extension build ' + arg('[project-path|remote-url]'))}
+- ${code('extension build ' + messages_arg('[project-path|remote-url]'))}
   ${commandDescriptions.build}
 
-- ${code('extension cleanup')}
-  ${commandDescriptions.cleanup}
-
 Common Options
-- ${code('--browser')} ${arg('<chrome|edge|firefox|chromium|chromium-based|gecko-based|firefox-based>')} Target browser/engine (default: chrome)
-- ${code('--profile')} ${arg('<path|boolean>')}        Browser profile configuration
-- ${code('--polyfill')} ${arg('[boolean]')}            Enable/disable cross-browser polyfill
+- ${code('--browser')} ${messages_arg('<chrome|edge|firefox|chromium|chromium-based|gecko-based|firefox-based>')} Target browser/engine (default: chromium)
+- ${code('--profile')} ${messages_arg('<path|boolean>')}        Browser profile configuration
+- ${code('--polyfill')} ${messages_arg('[boolean]')}            Enable/disable cross-browser polyfill
 - ${code('--no-telemetry')}                            Disable anonymous telemetry for this run
-- ${code('--port')} ${arg('<number>')}                 Development server port (default: 8080)
-- ${code('--starting-url')} ${arg('<url>')}            Initial URL to load in browser
-- ${code('--silent')} ${arg('[boolean]')}              Suppress console output during build
+- ${code('--ai-help')}                                 Show AI-assistant oriented help and tips
+- ${code('--format')} ${messages_arg('<pretty|json>')}          Output format for ${code('--ai-help')} (default: pretty)
+- ${code('--help')}                                    Show help output
+- ${code('--port')} ${messages_arg('<number>')}                 Development server port (default: 8080)
+- ${code('--starting-url')} ${messages_arg('<url>')}            Initial URL to load in browser
+- ${code('--silent')} ${messages_arg('[boolean]')}              Suppress console output during build
 
-Source Inspection
-- ${code('--source')} ${arg('<url|boolean>')}         Open URL and print HTML after content scripts inject
-  - When provided without a URL, falls back to ${arg('--starting-url')} or ${arg('https://example.com')}
-  - Watch mode is enabled by default when ${code('--source')} is present
+Source Inspection (dev command)
+- ${code('--source')} ${messages_arg('<url|boolean>')}         Open URL and print HTML after content scripts inject (dev only)
+  - 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.
+- ${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
+- ${code('--source-meta')} ${messages_arg('[boolean]')}        Output page metadata (readyState, viewport, frames)
+- ${code('--source-probe')} ${messages_arg('<selectors>')}     Comma-separated CSS selectors to probe
+- ${code('--source-tree')} ${messages_arg('<off|root-only>')}  Output a compact extension root tree
+- ${code('--source-console')} ${messages_arg('[boolean]')}     Output console summary (best-effort)
+- ${code('--source-dom')} ${messages_arg('[boolean]')}         Output DOM snapshots and diffs
+- ${code('--source-max-bytes')} ${messages_arg('<bytes>')}      Limit HTML output size (0 disables truncation)
+- ${code('--source-redact')} ${messages_arg('<off|safe|strict>')} Redact sensitive HTML content (default: safe for JSON/NDJSON)
+- ${code('--source-include-shadow')} ${messages_arg('<off|open-only|all>')} Control Shadow DOM inclusion (default: open-only)
+- ${code('--source-diff')} ${messages_arg('[boolean]')}        Include diff metadata on watch updates
 
 Browser-Specific Options
-- ${code('--chromium-binary')} ${arg('<path>')}        Custom Chromium binary path
-- ${code('--gecko-binary')}/${code('--firefox-binary')} ${arg('<path>')}           Custom Firefox/Gecko binary path
+- ${code('--chromium-binary')} ${messages_arg('<path>')}        Custom Chromium binary path
+- ${code('--gecko-binary')}/${code('--firefox-binary')} ${messages_arg('<path>')}           Custom Firefox/Gecko binary path
 
 Build Options
-- ${code('--zip')} ${arg('[boolean]')}                 Create ZIP archive of built extension
-- ${code('--zip-source')} ${arg('[boolean]')}          Include source files in ZIP
-- ${code('--zip-filename')} ${arg('<name>')}           Custom ZIP filename
+- ${code('--zip')} ${messages_arg('[boolean]')}                 Create ZIP archive of built extension
+- ${code('--zip-source')} ${messages_arg('[boolean]')}          Include source files in ZIP
+- ${code('--zip-filename')} ${messages_arg('<name>')}           Custom ZIP filename
 
 ${external_pintor_default().underline('Centralized Logger (terminal output)')}
 - The manager extension embeds a centralized logger that streams events to the CLI.
 - Enable and filter logs directly via ${code('extension dev')} flags:
-  - ${code('--logs')} ${arg('<off|error|warn|info|debug|trace>')}    Minimum level (default: info)
-  - ${code('--log-context')} ${arg('<list|all>')}                     Contexts: background,content,page,sidebar,popup,options,devtools
-  - ${code('--log-format')} ${arg('<pretty|json>')}                   Output format (default: pretty)
+  - ${code('--logs')} ${messages_arg('<off|error|warn|info|debug|trace>')}    Minimum level (default: off)
+  - ${code('--log-context')} ${messages_arg('<list|all>')}                     Contexts: background,content,page,sidebar,popup,options,devtools
+  - ${code('--log-format')} ${messages_arg('<pretty|json|ndjson>')}            Output format (default: pretty)
   - ${code('--no-log-timestamps')}                                   Hide ISO timestamps in pretty output
   - ${code('--no-log-color')}                                        Disable color in pretty output
-  - ${code('--log-url')} ${arg('<substring|/regex/>')}                Filter by event.url
-  - ${code('--log-tab')} ${arg('<id>')}                               Filter by tabId
+  - ${code('--log-url')} ${messages_arg('<substring|/regex/>')}                Filter by event.url
+  - ${code('--log-tab')} ${messages_arg('<id>')}                               Filter by tabId
 - Example: ${code('extension dev ./my-ext --logs=debug --log-context=all --log-format=pretty')}
 
 ${code('extension --help')}
@@ -179,6 +191,7 @@ ${external_pintor_default().underline('Path Resolution (important)')}
 
 AI Assistants
 - For AI-oriented guidance and deeper tips, run ${code('extension --ai-help')}
+- For machine-readable AI guidance, run ${code('extension --ai-help --format json')}
 
  Report issues
  - ${external_pintor_default().underline('https://github.com/cezaraugusto/extension/issues/new')}`;
@@ -197,13 +210,13 @@ Browser-Specific Configuration
 Centralized Logger (for AI & CI)
 - Logs from all contexts are centralized by the manager extension and streamed to the CLI.
 - Prefer these flags to control terminal logs during ${code('extension dev')}:
-  - ${code('--logs')} ${arg('<off|error|warn|info|debug|trace>')}    Minimum level
-  - ${code('--log-context')} ${arg('<list|all>')}                     Contexts to include
-  - ${code('--log-format')} ${arg('<pretty|json>')}                   Pretty for humans; JSON for machines/NDJSON pipelines
-  - ${code('--no-log-timestamps')} ${arg(' ')}                        Disable timestamps (pretty)
-  - ${code('--no-log-color')} ${arg(' ')}                             Disable ANSI colors (pretty)
-  - ${code('--log-url')} ${arg('<substring|/regex/>')}                Filter by URL
-  - ${code('--log-tab')} ${arg('<id>')}                               Filter by tabId
+  - ${code('--logs')} ${messages_arg('<off|error|warn|info|debug|trace>')}    Minimum level
+  - ${code('--log-context')} ${messages_arg('<list|all>')}                     Contexts to include
+  - ${code('--log-format')} ${messages_arg('<pretty|json|ndjson>')}            Pretty for humans; JSON for machines/NDJSON pipelines
+  - ${code('--no-log-timestamps')} ${messages_arg(' ')}                        Disable timestamps (pretty)
+  - ${code('--no-log-color')} ${messages_arg(' ')}                             Disable ANSI colors (pretty)
+  - ${code('--log-url')} ${messages_arg('<substring|/regex/>')}                Filter by URL
+  - ${code('--log-tab')} ${messages_arg('<id>')}                               Filter by tabId
 - Good CI pattern: ${code('EXTENSION_AUTHOR_MODE=development EXTENSION_AUTO_EXIT_MS=6000 extension dev ./ext --logs=info --log-format=json')}
 
 Special Folders for Entrypoints
@@ -238,20 +251,20 @@ Shadow DOM for Content Scripts
 - Prevents style conflicts with host page
 
 Environment Variables
-- Use ${code(arg('EXTENSION_PUBLIC_*'))} prefix for variables accessible in extension code
+- Use ${code(messages_arg('EXTENSION_PUBLIC_*'))} prefix for variables accessible in extension code
 - Supported in both ${code('process.env')} and ${code('import.meta.env')}
-- Environment file priority: ${external_pintor_default().underline(code(arg('.env.{browser}.{mode}')))} > ${external_pintor_default().underline(code(arg('.env.{browser}')))} > ${external_pintor_default().underline(code(arg('.env.{mode}')))} > ${external_pintor_default().underline(code(arg('.env')))}
-- Example: ${code(arg('EXTENSION_PUBLIC_API_KEY=your_key'))}
+- Environment file priority: ${external_pintor_default().underline(code(messages_arg('.env.{browser}.{mode}')))} > ${external_pintor_default().underline(code(messages_arg('.env.{browser}')))} > ${external_pintor_default().underline(code(messages_arg('.env.{mode}')))} > ${external_pintor_default().underline(code(messages_arg('.env')))}
+- Example: ${code(messages_arg('EXTENSION_PUBLIC_API_KEY=your_key'))}
 
 Available Templates
-- ${external_pintor_default().green('Frameworks')}: ${code(arg('react'))}, ${code(arg('preact'))}, ${code(arg('vue'))}, ${code(arg('svelte'))}
-- ${external_pintor_default().green('Languages')}: ${code(arg("javascript"))}, ${code(arg("typescript"))}
-- ${external_pintor_default().green('Contexts')}: ${code(arg('content'))} (content scripts), ${code(arg('new'))} (new tab), ${code(arg('action'))} (popup)
-- ${external_pintor_default().green('Styling')}: ${code(arg('tailwind'))}, ${code(arg('sass'))}, ${code(arg('less'))}
-- ${external_pintor_default().green('Configs')}: ${code(arg('eslint'))}, ${code(arg('prettier'))}, ${code(arg('stylelint'))}
+- ${external_pintor_default().green('Frameworks')}: ${code(messages_arg('react'))}, ${code(messages_arg('preact'))}, ${code(messages_arg('vue'))}, ${code(messages_arg('svelte'))}
+- ${external_pintor_default().green('Languages')}: ${code(messages_arg("javascript"))}, ${code(messages_arg("typescript"))}
+- ${external_pintor_default().green('Contexts')}: ${code(messages_arg('content'))} (content scripts), ${code(messages_arg('new'))} (new tab), ${code(messages_arg('action'))} (popup)
+- ${external_pintor_default().green('Styling')}: ${code(messages_arg('tailwind'))}, ${code(messages_arg('sass'))}, ${code(messages_arg('less'))}
+- ${external_pintor_default().green('Configs')}: ${code(messages_arg('eslint'))}, ${code(messages_arg('prettier'))}, ${code(messages_arg('stylelint'))}
 
 Webpack/Rspack Configuration
-- Create ${external_pintor_default().underline(code(arg('extension.config.js')))} for custom webpack configuration
+- Create ${external_pintor_default().underline(code(messages_arg('extension.config.js')))} for custom webpack configuration
 - Function receives base config, return modified config
 - Supports all webpack/rspack loaders and plugins
 - Example:
@@ -270,8 +283,8 @@ Managed Dependencies (Important)
 - If you truly need a different version, open an issue so we can evaluate a safe upgrade.
 
 Framework-Specific Configuration
-- Create ${external_pintor_default().underline(code(arg('vue.loader.js')))} for Vue-specific loader configuration
-- Create ${external_pintor_default().underline(code(arg('svelte.loader.js')))} for Svelte-specific loader configuration
+- Create ${external_pintor_default().underline(code(messages_arg('vue.loader.js')))} for Vue-specific loader configuration
+- Create ${external_pintor_default().underline(code(messages_arg('svelte.loader.js')))} for Svelte-specific loader configuration
 - Automatically detected and used by Extension.js
 - Example svelte.loader.js:
   ${code('module.exports = {')}
@@ -288,18 +301,32 @@ Hot Module Replacement (HMR)
 - Service workers, _locales and manifest changes reload the extension
 
 Source Inspection & Real-Time Monitoring
-- Use ${code('--source')} ${arg('<url|boolean>')} to inspect page HTML after content script injection
-  - When no URL is provided, falls back to ${arg('--starting-url')} or ${arg('https://example.com')}
+- Use ${code('extension dev --source')} ${messages_arg('<url|boolean>')} to inspect page HTML after content script injection
+  - When no URL is provided, falls back to ${messages_arg('--starting-url')} or ${messages_arg('https://example.com')}
   - Watch mode is enabled by default when ${code('--source')} is present
+- Use ${code('--watch-source')} to re-print HTML on rebuilds or file changes
+- Use ${code('--source-format')} ${messages_arg('<pretty|json|ndjson>')} for machine-friendly HTML output
+- Use ${code('--source-summary')} to emit a compact JSON summary instead of full HTML
+- Use ${code('--source-meta')} to emit page metadata (readyState, viewport, frames)
+- Use ${code('--source-probe')} to probe CSS selectors for quick validation
+- Use ${code('--source-tree')} to emit a compact extension root tree
+- Use ${code('--source-console')} to emit a console summary (best-effort)
+- Use ${code('--source-dom')} to emit DOM snapshots and diffs
+- Use ${code('--source-redact')} ${messages_arg('<off|safe|strict>')} to redact sensitive content
+- Use ${code('--source-max-bytes')} ${messages_arg('<bytes>')} to limit output size
+- Use ${code('--source-diff')} ${messages_arg('[boolean]')} to emit diff metadata for watch updates
+- Source events include frame context (frameId/frameUrl), and console summaries include best-effort script URLs.
+- Action timeline events ${code('action_event')} report navigation, injection, rebuilds, snapshots, and reloads.
 - Automatically enables Chrome remote debugging (port 9222) when source inspection is active
 - Extracts Shadow DOM content from ${code('#extension-root')} or ${code('[data-extension-root=\"true\"]')} elements
 - Useful for debugging content script behavior and style injection
-- Example: ${code('extension dev --source=' + arg('https://example.com'))}
+- 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.
 
 Non-Destructive Testing in CI
 - Prefer ${code('EXTENSION_AUTHOR_MODE=development')} to copy local templates and avoid network.
 - Reuse Playwright's Chromium via ${code('--chromium-binary')} path when available.
-- Set ${code(arg('EXTENSION_AUTO_EXIT_MS'))} and ${code(arg('EXTENSION_FORCE_KILL_MS'))} for non-interactive dev sessions.
+- Set ${code(messages_arg('EXTENSION_AUTO_EXIT_MS'))} and ${code(messages_arg('EXTENSION_FORCE_KILL_MS'))} for non-interactive dev sessions.
 
 File Watching & HMR Examples
 - Content script JS/TS changes trigger reinjection; CSS changes update styles live.
@@ -311,16 +338,121 @@ Troubleshooting
 - When ports conflict, pass ${code('--port 0')} to auto-select an available port.
 
 Non-Interactive / Auto Mode (CI)
-- Set ${code(arg('EXTENSION_AUTO_EXIT_MS'))} to enable self-termination after N milliseconds.
+- Set ${code(messages_arg('EXTENSION_AUTO_EXIT_MS'))} to enable self-termination after N milliseconds.
   Useful when ${code('pnpm extension dev')} would otherwise hang under Rspack watch.
-  Example: ${code(arg('EXTENSION_AUTO_EXIT_MS=6000'))} pnpm extension dev ./templates/react --browser chrome --source ${arg('https://example.com')}
-- Optional: ${code(arg('EXTENSION_FORCE_KILL_MS'))} to hard-exit after N ms as a fallback (defaults to auto-exit + 4000).
+  Example: ${code(messages_arg('EXTENSION_AUTO_EXIT_MS=6000'))} pnpm extension dev ./templates/react --browser chrome --source ${messages_arg('https://example.com')}
+- Optional: ${code(messages_arg('EXTENSION_FORCE_KILL_MS'))} to hard-exit after N ms as a fallback (defaults to auto-exit + 4000).
 
 Cross-Browser Compatibility
 - Use ${code('--polyfill')} flag to enable webextension-polyfill
 - Automatically handles browser API differences
 - Supports Chrome, Edge, Firefox with single codebase`;
     }
+    function programAIHelpJSON(version) {
+        return {
+            version,
+            commands: [
+                {
+                    name: 'create',
+                    summary: commandDescriptions.create,
+                    supportsSourceInspection: false
+                },
+                {
+                    name: 'dev',
+                    summary: commandDescriptions.dev,
+                    supportsSourceInspection: true
+                },
+                {
+                    name: 'start',
+                    summary: commandDescriptions.start,
+                    supportsSourceInspection: false
+                },
+                {
+                    name: 'preview',
+                    summary: commandDescriptions.preview,
+                    supportsSourceInspection: false
+                },
+                {
+                    name: 'build',
+                    summary: commandDescriptions.build,
+                    supportsSourceInspection: false
+                }
+            ],
+            globalOptions: [
+                {
+                    name: '--ai-help',
+                    description: 'Show AI-assistant oriented help and tips'
+                },
+                {
+                    name: '--format',
+                    values: [
+                        'pretty',
+                        'json'
+                    ],
+                    default: 'pretty',
+                    description: 'Output format for --ai-help'
+                },
+                {
+                    name: '--no-telemetry',
+                    description: 'Disable anonymous telemetry for this run'
+                }
+            ],
+            capabilities: {
+                sourceInspection: {
+                    supportedIn: [
+                        'dev'
+                    ],
+                    unsupportedIn: [
+                        'start',
+                        'preview',
+                        'build',
+                        'create'
+                    ],
+                    notes: [
+                        '--source supports URL fallback to --starting-url or https://example.com',
+                        'run-only preview mode does not perform source inspection'
+                    ]
+                },
+                logger: {
+                    levels: [
+                        'off',
+                        'error',
+                        'warn',
+                        'info',
+                        'debug',
+                        'trace',
+                        'all'
+                    ],
+                    formats: [
+                        'pretty',
+                        'json',
+                        'ndjson'
+                    ],
+                    notes: [
+                        'centralized logger streams logs from multiple extension contexts',
+                        '--logs defaults to off unless explicitly enabled'
+                    ]
+                },
+                managedDependencies: {
+                    enforcement: 'guarded',
+                    trigger: 'when managed packages are declared in package.json and referenced in extension.config',
+                    action: 'print an error and abort'
+                }
+            },
+            examples: [
+                'extension --ai-help',
+                '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'
+            ]
+        };
+    }
+    function invalidAIHelpFormat(value) {
+        return `${getLoggingPrefix('error')} Invalid value for ${code('--format')}: ${external_pintor_default().red(String(value))}\nAllowed values: ${messages_arg('pretty, json')}. Example: ${code('extension --ai-help --format json')}`;
+    }
+    function sourceInspectionNotSupported(command) {
+        return `${getLoggingPrefix('error')} ${code(`extension ${command}`)} currently runs in run-only preview mode and does not support source inspection.\nUse ${code('extension dev --source <url>')} for source inspection features.`;
+    }
     const external_semver_namespaceObject = require("semver");
     const external_node_fs_namespaceObject = require("node:fs");
     var external_node_fs_default = /*#__PURE__*/ __webpack_require__.n(external_node_fs_namespaceObject);
@@ -733,6 +865,84 @@ Cross-Browser Compatibility
         if (!hasExplicitSourceString) return hasStartingUrl ? String(startingUrl) : 'https://example.com';
         return String(source);
     }
+    function normalizeEnum(value, allowed) {
+        if (null == value) return;
+        const normalized = String(value).trim().toLowerCase();
+        if (!normalized) return;
+        return allowed.includes(normalized) ? normalized : void 0;
+    }
+    function normalizeSourceFormatOption(params) {
+        const allowed = [
+            'pretty',
+            'json',
+            'ndjson'
+        ];
+        const sourceFormat = normalizeEnum(params.sourceFormat, allowed);
+        if (sourceFormat) return sourceFormat;
+        const logFormat = normalizeEnum(params.logFormat, allowed);
+        if (logFormat) return logFormat;
+        if (params.sourceEnabled) return 'json';
+    }
+    function normalizeSourceRedactOption(sourceRedact, sourceFormat) {
+        const allowed = [
+            'off',
+            'safe',
+            'strict'
+        ];
+        const normalized = normalizeEnum(sourceRedact, allowed);
+        if (normalized) return normalized;
+        if (sourceFormat && 'pretty' !== sourceFormat) return 'safe';
+        return 'off';
+    }
+    function normalizeSourceMaxBytesOption(value) {
+        if (null == value) return;
+        const parsed = 'number' == typeof value ? value : Number(String(value).trim());
+        if (!Number.isFinite(parsed) || parsed < 0) return;
+        return Math.floor(parsed);
+    }
+    function normalizeSourceIncludeShadowOption(value, sourceEnabled) {
+        const allowed = [
+            'off',
+            'open-only',
+            'all'
+        ];
+        const normalized = normalizeEnum(value, allowed);
+        if (normalized) return normalized;
+        if (sourceEnabled) return 'open-only';
+    }
+    function normalizeSourceMetaOption(value, sourceEnabled) {
+        if (void 0 !== value) return 0 === String(value).trim().length ? true : Boolean(value);
+        if (sourceEnabled) return true;
+    }
+    function normalizeSourceTreeOption(value, sourceEnabled) {
+        const allowed = [
+            'off',
+            'root-only'
+        ];
+        const normalized = normalizeEnum(value, allowed);
+        if (normalized) return normalized;
+    }
+    function normalizeSourceConsoleOption(value, sourceEnabled) {
+        if (void 0 !== value) return 0 === String(value).trim().length ? true : Boolean(value);
+    }
+    function normalizeSourceDomOption(value, watchSource) {
+        if (void 0 !== value) return 0 === String(value).trim().length ? true : Boolean(value);
+        if (watchSource) return true;
+    }
+    function normalizeSourceProbeOption(raw) {
+        if (null == raw) return;
+        if (Array.isArray(raw)) {
+            const values = raw.map((value)=>String(value).trim()).filter((value)=>value.length > 0);
+            return values.length > 0 ? values : void 0;
+        }
+        if (0 === String(raw).trim().length) return;
+        const values = String(raw).split(',').map((value)=>value.trim()).filter((value)=>value.length > 0);
+        return values.length > 0 ? values : void 0;
+    }
+    function normalizeSourceDiffOption(value, watchSource) {
+        if (void 0 !== value) return 0 === String(value).trim().length ? true : Boolean(value);
+        if (watchSource) return true;
+    }
     function parseLogContexts(raw) {
         if (!raw || 0 === String(raw).trim().length) return;
         if ('all' === String(raw).trim().toLowerCase()) return;
@@ -748,9 +958,14 @@ Cross-Browser Compatibility
         const values = String(raw).split(',').map((s)=>s.trim()).filter((s)=>s.length > 0).filter((c)=>allowed.includes(c));
         return values.length > 0 ? values : void 0;
     }
+    function parseExtensionsList(raw) {
+        if (!raw || 0 === String(raw).trim().length) return;
+        const values = String(raw).split(',').map((value)=>value.trim()).filter((value)=>value.length > 0);
+        return values.length > 0 ? values : void 0;
+    }
     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).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('--no-runner', 'do not launch the browser runner (dev server still starts)').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>', '[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('--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).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('--no-runner', 'do not launch the browser runner (dev server still starts)').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 }) {
             if (devOptions.author || devOptions['authorMode']) {
                 process.env.EXTENSION_AUTHOR_MODE = 'true';
                 if (!process.env.EXTENSION_VERBOSE) process.env.EXTENSION_VERBOSE = '1';
@@ -771,8 +986,25 @@ Cross-Browser Compatibility
             const normalizedSource = normalizeSourceOption(devOptions.source, devOptions.startingUrl);
             if (normalizedSource) {
                 devOptions.source = normalizedSource;
-                devOptions.watchSource = true;
+                if (void 0 === devOptions.watchSource) devOptions.watchSource = true;
             }
+            const sourceEnabled = Boolean(devOptions.source || devOptions.watchSource);
+            const normalizedSourceFormat = normalizeSourceFormatOption({
+                sourceFormat: devOptions.sourceFormat,
+                logFormat: devOptions.logFormat,
+                sourceEnabled
+            });
+            devOptions.sourceFormat = normalizedSourceFormat;
+            if (sourceEnabled && normalizedSourceFormat) process.env.EXTENSION_SOURCE_FORMAT = normalizedSourceFormat;
+            devOptions.sourceRedact = normalizeSourceRedactOption(devOptions.sourceRedact, normalizedSourceFormat);
+            devOptions.sourceMeta = normalizeSourceMetaOption(devOptions.sourceMeta, sourceEnabled);
+            devOptions.sourceProbe = normalizeSourceProbeOption(devOptions.sourceProbe);
+            devOptions.sourceTree = normalizeSourceTreeOption(devOptions.sourceTree, sourceEnabled);
+            devOptions.sourceConsole = normalizeSourceConsoleOption(devOptions.sourceConsole, sourceEnabled);
+            devOptions.sourceDom = normalizeSourceDomOption(devOptions.sourceDom, devOptions.watchSource);
+            devOptions.sourceMaxBytes = normalizeSourceMaxBytesOption(devOptions.sourceMaxBytes);
+            devOptions.sourceIncludeShadow = normalizeSourceIncludeShadowOption(devOptions.sourceIncludeShadow, sourceEnabled);
+            devOptions.sourceDiff = normalizeSourceDiffOption(devOptions.sourceDiff, devOptions.watchSource);
             const { extensionDev } = dev_require('extension-develop');
             for (const vendor of list){
                 const vendorStart = Date.now();
@@ -793,8 +1025,20 @@ Cross-Browser Compatibility
                     startingUrl: devOptions.startingUrl,
                     source: devOptions.source,
                     watchSource: devOptions.watchSource,
+                    sourceFormat: devOptions.sourceFormat,
+                    sourceSummary: devOptions.sourceSummary,
+                    sourceMeta: devOptions.sourceMeta,
+                    sourceProbe: devOptions.sourceProbe,
+                    sourceTree: devOptions.sourceTree,
+                    sourceConsole: devOptions.sourceConsole,
+                    sourceDom: devOptions.sourceDom,
+                    sourceMaxBytes: devOptions.sourceMaxBytes,
+                    sourceRedact: devOptions.sourceRedact,
+                    sourceIncludeShadow: devOptions.sourceIncludeShadow,
+                    sourceDiff: devOptions.sourceDiff,
                     install: devOptions.install,
                     noRunner: false === devOptions.runner,
+                    extensions: parseExtensionsList(devOptions.extensions),
                     logLevel: logsOption || devOptions.logLevel || 'off',
                     logContexts: parseLogContexts(logContextOption),
                     logFormat: devOptions.logFormat || 'pretty',
@@ -820,7 +1064,12 @@ 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).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('--no-runner', 'do not launch the browser runner (build still runs)').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>', '[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('--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).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('--no-runner', 'do not launch the browser runner (build still runs)').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 }) {
+            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'));
+                process.exit(1);
+            }
             if (startOptions.author || startOptions.authorMode) {
                 process.env.EXTENSION_AUTHOR_MODE = 'true';
                 if (!process.env.EXTENSION_VERBOSE) process.env.EXTENSION_VERBOSE = '1';
@@ -835,6 +1084,25 @@ Cross-Browser Compatibility
             validateVendorsOrExit(list, (invalid, supported)=>{
                 console.error(unsupportedBrowserFlag(invalid, supported));
             });
+            const normalizedSource = normalizeSourceOption(startOptions.source, startOptions.startingUrl);
+            if (normalizedSource) startOptions.source = normalizedSource;
+            const sourceEnabled = Boolean(startOptions.source || startOptions.watchSource);
+            const normalizedSourceFormat = normalizeSourceFormatOption({
+                sourceFormat: startOptions.sourceFormat,
+                logFormat: startOptions.logFormat,
+                sourceEnabled
+            });
+            startOptions.sourceFormat = normalizedSourceFormat;
+            if (sourceEnabled && normalizedSourceFormat) process.env.EXTENSION_SOURCE_FORMAT = normalizedSourceFormat;
+            startOptions.sourceRedact = normalizeSourceRedactOption(startOptions.sourceRedact, normalizedSourceFormat);
+            startOptions.sourceMeta = normalizeSourceMetaOption(startOptions.sourceMeta, sourceEnabled);
+            startOptions.sourceProbe = normalizeSourceProbeOption(startOptions.sourceProbe);
+            startOptions.sourceTree = normalizeSourceTreeOption(startOptions.sourceTree, sourceEnabled);
+            startOptions.sourceConsole = normalizeSourceConsoleOption(startOptions.sourceConsole, sourceEnabled);
+            startOptions.sourceDom = normalizeSourceDomOption(startOptions.sourceDom, startOptions.watchSource);
+            startOptions.sourceMaxBytes = normalizeSourceMaxBytesOption(startOptions.sourceMaxBytes);
+            startOptions.sourceIncludeShadow = normalizeSourceIncludeShadowOption(startOptions.sourceIncludeShadow, sourceEnabled);
+            startOptions.sourceDiff = normalizeSourceDiffOption(startOptions.sourceDiff, startOptions.watchSource);
             const { extensionStart } = start_require('extension-develop');
             for (const vendor of list){
                 const vendorStart = Date.now();
@@ -855,8 +1123,20 @@ Cross-Browser Compatibility
                     port: startOptions.port,
                     install: startOptions.install,
                     noRunner: false === startOptions.runner,
+                    extensions: parseExtensionsList(startOptions.extensions),
                     source: 'string' == typeof startOptions.source ? startOptions.source : startOptions.source,
                     watchSource: startOptions.watchSource,
+                    sourceFormat: startOptions.sourceFormat,
+                    sourceSummary: startOptions.sourceSummary,
+                    sourceMeta: startOptions.sourceMeta,
+                    sourceProbe: startOptions.sourceProbe,
+                    sourceTree: startOptions.sourceTree,
+                    sourceConsole: startOptions.sourceConsole,
+                    sourceDom: startOptions.sourceDom,
+                    sourceMaxBytes: startOptions.sourceMaxBytes,
+                    sourceRedact: startOptions.sourceRedact,
+                    sourceIncludeShadow: startOptions.sourceIncludeShadow,
+                    sourceDiff: startOptions.sourceDiff,
                     logLevel: logsOption || startOptions.logLevel || 'off',
                     logContexts,
                     logFormat: startOptions.logFormat || 'pretty',
@@ -881,7 +1161,12 @@ Cross-Browser Compatibility
     }
     const preview_require = (0, external_module_namespaceObject.createRequire)(__rslib_import_meta_url__);
     function registerPreviewCommand(program, telemetry) {
-        program.command('preview').arguments('[project-name]').usage('preview [path-to-remote-extension] [options]').description(commandDescriptions.preview).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('--starting-url <url>', 'specify the starting URL for the browser. Defaults to `undefined`').option('--no-runner', 'do not launch the browser runner').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>', '[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('--author, --author-mode', '[internal] enable maintainer diagnostics (does not affect user runtime logs)').action(async function(pathOrRemoteUrl, { browser = 'chromium', ...previewOptions }) {
+        program.command('preview').arguments('[project-name]').usage('preview [path-to-remote-extension] [options]').description(commandDescriptions.preview).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('--starting-url <url>', 'specify the starting URL for the browser. Defaults to `undefined`').option('--no-runner', 'do not launch the browser runner').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('--author, --author-mode', '[internal] enable maintainer diagnostics (does not affect user runtime logs)').action(async function(pathOrRemoteUrl, { browser = 'chromium', ...previewOptions }) {
+            const hasSourceInspectionFlags = void 0 !== previewOptions.source || void 0 !== previewOptions.watchSource || void 0 !== previewOptions.sourceFormat || void 0 !== previewOptions.sourceSummary || void 0 !== previewOptions.sourceMeta || void 0 !== previewOptions.sourceProbe || void 0 !== previewOptions.sourceTree || void 0 !== previewOptions.sourceConsole || void 0 !== previewOptions.sourceDom || void 0 !== previewOptions.sourceMaxBytes || void 0 !== previewOptions.sourceRedact || void 0 !== previewOptions.sourceIncludeShadow || void 0 !== previewOptions.sourceDiff;
+            if (hasSourceInspectionFlags) {
+                console.error(sourceInspectionNotSupported('preview'));
+                process.exit(1);
+            }
             if (previewOptions.author || previewOptions['authorMode']) {
                 process.env.EXTENSION_AUTHOR_MODE = 'true';
                 if (!process.env.EXTENSION_VERBOSE) process.env.EXTENSION_VERBOSE = '1';
@@ -899,6 +1184,25 @@ Cross-Browser Compatibility
                 const isRemote = 'string' == typeof pathOrRemoteUrl && /^https?:/i.test(pathOrRemoteUrl);
                 if (isRemote) process.env.EXTJS_LIGHT = '1';
             }
+            const normalizedSource = normalizeSourceOption(previewOptions.source, previewOptions.startingUrl);
+            if (normalizedSource) previewOptions.source = normalizedSource;
+            const sourceEnabled = Boolean(previewOptions.source || previewOptions.watchSource);
+            const normalizedSourceFormat = normalizeSourceFormatOption({
+                sourceFormat: previewOptions.sourceFormat,
+                logFormat: previewOptions.logFormat,
+                sourceEnabled
+            });
+            previewOptions.sourceFormat = normalizedSourceFormat;
+            if (sourceEnabled && normalizedSourceFormat) process.env.EXTENSION_SOURCE_FORMAT = normalizedSourceFormat;
+            previewOptions.sourceRedact = normalizeSourceRedactOption(previewOptions.sourceRedact, normalizedSourceFormat);
+            previewOptions.sourceMeta = normalizeSourceMetaOption(previewOptions.sourceMeta, sourceEnabled);
+            previewOptions.sourceProbe = normalizeSourceProbeOption(previewOptions.sourceProbe);
+            previewOptions.sourceTree = normalizeSourceTreeOption(previewOptions.sourceTree, sourceEnabled);
+            previewOptions.sourceConsole = normalizeSourceConsoleOption(previewOptions.sourceConsole, sourceEnabled);
+            previewOptions.sourceDom = normalizeSourceDomOption(previewOptions.sourceDom, previewOptions.watchSource);
+            previewOptions.sourceMaxBytes = normalizeSourceMaxBytesOption(previewOptions.sourceMaxBytes);
+            previewOptions.sourceIncludeShadow = normalizeSourceIncludeShadowOption(previewOptions.sourceIncludeShadow, sourceEnabled);
+            previewOptions.sourceDiff = normalizeSourceDiffOption(previewOptions.sourceDiff, previewOptions.watchSource);
             const { extensionPreview } = preview_require('extension-develop');
             for (const vendor of list){
                 const vendorStart = Date.now();
@@ -918,8 +1222,20 @@ Cross-Browser Compatibility
                     startingUrl: previewOptions.startingUrl,
                     port: previewOptions.port,
                     noRunner: false === previewOptions.runner,
+                    extensions: parseExtensionsList(previewOptions.extensions),
                     source: 'string' == typeof previewOptions.source ? previewOptions.source : previewOptions.source,
                     watchSource: previewOptions.watchSource,
+                    sourceFormat: previewOptions.sourceFormat,
+                    sourceSummary: previewOptions.sourceSummary,
+                    sourceMeta: previewOptions.sourceMeta,
+                    sourceProbe: previewOptions.sourceProbe,
+                    sourceTree: previewOptions.sourceTree,
+                    sourceConsole: previewOptions.sourceConsole,
+                    sourceDom: previewOptions.sourceDom,
+                    sourceMaxBytes: previewOptions.sourceMaxBytes,
+                    sourceRedact: previewOptions.sourceRedact,
+                    sourceIncludeShadow: previewOptions.sourceIncludeShadow,
+                    sourceDiff: previewOptions.sourceDiff,
                     logLevel: logsOption || previewOptions.logLevel || 'off',
                     logContexts,
                     logFormat: previewOptions.logFormat || 'pretty',
@@ -943,7 +1259,7 @@ Cross-Browser Compatibility
         });
     }
     function registerBuildCommand(program, telemetry) {
-        program.command('build').arguments('[project-name]').usage('build [path-to-remote-extension] [options]').description(commandDescriptions.build).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 `false`').option('--zip [boolean]', 'whether or not to compress the extension into a ZIP file. Defaults to `false`').option('--zip-source [boolean]', 'whether or not to include the source files in the ZIP file. Defaults to `false`').option('--zip-filename <string>', 'specify the name of the ZIP file. Defaults to the extension name and version').option('--silent [boolean]', 'whether or not to open the browser automatically. Defaults to `false`').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', ...buildOptions }) {
+        program.command('build').arguments('[project-name]').usage('build [path-to-remote-extension] [options]').description(commandDescriptions.build).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 `false`').option('--zip [boolean]', 'whether or not to compress the extension into a ZIP file. Defaults to `false`').option('--zip-source [boolean]', 'whether or not to include the source files in the ZIP file. Defaults to `false`').option('--zip-filename <string>', 'specify the name of the ZIP file. Defaults to the extension name and version').option('--silent [boolean]', 'whether or not to open the browser automatically. Defaults to `false`').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('--author, --author-mode', '[internal] enable maintainer diagnostics (does not affect user runtime logs)').action(async function(pathOrRemoteUrl, { browser = 'chromium', ...buildOptions }) {
             if (buildOptions.author || buildOptions['authorMode']) {
                 process.env.EXTENSION_AUTHOR_MODE = 'true';
                 if (!process.env.EXTENSION_VERBOSE) process.env.EXTENSION_VERBOSE = '1';
@@ -974,7 +1290,8 @@ Cross-Browser Compatibility
                     zipSource: buildOptions.zipSource,
                     zipFilename: buildOptions.zipFilename,
                     silent: buildOptions.silent,
-                    install: buildOptions.install
+                    install: buildOptions.install,
+                    extensions: parseExtensionsList(buildOptions.extensions)
                 });
                 telemetry.track('cli_build_summary', {
                     ...buildSummary
@@ -1003,19 +1320,35 @@ Cross-Browser Compatibility
         }
     }
     process.env.EXTENSION_DEVELOP_VERSION = developVersion();
+    function resolveAIHelpFormatFromArgv(argv) {
+        const equalArg = argv.find((arg)=>arg.startsWith('--format='));
+        if (equalArg) return equalArg.slice(9);
+        const formatIndex = argv.indexOf('--format');
+        if (formatIndex >= 0) return argv[formatIndex + 1] || '';
+        return 'pretty';
+    }
     check_updates_checkUpdates().then((updateMessage)=>{
         if (!updateMessage) return;
         if ('true' === process.env.EXTENSION_CLI_BANNER_PRINTED) return void console.log(updateMessage.message);
         process.env.EXTENSION_CLI_UPDATE_SUFFIX = updateMessage.suffix;
     });
     const extensionJs = external_commander_namespaceObject.program;
-    extensionJs.name(cliPackageJson.name).description(cliPackageJson.description).version(cliPackageJson.version).option('--no-telemetry', 'disable anonymous telemetry for this run').option('--ai-help', 'show AI-assistant oriented help and tips').addHelpText('after', programUserHelp()).showHelpAfterError(true).showSuggestionAfterError(true);
+    extensionJs.name(cliPackageJson.name).description(cliPackageJson.description).version(cliPackageJson.version).option('--no-telemetry', 'disable anonymous telemetry for this run').option('--ai-help', 'show AI-assistant oriented help and tips').option('--format <pretty|json>', 'output format for --ai-help', 'pretty').addHelpText('after', programUserHelp()).showHelpAfterError(true).showSuggestionAfterError(true);
     registerCreateCommand(extensionJs, telemetry_cli_telemetry);
     registerDevCommand(extensionJs, telemetry_cli_telemetry);
     registerStartCommand(extensionJs, telemetry_cli_telemetry);
     registerPreviewCommand(extensionJs, telemetry_cli_telemetry);
     registerBuildCommand(extensionJs, telemetry_cli_telemetry);
     extensionJs.on('option:ai-help', function() {
+        const format = resolveAIHelpFormatFromArgv(process.argv).trim().toLowerCase();
+        if ('json' === format) {
+            console.log(JSON.stringify(programAIHelpJSON(cliPackageJson.version), null, 2));
+            process.exit(0);
+        }
+        if ('pretty' !== format) {
+            console.error(invalidAIHelpFormat(format));
+            process.exit(1);
+        }
         console.log(programAIHelp());
         process.exit(0);
     });

package/dist/utils/normalize-options.d.ts

@@ -1,2 +1,22 @@
 export declare function normalizeSourceOption(source: boolean | string | undefined, startingUrl?: string): string | undefined;
+export type SourceFormat = 'pretty' | 'json' | 'ndjson';
+export type SourceRedact = 'off' | 'safe' | 'strict';
+export type SourceIncludeShadow = 'off' | 'open-only' | 'all';
+export type SourceTreeMode = 'off' | 'root-only';
+export type SourceDomMode = 'off' | 'on';
+export declare function normalizeSourceFormatOption(params: {
+    sourceFormat?: string;
+    logFormat?: string;
+    sourceEnabled?: boolean;
+}): SourceFormat | undefined;
+export declare function normalizeSourceRedactOption(sourceRedact: string | undefined, sourceFormat: SourceFormat | undefined): SourceRedact;
+export declare function normalizeSourceMaxBytesOption(value: string | number | undefined): number | undefined;
+export declare function normalizeSourceIncludeShadowOption(value: string | undefined, sourceEnabled: boolean): SourceIncludeShadow | undefined;
+export declare function normalizeSourceMetaOption(value: boolean | string | undefined, sourceEnabled: boolean): boolean | undefined;
+export declare function normalizeSourceTreeOption(value: string | undefined, sourceEnabled: boolean): SourceTreeMode | undefined;
+export declare function normalizeSourceConsoleOption(value: boolean | string | undefined, sourceEnabled: boolean): boolean | undefined;
+export declare function normalizeSourceDomOption(value: boolean | string | undefined, watchSource: boolean | undefined): boolean | undefined;
+export declare function normalizeSourceProbeOption(raw: string | string[] | undefined): string[] | undefined;
+export declare function normalizeSourceDiffOption(value: boolean | string | undefined, watchSource: boolean | undefined): boolean | undefined;
 export declare function parseLogContexts(raw: string | undefined): Array<'background' | 'content' | 'page' | 'sidebar' | 'popup' | 'options' | 'devtools'> | undefined;
+export declare function parseExtensionsList(raw: string | undefined): string[] | undefined;

package/package.json

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