extension 3.17.0 → 3.18.1

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

@@ -77,6 +77,23 @@ 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 safariBuildCalled(): string;
+export declare function safariRequiresMacOS(platform: string): string;
+export declare function safariXcodeRequired(developerDir: string | null): string;
+export declare function safariToolchainMissing(tool: string): string;
+export declare function safariConverting(extensionDir: string): string;
+export declare function safariConverted(projectDir: string): string;
+export declare function safariBuilding(scheme: string): string;
+export declare function safariBuilt(appPath: string): string;
+export declare function safariOpening(target: string): string;
+export declare function safariFailed(error: unknown): string;
+export declare function safariDryRunNotBuilding(): string;
+export declare function safariDryRunConverter(cmd: string): string;
+export declare function safariDryRunXcodebuild(cmd: string): string;
+export declare function safariNextSteps(appName: string): string;
+export declare function safariRegistered(appName: string): string;
+export declare function safariNotYetRegistered(appName: string): string;
+export declare function safariRebuilt(appName: string): string;
 export declare function sourceInspectorInitialized(): string;
 export declare function sourceInspectorInitializationFailed(error: string): string;
 export declare function sourceInspectorChromeDebuggingRequired(port: number): string;

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

@@ -1,5 +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 managedBrowserCacheEnv(cacheRoot: string, browser: 'chrome' | 'chromium' | 'firefox' | 'edge' | 'chromium-based' | 'gecko-based' | 'firefox-based' | 'safari' | 'webkit-based'): Record<string, string>;
 export declare function resolveFromBinaries(compilation: CompilationLike, browser: 'chrome' | 'chromium' | 'firefox' | 'edge'): string | null;

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

@@ -8,4 +8,5 @@ export declare function prepareChromiumProfileForLaunch(profilePath: string): {
     removedArtifacts: string[];
 };
 export declare function markManagedEphemeralProfile(profilePath: string): void;
+export declare function removeManagedEphemeralProfile(profilePath: string | undefined | null): void;
 export declare function cleanupOldTempProfiles(baseDir: string, excludeBasename: string | undefined, maxAgeHours?: number): void;

package/dist/extension/browsers/browsers-lib/wsl-support.d.ts

@@ -0,0 +1,3 @@
+export declare function isWslEnv(): boolean;
+export declare function hasGuiDisplay(): boolean;
+export declare function normalizeBinaryPathForWsl(input: string): string;

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

@@ -1,4 +1,4 @@
-export type BrowserType = 'chrome' | 'edge' | 'firefox' | 'chromium' | 'chromium-based' | 'gecko-based' | 'firefox-based';
+export type BrowserType = 'chrome' | 'edge' | 'firefox' | 'chromium' | 'chromium-based' | 'gecko-based' | 'firefox-based' | 'safari' | 'webkit-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.

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

@@ -1,3 +1,10 @@
 import { ChildProcess } from 'child_process';
 import type { BrowserType } from '../../browsers-types';
-export declare function setupProcessSignalHandlers(browser: BrowserType, child: ChildProcess, cleanupInstance: () => void): void;
+export declare function __activeChromiumInstanceCount(): number;
+export declare function __resetChromiumProcessHandlersForTest(): void;
+/**
+ * Register a Chromium instance for process-exit cleanup. Returns a disposer that
+ * unregisters the instance (call it once the child has exited). Global process
+ * listeners are installed only on the first call.
+ */
+export declare function setupProcessSignalHandlers(browser: BrowserType, child: ChildProcess, cleanupInstance: () => void): () => void;

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

@@ -1,14 +1,9 @@
 import { ChildProcess, type StdioOptions } from 'child_process';
+import { hasGuiDisplay, isWslEnv, normalizeBinaryPathForWsl } from '../../browsers-lib/wsl-support';
+export { hasGuiDisplay, isWslEnv, normalizeBinaryPathForWsl };
 type ChromiumLogger = {
     warn?: (...args: unknown[]) => void;
 };
