extension-develop 4.1.19 → 4.1.20

package/dist/832~0.mjs

@@ -19,7 +19,7 @@ import * as __rspack_external_node_fs_1b05aee1 from "node:fs";
 import * as __rspack_external_node_os_4f3c9d58 from "node:os";
 import * as __rspack_external_node_path_806ed179 from "node:path";
 import * as __rspack_external_node_vm_ef240610 from "node:vm";
-var package_namespaceObject = /*#__PURE__*/ JSON.parse('{"rE":"4.1.19","El":{"@prefresh/core":"1.5.9","@prefresh/utils":"1.2.1","@rspack/core":"^2.2.3","@rspack/dev-server":"2.1.0","@rspack/plugin-preact-refresh":"2.0.1","@rspack/plugin-react-refresh":"2.0.2","@vue/compiler-sfc":"3.5.26","acorn":"^8.16.0","browser-extension-manifest-fields":"^3.0.1","case-sensitive-paths-webpack-plugin":"^2.4.0","content-security-policy-parser":"^0.6.0","cross-spawn":"^7.0.6","dotenv":"^17.2.3","es-module-lexer":"^3.0.2","extension-from-store":"^0.2.5","fflate":"^0.8.3","go-git-it":"^5.1.5","ignore":"^7.0.5","less":"4.6.7","less-loader":"13.0.0","parse5-utilities":"^1.0.0","pintor":"0.3.0","postcss":"8.5.23","postcss-loader":"8.2.1","postcss-preset-env":"11.1.1","postcss-scss":"4.0.9","preact":"10.27.3","prefers-yarn":"2.0.1","react-refresh":"0.18.0","sass-loader":"17.0.0","schema-utils":"^4.3.3","svelte-loader":"3.2.4","tiny-glob":"^0.2.9","vue":"3.5.26","vue-loader":"17.4.2","webextension-polyfill":"^0.12.0","webpack-merge":"^6.0.1","webpack-target-webextension":"^2.1.3","ws":"^8.20.1"}}');
+var package_namespaceObject = /*#__PURE__*/ JSON.parse('{"rE":"4.1.20","El":{"@prefresh/core":"1.5.9","@prefresh/utils":"1.2.1","@rspack/core":"^2.2.3","@rspack/dev-server":"2.1.0","@rspack/plugin-preact-refresh":"2.0.1","@rspack/plugin-react-refresh":"2.0.2","@vue/compiler-sfc":"3.5.26","acorn":"^8.16.0","browser-extension-manifest-fields":"^3.0.1","case-sensitive-paths-webpack-plugin":"^2.4.0","content-security-policy-parser":"^0.6.0","cross-spawn":"^7.0.6","dotenv":"^17.2.3","es-module-lexer":"^3.0.2","extension-from-store":"^0.2.5","fflate":"^0.8.3","go-git-it":"^5.1.5","ignore":"^7.0.5","less":"4.6.7","less-loader":"13.0.0","parse5-utilities":"^1.0.0","pintor":"0.3.0","postcss":"8.5.23","postcss-loader":"8.2.1","postcss-preset-env":"11.1.1","postcss-scss":"4.0.9","preact":"10.27.3","prefers-yarn":"2.0.1","react-refresh":"0.18.0","sass-loader":"17.0.0","schema-utils":"^4.3.3","svelte-loader":"3.2.4","tiny-glob":"^0.2.9","vue":"3.5.26","vue-loader":"17.4.2","webextension-polyfill":"^0.12.0","webpack-merge":"^6.0.1","webpack-target-webextension":"^2.1.3","ws":"^8.20.1"}}');
 const preloadedEnvKeys = new Set();
 function getPreloadedEnvKeys() {
     return preloadedEnvKeys;
@@ -682,7 +682,8 @@ function createPlaywrightMetadataWriter(options) {
             }
             if ('string' == typeof prev.executorAttachedAt) {
                 payload.executorAttachedAt = prev.executorAttachedAt;
-                payload.runtime = 'attached';
+                payload.runtime = 'detached' === prev.runtime ? 'detached' : 'attached';
+                if ('string' == typeof prev.executorDetachedAt) payload.executorDetachedAt = prev.executorDetachedAt;
             }
             if ('starting' !== status && 'string' == typeof prev.extensionLoadRefusedAt) {
                 const target = payload;
@@ -738,14 +739,25 @@ function createPlaywrightMetadataWriter(options) {
                 compiledAt: null
             });
         },
