@orkestrel/browser 0.0.23 → 0.0.25

package/dist/src/server/index.d.cts

@@ -22,9 +22,12 @@ import type { ChildProcess } from 'node:child_process';
 import type { EmitterErrorHandler } from '@orkestrel/emitter';
 import type { EmitterHooks } from '@orkestrel/emitter';
 import type { EmitterInterface } from '@orkestrel/emitter';
+import type { PoolToken } from '@orkestrel/pool';
 import type { Readable } from 'node:stream';
 import type { Result } from '@orkestrel/contract';
 import type { StdioServerOptions } from '@orkestrel/mcp/server';
+import type { ToolDefinition } from '@orkestrel/tool';
+import type { ToolInterface } from '@orkestrel/tool';
 
 /**
  * Discovers, launches, connects to, and owns Chromium-family browser sessions.
@@ -157,7 +160,13 @@ export declare const BROWSER_JOURNEY_SNAPSHOT_FILE = "journey.json";
  */
 export declare const BROWSER_KILL_GRACE_MS = 3000;
 
-/** Lists the flags always passed to a launched browser process, alongside the caller's own. */
+/**
+ * Lists the flags always passed to a launched browser process, alongside the caller's own.
+ *
+ * @remarks
+ * Disables account sync so extension installs cannot reset URL loader factories during page imports.
+ * Edge can still sign a fresh Windows profile in to the operating-system account.
+ */
 export declare const BROWSER_LAUNCH_ARGS: readonly string[];
 
 /**
@@ -185,12 +194,27 @@ export declare const BROWSER_RUN_DIRECTORY = "runs";
 /** Names the persisted run snapshot. */
 export declare const BROWSER_RUN_FILE = "run.json";
 
+/** Names the refusal when every browser is admitted to a holder. */
+export declare const BROWSER_SERVER_BUSY = "BROWSER_SERVER_BUSY";
+
+/** Sets the default context capacity per browser, including the shared holder. */
+export declare const BROWSER_SERVER_CONTEXTS = 2;
+
+/** Limits context capacity to the largest measured per-browser count. */
+export declare const BROWSER_SERVER_CONTEXTS_LIMIT = 4;
+
+/** Defines the holder tools independently of the shared browser's vocabulary. */
+export declare const BROWSER_SERVER_COPY: Readonly<Record<BrowserServerToolName, ToolDefinition>>;
+
 /** Names the notice that a browser and its session state were lost. */
 export declare const BROWSER_SERVER_CRASH = "BROWSER_SERVER_CRASH";
 
 /** Names the diagnostic when the warm floor spends its restart bound. */
 export declare const BROWSER_SERVER_EXHAUSTED = "BROWSER_SERVER_EXHAUSTED";
 
+/** Names the refusal for an unknown or ended holder. */
+export declare const BROWSER_SERVER_HOLDER = "BROWSER_SERVER_HOLDER";
+
 /** Names a failed attempt to warm a browser. */
 export declare const BROWSER_SERVER_LAUNCH = "BROWSER_SERVER_LAUNCH";
 
