extension-develop 4.0.11 → 4.0.12

package/dist/bridge-entry.d.ts

@@ -0,0 +1,5 @@
+export { BridgeConsumer, readReadyContract, type ConsumerOptions, type ReadyContractInfo } from './dev-server/control-bridge/consumer-client';
+export { BridgeController, type ControllerOptions, type CommandInput } from './dev-server/control-bridge/controller-client';
+export { readControlToken, controlTokenPath } from './dev-server/control-bridge/session-token';
+export { readPersistedControlPort, controlPortFilePath } from './dev-server/control-bridge/control-port-store';
+export type { LogEvent, LogLevel, LogContext, GapFrame, ReadyFrame, ResultFrame, BridgeTarget, CommandOp } from './dev-server/control-bridge/contracts';

package/dist/command-build.d.ts

@@ -0,0 +1,3 @@
+import { type BuildSummary } from './lib/build-summary';
+import type { BuildOptions } from './types';
+export declare function extensionBuild(pathOrRemoteUrl: string | undefined, buildOptions?: BuildOptions): Promise<BuildSummary>;

package/dist/command-dev.d.ts

@@ -0,0 +1,5 @@
+import { BuildEmitter, type BrowserLauncherFn } from './plugin-browsers';
+import type { DevOptions } from './types';
+export declare function extensionDev(pathOrRemoteUrl: string | undefined, devOptions: DevOptions & {
+    launcher?: BrowserLauncherFn;
+}): Promise<BuildEmitter>;

package/dist/command-preview.d.ts

@@ -0,0 +1,30 @@
+import type { PreviewOptions } from './types';
+/**
+ * Resolved browser launch options returned by extensionPreview.
+ * The caller is responsible for actually launching the browser.
+ */
+export interface ResolvedPreviewOptions {
+    browser: string;
+    outPath: string;
+    contextDir: string;
+    readyPath: string;
+    extensionsToLoad: string[];
+    noOpen?: boolean;
+    profile?: string | false;
+    persistProfile?: boolean;
+    preferences?: Record<string, unknown>;
+    browserFlags?: string[];
+    excludeBrowserFlags?: string[];
+    startingUrl?: string;
+    chromiumBinary?: string;
+    geckoBinary?: string;
+    instanceId?: string;
+    port?: number | string;
+    dryRun?: boolean;
+}
+/**
+ * Browser launcher callback. When provided, extensionPreview calls it
+ * instead of requiring plugin-browsers internally.
+ */
+export type PreviewLauncherFn = (opts: ResolvedPreviewOptions) => Promise<void>;
+export declare function extensionPreview(pathOrRemoteUrl: string | undefined, previewOptions: PreviewOptions, browserLauncher?: PreviewLauncherFn): Promise<void>;

package/dist/dev-server/auto-exit.d.ts

@@ -0,0 +1 @@
+export declare function setupAutoExit(autoExitMsRaw: string | number | undefined, forceKillMsRaw: string | number | undefined, onCleanup: () => Promise<void>): () => void;

package/dist/dev-server/cleanup.d.ts

@@ -0,0 +1,11 @@
+import { RspackDevServer } from '@rspack/dev-server';
+import { PortManager } from './port-manager';
+/**
+ * Creates cleanup handlers for process termination and uncaught errors.
+ * Registers signal handlers for graceful shutdown.
+ *
+ * @param devServer - The RspackDevServer instance
+ * @param portManager - The PortManager instance
+ * @returns A cleanup function and a cancel function for auto-exit
+ */
+export declare function setupCleanupHandlers(devServer: RspackDevServer, portManager: PortManager): () => void;

package/dist/dev-server/compiler-hooks.d.ts

@@ -0,0 +1,9 @@
+import { type Compiler } from '@rspack/core';
+export declare function setupCompilerLifecycleHooks(compiler: Compiler): void;
+export declare function setupNoBrowserBannerOnFirstDone(opts: {
+    compiler: Compiler;
+    browser: string;
+    manifestPath: string;
+    readyPath: string;
+}): void;
+export declare function setupCompilerDoneDiagnostics(compiler: Compiler, port?: number): void;

package/dist/dev-server/connectable-host.d.ts

@@ -0,0 +1,2 @@
+export declare function isWildcardHost(host: string | undefined | null): boolean;
+export declare function resolveConnectableHost(bindHost: string | undefined | null, publicHost?: string | undefined | null): string;

package/dist/dev-server/control-bridge/actions-file.d.ts

