extension 3.12.0 → 3.13.0

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

@@ -0,0 +1,37 @@
+import type { BrowserType } from '../browsers-types';
+export declare function isBannerPrinted(): boolean;
+type Info = {
+    extensionId?: string;
+    name?: string;
+    version?: string;
+} | null;
+type HostPort = {
+    host?: string;
+    port?: number | string;
+};
+export declare function printDevBannerOnce(opts: {
+    browser: BrowserType;
+    outPath: string;
+    hostPort?: HostPort;
+    getInfo: () => Promise<Info>;
+    fallback?: {
+        name?: string;
+        version?: string;
+        extensionId?: string;
+    };
+    browserVersionLine?: string;
+}): Promise<boolean>;
+export declare function printProdBannerOnce(opts: {
+    browser: BrowserType;
+    outPath: string;
+    browserVersionLine?: string;
+    runtime?: {
+        extensionId?: string;
+        name?: string;
+        version?: string;
+    };
+    includeExtensionId?: boolean;
+    readyPath?: string;
+    includeRunId?: boolean;
+}): Promise<boolean>;
+export {};

package/dist/browser/browsers-lib/constants.d.ts

@@ -0,0 +1,2 @@
+export declare const DEFAULT_DEBUG_PORT = 9222;
+export declare const PORT_OFFSET = 100;

package/dist/browser/browsers-lib/content-script-contracts.d.ts

@@ -0,0 +1,2 @@
+export declare const CANONICAL_CONTENT_SCRIPT_ENTRY_PREFIX = "content_scripts/content-";
+export declare function getCanonicalContentScriptEntryName(index: number): string;

package/dist/browser/browsers-lib/content-script-targets.d.ts

@@ -0,0 +1,33 @@
+import type { CompilationLike } from '../browsers-types';
+export type ContentScriptTargetRule = {
+    index: number;
+    world: 'extension' | 'main';
+    matches: string[];
+    excludeMatches: string[];
+    includeGlobs: string[];
+    excludeGlobs: string[];
+};
+type ManifestLike = {
+    content_scripts?: Array<{
+        world?: string;
+        matches?: string[];
+        exclude_matches?: string[];
+        include_globs?: string[];
+        exclude_globs?: string[];
+    }>;
+};
+export declare function isContentScriptEntryName(entryName: string): boolean;
+export declare function isCanonicalContentScriptAsset(assetName: string): boolean;
+/**
+ * Resolves the on-disk file for a canonical content bundle. In development the
+ * emitted name may include a fullhash (e.g. content_scripts/content-0.a1b2c3d4.js).
+ */
+export declare function resolveEmittedContentScriptFile(extensionOutPath: string, index: number, ext: 'js' | 'css'): string | null;
+export declare function getChangedContentScriptEntryNames(modifiedFilePaths: string[], dependencyPathsByEntry: Map<string, Set<string>>): string[];
+export declare function normalizeModuleResourcePath(resourcePath: unknown): string | undefined;
+export declare function readContentScriptRules(compilation: CompilationLike, extensionRoot?: string): ContentScriptTargetRule[];
+export declare function getContentScriptRulesFromManifest(manifest: ManifestLike): ContentScriptTargetRule[];
+export declare function selectContentScriptRules(rules: ContentScriptTargetRule[], entryNames: string[]): ContentScriptTargetRule[];
+export declare function urlMatchesContentScriptRule(rawUrl: string, rule: ContentScriptTargetRule): boolean;
+export declare function urlMatchesAnyContentScriptRule(rawUrl: string, rules: ContentScriptTargetRule[]): boolean;
+export {};

package/dist/browser/browsers-lib/html-merge.d.ts

@@ -0,0 +1 @@
+export declare function mergeShadowIntoDocument(mainHTML: string, shadowContent: string): string;

package/dist/browser/browsers-lib/instance-registry.d.ts

@@ -0,0 +1,8 @@
+export type InstanceRecord = {
+    cdpPort?: number;
+    rdpPort?: number;
+};
+export declare function setInstancePorts(instanceId: string | undefined, ports: InstanceRecord): void;
+export declare function getInstancePorts(instanceId: string | undefined): InstanceRecord | undefined;
+export declare function getLastCDPPort(): number | undefined;
+export declare function getLastRDPPort(): number | undefined;

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

