extension 3.13.0 → 3.13.3

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

@@ -0,0 +1,14 @@
+export declare const DEFAULT_DEBUG_PORT = 9222;
+export declare const PORT_OFFSET = 100;
+/** CDP sendCommand default timeout (ms). Override: EXTENSION_CDP_COMMAND_TIMEOUT_MS */
+export declare const CDP_COMMAND_TIMEOUT_MS: number;
+/** CDP HTTP endpoint timeout for /json discovery (ms). Override: EXTENSION_CDP_HTTP_TIMEOUT_MS */
+export declare const CDP_HTTP_TIMEOUT_MS: number;
+/** Firefox RDP evaluation timeout (ms). Override: EXTENSION_RDP_EVAL_TIMEOUT_MS */
+export declare const RDP_EVAL_TIMEOUT_MS: number;
+/** Firefox RDP connect retry count. Override: EXTENSION_RDP_MAX_RETRIES */
+export declare const RDP_MAX_RETRIES: number;
+/** Firefox RDP connect retry interval (ms). Override: EXTENSION_RDP_RETRY_INTERVAL_MS */
+export declare const RDP_RETRY_INTERVAL_MS: number;
+/** CDP WebSocket heartbeat interval (ms). Override: EXTENSION_CDP_HEARTBEAT_INTERVAL_MS */
+export declare const CDP_HEARTBEAT_INTERVAL_MS: number;

package/dist/extension/browsers/browsers-lib/normalize-options.d.ts

@@ -0,0 +1,12 @@
+import type { BrowserType } from '../browsers-types';
+import { PluginInterface } from '../browsers-types';
+export type NormalizedBrowser = BrowserType;
+export interface NormalizedOptions extends Omit<PluginInterface, 'browser'> {
+    browser: NormalizedBrowser;
+    noOpen?: boolean;
+    profile?: string | false;
+    startingUrl?: string;
+    source?: string;
+    dryRun?: boolean;
+}
+export declare function normalizePluginOptions(options: PluginInterface): NormalizedOptions;

package/dist/extension/browsers/browsers-lib/source-output.d.ts

@@ -0,0 +1,86 @@
+export type SourceFormat = 'pretty' | 'json' | 'ndjson';
+export type SourceRedact = 'off' | 'safe' | 'strict';
+export type SourceIncludeShadow = 'off' | 'open-only' | 'all';
+export type SourceStage = 'pre_injection' | 'post_injection' | 'updated';
+export type SourceOutputMeta = {
+    stage: SourceStage;
+    browser?: string;
+    mode?: string;
+    url?: string;
+    title?: string;
+    tabId?: number | string;
+};
+export type SourceSummary = {
+    counts: {
+        extensionRoots: number;
+        shadowRoots: number;
+        scripts: number;
+        styles: number;
+    };
+    markers: {
+        hasExtensionRootId: boolean;
+        hasContentScriptMarker: boolean;
+    };
+    snippet?: string;
+};
+export type DomSnapshotNode = {
+    key: string;
+    tag: string;
+    id?: string;
+    classes?: string;
+    role?: string;
+    ariaLabel?: string;
+    name?: string;
+    type?: string;
+    textLength?: number;
+    childCount?: number;
+};
+export type DomSnapshot = {
+    rootMode: 'shadow' | 'element';
+    depthLimit: number;
+    nodeLimit: number;
+    truncated: boolean;
+    nodes: DomSnapshotNode[];
+};
+export type NormalizedSourceOutputConfig = {
+    format: SourceFormat;
+    summary: boolean;
+    maxBytes: number;
+    redact: SourceRedact;
+    includeShadow: SourceIncludeShadow;
+};
+export declare function normalizeSourceOutputConfig(input: {
+    format?: string;
+    summary?: boolean;
+    maxBytes?: number;
+    redact?: string;
+    includeShadow?: string;
+    sourceEnabled?: boolean;
+    logFormat?: string;
+}): NormalizedSourceOutputConfig;
+export declare function applySourceRedaction(html: string, redact: SourceRedact): string;
+export declare function truncateByBytes(input: string, maxBytes: number): {
+    output: string;
+    truncated: boolean;
+    byteLength: number;
+};
+export declare function hashStringFNV1a(input: string): string;
+export declare function diffDomSnapshots(prev: DomSnapshot | undefined, next: DomSnapshot): {
+    added: number;
+    removed: number;
+    changed: number;
+    addedKeys: string[];
+    removedKeys: string[];
+    changedKeys: string[];
+};
+export declare function resolveActionFormat(): SourceFormat;
+export declare function emitActionEvent(action: string, payload?: Record<string, unknown>, _format?: SourceFormat): void;
+export declare function buildHtmlSummary(html: string): SourceSummary;
+export declare function formatHtmlSentinelBegin(meta: {
+    url?: string;
+    title?: string;
+    tabId?: number | string;
+    stage?: string;
+    truncated?: boolean;
+}): string;
+export declare function formatHtmlSentinelEnd(): string;