@@ -0,0 +1,38 @@
+import type { BridgeTarget, CommandOp } from './contracts';
+export declare const ACTION_RECORD_VERSION: 1;
+export interface ActionRecord {
+    v: typeof ACTION_RECORD_VERSION;
+    ts: string;
+    cmdId: string;
+    op: CommandOp;
+    target: BridgeTarget;
+    ok: boolean;
+    durationMs?: number;
+    principal: string;
+    exprHash?: string;
+    expr?: string;
+    errorName?: string;
+}
+export interface ActionsSink {
+    write(record: ActionRecord): void;
+}
+export interface ActionsFileOptions {
+    filePath: string;
+    maxBytes?: number;
+    maxLines?: number;
+    generations?: number;
+}
+export declare class ActionsFileWriter implements ActionsSink {
+    private readonly opts;
+    private bytes;
+    private lines;
+    private started;
+    constructor(options: ActionsFileOptions);
+    /** Rotate any prior file so a new run starts clean. No header is written. */
+    start(): void;
+    write(record: ActionRecord): void;
+    close(): void;
+    private rotatedName;
+    private rotate;
+}
+export declare function fnv1aHex(input: string): string;

package/dist/dev-server/control-bridge/broker.d.ts

@@ -0,0 +1,122 @@
+import { LogRingBuffer } from './ring-buffer';
+import type { LogsFileWriter } from './logs-file';
+import { type ActionsSink } from './actions-file';
+import { type AnyFrame, type CommandFrame, type IncomingLogEvent, type DevReloadKind, type ServerFrame } from './contracts';
+export interface BridgeConnection {
+    readonly id: string;
+    send(frame: ServerFrame | CommandFrame): void;
+    close(code?: number, reason?: string): void;
+}
+export interface BridgeBrokerOptions {
+    instanceId: string;
+    runId: string;
+    engine?: 'chromium' | 'firefox';
+    ring?: LogRingBuffer;
+    file?: LogsFileWriter;
+    allowControl?: boolean;
+    allowEval?: boolean;
+    controlToken?: string;
+    actions?: ActionsSink;
+    authorMode?: boolean;
+    now?: () => number;
+    setTimer?: (fn: () => void, ms: number) => ReturnType<typeof setTimeout>;
+    clearTimer?: (handle: ReturnType<typeof setTimeout>) => void;
+}
+export declare const CLOSE_BAD_INSTANCE = 4001;
+export declare const CLOSE_BAD_HELLO = 4002;
+export declare const CLOSE_CONTROL_UNAVAILABLE = 4003;
+export declare const DEFAULT_CMD_TIMEOUT_MS = 5000;
+export declare const MAX_CMD_TIMEOUT_MS = 30000;
+export declare class BridgeBroker {
+    private readonly instanceId;
+    private readonly runId;
+    private readonly engine?;
+    private readonly ring;
+    private readonly file?;
+    private readonly roles;
+    private readonly allowControl;
+    private readonly allowEval;
+    private readonly controlToken?;
+    private readonly actions?;
+    private readonly authorMode;
+    private readonly now;
+    private readonly setTimer;
+    private readonly clearTimer;
+    private readonly evalGate;
+    private readonly pending;
+    private staleResyncTimes;
+    /** True once any producer hello has been accepted this run. */
+    private producerEverConnected;
+    /** When the last accepted producer's socket closed (broker clock). */
+    private lastProducerDisconnectedAt;
+    /**
+     * When the last stale-instance producer hello arrived. Unlike
+     * staleResyncTimes (rate limiting, pruned to 60s) this is diagnosis state
+     * and is stamped even for rate-limited hellos.
+     */
+    private lastStaleHelloAt;
+    /**
+     * Latest reload broadcast not yet provably delivered. Latched when the
+     * broadcast reached zero producers (SW not started yet, or stopped after
+     * idling out) and, for content-scripts reloads, until a producer confirms
+     * reinjection ran with a `reload-ack` — a successful socket write proves
+     * nothing when the SW is wedged-but-connected (bug 27). Delivered once to
+     * the next producer that says hello, so an edit made while the SW was away
+     * (or dead at the pump) still applies instead of silently reloading nothing.
+     */
+    private pendingReload?;
+    constructor(options: BridgeBrokerOptions);
+    get consumerCount(): number;
+    get producerCount(): number;
+    get controllerCount(): number;
+    get pendingCount(): number;
+    onFrame(conn: BridgeConnection, frame: AnyFrame): void;
+    onClose(conn: BridgeConnection): void;
+    /**
+     * Dev-loop reload broadcast for the controller-less path. On a compile under
+     * `--no-browser` (no CDP controller to drive granular reinjection), the dev
+     * server calls this to push a typed {@link ReloadFrame} to every connected
+     * producer (the service worker), which performs the actual reload.
+     *
+     * NOT gated on `allowControl`: this is the dev loop reloading the developer's
+     * own extension on save, not an arbitrary controller-issued command. The
+     * launched-browser path never calls this — the controller owns reload there —
+     * so the two paths converge on one decision without double-reloading.
+     *
+     * Returns the number of producers notified (0 when the SW hasn't connected
+     * yet, e.g. before the first compile finishes writing the background bundle).
+     */
+    broadcastReload(instruction: {
+        type: DevReloadKind;
+        changedContentScriptEntries?: string[];
+        label?: string;
+        changedFiles?: string[];
+    }): number;
+    /**
+     * Keepalive for the dev extension's MV3 service worker: receiving any
+     * WebSocket message resets its ~30s idle timer, so the dev server pings
+     * all producers on an interval shorter than that. Without this, a quiet
+     * extension's SW stops between edits and reload broadcasts reach nothing.
+     */
+    pingProducers(): number;
+    ingestLog(incoming: IncomingLogEvent): void;
+    /** At most 3 stale-producer resync reloads per rolling minute. */
+    private allowStaleProducerResync;
+    private onHello;
+    /**
+     * Name WHY no producer is connected right now. Priority: a fresh
+     * stale-instance hello (resync in flight — strictly more actionable than
+     * either other cause) > nothing ever connected this run > a producer was
+     * here and left.
+     */
+    private diagnoseExecutorAbsence;
+    private gateEval;
+    private controllerReady;
+    private onCommand;
+    private onResult;
+    private onTimeout;
+    private firstExecutor;
+    private audit;
+    private fanOut;
+    private countRole;
+}