@@ -0,0 +1,208 @@
+import type { BrowserType } from '../browsers-types';
+type Browser = BrowserType;
+type Mode = 'development' | 'production' | 'none';
+export declare function capitalizedBrowserName(browser: Browser): string;
+export declare function creatingUserProfile(profilePath: string): string;
+export declare function browserInstanceAlreadyRunning(browser: Browser): string;
+export declare function browserInstanceExited(browser: Browser): string;
+export declare function stdoutData(browser: Browser, mode: Mode): string;
+export declare function cdpClientAttachedToTarget(sessionId: string, targetType: string): string;
+export declare function cdpPendingRejectFailed(message: string): string;
+export declare function cdpFailedToHandleMessage(message: string): string;
+export declare function cdpAutoAttachSetupFailed(message: string): string;
+export declare function cdpProtocolEventHandlerError(message: string): string;
+export declare function cdpFallbackManifestReadFailed(message: string): string;
+export declare function bannerEventHandlerFailed(message: string): string;
+export declare function bestEffortBannerPrintFailed(message: string): string;
+export declare function firefoxUnifiedLoggingFailed(message: string): string;
+export declare function firefoxRdpReloadCapabilitySummary(mode: 'native' | 'reinstall'): string;
+export declare function rdpAddTabFailed(message: string): string;
+export declare function skippingBrowserLaunchDueToCompileErrors(): string;
+export declare function manifestPreflightSummary(errorCount: number): string;
+export declare function browserNotInstalledError(browser: Browser, browserBinaryLocation: string): string;
+export declare function installDifferentBrowserHint(): string;
+export declare function injectingAddOnsError(browser: Browser, error: unknown): string;
+export declare function firefoxServiceWorkerError(browser: Browser): string;
+export declare function browserLaunchError(browser: Browser, error: unknown): string;
+export declare function enhancedProcessManagementStarting(browser: Browser): string;
+export declare function enhancedProcessManagementCleanup(browser: Browser): string;
+export declare function enhancedProcessManagementTerminating(browser: Browser): string;
+export declare function enhancedProcessManagementForceKill(browser: Browser): string;
+export declare function enhancedProcessManagementCleanupError(browser: Browser, error: unknown): string;
+export declare function enhancedProcessManagementInstanceCleanup(browser: Browser): string;
+export declare function enhancedProcessManagementInstanceCleanupComplete(browser: Browser): string;
+export declare function enhancedProcessManagementSignalHandling(browser: Browser): string;
+export declare function enhancedProcessManagementUncaughtException(browser: Browser, error: unknown): string;
+export declare function enhancedProcessManagementUnhandledRejection(browser: Browser, reason: unknown): string;
+export declare function generalBrowserError(browser: Browser, error: unknown): string;
+export declare function errorConnectingToBrowser(browser: Browser): string;
+export declare function addonInstallError(browser: Browser, message: string): string;
+export declare function pathIsNotDirectoryError(browser: Browser, profilePath: string): string;
+export declare function messagingClientClosedError(browser: Browser): string;
+export declare function requestWithoutTargetActorError(browser: Browser, requestType: string): string;
+export declare function connectionClosedError(browser: Browser): string;
+export declare function targetActorHasActiveRequestError(browser: Browser, targetActor: string): string;
+export declare function parsingPacketError(browser: Browser, error: unknown): string;
+export declare function messageWithoutSenderError(browser: Browser, message: {
+    from?: string;
+    type?: string;
+    error?: unknown;
+}): string;
+export declare function unexpectedMessageReceivedError(browser: Browser, message: string): string;
+export declare function isUsingStartingUrl(browser: Browser, value: unknown): string;
+export declare function profileFallbackWarning(browser: Browser, reason: string): string;
+export declare function pathPermissionError(browser: Browser, profilePath: string): string;
+export declare function profileCreationError(browser: Browser, error: unknown): string;
+export declare function chromeProcessExited(code: number): string;
+export declare function chromeProcessError(error: unknown): string;
+export declare function chromeFailedToSpawn(error: unknown): string;
+export declare function chromeInitializingEnhancedReload(): string;
+export declare function wslDockerDesktopRunnerDisabled(): string;
+export declare function locatingBrowser(browser: Browser): string;
+export declare function devChromeProfilePath(path: string): string;
+export declare function usingChromiumRunner(browser: Browser): string;
+export declare function usingFirefoxRunner(browser: Browser): string;
+export declare function chromiumDryRunNotLaunching(): string;
+export declare function chromiumDryRunBinary(path: string): string;
+export declare function chromiumDryRunFlags(flags: string): string;
+export declare function prettyPuppeteerInstallGuidance(browser: Browser, rawGuidance: string, cacheDir: string): string;
+export declare function firefoxLaunchCalled(): string;
+export declare function firefoxDetectionFailed(error: unknown): string;
+export declare function firefoxBinaryArgsExtracted(args: string): string;
+export declare function firefoxNoBinaryArgsFound(): string;
+export declare function firefoxFailedToExtractProfilePath(): string;
+export declare function firefoxFailedToStart(error: unknown): string;
+export declare function firefoxDryRunNotLaunching(): string;
+export declare function firefoxDryRunBinary(path: string): string;
+export declare function firefoxDryRunConfig(cfg: string): string;
+export declare function sourceInspectorInitialized(): string;
+export declare function sourceInspectorInitializationFailed(error: string): string;
+export declare function sourceInspectorChromeDebuggingRequired(port: number): string;
+export declare function sourceInspectorFirefoxDebuggingRequired(port: number): string;
+export declare function sourceInspectorWaitingForFirefox(): string;
+export declare function firefoxRemoteDebuggingReady(): string;
+export declare function sourceInspectorFirefoxNotReadyYet(retries: number, maxRetries: number): string;
+export declare function sourceInspectorWaitingForChrome(): string;
+export declare function chromeRemoteDebuggingReady(): string;
+export declare function sourceInspectorChromeNotReadyYet(retries: number, maxRetries: number): string;
+export declare function sourceInspectorOpeningUrl(url: string): string;
+export declare function sourceInspectorWaitingForPageLoad(): string;
+export declare function sourceInspectorCreatingTarget(): string;
+export declare function sourceInspectorFindingExistingTarget(): string;
+export declare function sourceInspectorUsingExistingTarget(targetId: string): string;
+export declare function sourceInspectorTargetCreated(targetId: string): string;
+export declare function sourceInspectorAttachingToTarget(): string;
+export declare function sourceInspectorAttachedToTarget(sessionId: string): string;
+export declare function sourceInspectorExtractingHTML(): string;
+export declare function sourceInspectorHTMLExtractionComplete(): string;
+export declare function sourceInspectorInspectionFailed(error: string): string;
+export declare function sourceInspectorStartingWatchMode(): string;
+export declare function sourceInspectorWatchModeActive(): string;
+export declare function sourceInspectorWatchModeStopped(): string;
+export declare function sourceInspectorCDPConnectionMaintained(): string;
+export declare function sourceInspectorNoActiveSession(): string;
+export declare function sourceInspectorReExtractingHTML(): string;
+export declare function sourceInspectorAttemptingReconnection(): string;
+export declare function sourceInspectorCannotReconnect(): string;
+export declare function sourceInspectorReconnectingToTarget(): string;
+export declare function sourceInspectorReconnectedToTarget(sessionId: string): string;
+export declare function sourceInspectorReconnectionFailed(error: string): string;
+export declare function sourceInspectorEnsuringNavigation(): string;
+export declare function sourceInspectorEnablingPageDomain(): string;
+export declare function sourceInspectorWaitingForContentScripts(): string;
+export declare function sourceInspectorWaitingForContentScriptReinjection(): string;
+export declare function sourceInspectorFileChanged(): string;
+export declare function sourceInspectorHTMLUpdateFailed(error: string): string;
+export declare function sourceInspectorCleanupComplete(): string;
+export declare function sourceInspectorCleanupError(error: string): string;
+export declare function sourceInspectorNotInitialized(): string;
+export declare function sourceInspectorInvalidWebSocketServer(): string;
+export declare function sourceInspectorUrlRequired(): string;
+export declare function sourceInspectorWillInspect(url: string): string;
+export declare function sourceInspectorSetupFailed(error: string): string;
+export declare function sourceInspectorHTMLOutputHeader(): string;
+export declare function sourceInspectorHTMLOutputTitle(title: string): string;
+export declare function sourceInspectorHTMLOutputFooter(): string;
+export declare function sourceInspectorClientNotInitialized(): string;
+export declare function sourceInspectorNoTabActorAvailable(): string;
+export declare function sourceInspectorNoTabTargetFound(): string;
+export declare function sourceInspectorHtmlExtractFailed(): string;
+export declare function cdpClientFoundTargets(count: number): string;
+export declare function cdpClientTargetWebSocketUrlStored(): string;
+export declare function cdpClientConnected(host: string, port: number): string;
+export declare function cdpClientConnectionError(error: string): string;
+export declare function cdpClientBrowserConnectionEstablished(): string;
+export declare function cdpClientConnectionClosed(): string;
+export declare function cdpClientMessageParseError(error: string): string;
+export declare function cdpClientPageLoadEventFired(): string;
+export declare function cdpClientLoadEventTimeout(): string;
+export declare function cdpClientTestingEvaluation(): string;
+export declare function cdpClientShadowDOMContentFound(found: boolean): string;
+export declare function cdpClientShadowDOMContentLength(length: number): string;
+export declare function cdpClientProcessingShadowDOM(): string;
+export declare function cdpClientFinalHTMLWithShadowDOMLength(length: number): string;
+export declare function cdpClientReturningMainHTML(): string;
+export declare function cdpClientExtensionReloadFailed(extensionId: string, error: string): string;
+export declare function cdpClientExtensionUnloadFailed(extensionId: string, error: string): string;
+export declare function cdpClientExtensionInfoFailed(extensionId: string, error: string): string;
+export declare function cdpClientExtensionLoadFailed(path: string, error: string): string;
+export declare function firefoxRdpClientFoundTargets(count: number): string;
+export declare function firefoxRdpClientUsingTarget(title: string, url: string): string;
+export declare function firefoxRdpClientConnected(host: string, port: number): string;
+export declare function firefoxRdpClientConnectionError(error: string): string;
+export declare function firefoxRdpClientConnectionClosed(): string;
+export declare function firefoxRdpClientNoSuitableTargets(): string;
+export declare function firefoxRdpClientPageLoadEventFired(): string;
+export declare function firefoxRdpClientLoadEventTimeout(): string;
+export declare function firefoxRdpClientTestingEvaluation(): string;
+export declare function firefoxRdpClientDocumentTitle(title: string): string;
+export declare function firefoxRdpClientFailedToGetMainHTML(): string;
+export declare function firefoxRdpClientFinalHTMLLength(length: number): string;
+export interface DevManifestInfo {
+    name?: string;
+    version?: string;
+    hostPermissions?: string[];
+    permissions?: string[];
+}
+export interface DevClientManagementInfo {
+    name?: string;
+    version?: string;
+}
+export interface DevClientMessage {
+    data?: {
+        id?: string;
+        management?: DevClientManagementInfo;
+    };
+}
+export declare function runningInDevelopment(manifest: DevManifestInfo, browser: BrowserType, message: DevClientMessage, browserVersionLine?: string, updateSuffix?: string, opts?: {
+    includeExtensionId?: boolean;
+    runLabel?: string;
+}): string;
+export declare function emptyLine(): string;
+export declare function separatorLine(): string;
+export declare function devChromiumDebugPort(finalPort: number, requestedPort: number): string;
+export declare function devFirefoxDebugPort(finalPort: number, requestedPort: number): string;
+export declare function devFirefoxProfilePath(profilePath: string): string;
+export declare function unifiedLogLine(head: string, message: string): string;
+export declare function devHtmlSampleRetry(sample: string): string;
+export declare function devHtmlSampleLate(sample: string): string;
+export declare function devSvelteProbeDetected(probe: string): string;
+export declare function cdpUnifiedExtensionLog(ts: string, payload: unknown): string;
+export declare function firefoxInspectSourceNonFatal(message: string): string;
+export declare function browserPluginFailedToLoad(browser: string, error: unknown): string;
+export declare function unsupportedBrowser(browser: string): string;
+export declare function browserRunnerError(body: string): string;
+export declare function requireChromiumBinaryForChromiumBased(): string;
+export declare function requireGeckoBinaryForGeckoBased(): string;
+export declare function invalidChromiumBinaryPath(p: string): string;
+export declare function invalidGeckoBinaryPath(p: string): string;
+export declare function firefoxDetectedFlatpak(): string;
+export declare function firefoxDetectedSnap(): string;
+export declare function firefoxDetectedTraditional(path: string): string;
+export declare function firefoxDetectedCustom(path: string): string;
+export declare function firefoxUsingFlatpakWithSandbox(): string;
+export declare function firefoxVersion(version: string): string;
+export declare function rdpInvalidRequestPayload(): string;
+export declare function chromiumDeveloperModeGuidance(browser?: BrowserType): string;
+export declare function chromiumHardReloadFailed(browser?: BrowserType): string;
+export {};

