@orkestrel/browser 0.0.5 → 0.0.7

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

@@ -1,4 +1,5 @@
 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';
@@ -14,6 +15,9 @@ 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);
@@ -30,6 +34,7 @@ export declare class Browser implements BrowserInterface {
     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>;
@@ -68,7 +73,7 @@ export declare const BROWSER_EXECUTABLE_PATHS: Readonly<Record<string, readonly
 /** Flag enabling headless mode on a launched browser process. */
 export declare const BROWSER_HEADLESS_ARG = "--headless=new";
 
-/** Grace period after SIGTERM before a launched process is escalated to SIGKILL during teardown. */
+/** Bound for each launched-process exit window during TERM-to-KILL teardown. */
 export declare const BROWSER_KILL_GRACE_MS = 3000;
 
 /** Flags always passed to a launched browser process, alongside the caller's own. */
@@ -80,6 +85,9 @@ 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>>;
 
@@ -190,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 [];
 };
@@ -222,12 +231,13 @@ export declare type BrowserEventMap = {
  *   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 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.
+ *   pages/contexts, then kills and awaits the process plus its POSIX process
+ *   group. 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),
+ *   process's exit and POSIX group drain (escalating to a kill only if needed),
  *   then performs the same local cleanup as `destroy()`. Use this to shut
  *   down a browser this instance doesn't own but wants to terminate anyway.
  *
@@ -266,6 +276,7 @@ export declare interface BrowserInterface {
     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>;
@@ -315,6 +326,19 @@ 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';
 
@@ -337,6 +361,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.
  *
@@ -446,6 +478,10 @@ export declare function isBrowserNotConnectedError(value: unknown): value is Bro
 /**
  * Launch a browser process with raw-CDP debugging flags.
  *
+ * @remarks
+ * POSIX launches own an isolated process group so lifecycle teardown can
+ * signal and await every Chromium subprocess without affecting the caller.
+ *
  * @param executable - Absolute path to the browser executable
  * @param port - Port the browser exposes its CDP endpoint on
  * @param headless - Whether to launch in headless mode
@@ -473,6 +509,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.
  *