package/dist/dev-server/control-bridge/consumer-client.d.ts

@@ -0,0 +1,43 @@
+import { type GapFrame, type LogEvent, type ReadyFrame } from './contracts';
+export interface ReadyContractInfo {
+    controlPort: number;
+    instanceId: string;
+    runId: string;
+    logsPath?: string;
+    status?: string;
+    /** Dev-server pid; absent in pre-4.1 contracts. */
+    pid?: number;
+    /** Browser CDP port, stamped post-launch — may lag `status: 'ready'`. */
+    cdpPort?: number;
+    /** Stamped when the launched browser exits while the server keeps running. */
+    browserExitedAt?: string;
+    browserExitCode?: number;
+    /** Last contract write time (ISO). */
+    ts?: string;
+}
+export declare function readReadyContract(projectPath: string, browser?: string): ReadyContractInfo | null;
+export interface ConsumerOptions {
+    controlPort: number;
+    instanceId: string;
+    host?: string;
+    path?: string;
+    reconnect?: boolean;
+    onReady?: (frame: ReadyFrame) => void;
+    onLog?: (event: LogEvent) => void;
+    onGap?: (frame: GapFrame) => void;
+    onClose?: () => void;
+}
+export declare class BridgeConsumer {
+    private readonly opts;
+    private socket;
+    private backoff;
+    private readonly maxBackoff;
+    private closed;
+    private timer;
+    constructor(options: ConsumerOptions);
+    start(): void;
+    close(): void;
+    private url;
+    private connect;
+    private scheduleReconnect;
+}

package/dist/dev-server/control-bridge/contracts.d.ts