package/dist/browser/browsers-lib/output-binaries-resolver.d.ts

@@ -0,0 +1,5 @@
+import type { CompilationLike } from '../browsers-types';
+export declare function getCompilationOutputPath(compilation: CompilationLike): string;
+export declare function computeBinariesBaseDir(compilation: CompilationLike): string;
+export declare function managedBrowserCacheEnv(cacheRoot: string, browser: 'chrome' | 'chromium' | 'firefox' | 'edge' | 'chromium-based' | 'gecko-based' | 'firefox-based'): Record<string, string>;
+export declare function resolveFromBinaries(compilation: CompilationLike, browser: 'chrome' | 'chromium' | 'firefox' | 'edge'): string | null;

package/dist/browser/browsers-lib/ready-message.d.ts

@@ -0,0 +1 @@
+export declare function ready(mode: 'development' | 'production', browser: string): string;

package/dist/browser/browsers-lib/runtime-options.d.ts

@@ -0,0 +1,12 @@
+import type { BrowserConfig } from '../browsers-types';
+import type { PluginInterface } from '../browsers-types';
+export declare const sharedBrowserRuntimeOptionKeys: readonly ["extension", "browser", "noOpen", "browserFlags", "excludeBrowserFlags", "profile", "preferences", "startingUrl", "instanceId", "port", "source", "watchSource", "sourceFormat", "sourceSummary", "sourceMeta", "sourceProbe", "sourceTree", "sourceConsole", "sourceDom", "sourceMaxBytes", "sourceRedact", "sourceIncludeShadow", "sourceDiff", "dryRun", "logLevel", "logContexts", "logFormat", "logTimestamps", "logColor", "logUrl", "logTab"];
+export type SharedBrowserRuntimeOptions = Pick<PluginInterface, (typeof sharedBrowserRuntimeOptionKeys)[number]>;
+export declare function pickSharedBrowserRuntimeOptions(options: SharedBrowserRuntimeOptions): SharedBrowserRuntimeOptions;
+export type BrowserLaunchRequestSource = Pick<PluginInterface, 'browser' | 'browserFlags' | 'excludeBrowserFlags' | 'profile' | 'preferences' | 'startingUrl' | 'port'>;
+export type BrowserLaunchRequest = Pick<PluginInterface & BrowserConfig, 'browser' | 'browserFlags' | 'excludeBrowserFlags' | 'profile' | 'preferences' | 'startingUrl' | 'port'> & {
+    mode: 'development' | 'production' | 'none';
+};
+export declare function buildBrowserLaunchRequest<T extends object = {}>(options: BrowserLaunchRequestSource, mode: 'development' | 'production' | 'none', extras?: T): BrowserLaunchRequest & T;
+export declare function toExtensionLoadList(extension: PluginInterface['extension']): string[];
+export declare function publishUserExtensionRoot(extension: PluginInterface['extension'], setExtensionRoot?: (root?: string) => void): void;

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