-        writeShutdown () {
+        writeShutdown (message = 'the dev session ended (watch closed)') {
             if (foreignLiveDevSession) return;
             try {
                 if (!__rspack_external_node_fs_1b05aee1.existsSync(readyPath)) return;
                 const prev = JSON.parse(__rspack_external_node_fs_1b05aee1.readFileSync(readyPath, 'utf-8'));
                 prev.status = 'stopped';
                 prev.code = 'shutdown';
-                prev.message = 'the dev session ended (watch closed)';
+                prev.message = message;
+                prev.ts = nowISO();
+                writeJsonAtomic(readyPath, prev);
+            } catch  {}
+        },
+        stampExecutorDetached () {
+            try {
+                if (!__rspack_external_node_fs_1b05aee1.existsSync(readyPath)) return;
+                const prev = JSON.parse(__rspack_external_node_fs_1b05aee1.readFileSync(readyPath, 'utf-8'));
+                if ('string' != typeof prev.executorAttachedAt) return;
+                prev.runtime = 'detached';
+                prev.executorDetachedAt = nowISO();
                 prev.ts = nowISO();
                 writeJsonAtomic(readyPath, prev);
             } catch  {}
@@ -754,9 +766,14 @@ function createPlaywrightMetadataWriter(options) {
             try {
                 if (!__rspack_external_node_fs_1b05aee1.existsSync(readyPath)) return;
                 const prev = JSON.parse(__rspack_external_node_fs_1b05aee1.readFileSync(readyPath, 'utf-8'));
-                if ('string' == typeof prev.executorAttachedAt) return;
-                prev.executorAttachedAt = nowISO();
                 prev.runtime = 'attached';
+                delete prev.executorDetachedAt;
+                if ('string' == typeof prev.executorAttachedAt) {
+                    prev.ts = nowISO();
+                    writeJsonAtomic(readyPath, prev);
+                    return;
+                }
+                prev.executorAttachedAt = nowISO();
                 if ('string' == typeof prev.extensionLoadRefusedAt) {
                     delete prev.extensionLoadRefusedAt;
                     delete prev.extensionLoadRefusedReason;
@@ -1854,5 +1871,8 @@ async function extensionPreview(pathOrRemoteUrl, previewOptions, browserLauncher
     if (!browserLauncher) throw new Error("extensionPreview requires a browserLauncher callback. The browser launch code has moved to programs/extension/browsers/.");
     await browserLauncher(resolvedOpts);
     metadata.writeReady();
+    process.once('exit', ()=>{
+        metadata.writeShutdown(`the ${metadataCommand} session ended`);
+    });
 }
 export { BUILD_COMMAND_DEFAULTS, DEV_COMMAND_DEFAULTS, PlaywrightPlugin, START_BUILD_DEFAULTS, assertNoManagedDependencyConflicts, autoExitForceKill, autoExitModeEnabled, autoExitTriggered, browserRunnerDisabled, bundlerFatalError, bundlerRecompiling, computeExtensionsToLoad, createPlaywrightMetadataWriter, devServerRestarting, devServerStartTimeout, extensionJsRunnerError, extensionPreview, getPreloadedEnvKeys, getSessionRunId, getSpecialFoldersDataForCompiler, getSpecialFoldersDataForProjectRoot, loadBrowserConfig, loadCommandConfig, loadCustomConfig, loadProjectConfigDefaults, mergeOptionLayers, messages_ready, noEntrypointsDetected, package_namespaceObject, portInUse, publicFolderShadowed, publicMustBeAtProjectRoot, resolveCompanionExtensionDirs, resolveCompanionExtensionsConfig, runnerCleanupError, runnerUncaughtException, runnerUnhandledRejection, sanitize, serverRestartRequiredFromSpecialFolderMessageOnly, shouldWarnPortConflict, spacerLine, specialFolderChangeDetected, specialFoldersSetupSummary, stampReadyDistExtensionId, stampReadyKnownExtensionId, withDarkMode };

package/dist/840~0.mjs

@@ -2152,7 +2152,7 @@ async function extensionBuild(pathOrRemoteUrl, buildOptions) {
                         if (warningDetails) humanLine(warningDetails);
                     }
                     for (const line of lintLines)humanLine(line);
-                    humanLine(buildComplete(browser, distDisplay, summary.total_bytes));
+                    humanLine(buildComplete(browser, distDisplay, summary.total_bytes, resolvedMode));
                     for (const artifact of getZipArtifacts(stats.compilation)){
                         const artifactPath = useStagingSwap && artifact.path.startsWith(stagingDistPath) ? distPath + artifact.path.slice(stagingDistPath.length) : artifact.path;
                         const zipDisplay = relativeToCwd(artifactPath) || artifactPath;
@@ -2212,6 +2212,9 @@ function viaBroker(broker, instruction) {
 function formatReloadingLine(label) {
     return `${messaging_prefix('info')} Reloading ${label}…`;
 }
+function formatQueuedReloadLine(label) {
+    return `${messaging_prefix('info')} Queued ${label} for the extension to apply when it reconnects.`;
+}
 async function dispatchReload(instruction, executor) {
     if (!instruction) return;
     if ('true' === process.env.EXTENSION_NO_RELOAD) return;
@@ -2221,8 +2224,11 @@ async function dispatchReload(instruction, executor) {
             if (instruction.label) console.log(formatReloadingLine(instruction.label));
             return;
         }
-        const warning = executor.broker.undeliveredReloadWarning?.();
-        if (warning) console.warn(warning);
+        const warning = executor.broker.undeliveredReloadWarning?.(executor.producerRestartExpected ? {
+            producerRestartExpected: true
+        } : void 0);
+        if (warning) return void console.warn(warning);
+        if (executor.producerRestartExpected && instruction.label) console.log(formatQueuedReloadLine(instruction.label));
     }
 }
 function isForcedFullPath(normalized) {
@@ -2674,6 +2680,43 @@ class BrowsersPlugin {
         });
     }
 }
+function union(previous, next) {
+    return [
+        ...new Set([
+            ...previous || [],
+            ...next || []
+        ])
+    ].sort();
+}
+function reloadSurvivingPackage(instruction) {
+    if (!instruction) return;
+    if ("content-scripts" === instruction.type || 'page' === instruction.type) return instruction;
+    const entries = instruction.changedContentScriptEntries || [];
+    if (0 === entries.length) return;
+    return {
+        ...instruction,
+        type: "content-scripts",
+        label: formatReloadContextLabel("content_script", instruction.changedAssets || [])
+    };
+}
+function mergeInstructions(previous, next) {
+    if (!previous) return next;
+    if (!next) return previous;
+    const entries = union(previous.changedContentScriptEntries, next.changedContentScriptEntries);
+    const scriptFiles = union(previous.changedScriptFiles, next.changedScriptFiles);
+    if (0 === entries.length) return scriptFiles.length > 0 ? {
+        ...next,
+        changedScriptFiles: scriptFiles
+    } : next;
+    const base = "content-scripts" === next.type ? next : previous;
+    return {
+        ...base,
+        changedContentScriptEntries: entries,
+        ...scriptFiles.length > 0 ? {
+            changedScriptFiles: scriptFiles
+        } : {}
+    };
+}
 class SafariDevPlugin {
     packager;
     static name = 'safari-dev';
@@ -2683,23 +2726,45 @@ class SafariDevPlugin {
     active = false;
     pending = null;
     idleWaiters = [];
+    reloadBroker;
     constructor(packager){
         this.packager = packager;
     }
+    setReloadBroker(broker) {
+        this.reloadBroker = broker;
+    }
     apply(compiler) {
+        const changedSources = compiler.hooks?.watchRun ? createChangedSourcesTracker(compiler) : void 0;
         compiler.hooks.done.tapPromise(SafariDevPlugin.name, async (stats)=>{
             const compilation = stats.compilation;
             const hasErrors = compilation.errors && compilation.errors.length > 0;
             if (hasErrors) return void this.emitter.emit('error', {
                 errors: compilation.errors.map((e)=>'string' == typeof e ? e : e.message || String(e))
             });
+            const outputPath = String(compilation.options?.output?.path || '');
+            const contextDir = String(compilation.options?.context || '');
+            let instruction;
+            if (!this.firstRun && changedSources) {
+                const { forcedFull, changedSources: sources } = changedSources.snapshot();
+                instruction = reloadSurvivingPackage(classifyReloadFromSources({
+                    changedSources: sources,
+                    forcedFull,
+                    getContentScriptCount: ()=>readContentScriptCount(compilation, outputPath),
+                    getSourceFeatureIndex: ()=>buildSourceFeatureIndex(compilation, contextDir),
+                    outputPath
+                }));
+            }
             const target = {
-                outputPath: String(compilation.options?.output?.path || ''),
-                contextDir: String(compilation.options?.context || '')
+                outputPath,
+                contextDir,
+                instruction
             };
             if (this.firstRun) return void await this.runOne(target, 'full');
             if (this.active) {
-                this.pending = target;
+                this.pending = {
+                    ...target,
+                    instruction: mergeInstructions(this.pending?.instruction, target.instruction)
+                };
                 return;
             }
             this.active = true;
@@ -2736,6 +2801,10 @@ class SafariDevPlugin {
             return;
         }
         if (wasFirstRun) this.firstRun = false;
+        if (!wasFirstRun && target.instruction && this.reloadBroker) await dispatchReload(target.instruction, {
+            broker: this.reloadBroker,
+            producerRestartExpected: true
+        });
         this.emitter.emit('compiled', {
             outputPath: target.outputPath,
             contextDir: target.contextDir,

package/dist/950~0.mjs

@@ -84,10 +84,11 @@ function buildAssetsTree(stats) {
     const assets = statsJson?.assets || [];
     return getAssetsTree(assets);
 }
-function buildComplete(browser, distDisplayPath, totalBytes) {
+function buildComplete(browser, distDisplayPath, totalBytes, mode) {
     const noun = artifactNoun(String(browser));
+    const builtFor = 'development' === mode ? 'built for development in' : 'none' === mode ? 'built in' : 'built for production in';
     const size = 'number' == typeof totalBytes && totalBytes > 0 ? ` (${getHumanSize(totalBytes)})` : '';
-    return `${getLoggingPrefix('success')} ${noun} built for production in ${pintor.underline(distDisplayPath)}${size}.`;
+    return `${getLoggingPrefix('success')} ${noun} ${builtFor} ${pintor.underline(distDisplayPath)}${size}.`;
 }
 function platformDocsUrl() {
     return String(process.env.EXTENSION_DEV_DOCS_URL || '').trim().replace(/\/+$/, '');

package/dist/command-preview.d.ts

@@ -1,8 +1,4 @@
 import type { PreviewOptions } from './types.js';
-/**
- * Resolved browser launch options returned by extensionPreview.
- * The caller is responsible for actually launching the browser.
- */
 export interface ResolvedPreviewOptions {
     browser: string;
     outPath: string;
@@ -29,9 +25,5 @@ export interface ResolvedPreviewOptions {
     logUrl?: string;
     logTab?: number | string;
 }
-/**
- * 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/control-bridge/actions-file.d.ts

@@ -28,7 +28,6 @@ export declare class ActionsFileWriter implements ActionsSink {
     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;

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

@@ -10,7 +10,7 @@ export interface BridgeConnection {
 export interface BridgeBrokerOptions {
     instanceId: string;
     runId: string;
-    engine?: 'chromium' | 'firefox';
+    engine?: 'chromium' | 'firefox' | 'webkit';
     ring?: LogRingBuffer;
     file?: LogsFileWriter;
     allowControl?: boolean;
@@ -22,6 +22,7 @@ export interface BridgeBrokerOptions {
     setTimer?: (fn: () => void, ms: number) => ReturnType<typeof setTimeout>;
     clearTimer?: (handle: ReturnType<typeof setTimeout>) => void;
     onExecutorAttached?: () => void;
+    onExecutorDetached?: () => void;
 }
 export { CLOSE_BAD_HELLO, CLOSE_BAD_INSTANCE, CLOSE_CONTROL_UNAVAILABLE, CLOSE_SLOW_CONSUMER } from './contracts.js';
 export declare const DEFAULT_CMD_TIMEOUT_MS = 5000;
@@ -47,8 +48,8 @@ export declare class BridgeBroker {
     private producerEverConnected;
     private readonly sessionStartedAt;
     private lastUndeliveredWarnKind;
-    /** Fired once, on the first producer hello, to stamp ready.json. */
     private readonly onExecutorAttached?;
+    private readonly onExecutorDetached?;
     private lastProducerDisconnectedAt;
     private lastStaleHelloAt;
     private pendingReload?;
@@ -66,10 +67,11 @@ export declare class BridgeBroker {
         changedFiles?: string[];
         changedScriptFiles?: string[];
     }): number;
-    undeliveredReloadWarning(): string | null;
+    undeliveredReloadWarning(options?: {
+        producerRestartExpected?: boolean;
+    }): string | null;
     pingProducers(): number;
     ingestLog(incoming: IncomingLogEvent): void;
-    /** At most 3 stale-producer resync reloads per rolling minute. */
     private allowStaleProducerResync;
     private onHello;
     private diagnoseExecutorAbsence;

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

@@ -4,26 +4,17 @@ export interface ReadyContractInfo {
     controlPort: number;
     instanceId: string;
     runId: string;
-    /** Ready-contract version, `ReadyMetadata['schemaVersion']` on current engines. */
     schemaVersion?: number;
-    /** Result-envelope capability advertisement, `1` on current engines. */
     schema?: number;
     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;
-    /** When the compile finished (ISO), the meaning of `status: 'ready'`. */
     compiledAt?: string;
-    /** When the extension's service worker attached to the control channel (ISO). */
     executorAttachedAt?: string;
-    /** `'attached'` once the SW has connected; absent while still launching. */
     runtime?: string;
-    /** Last contract write time (ISO). */
     ts?: string;
     binary?: string;
     binaryProvenance?: string;
@@ -55,7 +46,6 @@ export declare class BridgeConsumer {
     private timer;
     private lastCloseInfo;
     constructor(options: ConsumerOptions);
-    /** Why the last socket closed; null until a close has happened. */
     get lastClose(): ConsumerCloseInfo | null;
     start(): void;
     close(): void;

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

@@ -40,21 +40,7 @@ export interface BridgeTarget {
     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 {
@@ -68,7 +54,7 @@ export interface ReadyFrame {
     type: 'ready';
     runId: string;
     bufferedFrom?: number;
-    engine?: 'chromium' | 'firefox';
+    engine?: 'chromium' | 'firefox' | 'webkit';
     capabilities?: {
         eval?: boolean;
         storage?: boolean;
@@ -115,27 +101,12 @@ export interface ResultFrame {
         code?: BridgeRefusalCode;
     };
 }
-/**
- * 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[];
-    /** Emitted scripts/ bundles the SW should replay its executeScript calls for. */
     changedScriptFiles?: string[];
 }
 export interface ReloadAckFrame {
@@ -143,15 +114,6 @@ export interface ReloadAckFrame {
     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';
 }
@@ -159,11 +121,7 @@ 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";
-/** The hello named an instanceId from a previous dev session. */
 export declare const CLOSE_BAD_INSTANCE = 4001;
-/** The hello was malformed: wrong envelope version, or an unknown role. */
 export declare const CLOSE_BAD_HELLO = 4002;
-/** A controller dialed a session started without `--allow-control`. */
 export declare const CLOSE_CONTROL_UNAVAILABLE = 4003;
-/** The socket fell far enough behind that it was dropped to protect the broker. */
 export declare const CLOSE_SLOW_CONSUMER = 4008;

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

@@ -25,6 +25,5 @@ export declare class LogsFileWriter {
     private maybeNoteDrops;
     private writeHeader;
     private rotatedName;
-    /** Shift generations: drop the oldest, age each, move current → .1 */
     private rotate;
 }

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

@@ -1,22 +1,13 @@
-/** Increasing verbosity; a level selects itself plus everything more severe. */
 export declare const LOG_LEVEL_ORDER: readonly ['error', 'warn', 'info', 'debug', 'trace'];
 export type LogLevelFilter = (typeof LOG_LEVEL_ORDER)[number] | 'all' | 'off' | (string & {});
 export interface LogQuery {
-    /** One context, a comma-separated list, an array, or 'all'. */
     context?: string | string[];
-    /** Minimum severity. 'all' and 'off' select every level. */
     level?: LogLevelFilter;
-    /** Only structured dx.signal diagnostics. */
     signalsOnly?: boolean;
-    /** Only events after this point: a sequence number, or an ISO timestamp
-     * compared against the event's own clock. */
     since?: number | string;
-    /** Glob (`*` = any run of chars) or plain substring over url then hostname. */
     url?: string;
-    /** Only events carrying this tab id. */
     tab?: number | string;
 }
-/** A bridge log line as read off disk: dynamic, so the probed fields only. */
 export interface LogEventLike {
     type?: unknown;
     eventType?: unknown;
@@ -30,7 +21,6 @@ export interface LogEventLike {
     tabId?: unknown;
 }
 export declare function logLevelRank(level: string): number;
-/** How a `since` value is read: a sequence number, or a point in time. */
 export type LogSince = {
     seq: number;
 } | {
@@ -38,11 +28,5 @@ export type LogSince = {
 };
 export declare function parseLogSince(value: unknown): LogSince | null | undefined;
 export declare function isAfterSince(event: LogEventLike, since: LogSince): boolean;
-/** True when the event passes every clause of the query. */
 export declare function matchesLogQuery(event: LogEventLike, query: LogQuery): boolean;
-/**
- * One-shot read of a session's logs.ndjson. Returns an empty array when the
- * session has never written one: an absent file is "nothing logged yet", and
- * making that a throw would force every caller to guard it.
- */
 export declare function readLogEvents(projectPath: string, browser?: string, query?: LogQuery): LogEventLike[];