@@ -0,0 +1,164 @@
+export declare const LOG_EVENT_VERSION: 1;
+export declare const CONTROL_ENVELOPE_VERSION: 1;
+export type LogLevel = 'log' | 'info' | 'warn' | 'error' | 'debug' | 'trace';
+export type LogContext = 'background' | 'content' | 'page' | 'sidebar' | 'popup' | 'options' | 'devtools';
+export type LogEventType = 'log' | 'dx.signal';
+export type DxSignalStatus = 'ok' | 'warn' | 'fail';
+export interface LogEvent {
+    v: typeof LOG_EVENT_VERSION;
+    id: string;
+    seq: number;
+    timestamp: number;
+    level: LogLevel;
+    context: LogContext;
+    messageParts: unknown[];
+    eventType?: LogEventType;
+    code?: string;
+    status?: DxSignalStatus;
+    remediation?: string;
+    data?: Record<string, unknown>;
+    url?: string;
+    hostname?: string;
+    tabId?: number;
+    frameId?: number;
+    windowId?: number;
+    title?: string;
+    stack?: string;
+    errorName?: string;
+    sourceExtensionId?: string;
+    incognito?: boolean;
+    runId: string;
+    repeat?: number;
+}
+export type IncomingLogEvent = Omit<LogEvent, 'seq'> & {
+    seq?: number;
+};
+export type BridgeRole = 'producer' | 'consumer' | 'controller';
+export interface BridgeTarget {
+    context: 'background' | 'popup' | 'options' | 'sidebar' | 'devtools' | 'content' | 'page';
+    url?: string;
+    tabId?: number;
+}
+export type CommandOp = 'eval' | 'storage.get' | 'storage.set' | 'reload' | 'open' | 'tabs.query' | 'inspect';
+/**
+ * Granularity of a dev-loop reload. Mirrors `ReloadType` in
+ * plugin-reload/classify-reload.ts: the launched-browser path feeds this
+ * decision to the CDP controller; the `--no-browser` path feeds the same
+ * decision to the broker, which broadcasts a {@link ReloadFrame} to the SW
+ * producer.
+ */
+export type ReloadType = 'full' | 'service-worker' | 'content-scripts';
+/**
+ * Everything a {@link ReloadFrame} can carry in `reloadType`: the extension
+ * reload granularities plus `'page'` — a notify-only signal for page-only
+ * edits (popup/options/sidebar/devtools/newtab). For `'page'` the producer
+ * performs NO reload (livereload owns the refresh); it only forwards the
+ * announcement so the devtools pill mirrors the dev loop.
+ */
+export type DevReloadKind = ReloadType | 'page';
+export type GapReason = 'ring_overflow' | 'rate_limit' | 'disk_slow' | 'slow_consumer';
+export interface HelloFrame {
+    type: 'hello';
+    v: typeof CONTROL_ENVELOPE_VERSION;
+    role: BridgeRole;
+    instanceId: string;
+    token?: string;
+}
+export interface ReadyFrame {
+    type: 'ready';
+    runId: string;
+    bufferedFrom?: number;
+    engine?: 'chromium' | 'firefox';
+    capabilities?: {
+        eval?: boolean;
+        storage?: boolean;
+        reload?: boolean;
+        open?: Array<'popup' | 'options' | 'sidebar' | 'action' | 'command'>;
+        deepDom?: boolean;
+    };
+}
+export interface LogFrame {
+    type: 'log';
+    event: LogEvent;
+}
+export interface GapFrame {
+    type: 'gap';
+    dropped: number;
+    reason: GapReason;
+    sinceSeq: number;
+}
+export interface CommandFrame {
+    type: 'command';
+    cmdId: string;
+    op: CommandOp;
+    target: BridgeTarget;
+    args?: Record<string, unknown>;
+    timeoutMs?: number;
+}
+export interface ResultFrame {
+    type: 'result';
+    cmdId: string;
+    ok: boolean;
+    value?: unknown;
+    truncated?: boolean;
+    durationMs?: number;
+    error?: {
+        name: string;
+        message: string;
+        stack?: string;
+        engine?: string;
+    };
+}
+/**
+ * Dev-loop reload broadcast, server → producer. Sent by the broker on a compile
+ * that completed without a CDP controller (`--no-browser`, headless/CI, remote)
+ * so the service-worker producer can self-reload. Unlike a `reload` CommandFrame
+ * (a controller-issued, `--allow-control`-gated act verb that expects a result),
+ * this is a fire-and-forget dev-server signal — no cmdId, no result.
+ */
+export interface ReloadFrame {
+    type: 'reload';
+    reloadType: DevReloadKind;
+    changedContentScriptEntries?: string[];
+    /**
+     * Server-built human context label, e.g. "content_script (content/scripts.tsx)".
+     * Shown VERBATIM by every announcement surface (CLI stdout, the page's
+     * devtools console line, the devtools-extension pill) so the three can
+     * never disagree about what is reloading.
+     */
+    label?: string;
+    /** Project-relative source files that triggered this reload. */
+    changedFiles?: string[];
+}
+/**
+ * Producer → server receipt confirmation for a {@link ReloadFrame}: the SW's
+ * message pump actually processed the frame. A successful socket write proves
+ * nothing when the worker is wedged-but-connected (bug 27: the server printed
+ * "Reloading content_script…" while no scripting.executeScript ever left the
+ * producer). The broker latches a content-scripts reload until this ack
+ * arrives and replays the latch to the next producer hello, so an edit that
+ * landed on a dead pump still converges on the next SW start. Full/SW reloads
+ * are not latched-until-ack (replaying a restart would loop it); their
+ * convergence is the boot-time pending-reinject heal.
+ */
+export interface ReloadAckFrame {
+    type: 'reload-ack';
+    reloadType: DevReloadKind;
+    label?: string;
+}
+/**
+ * Server → producer keepalive. An MV3 service worker idles out after ~30s
+ * without events, and a stopped SW holds no control socket — reload
+ * broadcasts would reach zero producers and silently apply to nothing
+ * (quiet extensions lost SW/manifest reloads once >30s passed between
+ * edits). Receiving any WebSocket message resets the SW idle timer
+ * (Chrome 116+), so a periodic ping keeps the dev extension's SW
+ * responsive for the whole dev session. Producers ignore the frame.
+ */
+export interface PingFrame {
+    type: 'ping';
+}
+export type ClientFrame = HelloFrame | LogFrame | CommandFrame | ReloadAckFrame;
+export type ServerFrame = ReadyFrame | LogFrame | GapFrame | ResultFrame | ReloadFrame | PingFrame;
+export type AnyFrame = ClientFrame | ServerFrame;
+export declare const CONTROL_WS_PATH = "/extjs-control";