package/dist/{browser → extension/browsers}/run-chromium/chromium-source-inspection/cdp-client.d.ts

@@ -7,10 +7,13 @@ export declare class CDPClient {
     private eventCallbacks;
     private messageId;
     private pendingRequests;
+    private heartbeatTimer;
     constructor(port?: number, host?: string);
     private isDev;
     connect(): Promise<void>;
     disconnect(): void;
+    private startHeartbeat;
+    private stopHeartbeat;
     isConnected(): boolean;
     onProtocolEvent(handler: (message: Record<string, unknown>) => void): () => void;
     private handleMessage;

package/dist/extension/browsers/run-chromium/chromium-source-inspection/deterministic-hmr-harness.d.ts

@@ -0,0 +1,21 @@
+export type ContentScriptProbe = {
+    scriptPath: string;
+    probeId: string;
+};
+export type HmrIterationExpectation = {
+    scriptPath: string;
+    expectedToken: string;
+};
+export type HmrIterationResult = {
+    scriptPath: string;
+    expectedToken: string;
+    snapshotIndex: number;
+    passed: boolean;
+    reason: string;
+};
+export declare function listManifestContentScriptFiles(manifest: unknown): string[];
+export declare function contentScriptProbeId(scriptPath: string): string;
+export declare function buildContentScriptProbePlan(manifest: unknown): ContentScriptProbe[];
+export declare function buildIterationExpectations(probePlan: ContentScriptProbe[], tokenVersion: string): HmrIterationExpectation[];
+export declare function extractUpdatedHtmlFromNdjson(output: string): string[];
+export declare function evaluateDeterministicHmrIterations(expectations: HmrIterationExpectation[], updatedHtmlSnapshots: string[]): HmrIterationResult[];

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

@@ -0,0 +1,2 @@
+import { CDPClient } from './cdp-client';
+export declare function extractPageHtml(cdpClient: CDPClient, sessionId: string, logSamples?: boolean, includeShadow?: 'off' | 'open-only' | 'all'): Promise<string>;

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

@@ -0,0 +1,79 @@
+import { WebSocketServer } from 'ws';
+import type { PluginInterface } from '../../browsers-types';
+/**
+ * ChromiumSourceInspectionPlugin
+ *
+ * Intended responsibilities:
+ * - Dev-only page/extension inspection; attach to target and extract HTML
+ * - Optional watch mode to re-print HTML on file changes
+ */
+export declare class ChromiumSourceInspectionPlugin {
+    private devOptions;
+    private cdpClient;
+    private currentTargetId;
+    private currentSessionId;
+    private isInitialized;
+    private isWatching;
+    private hasInspectedSourceOnce;
+    private pendingWatchSourceUpdate;
+    private pendingWatchSourceRootMeta?;
+    private debounceTimer;
+    private watchSourceFlushTimer;
+    private isFlushingWatchSourceUpdate;
+    private lastFlushTimestamp;
+    private runtimeMode?;
+    private lastOutputHash?;
+    private lastByteLength?;
+    private lastSummary?;
+    private lastDomSnapshot?;
+    private consoleCounts;
+    private consoleTop;
+    constructor(devOptions: Pick<PluginInterface, 'port' | 'source' | 'watchSource'> & {
+        startingUrl?: string;
+        instanceId?: string;
+    }, _ctx?: unknown);
+    private isAuthorMode;
+    private getOutputConfig;
+    private getPageMetadata;
+    private getFrameContext;
+    private getDomSnapshot;
+    private getExtensionRootMeta;
+    /**
+     * Require structural evidence (counted roots or shadow style nodes) after the
+     * injection wait, with a short settle loop for async shadow hydration. Falls back to
+     * the same shadow-innerHTML probe as {@link waitForContentScriptInjection}.
+     */
+    private shouldEmitContentScriptInjected;
+    private getPageMetaSnapshot;
+    private getSelectorProbes;
+    private getExtensionRootTree;
+    private setupConsoleCapture;
+    private recordConsoleEvent;
+    private buildPrettyTitle;
+    private emitSourceOutput;
+    private emitExtraOutputs;
+    private emitEventPayload;
+    private getShadowStyleSnapshot;
+    private getCdpPort;
+    initialize(port?: number): Promise<void>;
+    inspectSource(url: string, options?: {
+        forceNavigate?: boolean;
+    }): Promise<string>;
+    startWatching(websocketServer: WebSocketServer): Promise<void>;
+    private setupWebSocketHandler;
+    private setupConnectionHandler;
+    stopWatching(): void;
+    private registerContentReloadSnapshotHook;
+    private scheduleWatchSourceUpdate;
+    private emitImmediateUpdatedSnapshotFromCurrentSession;
+    private handleFileChange;
+    private waitForContentScriptReinjection;
+    private emitUpdatedSnapshotFromCurrentSession;
+    private waitForMeaningfulContentScriptContent;
+    private waitForContentScriptStyles;
+    private reconnectToTarget;
+    printHTML(html: string): Promise<void>;
+    printUpdatedHTML(html: string): Promise<void>;
+    cleanup(): Promise<void>;
+    apply(compiler: any): void;
+}

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

@@ -0,0 +1 @@
+export declare function waitForChromeRemoteDebugging(port: number, instanceId?: string): Promise<void>;

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

@@ -0,0 +1,2 @@
+import { CDPClient } from './cdp-client';
+export declare function enableRuntimeAndLog(cdp: CDPClient, sessionId?: string): Promise<void>;

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

@@ -0,0 +1,7 @@
+import { CDPClient } from './cdp-client';
+export declare function ensureTargetAndSession(cdpClient: CDPClient, url: string, options?: {
+    forceNavigate?: boolean;
+}): Promise<{
+    targetId: string;
+    sessionId: string;
+}>;

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

@@ -0,0 +1,22 @@
+import type { ChromiumContext } from '../chromium-context';
+/**
+ * ChromiumUnifiedLoggerPlugin
+ *
+ * Intended responsibilities:
+ * - Wait for controller readiness; enable unified CDP logging
+ * - Respect level/contexts/filters/format/timestamps/color
+ */
+export declare class ChromiumUnifiedLoggerPlugin {
+    private readonly options;
+    private readonly ctx;
+    constructor(options: {
+        logLevel?: string;
+        logContexts?: string[];
+        logUrl?: string;
+        logTab?: number | string;
+        logFormat?: 'pretty' | 'json' | 'ndjson';
+        logTimestamps?: boolean;
+        logColor?: boolean;
+    }, ctx: ChromiumContext);
+    apply(_compiler: any): void;
+}

package/dist/extension/browsers/run-chromium/chromium-unified-logger/unified-logging.d.ts

@@ -0,0 +1,2 @@
+import type { Controller, ChromiumLogger } from '../chromium-types';
+export declare function setupUnifiedLogging(controller: Controller, opts: ChromiumLogger): Promise<void>;

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

@@ -0,0 +1,52 @@
+import type { FirefoxContext } from '../firefox-context';
+export declare class FirefoxSourceInspectionPlugin {
+    private readonly host;
+    private readonly _ctx?;
+    private devOptions?;
+    private client;
+    private currentConsoleActor;
+    private currentTabActor;
+    private isWatching;
+    private debounceTimer;
+    private initialized;
+    private lastUrlToInspect;
+    private lastOutputHash?;
+    private lastByteLength?;
+    private lastSummary?;
+    private lastDomSnapshot?;
+    private consoleCounts;
+    private consoleTop;
+    private consoleCaptureReady;
+    constructor(host: any, ctx?: FirefoxContext);
+    private setDevOptions;
+    private getOutputConfig;
+    private buildPrettyTitle;
+    private getFrameContext;
+    private emitSourceOutput;
+    private setupConsoleCapture;
+    private recordConsoleEvent;
+    private emitExtraOutputs;
+    private evaluateJson;
+    private evaluateString;
+    private getShadowStyleSnapshot;
+    private getDomSnapshot;
+    private getExtensionRootMeta;
+    private emitEventPayload;
+    private getRdpPort;
+    private initialize;
+    private resolveUrlToInspect;
+    private selectActors;
+    private ensureNavigatedAndLoaded;
+    private ensureUrlAndReady;
+    private resolveConsoleActor;
+    private printHTML;
+    private waitForContentScriptInjection;
+    private hasVisibleShadowHostContentFirefox;
+    /** Align with Chromium: settle root meta / shadow styles before emitting injection telemetry. */
+    private shouldEmitFirefoxContentScriptInjected;
+    private reopenTabAndResolveActors;
+    private waitForContentScriptStyles;
+    private handleFileChange;
+    private registerContentReloadSnapshotHook;
+    apply(compiler: any): void;
+}

package/dist/{browser → extension/browsers}/run-firefox/firefox-source-inspection/remote-firefox/messaging-client.d.ts

@@ -2,8 +2,12 @@ import EventEmitter from 'events';
 export declare class MessagingClient extends EventEmitter {
     private transport;
     private forwardingSetup;
+    private lastPort;
+    private reconnecting;
+    private disconnectedByUser;
     connect(port: number): Promise<void>;
     disconnect(): void;
+    private attemptReconnect;
     request(requestProps: unknown): Promise<unknown>;
     onError(error: Error): void;
     getTargets(): Promise<{
@@ -32,6 +36,7 @@ export declare class MessagingClient extends EventEmitter {
     private serializeDocument;
     private extractShadowContent;
     private mergeShadowIntoMain;
+    private isDev;
     getPageHTML(descriptorActor: string, consoleActorHint?: string): Promise<string>;
     closeTab(tabId: string): Promise<void>;
 }

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

@@ -0,0 +1,5 @@
+import { MessagingClient } from './messaging-client';
+export declare function selectActors(client: MessagingClient, urlToInspect: string): Promise<{
+    tabActor: string;
+    consoleActor: string;
+}>;

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

@@ -0,0 +1,2 @@
+import { MessagingClient } from './messaging-client';
+export declare function ensureNavigatedAndLoaded(client: MessagingClient, urlToInspect: string, tabActor: string): Promise<void>;

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

@@ -0,0 +1,14 @@
+import type { FirefoxContext } from '../firefox-context';
+/**
+ * FirefoxUnifiedLoggerPlugin
+ *
+ * Responsibilities:
+ * - Wait for RDP controller readiness; enable unified logging
+ * - Respect level/contexts/filters/format/timestamps/color
+ */
+export declare class FirefoxUnifiedLoggerPlugin {
+    private readonly options;
+    private readonly ctx;
+    constructor(options: FirefoxUnifiedLoggerPlugin['options'], ctx: FirefoxContext);
+    apply(_compiler: any): void;
+}

package/dist/extension/vitest.config.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("vite").UserConfig;
+export default _default;

package/package.json

@@ -4,7 +4,7 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/extension-js/extension.js.git",
-    "directory": "programs/cli"
+    "directory": "programs/extension"
   },
   "engines": {
     "node": ">=18"
@@ -15,6 +15,11 @@
       "import": "./dist/cli.cjs",
       "require": "./dist/cli.cjs"
     },
+    "./browsers": {
+      "types": "./dist/browsers.d.ts",
+      "import": "./dist/browsers.cjs",
+      "require": "./dist/browsers.cjs"
+    },
     "./types": {
       "types": "./types/index.d.ts"
     },
@@ -33,7 +38,7 @@
     "extension": "./bin/extension.cjs"
   },
   "name": "extension",
-  "version": "3.13.0",
+  "version": "3.13.3",
   "description": "Create cross-browser extensions with no build configuration.",
   "homepage": "https://extension.js.org/",
   "bugs": {
@@ -90,13 +95,19 @@
     "@types/chrome": "^0.1.33",
     "@types/node": "^25.2.0",
     "@types/webextension-polyfill": "0.12.4",
+    "chrome-location2": "4.0.0",
+    "chromium-location": "2.0.0",
     "cross-spawn": "^7.0.6",
-    "extension-create": "3.13.0",
-    "extension-develop": "3.13.0",
-    "extension-install": "3.13.0",
+    "edge-location": "2.2.0",
+    "firefox-location2": "3.0.0",
+    "extension-create": "3.13.3",
+    "extension-develop": "3.13.3",
+    "extension-install": "3.13.3",
     "commander": "^14.0.3",
     "pintor": "0.3.0",
     "semver": "^7.7.3",
+    "unique-names-generator": "^4.7.1",
+    "ws": "^8.19.0",
     "update-check": "^1.5.4"
   },
   "devDependencies": {