@gobing-ai/ts-browser-automation 0.5.10

package/README.md

@@ -0,0 +1,125 @@
+# @gobing-ai/ts-browser-automation
+
+Reusable Playwright persistent browser profile sessions: sign in once with a
+dedicated visible Chromium profile, then drive later automation headless against
+the same profile. Extracted from knowledge-kit's XHS publish flow (task 0088,
+[ADR-032](../../docs/00_ADR.md)).
+
+Part of the `@gobing-ai/ts-libs` monorepo and lockstep-versioned with it.
+
+- **License:** Apache-2.0.
+- The package never stores usernames/passwords and never exports cookies — the
+  Playwright user-data directory itself is the login artifact.
+
+---
+
+## Install & runtime requirements
+
+```sh
+bun add @gobing-ai/ts-browser-automation
+# Playwright is a required peer dependency (^1.55.0):
+bun add playwright@^1.55.0
+# Chromium is owned by the consumer (ADR-032):
+npx playwright install chromium
+```
+
+- **Runtime:** Node.js or Bun with Playwright's supported platforms.
+- A missing `playwright` peer or missing Chromium fails with a typed
+  `PlaywrightUnavailableError` at launch time — never at import. Importing the
+  module has no browser side effect.
+
+## Usage
+
+### 1. One-time headed login into a dedicated profile
+
+```ts
+import { loginWithProfile } from '@gobing-ai/ts-browser-automation';
+
+// You choose where the profile lives — the package has no default location.
+const profileDir = `${process.env.HOME}/.local/share/myapp/browser-profiles/xhs`;
+
+await loginWithProfile({
+    profileDir,
+    url: 'https://example-site.test/login',
+    // Site-owned readiness check: only your predicate can declare success.
+    isAuthenticated: async (page) => page.url().includes('/dashboard'),
+    timeoutMs: 5 * 60_000,
+});
+```
+
+A visible browser opens; sign in by hand. The context closes once your
+predicate passes — or on timeout, cancellation (`signal`), or error. If the
+deadline expires you get `LoginTimeoutError` with a re-login instruction; just
+run `loginWithProfile` again with the same `profileDir`.
+
+### 2. Later automation reusing the authenticated profile
+
+```ts
+import { withProfilePage } from '@gobing-ai/ts-browser-automation';
+
+const result = await withProfilePage(
+    {
+        profileDir,
+        headless: true,
+        url: 'https://example-site.test/feed',
+        // Guard the claim of an authenticated session (task 0088 R3):
+        isAuthenticated: (page) => page.url().includes('/feed'),
+        timeoutMs: 30_000,
+    },
+    async ({ context, page }) => {
+        // Full Playwright page/locator/upload APIs. Site-specific CDP is
+        // caller-owned, e.g. for closed-shadow DOM control:
+        const cdp = await context.newCDPSession(page);
+        return page.locator('#app').innerText();
+    },
+);
+```
+
+`withProfilePage` guarantees `context.close()` in a `finally` on every exit
+path. For full manual control (e.g. keeping one context across many steps),
+use the low-level `openPersistentBrowser({ profileDir, headless })` and close
+the returned `BrowserContext` yourself.
+
+## Behavior guarantees
+
+- **Dedicated profile, explicit path.** `profileDir` is required (empty/blank
+  or an existing file → `InvalidProfileDirError`) and resolved to an absolute
+  path. Relative input resolves against the current working directory.
+- **Owner-only creation.** A missing profile directory is created with `0o700`
+  on a headed launch, on local filesystems that enforce permission bits (POSIX;
+  mode bits are a no-op on Windows). Existing directories are adopted in place —
+  never moved, re-permissioned, or deleted.
+- **No silent unauthenticated sessions.** A headless run against a missing
+  profile fails with `BrowserProfileMissingError` instead of creating a fresh,
+  unauthenticated one.
+- **Single-process rule.** Playwright user-data directories hold session state
+  and cannot be opened by concurrent browser instances. One profile = one
+  browser at a time; concurrent use surfaces as `BrowserProfileBusyError`.
+- **Auth expiry is recoverable.** A profile whose site session has expired
+  fails the readiness predicate with `LoginTimeoutError` (message includes the
+  re-login instruction) — it never reports a false authenticated result.
+- **Sensitive material.** Cookies and local storage in the profile are session
+  material: never log profile contents, never commit a profile directory.
+
+## Caveats
+
+- **Some sites reject headless automation.** The headed path always remains
+  available for debugging (`headless: false` or `loginWithProfile`); the
+  package does not promise headless success on every site.
+- **App-specific choices stay outside the package** — no default profile
+  location, site selectors, or credentials. Callers own all of them.
+
+## Manual smoke (local, never unattended)
+
+1. Pick a disposable account and a profile directory outside this repository:
+   `PROFILE="$HOME/tmp/smoke-profile-$$"`.
+2. Headed login: `loginWithProfile({ profileDir: PROFILE, url: 'https://example-site.test/login', isAuthenticated: (p) => p.url().includes('/home'), timeoutMs: 300_000 })`
+   — sign in manually, confirm the context closes after your predicate passes.
+3. Headless reuse: run the `withProfilePage` example above with
+   `headless: true` and confirm the callback sees the authenticated page.
+4. Failure cases: re-run headless with a fresh non-existent `PROFILE`
+   (expect `BrowserProfileMissingError`); open the same profile in a second
+   browser and re-run (expect `BrowserProfileBusyError`); delete cookies via
+   the site and re-run with the predicate (expect `LoginTimeoutError`).
+
+Use a throwaway account. Do not run the headed-login step unattended or in CI.