package/dist/dev-server/control-bridge/control-port-store.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Control-port persistence — the reachability half of stale-SW self-healing.
+ *
+ * Chrome caches an extension's background service-worker script per profile:
+ * after a dev-server restart, a reused profile can keep running a SW whose
+ * baked control port belongs to the PREVIOUS session. With an ephemeral port
+ * per session that stale SW dials a dead port forever and no reload can reach
+ * it. Persisting the port per project+browser lets the stale producer reach
+ * the NEW server, whose broker then tells it to full-reload itself (see
+ * BridgeBroker.onHello).
+ *
+ * The file lives under the project's `.extension-js/` dir (with the control
+ * token), NOT under dist/: profiles can outlive dist/ — an explicit
+ * `--profile <path>` or a kept managed profile survives a dist wipe — and a
+ * port file that dies with dist strands the profile's cached SW on a dead
+ * port with no resync path (issue #484: permanent "no executor connected"
+ * against a live, awake SW). The port must live at least as long as any
+ * profile that may have it baked in.
+ *
+ * Paths are owned by lib/session-paths (re-exported here for the existing
+ * import surface); only the read/write logic lives in this file.
+ */
+export { controlPortFilePath, legacyControlPortFilePath } from '../../lib/session-paths';
+export declare function readPersistedControlPort(filePath: string): number | null;
+export declare function writePersistedControlPort(filePath: string, port: number): void;

package/dist/dev-server/control-bridge/controller-client.d.ts

@@ -0,0 +1,30 @@
+import { type BridgeTarget, type CommandOp, type ReadyFrame, type ResultFrame } from './contracts';
+export interface ControllerOptions {
+    controlPort: number;
+    instanceId: string;
+    token?: string;
+    host?: string;
+    path?: string;
+    connectTimeoutMs?: number;
+}
+export interface CommandInput {
+    op: CommandOp;
+    target: BridgeTarget;
+    args?: Record<string, unknown>;
+    timeoutMs?: number;
+}
+export declare class BridgeController {
+    private readonly opts;
+    private socket;
+    private ready;
+    private connectPromise;
+    private readonly pending;
+    constructor(options: ControllerOptions);
+    get capabilities(): ReadyFrame['capabilities'] | undefined;
+    connect(): Promise<ReadyFrame>;
+    /** Issue a command and resolve with the broker-routed result. */
+    command(input: CommandInput): Promise<ResultFrame>;
+    close(): void;
+    private resolveResult;
+    private failAllPending;
+}

package/dist/dev-server/control-bridge/logs-file.d.ts

@@ -0,0 +1,30 @@
+import { type LogEvent } from './contracts';
+export interface LogsFileOptions {
+    filePath: string;
+    runId: string;
+    maxBytes?: number;
+    maxLines?: number;
+    generations?: number;
+    flushIntervalMs?: number;
+    maxQueue?: number;
+}
+export declare class LogsFileWriter {
+    private readonly opts;
+    private queue;
+    private bytes;
+    private lines;
+    private droppedToDisk;
+    private timer;
+    private started;
+    constructor(options: LogsFileOptions);
+    start(): void;
+    write(event: LogEvent): void;
+    private enqueue;
+    flush(): void;
+    close(): void;
+    private maybeNoteDrops;
+    private writeHeader;
+    private rotatedName;
+    /** Shift generations: drop the oldest, age each, move current → .1 */
+    private rotate;
+}