@@ -482,7 +506,7 @@ export declare interface BrowserInterface {
  * Creates a browser a browse server connects while warming its pool.
  *
  * @param options - The launch the server composes: `headless`, `executable`, the profile it
- *   owns, `cdp.discover` set to `false`, and the signal its `destroy()` aborts
+ *   owns, the optional `viewport`, `cdp.discover` set to `false`, and the signal its `destroy()` aborts
  * @returns A browser whose `connect()` launches it
  */
 export declare type BrowserLaunchFunction = (options: BrowserOptions) => BrowserInterface;
@@ -499,21 +523,28 @@ export declare type BrowserLaunchFunction = (options: BrowserOptions) => Browser
  * absent. After the launch, a tool the toolset's manager adds under another name, such as a page
  * tool it adopts, is mirrored as a dispatcher with that tool's definition, and the mirror is
  * removed when the toolset withdraws the tool, so the server's tool list changes and a subscribed
- * client is notified. Startup warms the pool and leases one validated browser. The legacy
- * handshake and every tool call await that setup; concurrent callers share a replacement lease.
+ * client is notified. The server also advertises `acquire`, `execute`, `tools`, and `destroy` with
+ * `BROWSER_SERVER_COPY`. Startup warms the pool and assigns a prepared context to the shared holder. The legacy
+ * handshake and browser calls await that setup. Named holders each own a lease, a pending grant,
+ * and loss notices; concurrent calls on a holder share its replacement grant. Ending a holder
+ * closes its context and releases its lease, and admission counts that holder until disposal settles.
  * A launch creates `ROOT/.profiles/PID-UUID/` exclusively, connects a browser that never attaches to an
  * existing endpoint, opens one page in an isolated context, and constructs the page toolset with
  * that context and the file journey and run stores under the root, on a manager the toolset owns.
  * A dispatcher forwards its arguments and the call's context, signal included, to the toolset's
  * manager and returns that manager's value, or rejects with its failure message; a text value
  * reaches the client as one text block rather than as its JSON text.
- * A disconnect or current-page crash retires its slot. A failed call receives a liveness ping;
+ * A disconnect retires its browser and every hosted generation. A current-page crash retires only
+ * that holder's context. A failed call receives a liveness ping;
  * loss makes its outcome unresolved, while a known success remains successful. Pending losses
  * prefix the next outcome on a successor, or a refusal, and calls are never repeated.
+ * Concurrent checks share one ping per slot. Cancelling a call ends only its wait; the ping keeps
+ * its deadline and records loss for the next call.
  *
  * `start()` serves stdio and destroys the server at the end of its input, on `SIGINT`, and on
  * `SIGTERM`. `destroy()` stops reading requests and removes every dispatcher, then destroys every
- * slot through the pool — its toolset, which aborts the active replay, then its browser, then its
+ * slot through the pool — each toolset, which aborts its active replay, then its context and downloads,
+ * then its browser and its
  * profile — and rechecks the profile folders this server made or kept.
  *
  * Chromium on Linux refuses to start as the root user unless its sandbox is disabled, so a server
@@ -545,7 +576,7 @@ export declare class BrowserMCPServer implements BrowserMCPServerInterface {
 export declare interface BrowserMCPServerInterface {
     /**
      * Serves stdio, sweeps the profiles ended servers left, warms the pool, and resolves after the
-     * session leases a warm browser; the legacy handshake and every tool call await the same setup.
+     * shared holder consumes a prepared context on a warm browser; the legacy handshake and every tool call await the same setup.
      * Rejects with `BROWSER_SERVER_UNAVAILABLE` when no browser can serve and with
      * `BROWSER_TOOLSET_ENDED` after `destroy()`, and resolves when `destroy()` interrupts setup.
      */
@@ -566,6 +597,8 @@ export declare interface BrowserMCPServerInterface {
  *   `true`
  * - `executable` — the path of the Chromium executable the server launches. Default: the browser
  *   `findSystemBrowser` finds
+ * - `viewport` — the default viewport for every page in each browser's isolated context;
+ *   omission keeps the browser's launch default
  * - `readonly` — if `true`, refuses `record`, `save`, `edit`, and `forget`, and `replay` still writes runs;
  *   if `false` or omitted, every tool runs
  * - `launch` — creates each browser the pool warms. Default: `createBrowser`
@@ -573,18 +606,22 @@ export declare interface BrowserMCPServerInterface {
  *   `input` destroys the server. Default: `process.stdin` and `process.stdout`
  * - `pool.size` — the integer number of browsers kept warm, from 1 through
  *   `BROWSER_SERVER_POOL_LIMIT`. Default: `BROWSER_SERVER_POOL_SIZE`.
+ * - `pool.contexts` — the integer context capacity per browser, shared holder included, from 1
+ *   through `BROWSER_SERVER_CONTEXTS_LIMIT`. Default: `BROWSER_SERVER_CONTEXTS`.
  * - `log` — receives diagnostic lines. Default: `process.stderr`
- * @throws Thrown when `pool.size` is outside that range or is not an integer, with `BROWSER_SERVER_OPTIONS`
+ * @throws Thrown when `pool.size` or `pool.contexts` is outside its range or is not an integer, with `BROWSER_SERVER_OPTIONS`
  */
 export declare interface BrowserMCPServerOptions {
     readonly root?: string;
     readonly headless?: boolean;
     readonly executable?: string;
+    readonly viewport?: BrowserViewport;
     readonly readonly?: boolean;
     readonly launch?: BrowserLaunchFunction;
     readonly stdio?: StdioServerOptions;
     readonly pool?: {
         readonly size?: number;
+        readonly contexts?: number;
     };
     readonly log?: NodeJS.WritableStream;
 }
@@ -653,20 +690,65 @@ export declare interface BrowserProfileResult {
     readonly temporary: boolean;
 }
 
-/** Holds one warm browser a browse server owns: the browser, its profile, its isolated context, and its started toolset. */
+/** Describes the JSON catalog returned by the holder tools. */
+export declare interface BrowserServerCatalog {
+    readonly holder: string;
+    readonly tools: readonly ToolDefinition[];
+}
+
+/** Holds one prepared or assigned context generation and its downloads directory. */
+export declare interface BrowserServerContext {
+    readonly context: BrowserContextInterface;
+    readonly toolset: BrowserToolsetInterface;
+    readonly directory: string;
+}
+
+/** Identifies one admitted browser lifetime independently of its current pool token. */
+export declare interface BrowserServerHolder {
+    readonly id: string;
+    readonly purpose: string;
+    readonly abort: AbortController;
+}
+
+/** Binds a holder generation to the exact browser lease reserved for its lifetime. */
+export declare interface BrowserServerLease {
+    readonly token: PoolToken<BrowserSlot>;
+    readonly generation: BrowserServerContext;
+}
+
+/** Records a lost generation's cause and its own last URL. */
+export declare interface BrowserServerLoss {
+    readonly cause: unknown;
+    readonly url: string;
+}
+
+/** Binds shared catalog subscriptions to the exact generation that published them. */
+export declare interface BrowserServerMirror {
+    readonly lease: BrowserServerLease;
+    readonly added: (tool: ToolInterface) => void;
+    readonly removed: (tool: ToolInterface) => void;
+    readonly cleared: (tools: readonly ToolInterface[]) => void;
+}
+
+/** Names the server tools that manage independent browser holders. */
+export declare type BrowserServerToolName = 'acquire' | 'execute' | 'tools' | 'destroy';
+
+/** Holds page subscriptions for one prepared or assigned context generation. */
+export declare interface BrowserServerWatch {
+    readonly page: (page: BrowserPageInterface) => void;
+    readonly crashes: ReadonlyMap<BrowserPageInterface, () => void>;
+}
+
+/** Holds one pooled browser and its exclusively owned profile. */
 export declare interface BrowserSlot {
     readonly browser: BrowserInterface;
     readonly profile: string;
-    readonly context: BrowserContextInterface;
-    readonly toolset: BrowserToolsetInterface;
 }
 
 /** Holds the listeners and resolver of one browser slot's loss watch. */
 export declare interface BrowserSlotWatch {
     readonly resolve: (cause: unknown) => void;
     readonly disconnect: () => void;
-    readonly page: (page: BrowserPageInterface) => void;
-    readonly crashes: ReadonlyMap<BrowserPageInterface, () => void>;
     readonly subscription: Disposable;
 }
 
@@ -825,6 +907,8 @@ export declare class FileBrowserJourneyStore implements BrowserJourneyStoreInter
 /**
  * Persists runs and captures only in directories allocated by this instance.
  * @remarks Requires an existing root. Reopened stores can read and delete saved runs.
+ * Allocations of one journey share a process-local queue across instances; the filesystem lock
+ * still refuses conflicting mutations and allocations from another process.
  * @example
  * const store = new FileBrowserRunStore({ root: directory })
  * const slot = await store.open('check-ready')
@@ -832,6 +916,7 @@ export declare class FileBrowserJourneyStore implements BrowserJourneyStoreInter
 export declare class FileBrowserRunStore implements BrowserRunStoreInterface {
     #private;
     constructor(options: FileBrowserStoreOptions);
+    snapshot(bytes: Uint8Array, options?: BrowserStoreOptions): Promise<string>;
     open(name: string, options?: BrowserStoreOptions): Promise<BrowserRunSlot>;
     get(name: string, id: string, options?: BrowserStoreOptions): Promise<BrowserRun | undefined>;
     set(run: BrowserRun, options?: BrowserStoreOptions): Promise<void>;
@@ -1003,6 +1088,15 @@ export declare function parseBrowserLockEntry(name: string): number | undefined;
  */
 export declare function parseBrowserProfileRecord(text: string): BrowserProfileRecord | undefined;
 
+/**
+ * Parses positive integer viewport dimensions in WIDTHxHEIGHT form.
+ * @param value - The viewport environment variable, or undefined when unset
+ * @returns The viewport, or undefined when absent or malformed
+ * @example
+ * parseBrowserViewport('1280x720') // { width: 1280, height: 720 }
+ */
+export declare function parseBrowserViewport(value: string | undefined): BrowserViewport | undefined;
+
 /** Probes PATH (`which`/`where`) for every resolvable command name, in the given order. */
 export declare function probePathNames(names: readonly string[], platform: string): readonly string[];
 

package/dist/src/server/index.d.ts

@@ -22,9 +22,12 @@ import type { ChildProcess } from 'node:child_process';
 import type { EmitterErrorHandler } from '@orkestrel/emitter';
 import type { EmitterHooks } from '@orkestrel/emitter';
 import type { EmitterInterface } from '@orkestrel/emitter';
+import type { PoolToken } from '@orkestrel/pool';
 import type { Readable } from 'node:stream';
 import type { Result } from '@orkestrel/contract';
 import type { StdioServerOptions } from '@orkestrel/mcp/server';
+import type { ToolDefinition } from '@orkestrel/tool';
+import type { ToolInterface } from '@orkestrel/tool';
 
 /**
  * Discovers, launches, connects to, and owns Chromium-family browser sessions.
@@ -157,7 +160,13 @@ export declare const BROWSER_JOURNEY_SNAPSHOT_FILE = "journey.json";
  */
 export declare const BROWSER_KILL_GRACE_MS = 3000;
 
-/** Lists the flags always passed to a launched browser process, alongside the caller's own. */
+/**
+ * Lists the flags always passed to a launched browser process, alongside the caller's own.
+ *
+ * @remarks
+ * Disables account sync so extension installs cannot reset URL loader factories during page imports.
+ * Edge can still sign a fresh Windows profile in to the operating-system account.
+ */
 export declare const BROWSER_LAUNCH_ARGS: readonly string[];
 
 /**
@@ -185,12 +194,27 @@ export declare const BROWSER_RUN_DIRECTORY = "runs";
 /** Names the persisted run snapshot. */
 export declare const BROWSER_RUN_FILE = "run.json";
 
+/** Names the refusal when every browser is admitted to a holder. */
+export declare const BROWSER_SERVER_BUSY = "BROWSER_SERVER_BUSY";
+
+/** Sets the default context capacity per browser, including the shared holder. */
+export declare const BROWSER_SERVER_CONTEXTS = 2;
+
+/** Limits context capacity to the largest measured per-browser count. */
+export declare const BROWSER_SERVER_CONTEXTS_LIMIT = 4;
+
+/** Defines the holder tools independently of the shared browser's vocabulary. */
+export declare const BROWSER_SERVER_COPY: Readonly<Record<BrowserServerToolName, ToolDefinition>>;
+
 /** Names the notice that a browser and its session state were lost. */
 export declare const BROWSER_SERVER_CRASH = "BROWSER_SERVER_CRASH";
 
 /** Names the diagnostic when the warm floor spends its restart bound. */
 export declare const BROWSER_SERVER_EXHAUSTED = "BROWSER_SERVER_EXHAUSTED";
 
+/** Names the refusal for an unknown or ended holder. */
+export declare const BROWSER_SERVER_HOLDER = "BROWSER_SERVER_HOLDER";
+
 /** Names a failed attempt to warm a browser. */
 export declare const BROWSER_SERVER_LAUNCH = "BROWSER_SERVER_LAUNCH";
 
@@ -482,7 +506,7 @@ export declare interface BrowserInterface {
  * Creates a browser a browse server connects while warming its pool.
  *
  * @param options - The launch the server composes: `headless`, `executable`, the profile it
- *   owns, `cdp.discover` set to `false`, and the signal its `destroy()` aborts
+ *   owns, the optional `viewport`, `cdp.discover` set to `false`, and the signal its `destroy()` aborts
  * @returns A browser whose `connect()` launches it
  */
 export declare type BrowserLaunchFunction = (options: BrowserOptions) => BrowserInterface;
@@ -499,21 +523,28 @@ export declare type BrowserLaunchFunction = (options: BrowserOptions) => Browser
  * absent. After the launch, a tool the toolset's manager adds under another name, such as a page
  * tool it adopts, is mirrored as a dispatcher with that tool's definition, and the mirror is
  * removed when the toolset withdraws the tool, so the server's tool list changes and a subscribed
- * client is notified. Startup warms the pool and leases one validated browser. The legacy
- * handshake and every tool call await that setup; concurrent callers share a replacement lease.
+ * client is notified. The server also advertises `acquire`, `execute`, `tools`, and `destroy` with
+ * `BROWSER_SERVER_COPY`. Startup warms the pool and assigns a prepared context to the shared holder. The legacy
+ * handshake and browser calls await that setup. Named holders each own a lease, a pending grant,
+ * and loss notices; concurrent calls on a holder share its replacement grant. Ending a holder
+ * closes its context and releases its lease, and admission counts that holder until disposal settles.
  * A launch creates `ROOT/.profiles/PID-UUID/` exclusively, connects a browser that never attaches to an
  * existing endpoint, opens one page in an isolated context, and constructs the page toolset with
  * that context and the file journey and run stores under the root, on a manager the toolset owns.
  * A dispatcher forwards its arguments and the call's context, signal included, to the toolset's
  * manager and returns that manager's value, or rejects with its failure message; a text value
  * reaches the client as one text block rather than as its JSON text.
- * A disconnect or current-page crash retires its slot. A failed call receives a liveness ping;
+ * A disconnect retires its browser and every hosted generation. A current-page crash retires only
+ * that holder's context. A failed call receives a liveness ping;
  * loss makes its outcome unresolved, while a known success remains successful. Pending losses
  * prefix the next outcome on a successor, or a refusal, and calls are never repeated.
+ * Concurrent checks share one ping per slot. Cancelling a call ends only its wait; the ping keeps
+ * its deadline and records loss for the next call.
  *
  * `start()` serves stdio and destroys the server at the end of its input, on `SIGINT`, and on
  * `SIGTERM`. `destroy()` stops reading requests and removes every dispatcher, then destroys every
- * slot through the pool — its toolset, which aborts the active replay, then its browser, then its
+ * slot through the pool — each toolset, which aborts its active replay, then its context and downloads,
+ * then its browser and its
  * profile — and rechecks the profile folders this server made or kept.
  *
  * Chromium on Linux refuses to start as the root user unless its sandbox is disabled, so a server
@@ -545,7 +576,7 @@ export declare class BrowserMCPServer implements BrowserMCPServerInterface {
 export declare interface BrowserMCPServerInterface {
     /**
      * Serves stdio, sweeps the profiles ended servers left, warms the pool, and resolves after the
-     * session leases a warm browser; the legacy handshake and every tool call await the same setup.
+     * shared holder consumes a prepared context on a warm browser; the legacy handshake and every tool call await the same setup.
      * Rejects with `BROWSER_SERVER_UNAVAILABLE` when no browser can serve and with
      * `BROWSER_TOOLSET_ENDED` after `destroy()`, and resolves when `destroy()` interrupts setup.
      */
@@ -566,6 +597,8 @@ export declare interface BrowserMCPServerInterface {
  *   `true`
  * - `executable` — the path of the Chromium executable the server launches. Default: the browser
  *   `findSystemBrowser` finds
+ * - `viewport` — the default viewport for every page in each browser's isolated context;
+ *   omission keeps the browser's launch default
  * - `readonly` — if `true`, refuses `record`, `save`, `edit`, and `forget`, and `replay` still writes runs;
  *   if `false` or omitted, every tool runs
  * - `launch` — creates each browser the pool warms. Default: `createBrowser`
@@ -573,18 +606,22 @@ export declare interface BrowserMCPServerInterface {
  *   `input` destroys the server. Default: `process.stdin` and `process.stdout`
  * - `pool.size` — the integer number of browsers kept warm, from 1 through
  *   `BROWSER_SERVER_POOL_LIMIT`. Default: `BROWSER_SERVER_POOL_SIZE`.
+ * - `pool.contexts` — the integer context capacity per browser, shared holder included, from 1
+ *   through `BROWSER_SERVER_CONTEXTS_LIMIT`. Default: `BROWSER_SERVER_CONTEXTS`.
  * - `log` — receives diagnostic lines. Default: `process.stderr`
- * @throws Thrown when `pool.size` is outside that range or is not an integer, with `BROWSER_SERVER_OPTIONS`
+ * @throws Thrown when `pool.size` or `pool.contexts` is outside its range or is not an integer, with `BROWSER_SERVER_OPTIONS`
  */
 export declare interface BrowserMCPServerOptions {
     readonly root?: string;
     readonly headless?: boolean;
     readonly executable?: string;
+    readonly viewport?: BrowserViewport;
     readonly readonly?: boolean;
     readonly launch?: BrowserLaunchFunction;
     readonly stdio?: StdioServerOptions;
     readonly pool?: {
         readonly size?: number;
+        readonly contexts?: number;
     };
     readonly log?: NodeJS.WritableStream;
 }
@@ -653,20 +690,65 @@ export declare interface BrowserProfileResult {
     readonly temporary: boolean;
 }
 
-/** Holds one warm browser a browse server owns: the browser, its profile, its isolated context, and its started toolset. */
+/** Describes the JSON catalog returned by the holder tools. */
+export declare interface BrowserServerCatalog {
+    readonly holder: string;
+    readonly tools: readonly ToolDefinition[];
+}
+
+/** Holds one prepared or assigned context generation and its downloads directory. */
+export declare interface BrowserServerContext {
+    readonly context: BrowserContextInterface;
+    readonly toolset: BrowserToolsetInterface;
+    readonly directory: string;
+}
+
+/** Identifies one admitted browser lifetime independently of its current pool token. */
+export declare interface BrowserServerHolder {
+    readonly id: string;
+    readonly purpose: string;
+    readonly abort: AbortController;
+}
+
+/** Binds a holder generation to the exact browser lease reserved for its lifetime. */
+export declare interface BrowserServerLease {
+    readonly token: PoolToken<BrowserSlot>;
+    readonly generation: BrowserServerContext;
+}
+
+/** Records a lost generation's cause and its own last URL. */
+export declare interface BrowserServerLoss {
+    readonly cause: unknown;
+    readonly url: string;
+}
+
+/** Binds shared catalog subscriptions to the exact generation that published them. */
+export declare interface BrowserServerMirror {
+    readonly lease: BrowserServerLease;
+    readonly added: (tool: ToolInterface) => void;
+    readonly removed: (tool: ToolInterface) => void;
+    readonly cleared: (tools: readonly ToolInterface[]) => void;
+}
+
+/** Names the server tools that manage independent browser holders. */
+export declare type BrowserServerToolName = 'acquire' | 'execute' | 'tools' | 'destroy';
+
+/** Holds page subscriptions for one prepared or assigned context generation. */
+export declare interface BrowserServerWatch {
+    readonly page: (page: BrowserPageInterface) => void;
+    readonly crashes: ReadonlyMap<BrowserPageInterface, () => void>;
+}
+
+/** Holds one pooled browser and its exclusively owned profile. */
 export declare interface BrowserSlot {
     readonly browser: BrowserInterface;
     readonly profile: string;
-    readonly context: BrowserContextInterface;
-    readonly toolset: BrowserToolsetInterface;
 }
 
 /** Holds the listeners and resolver of one browser slot's loss watch. */
 export declare interface BrowserSlotWatch {
     readonly resolve: (cause: unknown) => void;
     readonly disconnect: () => void;
-    readonly page: (page: BrowserPageInterface) => void;
-    readonly crashes: ReadonlyMap<BrowserPageInterface, () => void>;
     readonly subscription: Disposable;
 }
 
@@ -825,6 +907,8 @@ export declare class FileBrowserJourneyStore implements BrowserJourneyStoreInter
 /**
  * Persists runs and captures only in directories allocated by this instance.
  * @remarks Requires an existing root. Reopened stores can read and delete saved runs.
+ * Allocations of one journey share a process-local queue across instances; the filesystem lock
+ * still refuses conflicting mutations and allocations from another process.
  * @example
  * const store = new FileBrowserRunStore({ root: directory })
  * const slot = await store.open('check-ready')
@@ -832,6 +916,7 @@ export declare class FileBrowserJourneyStore implements BrowserJourneyStoreInter
 export declare class FileBrowserRunStore implements BrowserRunStoreInterface {
     #private;
     constructor(options: FileBrowserStoreOptions);
+    snapshot(bytes: Uint8Array, options?: BrowserStoreOptions): Promise<string>;
     open(name: string, options?: BrowserStoreOptions): Promise<BrowserRunSlot>;
     get(name: string, id: string, options?: BrowserStoreOptions): Promise<BrowserRun | undefined>;
     set(run: BrowserRun, options?: BrowserStoreOptions): Promise<void>;
@@ -1003,6 +1088,15 @@ export declare function parseBrowserLockEntry(name: string): number | undefined;
  */
 export declare function parseBrowserProfileRecord(text: string): BrowserProfileRecord | undefined;
 
+/**
+ * Parses positive integer viewport dimensions in WIDTHxHEIGHT form.
+ * @param value - The viewport environment variable, or undefined when unset
+ * @returns The viewport, or undefined when absent or malformed
+ * @example
+ * parseBrowserViewport('1280x720') // { width: 1280, height: 720 }
+ */
+export declare function parseBrowserViewport(value: string | undefined): BrowserViewport | undefined;
+
 /** Probes PATH (`which`/`where`) for every resolvable command name, in the given order. */
 export declare function probePathNames(names: readonly string[], platform: string): readonly string[];