-export declare function isWslEnv(): boolean;
-/**
- * Whether a Linux GUI display server is reachable. WSLg sets these
- * automatically when shipping its X / Wayland sockets into the distro;
- * a normal Linux desktop session also sets them. Headless WSL has neither.
- */
-export declare function hasGuiDisplay(): boolean;
 /**
  * Native Linux browser binary for use under WSL+GUI. Prefers real binaries
  * over wrapper scripts. Returns null when not in WSL, when no GUI is
@@ -21,7 +16,6 @@ export declare function resolveWslLinuxBinary(browser: string): string | null;
  * breaks `--remote-debugging-pipe`. No-op outside WSL+GUI.
  */
 export declare function preferRealChromeBinary(binary: string | null | undefined): string | null;
-export declare function normalizeBinaryPathForWsl(input: string): string;
 export declare function resolveWslWindowsBinary(browser: string): string | null;
 export declare function spawnChromiumProcess(opts: {
     binary: string;
@@ -30,4 +24,3 @@ export declare function spawnChromiumProcess(opts: {
     browser: string;
     logger?: ChromiumLogger;
 }): Promise<ChildProcess>;
-export {};

package/dist/extension/browsers/run-chromium/chromium-source-inspection/cdp-client.d.ts

@@ -57,6 +57,12 @@ export declare class CDPClient {
         awaitPromise?: boolean;
     }): Promise<unknown>;
     getPageHTML(sessionId: string, includeShadow?: 'off' | 'open-only' | 'all'): Promise<string>;
+    getClosedShadowRoots(sessionId: string, maxBytes?: number): Promise<Array<{
+        host: string;
+        type: string;
+        html: string;
+        truncated?: boolean;
+    }>>;
     closeTarget(targetId: string): Promise<void>;
     forceReloadExtension(extensionId: string): Promise<boolean>;
     getExtensionInfo(extensionId: string): Promise<{

package/dist/extension/browsers/run-chromium/chromium-source-inspection/cdp-extension-controller/logging.d.ts

@@ -1,7 +1,2 @@
-import type { Controller } from '../../chromium-types';
 import { CDPClient } from '../cdp-client';
-export declare function enableUnifiedLoggingForAllTargets(controller: Controller): Promise<void>;
-export declare function enableRuntimeForAttachedTarget(controller: {
-    enableRuntimeForSession: (sessionId: string) => Promise<void>;
-}, sessionId: string): Promise<void>;
 export declare function registerAutoEnableLogging(cdp: CDPClient, getExtensionId: () => string | null): void;

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

@@ -37,6 +37,7 @@ export declare class ChromiumSourceInspectionPlugin {
     private getPageMetadata;
     private getFrameContext;
     private getDomSnapshot;
+    private readBuildSignature;
     private getExtensionRootMeta;
     /**
      * Require structural evidence (counted roots or shadow style nodes) after the

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

@@ -6,8 +6,4 @@ export declare class FirefoxBinaryDetector {
         binary: string;
         args: string[];
     };
-    static validateFirefoxBinary(binaryPath: string): Promise<{
-        version: string;
-        path: string;
-    }>;
 }

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

@@ -1,2 +1,6 @@
 import { ChildProcess } from 'child_process';
-export declare function setupFirefoxProcessHandlers(browser: 'firefox' | 'chrome' | 'edge' | 'chromium-based', childRef: () => ChildProcess | null, cleanupInstance: () => Promise<void>): void;
+type FirefoxBrowserKind = 'firefox' | 'chrome' | 'edge' | 'chromium-based';
+export declare function __activeFirefoxInstanceCount(): number;
+export declare function __resetFirefoxProcessHandlersForTest(): void;
+export declare function setupFirefoxProcessHandlers(browser: FirefoxBrowserKind, childRef: () => ChildProcess | null, cleanupInstance: () => Promise<void>): () => void;
+export {};

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

@@ -1,11 +1,10 @@
 import { ChildProcess } from 'child_process';
+import { hasGuiDisplay, isWslEnv, normalizeBinaryPathForWsl } from '../../browsers-lib/wsl-support';
+export { hasGuiDisplay, isWslEnv, normalizeBinaryPathForWsl };
 type FirefoxLogger = {
     warn?: (...args: unknown[]) => void;
 };
-export declare function isWslEnv(): boolean;
-export declare function hasGuiDisplay(): boolean;
 export declare function resolveWslLinuxBinary(): string | null;
-export declare function normalizeBinaryPathForWsl(input: string): string;
 export declare function resolveWslWindowsBinary(): string | null;
 export declare function spawnFirefoxProcess(opts: {
     binary: string;
@@ -14,4 +13,3 @@ export declare function spawnFirefoxProcess(opts: {
     fallbackBinary?: string | null;
     logger?: FirefoxLogger;
 }): Promise<ChildProcess>;
-export {};

package/dist/extension/browsers/run-firefox/firefox-source-inspection/remote-firefox/evaluate.d.ts

@@ -14,5 +14,6 @@ export declare function resolveActorForEvaluation(client: RdpClientLike, descrip
 export declare function serializeDocument(client: RdpClientLike, actorToUse: string): Promise<string>;
 export declare function extractShadowContent(client: RdpClientLike, actorToUse: string): Promise<string>;
 export declare function mergeShadowIntoMain(mainHTML: string, shadowContent: string): string;
+export declare const GET_PAGE_HTML_WITH_SHADOW_EXPRESSION = "(() => { try { var selector = '#extension-root,[data-extension-root]:not([data-extension-root=\"extension-js-devtools\"])'; var serializeShadowRoot = function(shadowRoot, serializer) { if (!shadowRoot) return ''; var stylesheetCss = Array.from(shadowRoot.styleSheets || []).map(function(sheet) { try { return Array.from(sheet.cssRules || []).map(function(rule) { return String(rule.cssText || ''); }).join('\\n'); } catch (e) { return ''; } }).filter(Boolean).join('\\n'); var adoptedCss = Array.from(shadowRoot.adoptedStyleSheets || []).map(function(sheet) { try { return Array.from(sheet.cssRules || []).map(function(rule) { return String(rule.cssText || ''); }).join('\\n'); } catch (e) { return ''; } }).filter(Boolean).join('\\n'); var stylesheetMarkup = stylesheetCss ? '<style>' + stylesheetCss + '</style>' : ''; var adoptedMarkup = adoptedCss ? '<style>' + adoptedCss + '</style>' : ''; var childMarkup = Array.from(shadowRoot.childNodes || []).map(function(node) { try { if (node && node.nodeType === 1 && String(node.nodeName || '').toLowerCase() === 'style') { return '<style>' + String(node.textContent || '') + '</style>'; } return serializer.serializeToString(node); } catch (e) { return ''; } }).join(''); return stylesheetMarkup + adoptedMarkup + childMarkup; }; var cloned = document.documentElement.cloneNode(true); var clonedHosts = Array.from(cloned.querySelectorAll(selector)); var liveHosts = Array.from(document.querySelectorAll(selector)); if (!clonedHosts.length) { var body = cloned.querySelector('body') || cloned; var newRoot = document.createElement('div'); newRoot.id='extension-root'; body.appendChild(newRoot); clonedHosts = [newRoot]; } var s = new XMLSerializer(); for (var i = 0; i < clonedHosts.length; i++) { var host = clonedHosts[i]; var live = liveHosts[i]; var shadow = ''; try { if (live && live.shadowRoot) { shadow = serializeShadowRoot(live.shadowRoot, s); } } catch (e) {} try { host.innerHTML = shadow; } catch (e) {} } return String('<!DOCTYPE html>' + (cloned.outerHTML || document.documentElement.outerHTML)); } catch(e) { try { return String(document.documentElement.outerHTML); } catch(_) { return '' } } })()";
 export declare function getPageHTML(client: RdpClientLike, descriptorActor: string, consoleActorHint?: string): Promise<string>;
 export {};

package/dist/extension/browsers/run-safari/safari-launch/dry-run.d.ts

@@ -0,0 +1 @@
+export declare function logSafariDryRun(converterCmd: string, xcodebuildCmd: string): void;

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

@@ -0,0 +1,5 @@
+import type { BrowserLogger } from '../../browsers-types';
+import type { SafariPluginLike } from '../safari-types';
+export type SafariPipelineMode = 'full' | 'resync';
+export declare function safariPreflightError(): string | null;
+export declare function packageSafariExtension(host: SafariPluginLike, outputPath: string, logger?: BrowserLogger, mode?: SafariPipelineMode): Promise<void>;

package/dist/extension/browsers/run-safari/safari-launch/safari-config.d.ts

@@ -0,0 +1,16 @@
+import type { CompilationLike } from '../../browsers-types';
+import type { SafariBuildConfig, SafariPluginLike } from '../safari-types';
+export declare function resolveSafariBuildConfig(compilation: CompilationLike, host: SafariPluginLike): SafariBuildConfig;
+export declare function composeConverterArgs(config: SafariBuildConfig): string[];
+export declare function macOsSchemeName(config: SafariBuildConfig): string;
+export declare function xcodeProjectPath(config: SafariBuildConfig): string;
+export declare function derivedDataPath(config: SafariBuildConfig): string;
+export declare function builtAppPath(config: SafariBuildConfig): string;
+/**
+ * Arguments passed to `xcodebuild`. Local builds use ad-hoc signing (identity
+ * `-`): a Developer ID isn't required, yet the embedded `.appex` still gets a
+ * signature so `ValidateEmbeddedBinary` passes. Fully disabling signing leaves
+ * the appex unsigned and that validation step fails. Real distribution signing
+ * belongs to a separate deployment stage.
+ */
+export declare function composeXcodebuildArgs(config: SafariBuildConfig): string[];

package/dist/extension/browsers/run-safari/safari-launch/toolchain.d.ts

@@ -0,0 +1,10 @@
+export interface SafariToolchain {
+    platformOk: boolean;
+    developerDir: string | null;
+    needsFullXcode: boolean;
+    converter: string | null;
+    xcodebuild: string | null;
+    ok: boolean;
+}
+export declare function isMacOS(): boolean;
+export declare function detectSafariToolchain(): SafariToolchain;

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

@@ -0,0 +1,18 @@
+import type { PluginInterface } from '../browsers-types';
+export type SafariPluginLike = Pick<PluginInterface, 'extension' | 'noOpen' | 'instanceId' | 'dryRun'> & {
+    browser: PluginInterface['browser'];
+    safariBinary?: string;
+    appName?: string;
+    macOsOnly?: boolean;
+    forceRegenerate?: boolean;
+};
+export interface SafariBuildConfig {
+    extensionDir: string;
+    projectLocation: string;
+    appName: string;
+    bundleIdentifier: string;
+    macOsOnly: boolean;
+    language: 'swift' | 'objc';
+    open: boolean;
+    safariBinary?: string;
+}

package/dist/extension/commands/act.d.ts

@@ -0,0 +1,6 @@
+import type { Command } from 'commander';
+export declare function readRecentConsole(projectPath: string, browser: string, target: {
+    context?: string;
+    tabId?: number;
+}, limit: number): unknown[];
+export declare function registerActCommands(program: Command): void;

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

@@ -1,5 +1,6 @@
 export type WaitFormat = 'pretty' | 'json';
 export type WaitCommand = 'dev' | 'start';
+export declare const READY_CONTRACT_FRESHNESS_MS = 60000;
 export type ReadyContractPayload = {
     status?: string;
     message?: string;
@@ -33,5 +34,6 @@ export type RunWaitModeResult = {
         browser: string;
     }>;
 };
+export declare function isFreshContractPayload(payload: ReadyContractPayload): boolean;
 export declare function runWaitMode(options: RunWaitModeOptions): Promise<RunWaitModeResult>;
 export declare function runDevWaitMode(options: Omit<RunWaitModeOptions, 'command'>): Promise<RunWaitModeResult>;

package/dist/extension/commands/logs.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function registerLogsCommand(program: Command): void;

package/dist/extension/commands/publish.d.ts

@@ -0,0 +1,15 @@
+import type { Command } from 'commander';
+export interface PublishRequest {
+    url: string;
+    headers: Record<string, string>;
+    body: string;
+}
+export interface PublishInput {
+    token?: string;
+    api?: string;
+    ttl?: string | number;
+    buildSha?: string;
+}
+/** Build the HTTP request (pure, unit-testable — no network). */
+export declare function buildPublishRequest(opts: PublishInput): PublishRequest;
+export declare function registerPublishCommand(program: Command): void;

package/dist/extension/helpers/extension-develop-runtime.d.ts

@@ -7,3 +7,8 @@ export declare function loadExtensionDevelopModule<T = any>(startDir?: string):
  * `extension preview` start significantly faster.
  */
 export declare function loadExtensionDevelopPreviewModule<T = any>(startDir?: string): Promise<T>;
+/**
+ * Load only the lightweight agent-bridge entry (BridgeConsumer / readReadyContract)
+ * for the `extension logs` command. Avoids pulling in rspack like preview does.
+ */
+export declare function loadExtensionDevelopBridgeModule<T = any>(startDir?: string): Promise<T>;

package/dist/extension/helpers/messages.d.ts

@@ -13,6 +13,13 @@ 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 logs: "Prints or streams logs from every context of a running dev session";
+    readonly eval: "Evaluates an expression in a running extension context (requires --allow-eval)";
+    readonly storage: "Reads or writes chrome.storage in a running extension (requires --allow-control)";
+    readonly reload: "Reloads a running extension or tab (requires --allow-control)";
+    readonly open: "Opens an extension surface — popup, options, or sidebar (requires --allow-control)";
+    readonly inspect: "Inspects a page/content DOM via the agent bridge (CDP-free; requires --allow-control)";
+    readonly publish: "Publishes to extension.dev and prints a shareable URL (requires EXTENSION_DEV_TOKEN)";
     readonly install: "Installs a managed browser binary into Extension.js cache";
     readonly uninstall: "Removes managed browser binaries from Extension.js cache";
     readonly telemetry: "Manage anonymous telemetry consent (enable, disable, or show status)";
@@ -30,13 +37,14 @@ export declare function noURLWithoutStart(argument: string): string;
 export declare function notImplemented(argument: string): string;
 export declare function programUserHelp(): string;
 export declare function unsupportedBrowserFlag(value: string, supported: string[]): string;
+export declare function safariCommandNotSupported(command: 'dev' | 'preview' | 'start'): 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' | 'install' | 'uninstall' | 'telemetry';
+        name: 'create' | 'dev' | 'start' | 'preview' | 'build' | 'logs' | 'eval' | 'storage' | 'reload' | 'open' | 'inspect' | 'publish' | 'install' | 'uninstall' | 'telemetry';
         summary: string;
         supportsSourceInspection: boolean;
     }>;
@@ -62,6 +70,15 @@ export type ProgramAIHelpJSON = {
             trigger: string;
             action: string;
         };
+        readyContract: {
+            readyPath: string;
+            eventsPath: string;
+            waitFlag: string;
+            statuses: string[];
+            readyFields: string[];
+            eventTypes: string[];
+            notes: string[];
+        };
         dockerAndContainers: {
             hostFlag: string;
             sandboxDetection: string[];

package/dist/extension/helpers/telemetry.d.ts

@@ -21,6 +21,7 @@ type TelemetryStorage = {
     idFile: string;
     consentFile: string;
 };
+export declare const DEFAULT_POSTHOG_KEY: string;
 export declare function resolveTelemetryStorage(): TelemetryStorage | null;
 export declare function resolveTelemetryConsent(argv?: string[]): {
     enabled: boolean;

package/dist/extension/helpers/vendors.d.ts

@@ -1,4 +1,5 @@
-export type Browser = 'chrome' | 'edge' | 'firefox' | 'chromium' | 'chromium-based' | 'gecko-based' | 'firefox-based';
+export type Browser = 'chrome' | 'edge' | 'firefox' | 'chromium' | 'chromium-based' | 'gecko-based' | 'firefox-based' | 'safari' | 'webkit-based';
+export declare function isSafariVendor(value: string): boolean;
 export declare function parseOptionalBoolean(value?: string): boolean;
 export declare const vendors: (browser?: Browser | "all") => string[];
 export declare function validateVendorsOrExit(vendorsList: string[], onInvalid: (invalid: string, supported: string[]) => void): void;

package/package.json

@@ -38,7 +38,7 @@
     "extension": "./bin/extension.cjs"
   },
   "name": "extension",
-  "version": "3.17.0",
+  "version": "3.18.1",
   "description": "Create cross-browser extensions with no build configuration.",
   "homepage": "https://extension.js.org/",
   "bugs": {
@@ -100,14 +100,14 @@
     "cross-spawn": "^7.0.6",
     "edge-location": "2.2.0",
     "firefox-location2": "3.0.0",
-    "extension-create": "3.17.0",
-    "extension-develop": "3.17.0",
-    "extension-install": "3.17.0",
+    "extension-create": "3.18.1",
+    "extension-develop": "3.18.1",
+    "extension-install": "3.18.1",
     "commander": "^14.0.3",
     "pintor": "0.3.0",
     "semver": "^7.7.3",
     "unique-names-generator": "^4.7.1",
-    "ws": "^8.19.0",
+    "ws": "^8.20.1",
     "update-check": "^1.5.4"
   },
   "devDependencies": {