@@ -0,0 +1,11 @@
+export declare function shortInstanceId(instanceId?: string): string;
+export declare function instanceOffsetFromId(instanceId?: string): number;
+export declare function deriveDebugPortWithInstance(optionPort?: number | string, instanceId?: string): number;
+export declare function calculateDebugPort(portFromConfig?: number | string, devServerPort?: number, defaultPort?: number): number;
+export declare function filterBrowserFlags(defaultFlags: string[], excludeFlags?: string[]): string[];
+export declare function findAvailablePortNear(startPort: number, maxAttempts?: number, host?: string): Promise<number>;
+export declare function prepareChromiumProfileForLaunch(profilePath: string): {
+    removedArtifacts: string[];
+};
+export declare function markManagedEphemeralProfile(profilePath: string): void;
+export declare function cleanupOldTempProfiles(baseDir: string, excludeBasename: string | undefined, maxAgeHours?: number): void;

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

@@ -0,0 +1,270 @@
+export type BrowserType = 'chrome' | 'edge' | 'firefox' | 'chromium' | 'chromium-based' | 'gecko-based' | 'firefox-based';
+/**
+ * Lightweight stand-in for rspack's Compilation used by browser-launching code.
+ * Only the properties actually read by launch/reload/inspection flows are declared.
+ */
+export interface CompilationLike {
+    options: {
+        mode?: string;
+        output?: {
+            path?: string;
+        };
+        context?: string;
+    };
+    outputOptions?: {
+        path?: string;
+    };
+    getAsset?: (name: string) => {
+        source: {
+            source: () => string;
+        };
+    } | undefined;
+}
+/**
+ * Minimal logger interface mirroring the shape returned by
+ * rspack's `compiler.getInfrastructureLogger()`.
+ */
+export interface BrowserLogger {
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+    debug: (...args: unknown[]) => void;
+}
+/**
+ * Stand-in for rspack's BrowserConfig — the subset used by browser-config helpers.
+ */
+export interface BrowserConfig {
+    extensionPath: string;
+    profilePath: string | false;
+    preferences: Record<string, unknown>;
+    browserFlags: string[];
+    startingUrl: string | undefined;
+}
+/**
+ * List of default browser flags used by extension.js.
+ * These can be excluded using the `excludeBrowserFlags` option.
+ *
+ * Each flag disables or modifies a specific browser feature for a more controlled development environment.
+ */
+export type DefaultBrowserFlags = '--no-first-run' | '--disable-client-side-phishing-detection' | '--disable-component-extensions-with-background-pages' | '--disable-default-apps' | '--disable-features=InterestFeedContentSuggestions' | '--disable-features=Translate' | '--hide-scrollbars' | '--mute-audio' | '--no-default-browser-check' | '--ash-no-nudges' | '--disable-search-engine-choice-screen' | '--disable-features=MediaRoute' | '--use-mock-keychain' | '--disable-background-networking' | '--disable-breakpad' | '--disable-component-update' | '--disable-domain-reliability' | '--disable-features=AutofillServerCommunicatio' | '--disable-features=CertificateTransparencyComponentUpdate' | '--disable-sync' | '--disable-features=OptimizationHints' | '--disable-features=DialMediaRouteProvider' | '--no-pings' | '--enable-features=SidePanelUpdates';
+/**
+ * Options for the browser plugin.
+ */
+export interface PluginOptions {
+    /**
+     * Do not open the browser automatically after launch.
+     * @default false
+     */
+    noOpen?: boolean;
+    /**
+     * Additional browser flags to pass to the browser process.
+     * Example: ['--disable-extensions', '--disable-gpu']
+     */
+    browserFlags?: string[];
+    /**
+     * Array of browser flags to exclude from the default set.
+     * Example: ['--hide-scrollbars', '--mute-audio']
+     */
+    excludeBrowserFlags?: Array<DefaultBrowserFlags | string>;
+    /**
+     * Path to the browser profile directory, or false for a temporary profile.
+     * Example: 'dist/extension' or false
+     */
+    profile?: string | false;
+    /**
+     * Use a persistent managed profile for development.
+     * Defaults to false (ephemeral temp profiles are used).
+     */
+    persistProfile?: boolean;
+    /**
+     * Browser preferences object.
+     * Example: { extensions: ['dist/extension', 'dist/extension2'] }
+     */
+    preferences?: Record<string, unknown>;
+    /**
+     * Firefox only: persist changes made to the profile directory.
+     */
+    keepProfileChanges?: boolean;
+    /**
+     * Firefox only: copy an existing profile before launching.
+     */
+    copyFromProfile?: string;
+    /**
+     * URL to open when the browser starts.
+     * Example: 'http://localhost:3000'
+     */
+    startingUrl?: string;
+    /**
+     * Enable the browser console.
+     * @default false
+     */
+    browserConsole?: boolean;
+    /**
+     * Open DevTools automatically.
+     * @default false
+     */
+    devtools?: boolean;
+    /**
+     * Path to the Chromium binary.
+     * Example: '/path/to/chromium'
+     */
+    chromiumBinary?: string;
+    /**
+     * Path to the Gecko (Firefox) binary.
+     * Example: '/path/to/gecko'
+     */
+    geckoBinary?: string;
+}
+/**
+ * Main interface for the browser plugin.
+ */
+export interface PluginInterface extends PluginOptions {
+    /**
+     * Browser type to launch.
+     * @default 'chrome'
+     * @see DevOptions['browser']
+     * Example: 'chrome' | 'edge' | 'firefox'
+     */
+    browser: BrowserType;
+    /**
+     * Path(s) to the extension(s) to load.
+     * Example: 'dist/extension' or ['dist/extension', 'dist/extension2']
+     */
+    extension: string | string[];
+    /**
+     * Port to use for the extension or debugging.
+     * Example: 12345 or '12345'
+     */
+    port?: string | number;
+    /**
+     * Internal auto-generated instance ID (not user-configurable).
+     * Example: '1234567890'
+     */
+    instanceId?: string;
+    /**
+     * Path to source files for inspection.
+     * Example: 'dist/extension'
+     */
+    source?: string;
+    /**
+     * Whether to watch the source directory for changes.
+     * @default false
+     */
+    watchSource?: boolean;
+    /**
+     * Output format for source inspection HTML.
+     */
+    sourceFormat?: 'pretty' | 'json' | 'ndjson';
+    /**
+     * Output a compact summary instead of full HTML.
+     * @default false
+     */
+    sourceSummary?: boolean;
+    /**
+     * Output page metadata (readyState, viewport, frames).
+     */
+    sourceMeta?: boolean;
+    /**
+     * CSS selectors to probe for debugging.
+     */
+    sourceProbe?: string[];
+    /**
+     * Output a compact extension root tree.
+     */
+    sourceTree?: 'off' | 'root-only';
+    /**
+     * Output console summary (best-effort).
+     */
+    sourceConsole?: boolean;
+    /**
+     * Output DOM snapshots and diffs.
+     */
+    sourceDom?: boolean;
+    /**
+     * Maximum HTML bytes to print (0 disables truncation).
+     */
+    sourceMaxBytes?: number;
+    /**
+     * Redaction mode for HTML output.
+     */
+    sourceRedact?: 'off' | 'safe' | 'strict';
+    /**
+     * Control Shadow DOM inclusion when extracting HTML.
+     */
+    sourceIncludeShadow?: 'off' | 'open-only' | 'all';
+    /**
+     * Include diff metadata on watch updates.
+     */
+    sourceDiff?: boolean;
+    /**
+     * Log level for unified logger (Chromium CDP logging).
+     * One of: 'off', 'error', 'warn', 'info', 'debug', 'trace', 'all'
+     */
+    logLevel?: 'off' | 'error' | 'warn' | 'info' | 'debug' | 'trace' | 'all';
+    /**
+     * Log contexts to enable.
+     * Example: ['background', 'content', 'page']
+     */
+    logContexts?: Array<'background' | 'content' | 'page' | 'sidebar' | 'popup' | 'options' | 'devtools'>;
+    /**
+     * Log output format.
+     * One of: 'pretty', 'json'
+     */
+    logFormat?: 'pretty' | 'json' | 'ndjson';
+    /**
+     * Include timestamps in logs.
+     * @default true
+     */
+    logTimestamps?: boolean;
+    /**
+     * Enable colored log output.
+     * @default false
+     */
+    logColor?: boolean;
+    /**
+     * URL to send logs to.
+     * Example: 'http://localhost:3000'
+     */
+    logUrl?: string;
+    /**
+     * Tab ID or index for logging context.
+     */
+    logTab?: number | string;
+    /**
+     * Perform a dry run without launching the browser.
+     * @default false
+     */
+    dryRun?: boolean;
+}
+/**
+ * Runtime state shared with post-launch setup helpers (CDP/RDP).
+ * Extends the main PluginInterface with transient fields used during runtime.
+ */
+export interface PluginRuntime extends PluginInterface {
+}
+export type LogLevel = 'off' | 'error' | 'warn' | 'info' | 'debug' | 'trace' | 'all';
+export type LogContext = 'background' | 'content' | 'page' | 'sidebar' | 'popup' | 'options' | 'devtools';
+export type LogFormat = 'pretty' | 'json' | 'ndjson';
+/**
+ * Unified controller interface used by post-launch logging flows.
+ * Implemented by both CDP and RDP controllers.
+ */
+export interface Controller {
+    enableUnifiedLogging: (opts: {
+        level?: string;
+        contexts?: string[] | undefined;
+        urlFilter?: string | undefined;
+        tabFilter?: number | string | undefined;
+        format?: 'pretty' | 'json' | 'ndjson';
+        timestamps?: boolean;
+        color?: boolean;
+    }) => Promise<void>;
+    /**
+     * Optional event subscription hook for protocol events (CDP/RDP).
+     * Present in Chromium CDP flows; Firefox may omit it.
+     */
+    onProtocolEvent?: (cb: (evt: {
+        method?: string;
+        params?: unknown;
+    }) => void) => void;
+}