package/dist/errors.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Typed failure surface for @gobing-ai/ts-browser-automation (task 0088).
+ * Each failure mode named in the task (missing/busy profile, auth expiry,
+ * timeout, cancellation, missing Playwright) maps to one error class so
+ * callers can branch without string matching.
+ */
+/** Base class for every error this package throws. */
+export declare class BrowserAutomationError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** `profileDir` was empty or blank. */
+export declare class InvalidProfileDirError extends BrowserAutomationError {
+    constructor(message?: string);
+}
+/** A headless run targeted a profile directory that does not exist. */
+export declare class BrowserProfileMissingError extends BrowserAutomationError {
+    constructor(profileDir: string);
+}
+/** The profile directory is locked by another Chromium instance (singleton rule). */
+export declare class BrowserProfileBusyError extends BrowserAutomationError {
+    constructor(profileDir: string, cause: unknown);
+}
+/** The `playwright` peer dependency or its Chromium browser is not installed. */
+export declare class PlaywrightUnavailableError extends BrowserAutomationError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * The caller-owned readiness predicate never passed within the deadline.
+ * Recoverable: the message carries the re-login instruction.
+ */
+export declare class LoginTimeoutError extends BrowserAutomationError {
+    constructor(message: string);
+}
+/** The caller aborted the operation via `AbortSignal`. */
+export declare class OperationAbortedError extends BrowserAutomationError {
+    constructor(message?: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,sDAAsD;AACtD,qBAAa,sBAAuB,SAAQ,KAAK;gBACjC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI7D;AAED,uCAAuC;AACvC,qBAAa,sBAAuB,SAAQ,sBAAsB;gBAClD,OAAO,SAAkF;CAIxG;AAED,uEAAuE;AACvE,qBAAa,0BAA2B,SAAQ,sBAAsB;gBACtD,UAAU,EAAE,MAAM;CAOjC;AAED,qFAAqF;AACrF,qBAAa,uBAAwB,SAAQ,sBAAsB;gBACnD,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;CAQjD;AAED,iFAAiF;AACjF,qBAAa,0BAA2B,SAAQ,sBAAsB;gBACtD,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI7D;AAED;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,sBAAsB;gBAC7C,OAAO,EAAE,MAAM;CAI9B;AAED,0DAA0D;AAC1D,qBAAa,qBAAsB,SAAQ,sBAAsB;gBACjD,OAAO,SAAgE;CAItF"}

package/dist/errors.js

@@ -0,0 +1,60 @@
+/**
+ * Typed failure surface for @gobing-ai/ts-browser-automation (task 0088).
+ * Each failure mode named in the task (missing/busy profile, auth expiry,
+ * timeout, cancellation, missing Playwright) maps to one error class so
+ * callers can branch without string matching.
+ */
+/** Base class for every error this package throws. */
+export class BrowserAutomationError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'BrowserAutomationError';
+    }
+}
+/** `profileDir` was empty or blank. */
+export class InvalidProfileDirError extends BrowserAutomationError {
+    constructor(message = 'profileDir must be a non-empty path to a dedicated browser profile directory.') {
+        super(message);
+        this.name = 'InvalidProfileDirError';
+    }
+}
+/** A headless run targeted a profile directory that does not exist. */
+export class BrowserProfileMissingError extends BrowserAutomationError {
+    constructor(profileDir) {
+        super(`Profile directory does not exist: "${profileDir}". Headless runs never create a profile — ` +
+            'run loginWithProfile() headed once to create and authenticate it.');
+        this.name = 'BrowserProfileMissingError';
+    }
+}
+/** The profile directory is locked by another Chromium instance (singleton rule). */
+export class BrowserProfileBusyError extends BrowserAutomationError {
+    constructor(profileDir, cause) {
+        super(`Profile directory is already in use by another browser instance: "${profileDir}". ` +
+            'Close the other instance or use a different profileDir — a profile must never be shared by concurrent browsers.', { cause });
+        this.name = 'BrowserProfileBusyError';
+    }
+}
+/** The `playwright` peer dependency or its Chromium browser is not installed. */
+export class PlaywrightUnavailableError extends BrowserAutomationError {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'PlaywrightUnavailableError';
+    }
+}
+/**
+ * The caller-owned readiness predicate never passed within the deadline.
+ * Recoverable: the message carries the re-login instruction.
+ */
+export class LoginTimeoutError extends BrowserAutomationError {
+    constructor(message) {
+        super(message);
+        this.name = 'LoginTimeoutError';
+    }
+}
+/** The caller aborted the operation via `AbortSignal`. */
+export class OperationAbortedError extends BrowserAutomationError {
+    constructor(message = 'Browser automation operation was cancelled via AbortSignal.') {
+        super(message);
+        this.name = 'OperationAbortedError';
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { BrowserAutomationError, BrowserProfileBusyError, BrowserProfileMissingError, InvalidProfileDirError, LoginTimeoutError, OperationAbortedError, PlaywrightUnavailableError, } from './errors';
+export type { BrowserLauncher, PersistentLauncherOptions, ProfileLaunchRequest } from './launcher';
+export type { IsAuthenticatedPredicate, LoginWithProfileOptions, OpenPersistentBrowserOptions, ProfilePageHandle, WithProfilePageOptions, } from './operations';
+export { loginWithProfile, openPersistentBrowser, withProfilePage } from './operations';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,sBAAsB,EACtB,uBAAuB,EACvB,0BAA0B,EAC1B,sBAAsB,EACtB,iBAAiB,EACjB,qBAAqB,EACrB,0BAA0B,GAC7B,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,eAAe,EAAE,yBAAyB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AACnG,YAAY,EACR,wBAAwB,EACxB,uBAAuB,EACvB,4BAA4B,EAC5B,iBAAiB,EACjB,sBAAsB,GACzB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { BrowserAutomationError, BrowserProfileBusyError, BrowserProfileMissingError, InvalidProfileDirError, LoginTimeoutError, OperationAbortedError, PlaywrightUnavailableError, } from './errors.js';
+export { loginWithProfile, openPersistentBrowser, withProfilePage } from './operations.js';

package/dist/launcher.d.ts

@@ -0,0 +1,43 @@
+import { type FileSystem } from '@gobing-ai/ts-runtime';
+import type { BrowserContext } from 'playwright';
+/** Request for one persistent-context launch. `profileDir` is resolved to an absolute path before launch. */
+export interface ProfileLaunchRequest {
+    profileDir: string;
+    headless: boolean;
+}
+/**
+ * Seam for opening a persistent Chromium context. The package's default
+ * implementation is {@link createPersistentLauncher}; tests and consumers may
+ * inject their own to fake or customise browser provisioning.
+ */
+export interface BrowserLauncher {
+    launch(request: ProfileLaunchRequest): Promise<BrowserContext>;
+}
+/** Options for the internal persistent launcher; all fields optional with safe defaults. */
+export interface PersistentLauncherOptions {
+    /** Playwright loader override (tests inject a fake; the default lazily imports the peer). */
+    loadPlaywright?: () => Promise<typeof import('playwright')>;
+    /** Filesystem for profile-directory existence checks (default: ts-runtime node/bun). */
+    fileSystem?: FileSystem;
+}
+/**
+ * Create the profile directory with owner-only permissions when it does not
+ * exist. A headless run never creates one: an absent profile means no
+ * authenticated session exists, and silently launching a fresh one would
+ * fake a login (task 0088 R4).
+ */
+export declare function ensureProfileDir(profileDir: string, headless: boolean, fs: FileSystem): Promise<void>;
+/**
+ * @internal Test-visible seam: the real runtime-lazy `import('playwright')`.
+ * Exported only so the coverage test can execute it without launching a
+ * browser — every default-launcher path that reaches it would call the real
+ * `launchPersistentContext` next.
+ */
+export declare function defaultLoadPlaywright(): Promise<typeof import('playwright')>;
+/**
+ * Default {@link BrowserLauncher}: lazily imports the `playwright` peer,
+ * guarantees an owner-only profile directory, and maps known Chromium/Playwright
+ * launch failures onto this package's typed errors.
+ */
+export declare function createPersistentLauncher(options?: PersistentLauncherOptions): BrowserLauncher;
+//# sourceMappingURL=launcher.d.ts.map

package/dist/launcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"launcher.d.ts","sourceRoot":"","sources":["../src/launcher.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,KAAK,UAAU,EAAkB,MAAM,uBAAuB,CAAC;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAkBjD,6GAA6G;AAC7G,MAAM,WAAW,oBAAoB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC5B,MAAM,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CAClE;AAED,4FAA4F;AAC5F,MAAM,WAAW,yBAAyB;IACtC,6FAA6F;IAC7F,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,cAAc,YAAY,CAAC,CAAC,CAAC;IAC5D,wFAAwF;IACxF,UAAU,CAAC,EAAE,UAAU,CAAC;CAC3B;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAS3G;AAED;;;;;GAKG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,cAAc,YAAY,CAAC,CAAC,CAElF;AAcD;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,GAAE,yBAA8B,GAAG,eAAe,CAyBjG"}

package/dist/launcher.js

@@ -0,0 +1,83 @@
+/**
+ * Browser adapter — the single sanctioned exception to the ts-runtime
+ * platform-API ownership rule (ADR-032): the Playwright runtime import and
+ * the owner-only (0o700) creation of the profile directory live in this
+ * module and nowhere else. Generic path math and existence checks route
+ * through @gobing-ai/ts-runtime. No browser side effect happens at import.
+ */
+import { mkdir } from 'node:fs/promises';
+import { nodeBunFactory } from '@gobing-ai/ts-runtime';
+import { BrowserProfileBusyError, BrowserProfileMissingError, InvalidProfileDirError, PlaywrightUnavailableError, } from './errors.js';
+import { resolveProfileDir } from './profile-dir.js';
+/** Owner-only access for a newly created profile directory (existing directories are adopted in place). */
+const PROFILE_DIR_MODE = 0o700;
+/** Chromium singleton/lock failure signatures surfaced by Playwright when a profile is already open. */
+const BUSY_PROFILE_PATTERN = /singleton|already in use|in use by another/i;
+/** Playwright's "browser executable missing" signature. */
+const CHROMIUM_MISSING_PATTERN = /playwright install|executable doesn't exist/i;
+/**
+ * Create the profile directory with owner-only permissions when it does not
+ * exist. A headless run never creates one: an absent profile means no
+ * authenticated session exists, and silently launching a fresh one would
+ * fake a login (task 0088 R4).
+ */
+export async function ensureProfileDir(profileDir, headless, fs) {
+    const existing = await fs.stat(profileDir);
+    if (existing) {
+        if (!existing.isDirectory())
+            throw new InvalidProfileDirError(`profileDir is not a directory: "${profileDir}".`);
+        return; // adopt the existing directory in place — never move, re-permission, or delete
+    }
+    if (headless)
+        throw new BrowserProfileMissingError(profileDir);
+    await mkdir(profileDir, { recursive: true, mode: PROFILE_DIR_MODE });
+}
+/**
+ * @internal Test-visible seam: the real runtime-lazy `import('playwright')`.
+ * Exported only so the coverage test can execute it without launching a
+ * browser — every default-launcher path that reaches it would call the real
+ * `launchPersistentContext` next.
+ */
+export async function defaultLoadPlaywright() {
+    return import('playwright');
+}
+function mapLaunchError(profileDir, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (BUSY_PROFILE_PATTERN.test(message))
+        return new BrowserProfileBusyError(profileDir, error);
+    if (CHROMIUM_MISSING_PATTERN.test(message)) {
+        return new PlaywrightUnavailableError('Chromium is not installed for Playwright. Run `npx playwright install chromium` and retry.', { cause: error });
+    }
+    return error;
+}
+/**
+ * Default {@link BrowserLauncher}: lazily imports the `playwright` peer,
+ * guarantees an owner-only profile directory, and maps known Chromium/Playwright
+ * launch failures onto this package's typed errors.
+ */
+export function createPersistentLauncher(options = {}) {
+    const loadPlaywright = options.loadPlaywright ?? defaultLoadPlaywright;
+    const fs = options.fileSystem ?? nodeBunFactory.createFileSystem();
+    return {
+        async launch(request) {
+            const profileDir = resolveProfileDir(request.profileDir);
+            await ensureProfileDir(profileDir, request.headless, fs);
+            let playwright;
+            try {
+                playwright = await loadPlaywright();
+            }
+            catch (error) {
+                if (error instanceof PlaywrightUnavailableError)
+                    throw error;
+                throw new PlaywrightUnavailableError('The "playwright" peer dependency is not installed. Add playwright@^1.55.0 to your dependencies ' +
+                    'and run `npx playwright install chromium` to download the browser.', { cause: error });
+            }
+            try {
+                return await playwright.chromium.launchPersistentContext(profileDir, { headless: request.headless });
+            }
+            catch (error) {
+                throw mapLaunchError(profileDir, error);
+            }
+        },
+    };
+}

package/dist/operations.d.ts

@@ -0,0 +1,64 @@
+import type { BrowserContext, Page } from 'playwright';
+import { type BrowserLauncher } from './launcher';
+/** Caller-owned readiness check. The package never infers authentication from profile state. */
+export type IsAuthenticatedPredicate = (page: Page) => boolean | Promise<boolean>;
+/** Options for the low-level persistent-context opener with caller-owned lifetime. */
+export interface OpenPersistentBrowserOptions {
+    /** Dedicated Chromium user-data directory (created owner-only when absent; adopted in place when present). */
+    profileDir: string;
+    headless: boolean;
+    /** Launcher override (tests / custom browser provisioning). */
+    launcher?: BrowserLauncher;
+}
+/**
+ * Low-level persistent-context opener. The returned context's lifetime is
+ * caller-owned — close it in a `finally` block, or prefer {@link withProfilePage}.
+ */
+export declare function openPersistentBrowser(options: OpenPersistentBrowserOptions): Promise<BrowserContext>;
+/** Options for the headed one-time login that polls the caller's readiness predicate. */
+export interface LoginWithProfileOptions {
+    /** Dedicated Chromium user-data directory. */
+    profileDir: string;
+    /** Login page to open in the visible browser. */
+    url: string;
+    /** Site-owned readiness check polled until it passes or the deadline expires. */
+    isAuthenticated: IsAuthenticatedPredicate;
+    /** Finite deadline for predicate confirmation. */
+    timeoutMs: number;
+    signal?: AbortSignal;
+    launcher?: BrowserLauncher;
+}
+/**
+ * Open a headed browser on `url`, let the user sign in, and resolve only once
+ * `isAuthenticated(page)` passes. The context is closed on success, timeout,
+ * cancellation, and error. No credential is ever read or stored — the profile
+ * directory itself is the login artifact.
+ */
+export declare function loginWithProfile(options: LoginWithProfileOptions): Promise<void>;
+/** Handle returned to the callback with the opened context and its page. */
+export interface ProfilePageHandle {
+    context: BrowserContext;
+    page: Page;
+}
+/** Options for the scoped callback helper that guarantees context closure in `finally`. */
+export interface WithProfilePageOptions {
+    /** Dedicated Chromium user-data directory. */
+    profileDir: string;
+    /** Headless reuse defaults to `false`; pass `true` for unattended runs (requires an existing profile). */
+    headless?: boolean;
+    url?: string;
+    /** When provided, the callback runs only after the readiness predicate passes (task 0088 R3). */
+    isAuthenticated?: IsAuthenticatedPredicate;
+    /** Deadline for predicate confirmation (default 30s; ignored without `isAuthenticated`). */
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    launcher?: BrowserLauncher;
+}
+/**
+ * Scoped session helper: launch a persistent context, hand the caller
+ * `{ context, page }`, and guarantee `context.close()` in `finally` on every
+ * exit path. `context` is a genuine Playwright context — callers own
+ * site-specific CDP via `context.newCDPSession(page)`.
+ */
+export declare function withProfilePage<T>(options: WithProfilePageOptions, callback: (handle: ProfilePageHandle) => Promise<T>): Promise<T>;
+//# sourceMappingURL=operations.d.ts.map

package/dist/operations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operations.d.ts","sourceRoot":"","sources":["../src/operations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAEvD,OAAO,EAAE,KAAK,eAAe,EAA4B,MAAM,YAAY,CAAC;AAa5E,gGAAgG;AAChG,MAAM,MAAM,wBAAwB,GAAG,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAElF,sFAAsF;AACtF,MAAM,WAAW,4BAA4B;IACzC,8GAA8G;IAC9G,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,eAAe,CAAC;CAC9B;AAED;;;GAGG;AACH,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,4BAA4B,GAAG,OAAO,CAAC,cAAc,CAAC,CAK1G;AAED,yFAAyF;AACzF,MAAM,WAAW,uBAAuB;IACpC,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,GAAG,EAAE,MAAM,CAAC;IACZ,iFAAiF;IACjF,eAAe,EAAE,wBAAwB,CAAC;IAC1C,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,QAAQ,CAAC,EAAE,eAAe,CAAC;CAC9B;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CActF;AAED,4EAA4E;AAC5E,MAAM,WAAW,iBAAiB;IAC9B,OAAO,EAAE,cAAc,CAAC;IACxB,IAAI,EAAE,IAAI,CAAC;CACd;AAED,2FAA2F;AAC3F,MAAM,WAAW,sBAAsB;IACnC,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB,0GAA0G;IAC1G,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,iGAAiG;IACjG,eAAe,CAAC,EAAE,wBAAwB,CAAC;IAC3C,4FAA4F;IAC5F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,QAAQ,CAAC,EAAE,eAAe,CAAC;CAC9B;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,CAAC,EACnC,OAAO,EAAE,sBAAsB,EAC/B,QAAQ,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,OAAO,CAAC,CAAC,CAAC,GACpD,OAAO,CAAC,CAAC,CAAC,CAiBZ"}

package/dist/operations.js

@@ -0,0 +1,124 @@
+import { LoginTimeoutError, OperationAbortedError } from './errors.js';
+import { createPersistentLauncher } from './launcher.js';
+import { resolveProfileDir } from './profile-dir.js';
+const DEFAULT_TIMEOUT_MS = 30_000;
+const POLL_INTERVAL_MS = 250;
+// Lazily built so importing the module has no side effects (sideEffects: false).
+let defaultLauncher;
+function getDefaultLauncher() {
+    if (defaultLauncher === undefined)
+        defaultLauncher = createPersistentLauncher();
+    return defaultLauncher;
+}
+/**
+ * Low-level persistent-context opener. The returned context's lifetime is
+ * caller-owned — close it in a `finally` block, or prefer {@link withProfilePage}.
+ */
+export async function openPersistentBrowser(options) {
+    return (options.launcher ?? getDefaultLauncher()).launch({
+        profileDir: resolveProfileDir(options.profileDir),
+        headless: options.headless,
+    });
+}
+/**
+ * Open a headed browser on `url`, let the user sign in, and resolve only once
+ * `isAuthenticated(page)` passes. The context is closed on success, timeout,
+ * cancellation, and error. No credential is ever read or stored — the profile
+ * directory itself is the login artifact.
+ */
+export async function loginWithProfile(options) {
+    assertNotAborted(options.signal);
+    assertFiniteTimeoutMs(options.timeoutMs);
+    const context = await (options.launcher ?? getDefaultLauncher()).launch({
+        profileDir: resolveProfileDir(options.profileDir),
+        headless: false,
+    });
+    try {
+        const page = await openPage(context);
+        await page.goto(options.url);
+        await pollPredicate(page, options.isAuthenticated, options.timeoutMs, options.signal);
+    }
+    finally {
+        await context.close();
+    }
+}
+/**
+ * Scoped session helper: launch a persistent context, hand the caller
+ * `{ context, page }`, and guarantee `context.close()` in `finally` on every
+ * exit path. `context` is a genuine Playwright context — callers own
+ * site-specific CDP via `context.newCDPSession(page)`.
+ */
+export async function withProfilePage(options, callback) {
+    assertNotAborted(options.signal);
+    if (options.isAuthenticated !== undefined)
+        assertFiniteTimeoutMs(options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    const context = await (options.launcher ?? getDefaultLauncher()).launch({
+        profileDir: resolveProfileDir(options.profileDir),
+        headless: options.headless ?? false,
+    });
+    try {
+        const page = await openPage(context);
+        if (options.url !== undefined)
+            await page.goto(options.url);
+        if (options.isAuthenticated !== undefined) {
+            await pollPredicate(page, options.isAuthenticated, options.timeoutMs ?? DEFAULT_TIMEOUT_MS, options.signal);
+        }
+        return await callback({ context, page });
+    }
+    finally {
+        await context.close();
+    }
+}
+function assertNotAborted(signal) {
+    if (signal?.aborted)
+        throw new OperationAbortedError();
+}
+async function openPage(context) {
+    const existing = context.pages()[0];
+    return existing ?? (await context.newPage());
+}
+/** Rejects a non-finite or negative timeout at op entry — before any browser opens — so a bad value cannot park a headed window in an endless poll. */
+function assertFiniteTimeoutMs(timeoutMs) {
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 0) {
+        throw new TypeError(`timeoutMs must be a finite non-negative number of milliseconds; received ${timeoutMs}`);
+    }
+}
+async function pollPredicate(page, predicate, timeoutMs, signal) {
+    const timeoutError = new LoginTimeoutError(`Authentication was not confirmed within ${timeoutMs}ms. The profile's site session has likely ` +
+        'expired or the sign-in was not completed: re-run loginWithProfile() with the same profileDir to sign in again.');
+    let timer;
+    let onAbort;
+    let stopped = false;
+    const deadline = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(timeoutError), timeoutMs);
+        if (signal) {
+            onAbort = () => reject(new OperationAbortedError());
+            signal.addEventListener('abort', onAbort, { once: true });
+            if (signal.aborted)
+                onAbort();
+        }
+    });
+    const poll = async () => {
+        for (;;) {
+            if (stopped)
+                return;
+            assertNotAborted(signal);
+            if (await predicate(page))
+                return;
+            await sleep(POLL_INTERVAL_MS);
+        }
+    };
+    try {
+        await Promise.race([poll(), deadline]);
+    }
+    finally {
+        stopped = true;
+        if (timer)
+            clearTimeout(timer);
+        if (signal && onAbort)
+            signal.removeEventListener('abort', onAbort);
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/profile-dir.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Validate a caller-supplied `profileDir` and resolve it to an absolute path
+ * (relative inputs resolve against the current working directory). Rejection
+ * of empty/blank paths happens here so every operation and launcher entry
+ * point behaves identically.
+ */
+export declare function resolveProfileDir(profileDir: string): string;
+//# sourceMappingURL=profile-dir.d.ts.map

package/dist/profile-dir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile-dir.d.ts","sourceRoot":"","sources":["../src/profile-dir.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAS5D"}

package/dist/profile-dir.js

@@ -0,0 +1,18 @@
+import { isAbsolutePath, resolvePath } from '@gobing-ai/ts-runtime';
+import { InvalidProfileDirError } from './errors.js';
+/**
+ * Validate a caller-supplied `profileDir` and resolve it to an absolute path
+ * (relative inputs resolve against the current working directory). Rejection
+ * of empty/blank paths happens here so every operation and launcher entry
+ * point behaves identically.
+ */
+export function resolveProfileDir(profileDir) {
+    if (profileDir.trim() === '') {
+        throw new InvalidProfileDirError();
+    }
+    const resolved = resolvePath(profileDir);
+    if (!isAbsolutePath(resolved)) {
+        throw new InvalidProfileDirError(`profileDir could not be resolved to an absolute path: "${profileDir}".`);
+    }
+    return resolved;
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+    "name": "@gobing-ai/ts-browser-automation",
+    "version": "0.5.10",
+    "description": "@gobing-ai/ts-browser-automation — Reusable Playwright persistent browser profile sessions: headed login, headless reuse.",
+    "keywords": [
+        "typescript",
+        "browser",
+        "playwright",
+        "chromium",
+        "automation",
+        "session"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/gobing-ai/ts-libs.git",
+        "directory": "packages/browser-automation"
+    },
+    "author": "Robin Min <minlongbing@gmail.com>",
+    "contributors": [
+        "Robin Min <minlongbing@gmail.com>"
+    ],
+    "type": "module",
+    "private": false,
+    "sideEffects": false,
+    "license": "Apache-2.0",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        }
+    },
+    "files": [
+        "dist",
+        "src",
+        "README.md"
+    ],
+    "scripts": {
+        "build": "tsc -p tsconfig.build.json && bun ../../scripts/builder.ts fix-dist-esm-extensions dist",
+        "test": "NODE_ENV=test bun test --coverage --coverage-dir=.coverage --reporter=dots",
+        "test:full": "NODE_ENV=test bun test --update-snapshots --coverage --coverage-dir=.coverage",
+        "typecheck": "tsc --noEmit",
+        "lint": "biome check . && bun run typecheck",
+        "format": "biome check . --write",
+        "check": "bun run lint && bun run test",
+        "prepublishOnly": "bun run build",
+        "release": "echo 'Manual publish is disabled. Releases go through GitHub Actions via Trusted Publishing — push a tag: git tag @gobing-ai/ts-browser-automation-v<version> && git push --tags' && exit 1"
+    },
+    "dependencies": {
+        "@gobing-ai/ts-runtime": "workspace:*"
+    },
+    "peerDependencies": {
+        "playwright": "^1.55.0"
+    },
+    "devDependencies": {
+        "@types/bun": "1.3.14",
+        "playwright": "1.55.0"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}

