@orkestrel/browser 0.0.3 → 0.0.6

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

@@ -1,17 +1,23 @@
 import { BrowserContextInterface } from '../core/index.ts';
+import { BrowserContextOptions } from '../core/index.ts';
 import { BrowserError } from '../core/index.ts';
 import { BrowserPageInterface } from '../core/index.ts';
 import { BrowserPageOptions } from '../core/index.ts';
 import { BrowserViewport } from '../core/index.ts';
 import { CDPTarget } from '../core/index.ts';
-import { CDPTransportEventMap } from '../../core/index.ts';
+import { CDPTransportEventMap } from '../core/index.ts';
+import { CDPTransportEventMap as CDPTransportEventMap_2 } from '../../core/index.ts';
 import { CDPTransportInterface } from '../../core/index.ts';
 import { CDPTransportInterface as CDPTransportInterface_2 } from '../core/index.ts';
 import { ChildProcess } from 'node:child_process';
+import { EmitterErrorHandler } from '@orkestrel/emitter';
 import { EmitterHooks } from '@orkestrel/emitter';
 import { EmitterInterface } from '@orkestrel/emitter';
 import { ScreenshotWriterInterface } from '../core/index.ts';
 
+/**
+ * Discovers, launches, connects to, and owns Chromium-family browser sessions.
+ */
 export declare class Browser implements BrowserInterface {
     #private;
     constructor(options?: BrowserOptions);
@@ -19,25 +25,18 @@ export declare class Browser implements BrowserInterface {
     get engine(): BrowserEngine;
     get status(): BrowserStatus;
     get connection(): BrowserConnection | undefined;
+    get owned(): boolean | undefined;
     get connected(): boolean;
     get pid(): number | undefined;
     discover(): Promise<BrowserDiscoveryResult>;
     connect(): Promise<void>;
+    adopt(): void;
     disconnect(): Promise<void>;
     context(index?: number): BrowserContextInterface | undefined;
     contexts(): readonly BrowserContextInterface[];
+    isolate(options?: BrowserContextOptions): Promise<BrowserContextInterface>;
     create(options?: BrowserPageOptions): Promise<BrowserPageInterface>;
     destroy(): Promise<void>;
-    /**
-     * Gracefully shut down the remote browser, whether this instance owns its
-     * process or merely attached to it via CDP.
-     *
-     * @remarks
-     * Sends CDP `Browser.close` best-effort; on an owned browser also awaits
-     * the process's exit (bounded by the kill-escalation grace period,
-     * escalating to a kill only if it does not exit in time). Ends in the
-     * same local-cleanup state as `destroy()`.
-     */
     close(): Promise<void>;
 }
 
@@ -80,12 +79,15 @@ export declare const BROWSER_KILL_GRACE_MS = 3000;
 /** Flags always passed to a launched browser process, alongside the caller's own. */
 export declare const BROWSER_LAUNCH_ARGS: readonly string[];
 
-/** Sentinel result returned by discovery when no browser is reachable. */
-export declare const BROWSER_NOT_FOUND_RESULT: BrowserDiscoveryResult;
-
 /** Bound for the `discover: false` port-occupancy probe before launching — short, since it only needs to detect an already-listening CDP endpoint, not perform full discovery. */
 export declare const BROWSER_PORT_PROBE_TIMEOUT_MS = 200;
 
+/** Machine-readable error-context cause for an owned browser process exiting. */
+export declare const BROWSER_PROCESS_EXIT_CAUSE = "process-exit";
+
+/** Prefix for isolated browser profiles created beneath the operating-system temp directory. */
+export declare const BROWSER_PROFILE_PREFIX = "orkestrel-browser-";
+
 /** Per-OS default Playwright browser cache directory, relative to the home directory (win32 uses `LOCALAPPDATA` directly). */
 export declare const BROWSER_STORE_CACHE_DIRS: Readonly<Record<string, string>>;
 
@@ -101,6 +103,9 @@ export declare const BROWSER_STORE_GLOBS: Readonly<Record<string, string>>;
 /** Name of the top-level Chromium symlink/binary Playwright maintains inside a browser store base. */
 export declare const BROWSER_STORE_LINK_NAME = "chromium";
 
+/** Machine-readable error-context cause for a CDP transport disconnecting while its browser remains alive. */
+export declare const BROWSER_TRANSPORT_LOSS_CAUSE = "transport-loss";
+
 /** Brief defer applied once when a transport loss is observed on an owned process, giving a near-simultaneous process-exit event (which libuv may reap slightly later than the socket close) first say over the diagnosis. */
 export declare const BROWSER_TRANSPORT_LOSS_DEFER_MS = 50;
 
@@ -125,7 +130,7 @@ export declare const BROWSER_WINDOWS_SUFFIXES: readonly string[];
  *   listening there, so a demanded fresh launch never silently attaches to a
  *   stranger browser
  */
-export declare interface BrowserCdpOptions {
+export declare interface BrowserCDPOptions {
     readonly port?: number;
     readonly host?: string;
     readonly endpoint?: string;
@@ -193,6 +198,7 @@ export declare type BrowserEventMap = {
     readonly disconnect: readonly [];
     readonly launch: readonly [engine: BrowserEngine];
     readonly page: readonly [page: BrowserPageInterface];
+    readonly context: readonly [context: BrowserContextInterface];
     readonly error: readonly [error: unknown];
     readonly destroy: readonly [];
 };
@@ -215,22 +221,19 @@ export declare type BrowserEventMap = {
  * **Lifecycle:**
  * - `discover` — passive CDP probe, no side effects
  * - `connect` — establish connection using the strategy above
- * - `disconnect` — detach from the browser. For `'cdp'` and `'persistent'`
- *   connections this closes the client WITHOUT killing the browser process —
- *   a `'persistent'` (profile-backed) launch releases ownership of its process
- *   (no kill, no exit listener) so the browser stays alive for later
- *   reattachment via CDP discovery on the same port. Rejects with the coded
- *   `BrowserConnectionError` for `'launch'` (ephemeral, no profile) sessions —
- *   use `destroy()` instead. An external disconnect (transport loss while the
- *   owned process is still alive, or the owned process exiting on its own)
- *   drives this same released/disconnected state automatically, preceded by
+ * - `adopt` — explicitly assume responsibility for terminating the connected
+ *   browser, including a browser this instance attached to over CDP
+ * - `disconnect` — detach from the browser. For attached CDP connections this
+ *   closes only the client. For owned launches and adopted connections, it
+ *   retains ownership and the endpoint so the same instance can reconnect
+ *   and remains responsible for eventual termination. An external disconnect
+ *   (transport loss while the owned process is still alive, or the owned
+ *   process exiting on its own) drives the disconnected state, preceded by
  *   a coded `error` — `connect()` on the same instance can reattach afterward.
- * - `destroy` — release local resources. On an owned (`'launch'`/`'persistent'`)
- *   browser this closes pages/contexts, then kills the process (SIGTERM,
- *   escalating to SIGKILL). On a `'cdp'`-attached browser this is a LOCAL
- *   DETACH ONLY — the client is closed and local context/page objects are
- *   dropped WITHOUT sending any remote close to the browser, since other
- *   clients may share those targets. Idempotent.
+ * - `destroy` — release local resources. On a launched browser this closes
+ *   pages/contexts, then kills and awaits the process. On an adopted browser
+ *   it sends `Browser.close`. On a merely attached browser this is a LOCAL
+ *   DETACH ONLY because other clients may share its targets. Idempotent.
  * - `close` — graceful REMOTE shutdown: best-effort sends CDP `Browser.close`
  *   (works whether attached or owned), and when owned also awaits the
  *   process's exit (escalating to a kill only if it doesn't exit in time),
@@ -247,21 +250,32 @@ export declare interface BrowserInterface {
     readonly engine: BrowserEngine;
     readonly status: BrowserStatus;
     readonly connection: BrowserConnection | undefined;
+    /**
+     * Whether this instance is responsible for terminating the represented browser.
+     *
+     * @remarks
+     * `true` for launched and explicitly adopted sessions, `false` for an
+     * active attachment, and `undefined` when no session is represented.
+     */
+    readonly owned: boolean | undefined;
     readonly connected: boolean;
     /**
      * The process this instance launched, if any, while it is believed alive.
      *
      * @remarks
-     * Remains readable after a persistent disconnect-release (the process
-     * keeps running, detached from this instance) until `destroy()` or an
+     * Remains readable after a persistent disconnect (the process keeps
+     * running, detached from the transport) until `destroy()` or an
      * observed process exit clears it.
      */
     readonly pid: number | undefined;
     discover(): Promise<BrowserDiscoveryResult>;
     connect(): Promise<void>;
+    /** Assume responsibility for terminating the currently connected browser. */
+    adopt(): void;
     disconnect(): Promise<void>;
     context(index?: number): BrowserContextInterface | undefined;
     contexts(): readonly BrowserContextInterface[];
+    isolate(options?: BrowserContextOptions): Promise<BrowserContextInterface>;
     create(options?: BrowserPageOptions): Promise<BrowserPageInterface>;
     destroy(): Promise<void>;
     close(): Promise<void>;
@@ -279,6 +293,7 @@ export declare class BrowserNotConnectedError extends BrowserError {
  *
  * @remarks
  * - `on` — initial event listeners wired at construction
+ * - `error` — observer error handler forwarded to the emitter
  * - `headless` — launch in headless mode (default `true`; ignored for CDP connections)
  * - `executable` — absolute path to a browser executable; when provided, skips
  *   system browser discovery and launches this binary directly
@@ -297,10 +312,11 @@ export declare class BrowserNotConnectedError extends BrowserError {
  */
 export declare interface BrowserOptions {
     readonly on?: EmitterHooks<BrowserEventMap>;
+    readonly error?: EmitterErrorHandler;
     readonly headless?: boolean;
     readonly executable?: string;
     readonly profile?: string;
-    readonly cdp?: BrowserCdpOptions;
+    readonly cdp?: BrowserCDPOptions;
     readonly timeout?: number;
     readonly viewport?: BrowserViewport;
     readonly signal?: AbortSignal;
@@ -309,11 +325,24 @@ export declare interface BrowserOptions {
     readonly browsers?: SystemBrowserOptions;
 }
 
+/**
+ * Resolved browser profile directory used for a Chromium-family launch.
+ *
+ * @remarks
+ * `temporary` is true only for an isolated profile created by
+ * {@link createBrowserProfile}; caller-supplied persistent profiles are
+ * never removed by the library.
+ */
+export declare interface BrowserProfileResult {
+    readonly path: string;
+    readonly temporary: boolean;
+}
+
 /** Lifecycle status of a browser wrapper. */
 export declare type BrowserStatus = 'idle' | 'connecting' | 'connected' | 'disconnected' | 'error';
 
 /** Classify a `/json/version` `Browser` string into a {@link BrowserEngine} (`Edg/` → edge, `Chrome/` → chrome, else chromium). */
-export declare function browserToEngine(browser: string): BrowserEngine;
+export declare function browserToEngine(browser?: string): BrowserEngine;
 
 /**
  * Create a raw-CDP Browser façade.
@@ -331,6 +360,14 @@ export declare function browserToEngine(browser: string): BrowserEngine;
  */
 export declare function createBrowser(options?: BrowserOptions): BrowserInterface;
 
+/**
+ * Resolve a persistent caller profile or create an isolated temporary one.
+ *
+ * @param path - Optional caller-owned persistent user-data directory
+ * @returns The resolved profile and whether the library owns its lifecycle
+ */
+export declare function createBrowserProfile(path?: string): Promise<BrowserProfileResult>;
+
 /**
  * Create a Node `WebSocket`-backed CDP transport.
  *
@@ -360,7 +397,7 @@ export declare function defaultStoreBases(env: Readonly<Record<string, string |
  * @param host - Host the browser exposes its CDP endpoint on (default `127.0.0.1`)
  * @returns Normalized CDP targets
  */
-export declare function fetchCdpTargets(port: number, timeout: number, host?: string): Promise<readonly CDPTarget[]>;
+export declare function fetchCDPTargets(port: number, timeout: number, host?: string): Promise<readonly CDPTarget[]>;
 
 /** Check the env-override keys (`PLAYWRIGHT_EXECUTABLE_PATH`, `CHROME_PATH`) in order, returning every one that exists. */
 export declare function findAllEnvOverrides(env: Readonly<Record<string, string | undefined>>): readonly string[];
@@ -467,6 +504,18 @@ export declare function probeAllPathNames(names: readonly string[], platform: st
 /** Probe PATH (`which`/`where`) for the first resolvable command name. */
 export declare function probePathNames(names: readonly string[], platform: string): string | undefined;
 
+/**
+ * Remove a library-owned isolated browser profile.
+ *
+ * @remarks
+ * The path must remain a direct child of the operating-system temp directory
+ * with {@link BROWSER_PROFILE_PREFIX}; this defensive check prevents a
+ * malformed profile value from widening recursive deletion.
+ *
+ * @param profile - Resolved profile lifecycle result
+ */
+export declare function removeBrowserProfile(profile: BrowserProfileResult): Promise<void>;
+
 /**
  * One discovered browser executable on this machine.
  *
@@ -518,32 +567,21 @@ export declare interface SystemBrowserOptions {
  *
  * @throws When the endpoint does not become ready before the timeout
  */
-export declare function waitForCdpReady(port: number, timeout: number, host?: string): Promise<string>;
+export declare function waitForCDPReady(port: number, timeout: number, host?: string, signal?: AbortSignal): Promise<string>;
 
 /**
- * `@orkestrel/websocket`-backed {@link CDPTransportInterface} — the dumb text
- * pipe a {@link import('@src/core').CDPClientInterface} sends and receives
- * JSON-RPC frames over.
+ * `@orkestrel/websocket`-backed raw CDP text transport.
  *
  * @remarks
- * `start()` hand-rolls the RFC 6455 client handshake: it opens a `node:http`
- * `GET` carrying `Connection: Upgrade` / `Upgrade: websocket` / a random
- * `Sec-WebSocket-Key` / `Sec-WebSocket-Version`, awaits the client `'upgrade'`
- * event, and validates `Sec-WebSocket-Accept === computeWebSocketAccept(key)`
- * — a mismatch (or a connection/request error, or a timeout) rejects `start()`
- * with a coded {@link BrowserConnectionError} and cleans up the socket. On
- * success it wraps the raw upgraded socket in `createNodeWebSocket({ socket,
- * head })` (CLIENT mode — no `key` — so outgoing frames are masked per RFC
- * 6455 §5.3) and bridges its `message`/`close`/`error` events onto this
- * transport's emitter. `start()` opens a fresh socket each call (safe to call
- * again after `close()` — a new request/socket/NodeWebSocket triple is
- * created every time, which is what `CDPClient.reconnect()` depends on). CDP
- * frames are text-only, so `message` always carries a `string`.
+ * Performs and validates the RFC 6455 HTTP upgrade, then delegates frame
+ * handling to `@orkestrel/websocket`. Concurrent and repeated `start()` /
+ * `close()` calls share their active transition, and a later `start()` opens a
+ * fresh socket after the prior one closes.
  */
 export declare class WebSocketCDPTransport implements CDPTransportInterface {
     #private;
     constructor(options: WebSocketCDPTransportOptions);
-    get emitter(): EmitterInterface<CDPTransportEventMap>;
+    get emitter(): EmitterInterface<CDPTransportEventMap_2>;
     start(): Promise<void>;
     send(data: string): Promise<void>;
     close(): Promise<void>;
@@ -553,10 +591,14 @@ export declare class WebSocketCDPTransport implements CDPTransportInterface {
  * Options for creating a WebSocketCDPTransport.
  *
  * @remarks
+ * - `on` — initial event listeners wired at construction
+ * - `error` — observer error handler forwarded to the emitter
  * - `url` — the CDP WebSocket debugger URL to connect to
  * - `timeout` — ms before the connection attempt fails (default from constants)
  */
 export declare interface WebSocketCDPTransportOptions {
+    readonly on?: EmitterHooks<CDPTransportEventMap>;
+    readonly error?: EmitterErrorHandler;
     readonly url: string;
     readonly timeout?: number;
 }

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

@@ -1,17 +1,23 @@
 import { BrowserContextInterface } from '../core/index.ts';
+import { BrowserContextOptions } from '../core/index.ts';
 import { BrowserError } from '../core/index.ts';
 import { BrowserPageInterface } from '../core/index.ts';
 import { BrowserPageOptions } from '../core/index.ts';
 import { BrowserViewport } from '../core/index.ts';
 import { CDPTarget } from '../core/index.ts';
-import { CDPTransportEventMap } from '../../core/index.ts';
+import { CDPTransportEventMap } from '../core/index.ts';
+import { CDPTransportEventMap as CDPTransportEventMap_2 } from '../../core/index.ts';
 import { CDPTransportInterface } from '../../core/index.ts';
 import { CDPTransportInterface as CDPTransportInterface_2 } from '../core/index.ts';
 import { ChildProcess } from 'node:child_process';
+import { EmitterErrorHandler } from '@orkestrel/emitter';
 import { EmitterHooks } from '@orkestrel/emitter';
 import { EmitterInterface } from '@orkestrel/emitter';
 import { ScreenshotWriterInterface } from '../core/index.ts';
 
+/**
+ * Discovers, launches, connects to, and owns Chromium-family browser sessions.
+ */
 export declare class Browser implements BrowserInterface {
     #private;
     constructor(options?: BrowserOptions);
@@ -19,25 +25,18 @@ export declare class Browser implements BrowserInterface {
     get engine(): BrowserEngine;
     get status(): BrowserStatus;
     get connection(): BrowserConnection | undefined;
+    get owned(): boolean | undefined;
     get connected(): boolean;
     get pid(): number | undefined;
     discover(): Promise<BrowserDiscoveryResult>;
     connect(): Promise<void>;
+    adopt(): void;
     disconnect(): Promise<void>;
     context(index?: number): BrowserContextInterface | undefined;
     contexts(): readonly BrowserContextInterface[];
+    isolate(options?: BrowserContextOptions): Promise<BrowserContextInterface>;
     create(options?: BrowserPageOptions): Promise<BrowserPageInterface>;
     destroy(): Promise<void>;
-    /**
-     * Gracefully shut down the remote browser, whether this instance owns its
-     * process or merely attached to it via CDP.
-     *
-     * @remarks
-     * Sends CDP `Browser.close` best-effort; on an owned browser also awaits
-     * the process's exit (bounded by the kill-escalation grace period,
-     * escalating to a kill only if it does not exit in time). Ends in the
-     * same local-cleanup state as `destroy()`.
-     */
     close(): Promise<void>;
 }
 
@@ -80,12 +79,15 @@ export declare const BROWSER_KILL_GRACE_MS = 3000;
 /** Flags always passed to a launched browser process, alongside the caller's own. */
 export declare const BROWSER_LAUNCH_ARGS: readonly string[];
 
-/** Sentinel result returned by discovery when no browser is reachable. */
-export declare const BROWSER_NOT_FOUND_RESULT: BrowserDiscoveryResult;
-
 /** Bound for the `discover: false` port-occupancy probe before launching — short, since it only needs to detect an already-listening CDP endpoint, not perform full discovery. */
 export declare const BROWSER_PORT_PROBE_TIMEOUT_MS = 200;
 
+/** Machine-readable error-context cause for an owned browser process exiting. */
+export declare const BROWSER_PROCESS_EXIT_CAUSE = "process-exit";
+
+/** Prefix for isolated browser profiles created beneath the operating-system temp directory. */
+export declare const BROWSER_PROFILE_PREFIX = "orkestrel-browser-";
+
 /** Per-OS default Playwright browser cache directory, relative to the home directory (win32 uses `LOCALAPPDATA` directly). */
 export declare const BROWSER_STORE_CACHE_DIRS: Readonly<Record<string, string>>;
 
@@ -101,6 +103,9 @@ export declare const BROWSER_STORE_GLOBS: Readonly<Record<string, string>>;
 /** Name of the top-level Chromium symlink/binary Playwright maintains inside a browser store base. */
 export declare const BROWSER_STORE_LINK_NAME = "chromium";
 
+/** Machine-readable error-context cause for a CDP transport disconnecting while its browser remains alive. */
+export declare const BROWSER_TRANSPORT_LOSS_CAUSE = "transport-loss";
+
 /** Brief defer applied once when a transport loss is observed on an owned process, giving a near-simultaneous process-exit event (which libuv may reap slightly later than the socket close) first say over the diagnosis. */
 export declare const BROWSER_TRANSPORT_LOSS_DEFER_MS = 50;
 
@@ -125,7 +130,7 @@ export declare const BROWSER_WINDOWS_SUFFIXES: readonly string[];
  *   listening there, so a demanded fresh launch never silently attaches to a
  *   stranger browser
  */
-export declare interface BrowserCdpOptions {
+export declare interface BrowserCDPOptions {
     readonly port?: number;
     readonly host?: string;
     readonly endpoint?: string;
@@ -193,6 +198,7 @@ export declare type BrowserEventMap = {
     readonly disconnect: readonly [];
     readonly launch: readonly [engine: BrowserEngine];
     readonly page: readonly [page: BrowserPageInterface];
+    readonly context: readonly [context: BrowserContextInterface];
     readonly error: readonly [error: unknown];
     readonly destroy: readonly [];
 };
@@ -215,22 +221,19 @@ export declare type BrowserEventMap = {
  * **Lifecycle:**
  * - `discover` — passive CDP probe, no side effects
  * - `connect` — establish connection using the strategy above
- * - `disconnect` — detach from the browser. For `'cdp'` and `'persistent'`
- *   connections this closes the client WITHOUT killing the browser process —
- *   a `'persistent'` (profile-backed) launch releases ownership of its process
- *   (no kill, no exit listener) so the browser stays alive for later
- *   reattachment via CDP discovery on the same port. Rejects with the coded
- *   `BrowserConnectionError` for `'launch'` (ephemeral, no profile) sessions —
- *   use `destroy()` instead. An external disconnect (transport loss while the
- *   owned process is still alive, or the owned process exiting on its own)
- *   drives this same released/disconnected state automatically, preceded by
+ * - `adopt` — explicitly assume responsibility for terminating the connected
+ *   browser, including a browser this instance attached to over CDP
+ * - `disconnect` — detach from the browser. For attached CDP connections this
+ *   closes only the client. For owned launches and adopted connections, it
+ *   retains ownership and the endpoint so the same instance can reconnect
+ *   and remains responsible for eventual termination. An external disconnect
+ *   (transport loss while the owned process is still alive, or the owned
+ *   process exiting on its own) drives the disconnected state, preceded by
  *   a coded `error` — `connect()` on the same instance can reattach afterward.
- * - `destroy` — release local resources. On an owned (`'launch'`/`'persistent'`)
- *   browser this closes pages/contexts, then kills the process (SIGTERM,
- *   escalating to SIGKILL). On a `'cdp'`-attached browser this is a LOCAL
- *   DETACH ONLY — the client is closed and local context/page objects are
- *   dropped WITHOUT sending any remote close to the browser, since other
- *   clients may share those targets. Idempotent.
+ * - `destroy` — release local resources. On a launched browser this closes
+ *   pages/contexts, then kills and awaits the process. On an adopted browser
+ *   it sends `Browser.close`. On a merely attached browser this is a LOCAL
+ *   DETACH ONLY because other clients may share its targets. Idempotent.
  * - `close` — graceful REMOTE shutdown: best-effort sends CDP `Browser.close`
  *   (works whether attached or owned), and when owned also awaits the
  *   process's exit (escalating to a kill only if it doesn't exit in time),
@@ -247,21 +250,32 @@ export declare interface BrowserInterface {
     readonly engine: BrowserEngine;
     readonly status: BrowserStatus;
     readonly connection: BrowserConnection | undefined;
+    /**
+     * Whether this instance is responsible for terminating the represented browser.
+     *
+     * @remarks
+     * `true` for launched and explicitly adopted sessions, `false` for an
+     * active attachment, and `undefined` when no session is represented.
+     */
+    readonly owned: boolean | undefined;
     readonly connected: boolean;
     /**
      * The process this instance launched, if any, while it is believed alive.
      *
      * @remarks
-     * Remains readable after a persistent disconnect-release (the process
-     * keeps running, detached from this instance) until `destroy()` or an
+     * Remains readable after a persistent disconnect (the process keeps
+     * running, detached from the transport) until `destroy()` or an
      * observed process exit clears it.
      */
     readonly pid: number | undefined;
     discover(): Promise<BrowserDiscoveryResult>;
     connect(): Promise<void>;
+    /** Assume responsibility for terminating the currently connected browser. */
+    adopt(): void;
     disconnect(): Promise<void>;
     context(index?: number): BrowserContextInterface | undefined;
     contexts(): readonly BrowserContextInterface[];
+    isolate(options?: BrowserContextOptions): Promise<BrowserContextInterface>;
     create(options?: BrowserPageOptions): Promise<BrowserPageInterface>;
     destroy(): Promise<void>;
     close(): Promise<void>;
@@ -279,6 +293,7 @@ export declare class BrowserNotConnectedError extends BrowserError {
  *
  * @remarks
  * - `on` — initial event listeners wired at construction
+ * - `error` — observer error handler forwarded to the emitter
  * - `headless` — launch in headless mode (default `true`; ignored for CDP connections)
  * - `executable` — absolute path to a browser executable; when provided, skips
  *   system browser discovery and launches this binary directly
@@ -297,10 +312,11 @@ export declare class BrowserNotConnectedError extends BrowserError {
  */
 export declare interface BrowserOptions {
     readonly on?: EmitterHooks<BrowserEventMap>;
+    readonly error?: EmitterErrorHandler;
     readonly headless?: boolean;
     readonly executable?: string;
     readonly profile?: string;
-    readonly cdp?: BrowserCdpOptions;
+    readonly cdp?: BrowserCDPOptions;
     readonly timeout?: number;
     readonly viewport?: BrowserViewport;
     readonly signal?: AbortSignal;
@@ -309,11 +325,24 @@ export declare interface BrowserOptions {
     readonly browsers?: SystemBrowserOptions;
 }
 
+/**
+ * Resolved browser profile directory used for a Chromium-family launch.
+ *
+ * @remarks
+ * `temporary` is true only for an isolated profile created by
+ * {@link createBrowserProfile}; caller-supplied persistent profiles are
+ * never removed by the library.
+ */
+export declare interface BrowserProfileResult {
+    readonly path: string;
+    readonly temporary: boolean;
+}
+
 /** Lifecycle status of a browser wrapper. */
 export declare type BrowserStatus = 'idle' | 'connecting' | 'connected' | 'disconnected' | 'error';
 
 /** Classify a `/json/version` `Browser` string into a {@link BrowserEngine} (`Edg/` → edge, `Chrome/` → chrome, else chromium). */
-export declare function browserToEngine(browser: string): BrowserEngine;
+export declare function browserToEngine(browser?: string): BrowserEngine;
 
 /**
  * Create a raw-CDP Browser façade.
@@ -331,6 +360,14 @@ export declare function browserToEngine(browser: string): BrowserEngine;
  */
 export declare function createBrowser(options?: BrowserOptions): BrowserInterface;
 
+/**
+ * Resolve a persistent caller profile or create an isolated temporary one.
+ *
+ * @param path - Optional caller-owned persistent user-data directory
+ * @returns The resolved profile and whether the library owns its lifecycle
+ */
+export declare function createBrowserProfile(path?: string): Promise<BrowserProfileResult>;
+
 /**
  * Create a Node `WebSocket`-backed CDP transport.
  *
@@ -360,7 +397,7 @@ export declare function defaultStoreBases(env: Readonly<Record<string, string |
  * @param host - Host the browser exposes its CDP endpoint on (default `127.0.0.1`)
  * @returns Normalized CDP targets
  */
-export declare function fetchCdpTargets(port: number, timeout: number, host?: string): Promise<readonly CDPTarget[]>;
+export declare function fetchCDPTargets(port: number, timeout: number, host?: string): Promise<readonly CDPTarget[]>;
 
 /** Check the env-override keys (`PLAYWRIGHT_EXECUTABLE_PATH`, `CHROME_PATH`) in order, returning every one that exists. */
 export declare function findAllEnvOverrides(env: Readonly<Record<string, string | undefined>>): readonly string[];
@@ -467,6 +504,18 @@ export declare function probeAllPathNames(names: readonly string[], platform: st
 /** Probe PATH (`which`/`where`) for the first resolvable command name. */
 export declare function probePathNames(names: readonly string[], platform: string): string | undefined;
 
+/**
+ * Remove a library-owned isolated browser profile.
+ *
+ * @remarks
+ * The path must remain a direct child of the operating-system temp directory
+ * with {@link BROWSER_PROFILE_PREFIX}; this defensive check prevents a
+ * malformed profile value from widening recursive deletion.
+ *
+ * @param profile - Resolved profile lifecycle result
+ */
+export declare function removeBrowserProfile(profile: BrowserProfileResult): Promise<void>;
+
 /**
  * One discovered browser executable on this machine.
  *
@@ -518,32 +567,21 @@ export declare interface SystemBrowserOptions {
  *
  * @throws When the endpoint does not become ready before the timeout
  */
-export declare function waitForCdpReady(port: number, timeout: number, host?: string): Promise<string>;
+export declare function waitForCDPReady(port: number, timeout: number, host?: string, signal?: AbortSignal): Promise<string>;
 
 /**
- * `@orkestrel/websocket`-backed {@link CDPTransportInterface} — the dumb text
- * pipe a {@link import('@src/core').CDPClientInterface} sends and receives
- * JSON-RPC frames over.
+ * `@orkestrel/websocket`-backed raw CDP text transport.
  *
  * @remarks
- * `start()` hand-rolls the RFC 6455 client handshake: it opens a `node:http`
- * `GET` carrying `Connection: Upgrade` / `Upgrade: websocket` / a random
- * `Sec-WebSocket-Key` / `Sec-WebSocket-Version`, awaits the client `'upgrade'`
- * event, and validates `Sec-WebSocket-Accept === computeWebSocketAccept(key)`
- * — a mismatch (or a connection/request error, or a timeout) rejects `start()`
- * with a coded {@link BrowserConnectionError} and cleans up the socket. On
- * success it wraps the raw upgraded socket in `createNodeWebSocket({ socket,
- * head })` (CLIENT mode — no `key` — so outgoing frames are masked per RFC
- * 6455 §5.3) and bridges its `message`/`close`/`error` events onto this
- * transport's emitter. `start()` opens a fresh socket each call (safe to call
- * again after `close()` — a new request/socket/NodeWebSocket triple is
- * created every time, which is what `CDPClient.reconnect()` depends on). CDP
- * frames are text-only, so `message` always carries a `string`.
+ * Performs and validates the RFC 6455 HTTP upgrade, then delegates frame
+ * handling to `@orkestrel/websocket`. Concurrent and repeated `start()` /
+ * `close()` calls share their active transition, and a later `start()` opens a
+ * fresh socket after the prior one closes.
  */
 export declare class WebSocketCDPTransport implements CDPTransportInterface {
     #private;
     constructor(options: WebSocketCDPTransportOptions);
-    get emitter(): EmitterInterface<CDPTransportEventMap>;
+    get emitter(): EmitterInterface<CDPTransportEventMap_2>;
     start(): Promise<void>;
     send(data: string): Promise<void>;
     close(): Promise<void>;
@@ -553,10 +591,14 @@ export declare class WebSocketCDPTransport implements CDPTransportInterface {
  * Options for creating a WebSocketCDPTransport.
  *
  * @remarks
+ * - `on` — initial event listeners wired at construction
+ * - `error` — observer error handler forwarded to the emitter
  * - `url` — the CDP WebSocket debugger URL to connect to
  * - `timeout` — ms before the connection attempt fails (default from constants)
  */
 export declare interface WebSocketCDPTransportOptions {
+    readonly on?: EmitterHooks<CDPTransportEventMap>;
+    readonly error?: EmitterErrorHandler;
     readonly url: string;
     readonly timeout?: number;
 }