package/src/errors.ts

@@ -0,0 +1,72 @@
+/**
+ * Typed failure surface for @gobing-ai/ts-browser-automation (task 0088).
+ * Each failure mode named in the task (missing/busy profile, auth expiry,
+ * timeout, cancellation, missing Playwright) maps to one error class so
+ * callers can branch without string matching.
+ */
+
+/** Base class for every error this package throws. */
+export class BrowserAutomationError extends Error {
+    constructor(message: string, options?: { cause?: unknown }) {
+        super(message, options);
+        this.name = 'BrowserAutomationError';
+    }
+}
+
+/** `profileDir` was empty or blank. */
+export class InvalidProfileDirError extends BrowserAutomationError {
+    constructor(message = 'profileDir must be a non-empty path to a dedicated browser profile directory.') {
+        super(message);
+        this.name = 'InvalidProfileDirError';
+    }
+}
+
+/** A headless run targeted a profile directory that does not exist. */
+export class BrowserProfileMissingError extends BrowserAutomationError {
+    constructor(profileDir: string) {
+        super(
+            `Profile directory does not exist: "${profileDir}". Headless runs never create a profile — ` +
+                'run loginWithProfile() headed once to create and authenticate it.',
+        );
+        this.name = 'BrowserProfileMissingError';
+    }
+}
+
+/** The profile directory is locked by another Chromium instance (singleton rule). */
+export class BrowserProfileBusyError extends BrowserAutomationError {
+    constructor(profileDir: string, cause: unknown) {
+        super(
+            `Profile directory is already in use by another browser instance: "${profileDir}". ` +
+                'Close the other instance or use a different profileDir — a profile must never be shared by concurrent browsers.',
+            { cause },
+        );
+        this.name = 'BrowserProfileBusyError';
+    }
+}
+
+/** The `playwright` peer dependency or its Chromium browser is not installed. */
+export class PlaywrightUnavailableError extends BrowserAutomationError {
+    constructor(message: string, options?: { cause?: unknown }) {
+        super(message, options);
+        this.name = 'PlaywrightUnavailableError';
+    }
+}
+
+/**
+ * The caller-owned readiness predicate never passed within the deadline.
+ * Recoverable: the message carries the re-login instruction.
+ */
+export class LoginTimeoutError extends BrowserAutomationError {
+    constructor(message: string) {
+        super(message);
+        this.name = 'LoginTimeoutError';
+    }
+}
+
+/** The caller aborted the operation via `AbortSignal`. */
+export class OperationAbortedError extends BrowserAutomationError {
+    constructor(message = 'Browser automation operation was cancelled via AbortSignal.') {
+        super(message);
+        this.name = 'OperationAbortedError';
+    }
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+export {
+    BrowserAutomationError,
+    BrowserProfileBusyError,
+    BrowserProfileMissingError,
+    InvalidProfileDirError,
+    LoginTimeoutError,
+    OperationAbortedError,
+    PlaywrightUnavailableError,
+} from './errors';
+export type { BrowserLauncher, PersistentLauncherOptions, ProfileLaunchRequest } from './launcher';
+export type {
+    IsAuthenticatedPredicate,
+    LoginWithProfileOptions,
+    OpenPersistentBrowserOptions,
+    ProfilePageHandle,
+    WithProfilePageOptions,
+} from './operations';
+export { loginWithProfile, openPersistentBrowser, withProfilePage } from './operations';

package/src/launcher.ts

@@ -0,0 +1,120 @@
+/**
+ * Browser adapter — the single sanctioned exception to the ts-runtime
+ * platform-API ownership rule (ADR-032): the Playwright runtime import and
+ * the owner-only (0o700) creation of the profile directory live in this
+ * module and nowhere else. Generic path math and existence checks route
+ * through @gobing-ai/ts-runtime. No browser side effect happens at import.
+ */
+import { mkdir } from 'node:fs/promises';
+import { type FileSystem, nodeBunFactory } from '@gobing-ai/ts-runtime';
+import type { BrowserContext } from 'playwright';
+import {
+    BrowserProfileBusyError,
+    BrowserProfileMissingError,
+    InvalidProfileDirError,
+    PlaywrightUnavailableError,
+} from './errors';
+import { resolveProfileDir } from './profile-dir';
+
+/** Owner-only access for a newly created profile directory (existing directories are adopted in place). */
+const PROFILE_DIR_MODE = 0o700;
+
+/** Chromium singleton/lock failure signatures surfaced by Playwright when a profile is already open. */
+const BUSY_PROFILE_PATTERN = /singleton|already in use|in use by another/i;
+
+/** Playwright's "browser executable missing" signature. */
+const CHROMIUM_MISSING_PATTERN = /playwright install|executable doesn't exist/i;
+
+/** Request for one persistent-context launch. `profileDir` is resolved to an absolute path before launch. */
+export interface ProfileLaunchRequest {
+    profileDir: string;
+    headless: boolean;
+}
+
+/**
+ * Seam for opening a persistent Chromium context. The package's default
+ * implementation is {@link createPersistentLauncher}; tests and consumers may
+ * inject their own to fake or customise browser provisioning.
+ */
+export interface BrowserLauncher {
+    launch(request: ProfileLaunchRequest): Promise<BrowserContext>;
+}
+
+/** Options for the internal persistent launcher; all fields optional with safe defaults. */
+export interface PersistentLauncherOptions {
+    /** Playwright loader override (tests inject a fake; the default lazily imports the peer). */
+    loadPlaywright?: () => Promise<typeof import('playwright')>;
+    /** Filesystem for profile-directory existence checks (default: ts-runtime node/bun). */
+    fileSystem?: FileSystem;
+}
+
+/**
+ * Create the profile directory with owner-only permissions when it does not
+ * exist. A headless run never creates one: an absent profile means no
+ * authenticated session exists, and silently launching a fresh one would
+ * fake a login (task 0088 R4).
+ */
+export async function ensureProfileDir(profileDir: string, headless: boolean, fs: FileSystem): Promise<void> {
+    const existing = await fs.stat(profileDir);
+    if (existing) {
+        if (!existing.isDirectory())
+            throw new InvalidProfileDirError(`profileDir is not a directory: "${profileDir}".`);
+        return; // adopt the existing directory in place — never move, re-permission, or delete
+    }
+    if (headless) throw new BrowserProfileMissingError(profileDir);
+    await mkdir(profileDir, { recursive: true, mode: PROFILE_DIR_MODE });
+}
+
+/**
+ * @internal Test-visible seam: the real runtime-lazy `import('playwright')`.
+ * Exported only so the coverage test can execute it without launching a
+ * browser — every default-launcher path that reaches it would call the real
+ * `launchPersistentContext` next.
+ */
+export async function defaultLoadPlaywright(): Promise<typeof import('playwright')> {
+    return import('playwright');
+}
+
+function mapLaunchError(profileDir: string, error: unknown): unknown {
+    const message = error instanceof Error ? error.message : String(error);
+    if (BUSY_PROFILE_PATTERN.test(message)) return new BrowserProfileBusyError(profileDir, error);
+    if (CHROMIUM_MISSING_PATTERN.test(message)) {
+        return new PlaywrightUnavailableError(
+            'Chromium is not installed for Playwright. Run `npx playwright install chromium` and retry.',
+            { cause: error },
+        );
+    }
+    return error;
+}
+
+/**
+ * Default {@link BrowserLauncher}: lazily imports the `playwright` peer,
+ * guarantees an owner-only profile directory, and maps known Chromium/Playwright
+ * launch failures onto this package's typed errors.
+ */
+export function createPersistentLauncher(options: PersistentLauncherOptions = {}): BrowserLauncher {
+    const loadPlaywright = options.loadPlaywright ?? defaultLoadPlaywright;
+    const fs = options.fileSystem ?? nodeBunFactory.createFileSystem();
+    return {
+        async launch(request: ProfileLaunchRequest): Promise<BrowserContext> {
+            const profileDir = resolveProfileDir(request.profileDir);
+            await ensureProfileDir(profileDir, request.headless, fs);
+            let playwright: typeof import('playwright');
+            try {
+                playwright = await loadPlaywright();
+            } catch (error) {
+                if (error instanceof PlaywrightUnavailableError) throw error;
+                throw new PlaywrightUnavailableError(
+                    'The "playwright" peer dependency is not installed. Add playwright@^1.55.0 to your dependencies ' +
+                        'and run `npx playwright install chromium` to download the browser.',
+                    { cause: error },
+                );
+            }
+            try {
+                return await playwright.chromium.launchPersistentContext(profileDir, { headless: request.headless });
+            } catch (error) {
+                throw mapLaunchError(profileDir, error);
+            }
+        },
+    };
+}

package/src/operations.ts

@@ -0,0 +1,180 @@
+import type { BrowserContext, Page } from 'playwright';
+import { LoginTimeoutError, OperationAbortedError } from './errors';
+import { type BrowserLauncher, createPersistentLauncher } from './launcher';
+import { resolveProfileDir } from './profile-dir';
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+const POLL_INTERVAL_MS = 250;
+
+// Lazily built so importing the module has no side effects (sideEffects: false).
+let defaultLauncher: BrowserLauncher | undefined;
+function getDefaultLauncher(): BrowserLauncher {
+    if (defaultLauncher === undefined) defaultLauncher = createPersistentLauncher();
+    return defaultLauncher;
+}
+
+/** Caller-owned readiness check. The package never infers authentication from profile state. */
+export type IsAuthenticatedPredicate = (page: Page) => boolean | Promise<boolean>;
+
+/** Options for the low-level persistent-context opener with caller-owned lifetime. */
+export interface OpenPersistentBrowserOptions {
+    /** Dedicated Chromium user-data directory (created owner-only when absent; adopted in place when present). */
+    profileDir: string;
+    headless: boolean;
+    /** Launcher override (tests / custom browser provisioning). */
+    launcher?: BrowserLauncher;
+}
+
+/**
+ * Low-level persistent-context opener. The returned context's lifetime is
+ * caller-owned — close it in a `finally` block, or prefer {@link withProfilePage}.
+ */
+export async function openPersistentBrowser(options: OpenPersistentBrowserOptions): Promise<BrowserContext> {
+    return (options.launcher ?? getDefaultLauncher()).launch({
+        profileDir: resolveProfileDir(options.profileDir),
+        headless: options.headless,
+    });
+}
+
+/** Options for the headed one-time login that polls the caller's readiness predicate. */
+export interface LoginWithProfileOptions {
+    /** Dedicated Chromium user-data directory. */
+    profileDir: string;
+    /** Login page to open in the visible browser. */
+    url: string;
+    /** Site-owned readiness check polled until it passes or the deadline expires. */
+    isAuthenticated: IsAuthenticatedPredicate;
+    /** Finite deadline for predicate confirmation. */
+    timeoutMs: number;
+    signal?: AbortSignal;
+    launcher?: BrowserLauncher;
+}
+
+/**
+ * Open a headed browser on `url`, let the user sign in, and resolve only once
+ * `isAuthenticated(page)` passes. The context is closed on success, timeout,
+ * cancellation, and error. No credential is ever read or stored — the profile
+ * directory itself is the login artifact.
+ */
+export async function loginWithProfile(options: LoginWithProfileOptions): Promise<void> {
+    assertNotAborted(options.signal);
+    assertFiniteTimeoutMs(options.timeoutMs);
+    const context = await (options.launcher ?? getDefaultLauncher()).launch({
+        profileDir: resolveProfileDir(options.profileDir),
+        headless: false,
+    });
+    try {
+        const page = await openPage(context);
+        await page.goto(options.url);
+        await pollPredicate(page, options.isAuthenticated, options.timeoutMs, options.signal);
+    } finally {
+        await context.close();
+    }
+}
+
+/** Handle returned to the callback with the opened context and its page. */
+export interface ProfilePageHandle {
+    context: BrowserContext;
+    page: Page;
+}
+
+/** Options for the scoped callback helper that guarantees context closure in `finally`. */
+export interface WithProfilePageOptions {
+    /** Dedicated Chromium user-data directory. */
+    profileDir: string;
+    /** Headless reuse defaults to `false`; pass `true` for unattended runs (requires an existing profile). */
+    headless?: boolean;
+    url?: string;
+    /** When provided, the callback runs only after the readiness predicate passes (task 0088 R3). */
+    isAuthenticated?: IsAuthenticatedPredicate;
+    /** Deadline for predicate confirmation (default 30s; ignored without `isAuthenticated`). */
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    launcher?: BrowserLauncher;
+}
+
+/**
+ * Scoped session helper: launch a persistent context, hand the caller
+ * `{ context, page }`, and guarantee `context.close()` in `finally` on every
+ * exit path. `context` is a genuine Playwright context — callers own
+ * site-specific CDP via `context.newCDPSession(page)`.
+ */
+export async function withProfilePage<T>(
+    options: WithProfilePageOptions,
+    callback: (handle: ProfilePageHandle) => Promise<T>,
+): Promise<T> {
+    assertNotAborted(options.signal);
+    if (options.isAuthenticated !== undefined) assertFiniteTimeoutMs(options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    const context = await (options.launcher ?? getDefaultLauncher()).launch({
+        profileDir: resolveProfileDir(options.profileDir),
+        headless: options.headless ?? false,
+    });
+    try {
+        const page = await openPage(context);
+        if (options.url !== undefined) await page.goto(options.url);
+        if (options.isAuthenticated !== undefined) {
+            await pollPredicate(page, options.isAuthenticated, options.timeoutMs ?? DEFAULT_TIMEOUT_MS, options.signal);
+        }
+        return await callback({ context, page });
+    } finally {
+        await context.close();
+    }
+}
+
+function assertNotAborted(signal: AbortSignal | undefined): void {
+    if (signal?.aborted) throw new OperationAbortedError();
+}
+
+async function openPage(context: BrowserContext): Promise<Page> {
+    const existing = context.pages()[0];
+    return existing ?? (await context.newPage());
+}
+
+/** Rejects a non-finite or negative timeout at op entry — before any browser opens — so a bad value cannot park a headed window in an endless poll. */
+function assertFiniteTimeoutMs(timeoutMs: number): void {
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 0) {
+        throw new TypeError(`timeoutMs must be a finite non-negative number of milliseconds; received ${timeoutMs}`);
+    }
+}
+
+async function pollPredicate(
+    page: Page,
+    predicate: IsAuthenticatedPredicate,
+    timeoutMs: number,
+    signal: AbortSignal | undefined,
+): Promise<void> {
+    const timeoutError = new LoginTimeoutError(
+        `Authentication was not confirmed within ${timeoutMs}ms. The profile's site session has likely ` +
+            'expired or the sign-in was not completed: re-run loginWithProfile() with the same profileDir to sign in again.',
+    );
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let onAbort: (() => void) | undefined;
+    let stopped = false;
+    const deadline = new Promise<never>((_, reject) => {
+        timer = setTimeout(() => reject(timeoutError), timeoutMs);
+        if (signal) {
+            onAbort = () => reject(new OperationAbortedError());
+            signal.addEventListener('abort', onAbort, { once: true });
+            if (signal.aborted) onAbort();
+        }
+    });
+    const poll = async () => {
+        for (;;) {
+            if (stopped) return;
+            assertNotAborted(signal);
+            if (await predicate(page)) return;
+            await sleep(POLL_INTERVAL_MS);
+        }
+    };
+    try {
+        await Promise.race([poll(), deadline]);
+    } finally {
+        stopped = true;
+        if (timer) clearTimeout(timer);
+        if (signal && onAbort) signal.removeEventListener('abort', onAbort);
+    }
+}
+
+function sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/profile-dir.ts

@@ -0,0 +1,19 @@
+import { isAbsolutePath, resolvePath } from '@gobing-ai/ts-runtime';
+import { InvalidProfileDirError } from './errors';
+
+/**
+ * Validate a caller-supplied `profileDir` and resolve it to an absolute path
+ * (relative inputs resolve against the current working directory). Rejection
+ * of empty/blank paths happens here so every operation and launcher entry
+ * point behaves identically.
+ */
+export function resolveProfileDir(profileDir: string): string {
+    if (profileDir.trim() === '') {
+        throw new InvalidProfileDirError();
+    }
+    const resolved = resolvePath(profileDir);
+    if (!isAbsolutePath(resolved)) {
+        throw new InvalidProfileDirError(`profileDir could not be resolved to an absolute path: "${profileDir}".`);
+    }
+    return resolved;
+}