@webhands/core 0.1.0 → 0.3.0

package/dist/playwright-launch-transport.js

@@ -1,7 +1,23 @@
 import { stat } from 'node:fs/promises';
-import { chromium, errors as pwErrors, } from 'playwright';
-import { MissingBrowserBinaryError, MissingProfileError } from './errors.js';
+import { chromium } from 'playwright';
+import { MissingBrowserBinaryError, MissingProfileError, MissingStealthDependencyError, } from './errors.js';
+import { composeWithHands } from './hand-host.js';
 import { resolveProfileLocation, } from './profile-location.js';
+/**
+ * The package name of the optional stealth dependency. Kept as a runtime value
+ * (not an `import('patchright')` literal) so TypeScript does NOT try to resolve
+ * its types at build time, since it is an OPTIONAL dependency that is legitimately
+ * absent when stealth is never enabled.
+ */
+const STEALTH_PACKAGE = 'patchright';
+/** The default lazy import of the OPTIONAL `patchright` dependency. */
+const defaultStealthImporter = async () => {
+    // Indirect (non-literal specifier) so tsc/bundlers do not resolve the
+    // optional dep eagerly, and the module load never fails when it is absent;
+    // the import only runs when stealth is opted in.
+    const specifier = STEALTH_PACKAGE;
+    return (await import(specifier));
+};
 /**
  * The v1 concrete transport: a Playwright browser the controller LAUNCHES
  * against a dedicated, persistent profile directory it owns (PRD "Solution,
@@ -18,16 +34,40 @@ import { resolveProfileLocation, } from './profile-location.js';
  * `WEBHANDS_HOME` env var, or `~/.webhands`). See
  * {@link resolveProfileLocation}. Because that is a SHARED location, tests pass
  * a temp `root` (or set the env var) and assert the real home is untouched.
+ *
+ * STEALTH (opt-in, default OFF): the third constructor arg can enable a
+ * Patchright-backed launch ({@link PlaywrightLaunchTransportOptions}). Patchright
+ * is an OPTIONAL dependency imported lazily only when stealth is enabled; if it
+ * is absent the transport throws {@link MissingStealthDependencyError} rather
+ * than falling back to vanilla. This addresses ONLY the CDP `Runtime.enable`
+ * automation tell; a real profile/IP/session reputation still matter (ADR-0002).
  */
 export class PlaywrightLaunchTransport {
     #location;
+    #hands;
+    #stealth;
+    #systemBrowser;
+    #importStealthChromium;
     /**
      * @param location overrides for where profiles live (a `root` dir and/or an
      *   `env`). Omit in production to use `~/.webhands`; pass a temp
      *   `root` in tests to isolate the shared profile location.
+     * @param hands explicitly-loaded third-party hands to compose alongside the
+     *   built-ins (Phase 2, ADR-0007). These come from {@link loadHands} against
+     *   the operator's explicit config; the transport does NOT discover them. Omit
+     *   for the built-ins-only surface.
+     * @param options transport-construction policy, notably the opt-in `stealth`
+     *   toggle and optional `systemBrowser` (see
+     *   {@link PlaywrightLaunchTransportOptions}). Defaults to vanilla Playwright,
+     *   bundled Chromium, stealth OFF.
      */
-    constructor(location = {}) {
+    constructor(location = {}, hands = [], options = {}) {
         this.#location = location;
+        this.#hands = hands;
+        this.#stealth = options.stealth === true;
+        this.#systemBrowser = options.systemBrowser;
+        this.#importStealthChromium =
+            options.importStealthChromium ?? defaultStealthImporter;
     }
     async open(target) {
         if (target.mode !== 'launch') {
@@ -45,15 +85,35 @@ export class PlaywrightLaunchTransport {
             throw new MissingProfileError(loc.profile, loc.profileDir);
         }
         const headless = target.headed !== true;
+        // Pick the engine: the lazily-imported stealth (Patchright) chromium when
+        // opted in, else vanilla Playwright's. Resolving the stealth module is where
+        // an absent optional dependency surfaces as the typed
+        // MissingStealthDependencyError (we never fall back to vanilla silently).
+        const launcher = this.#stealth
+            ? await this.#resolveStealthLauncher()
+            : chromium;
+        // Launch options: forward headless, the optional systemBrowser (Playwright's
+        // `channel`, e.g. 'chrome' to drive system Chrome, Patchright's recommended
+        // setup), and for stealth drop Playwright's automation-flavoured default
+        // args so they cannot re-add the fingerprint Patchright just removed.
+        const launchOptions = { headless };
+        if (this.#systemBrowser !== undefined) {
+            launchOptions.channel = this.#systemBrowser;
+        }
+        if (this.#stealth) {
+            launchOptions.ignoreDefaultArgs = ['--enable-automation'];
+        }
         let context;
         try {
-            context = await chromium.launchPersistentContext(loc.profileDir, {
-                headless,
-            });
+            context = await launcher.launchPersistentContext(loc.profileDir, launchOptions);
         }
         catch (cause) {
             if (isMissingBrowserBinary(cause)) {
-                throw new MissingBrowserBinaryError('chromium', undefined, { cause });
+                // With systemBrowser set (e.g. 'chrome') the "binary missing" failure
+                // means the SYSTEM browser is absent, not the bundled Chromium; name
+                // what is actually missing so the CLI's fix message is accurate.
+                const browser = this.#systemBrowser ?? 'chromium';
+                throw new MissingBrowserBinaryError(browser, undefined, { cause });
             }
             throw cause;
         }
@@ -61,7 +121,32 @@ export class PlaywrightLaunchTransport {
         // the single active page (PRD: single active session in v1). Create one if
         // the build ever changes that invariant.
         const pwPage = context.pages()[0] ?? (await context.newPage());
-        return makeSession(context, pwPage);
+        return makeSession(context, pwPage, this.#hands);
+    }
+    /**
+     * Resolve the stealth (`patchright`) chromium via the injected lazy importer.
+     *
+     * Confines the brittle "optional dependency absent" detection to ONE spot
+     * (mirroring {@link isMissingBrowserBinary}): any failure to import the
+     * optional package becomes the typed {@link MissingStealthDependencyError}, so
+     * the caller never silently degrades to vanilla Playwright.
+     */
+    async #resolveStealthLauncher() {
+        let mod;
+        try {
+            mod = await this.#importStealthChromium();
+        }
+        catch (cause) {
+            throw new MissingStealthDependencyError('patchright', undefined, {
+                cause,
+            });
+        }
+        if (mod === null ||
+            typeof mod !== 'object' ||
+            typeof mod.chromium?.launchPersistentContext !== 'function') {
+            throw new MissingStealthDependencyError('patchright');
+        }
+        return mod.chromium;
     }
 }
 /** True iff `path` exists and is a directory. */
@@ -79,227 +164,75 @@ async function isExistingDirectory(path) {
  * does not export a typed error for this, so we detect on the message (it
  * instructs the user to run `playwright install`). We confine that brittle
  * string match to this one spot and re-raise as a stable typed error.
+ *
+ * This also covers the `channel: 'chrome'` case, where the missing binary is the
+ * SYSTEM Chrome, not the bundled Chromium. Playwright phrases that as the
+ * channel/distribution not being found; we match those variants too so the
+ * stealth+system-Chrome path still yields the typed MissingBrowserBinaryError.
  */
 function isMissingBrowserBinary(cause) {
     const message = cause instanceof Error ? cause.message : String(cause ?? '');
     return (/Executable doesn't exist/i.test(message) ||
         /please run the following command to download new browsers/i.test(message) ||
-        /playwright install/i.test(message));
+        /playwright install/i.test(message) ||
+        // channel: 'chrome' (or other system channels) not installed on the host.
+        /Chromium distribution '.*' is not found/i.test(message) ||
+        /No "?(chrome|msedge|chromium)"? .* found/i.test(message));
 }
-/** Wrap a live Playwright persistent context into the seam's {@link Session}. */
-function makeSession(context, pwPage) {
+/**
+ * Wrap a live Playwright persistent context into the seam's {@link Session}.
+ *
+ * The VERB surface comes from the shared hand-host ({@link composeBuiltInPage}),
+ * which is the single place the eight built-in verbs are composed (no duplicated
+ * page-object literal). Only the SESSION LIFECYCLE is per-transport here: the
+ * launch transport listens on the context's `'close'` event and its `close()`
+ * calls `context.close()`, which KILLS the browser this transport spawned
+ * (contrast the attach transport, which detaches without killing the user's
+ * browser, ADR-0002).
+ */
+function makeSession(context, pwPage, extraHands) {
     let closed = false;
     const ensureOpen = () => {
         if (closed) {
             throw new Error('session is closed');
         }
     };
-    const page = {
-        async navigate(url) {
-            ensureOpen();
-            // "Settled" for `goto` = the `load` event: the document and its
-            // subresources have loaded (PRD story 6, "navigate ... and wait for it
-            // to settle"). We deliberately do NOT wait for `networkidle`:
-            // Playwright discourages it, and it hangs forever on pages with
-            // long-poll / streaming / analytics beacons (exactly the logged-in apps
-            // this tool targets). Content rendered AFTER load (XHR-injected prices,
-            // hydrated lists) is the job of the explicit `wait` verb (story 10), not
-            // of `goto`.
-            await pwPage.goto(url, { waitUntil: 'load' });
-        },
-        async snapshot(options) {
-            ensureOpen();
-            const url = pwPage.url();
-            if (options?.full === true) {
-                // `--full`: the raw DOM. `documentElement.outerHTML` is the serialized
-                // live DOM (post-script render), which is what an agent that wants the
-                // real HTML expects — not the original network response.
-                const content = await pwPage.evaluate(() => document.documentElement.outerHTML);
-                return { url, view: 'full', content };
-            }
-            // Default: the token-cheap accessibility tree + visible text with stable
-            // `[ref=...]` element refs. Playwright's `ariaSnapshot({mode: 'ai'})`
-            // emits exactly that — a YAML aria tree (roles + accessible names +
-            // text) where each node carries a stable `[ref=eN]` reference, assigned
-            // deterministically by traversal order so re-snapshotting an unchanged
-            // page yields the same refs. The string crosses the seam as opaque,
-            // transport-neutral text (no Playwright type leaks, ADR-0003).
-            const content = await pwPage.ariaSnapshot({ mode: 'ai' });
-            return { url, view: 'accessibility', content };
-        },
-        async click(t) {
-            ensureOpen();
-            await clickLocator(pwPage, t);
-        },
-        async type(t, text) {
-            ensureOpen();
-            await resolveLocator(pwPage, t).fill(text);
-        },
-        async eval(expression) {
-            ensureOpen();
-            // The `eval` escape hatch (PRD story 9): run the raw JS EXPRESSION in the
-            // page and return its serializable result. Playwright's `evaluate`
-            // already IS the seam's serialization contract (see {@link Page.eval}):
-            // it passes a string as an expression, awaits a returned Promise, and
-            // structurally clones the result out of the page by VALUE. That clone is
-            // richer than JSON: it preserves NaN/Infinity/BigInt and circular
-            // structures (back-refs become a `[Circular]` marker), yields `undefined`
-            // for functions/symbols, and returns an opaque preview string for a live
-            // host object (a DOM node never crosses the process boundary). A page-side
-            // throw rejects. We pass it straight through rather than re-encode it:
-            // wrapping the value in a transport-specific envelope would invent a
-            // dialect the seam deliberately avoids. The thrown error is a plain
-            // `Error`, so no Playwright/CDP type leaks across the seam (ADR-0003).
-            return pwPage.evaluate(expression);
-        },
-        async wait(condition) {
-            ensureOpen();
-            await waitFor(pwPage, condition);
-        },
-        async cookies() {
-            ensureOpen();
-            const raw = await context.cookies();
-            return raw.map(toSeamCookie);
-        },
-        async setCookies(cookies) {
-            ensureOpen();
-            await context.addCookies(cookies.map(fromSeamCookie));
-        },
+    // Resolves the first time the context is gone — whether the USER closed the
+    // window (Playwright fires the context 'close' event) or our own close()
+    // ran. This is what lets `setup-profile` hold the headed window open and
+    // block on waitForClose() until the human is done.
+    let resolveClosed;
+    const closedSignal = new Promise((resolve) => {
+        resolveClosed = resolve;
+    });
+    const markClosed = () => {
+        if (closed)
+            return;
+        closed = true;
+        resolveClosed();
     };
+    context.on('close', markClosed);
+    // Build the verb surface from the built-in hands over a live hand-context.
+    // The host keeps the live `pwPage`/`context` in-process (they never cross the
+    // seam, ADR-0003); the hand-context carries live page access only.
+    const handContext = { pwPage, context, ensureOpen };
+    const { page, dispose: disposeHands } = composeWithHands(handContext, extraHands);
     return {
         page,
         async close() {
-            if (closed)
+            if (closed) {
                 return;
-            closed = true;
+            }
+            // Dispose the hands first (their in-process resources), THEN tear down
+            // the browser: context.close() fires the 'close' event, which runs
+            // markClosed and KILLS the browser this transport spawned.
+            await disposeHands();
             await context.close();
+            markClosed();
+        },
+        waitForClose() {
+            return closedSignal;
         },
-    };
-}
-/**
- * Run the `wait` verb's three forms (PRD story 10) against a Playwright page.
- *
- * - `timeout` — pace by a fixed delay (`waitForTimeout`), so an agent can act
- *   like a human and let XHR-rendered content land.
- * - `locator` — block until the addressed element appears (`Locator.waitFor()`),
- *   the form for content rendered AFTER `goto` settled on `load`.
- * - `navigation` — block until the NEXT navigation settles to `load`. We use
- *   `waitForNavigation()` even though Playwright marks it `@deprecated` ("racy,
- *   use waitForURL"): that deprecation targets in-process TEST code that can arm
- *   the wait BEFORE the action and pass a target URL. Neither holds here. Across
- *   this seam verbs are DISCRETE sequential calls (`click` then `wait`), so we
- *   CANNOT arm before the trigger; and the realistic trigger is an async,
- *   JS-driven transition (a redirect / SPA route change that fires AFTER the
- *   agent's action, the "let XHR-rendered content load" case of story 10), so
- *   "wait for the NEXT navigation" is exactly right — whereas `waitForLoadState`
- *   would see the already-loaded current page and return before the pending
- *   transition. `waitForURL` is unusable because the verb has no target URL by
- *   design (the agent waits for "a navigation", not a known address). (See the
- *   task's ## Decisions note.)
- *
- * Shared by both Playwright transports so the verb behaviour stays identical
- * (the forward-note's "do NOT write a parallel second implementation").
- */
-export async function waitFor(page, condition) {
-    switch (condition.kind) {
-        case 'timeout':
-            await page.waitForTimeout(condition.ms);
-            return;
-        case 'locator':
-            await resolveLocator(page, condition.target).waitFor();
-            return;
-        case 'navigation':
-            // eslint-disable-next-line @typescript-eslint/no-deprecated
-            await page.waitForNavigation();
-            return;
-    }
-}
-/**
- * Resolve a raw Playwright locator EXPRESSION (ADR-0004) against the page. The
- * verb surface passes locator expressions like `getByRole('button', …)`; we
- * evaluate them in a small sandbox where `page`/`p` is the page, so the full
- * Playwright locator grammar is available without leaking the type across the
- * seam.
- *
- * Exported (with {@link clickLocator}/{@link waitFor}) so the attach transport
- * resolves locators IDENTICALLY — one resolution path, no parallel addressing
- * scheme (the forward-note's "do NOT write a parallel second implementation").
- */
-export function resolveLocator(page, expression) {
-    // eslint-disable-next-line no-new-func
-    const factory = new Function('page', 'p', `return (${expression});`);
-    return factory(page, page);
-}
-/**
- * How long a normal, actionability-checked `click` may wait before we treat the
- * element as un-clickable and fall back to a dispatched click. Short on purpose:
- * a hidden custom input never becomes actionable, so the regular click would
- * otherwise burn Playwright's full default timeout (30s) before the escape path
- * runs. The visible-element happy path clicks immediately and never hits this;
- * this bound is the latency cost paid ONLY on the hidden/non-actionable path,
- * and is long enough to tolerate a slow-but-eventually-actionable element
- * (animations, late layout) before deciding to dispatch.
- */
-const NORMAL_CLICK_TIMEOUT_MS = 1_000;
-/**
- * Run the `click` verb against a Playwright page (PRD story 8), shared by both
- * Playwright transports so the verb behaves identically (mirrors {@link waitFor};
- * the forward-note's "do NOT write a parallel second implementation").
- *
- * First try a normal `Locator.click()`, which AUTO-WAITS for the element to be
- * visible and actionable — the right behaviour for a real button. A hidden
- * custom input (the case the prd calls out) NEVER becomes actionable, so that
- * click times out; on a Playwright `TimeoutError` we fall back to
- * `dispatchEvent('click')`, which fires a click WITHOUT the actionability
- * checks. The fallback is deliberately the documented Playwright escape (a
- * sibling to the `eval` hatch, ADR-0004), not a reimplemented click: we keep
- * the locator a raw resolved expression and only change HOW the resolved
- * locator is clicked.
- *
- * Only a timeout triggers the fallback. The fallback `dispatchEvent` is itself
- * bounded by the same short timeout, so a locator that resolves NO element (a
- * bad locator) surfaces its timeout quickly instead of hanging the dispatch on
- * Playwright's 30s default — the dispatch escape is for elements that EXIST but
- * are not actionable (hidden custom inputs), not for absent ones.
- */
-export async function clickLocator(page, expression) {
-    const target = resolveLocator(page, expression);
-    try {
-        await target.click({ timeout: NORMAL_CLICK_TIMEOUT_MS });
-    }
-    catch (cause) {
-        if (!(cause instanceof pwErrors.TimeoutError)) {
-            throw cause;
-        }
-        // The element never became actionable (e.g. a hidden custom input). Fire
-        // the click without actionability checks, the prd's explicit escape path.
-        await target.dispatchEvent('click', { timeout: NORMAL_CLICK_TIMEOUT_MS });
-    }
-}
-/** Map a Playwright cookie to the transport-neutral seam {@link Cookie}. */
-function toSeamCookie(c) {
-    return {
-        name: c.name,
-        value: c.value,
-        domain: c.domain,
-        path: c.path,
-        expires: c.expires,
-        httpOnly: c.httpOnly,
-        secure: c.secure,
-        sameSite: c.sameSite,
-    };
-}
-/** Map a seam {@link Cookie} to a Playwright cookie shape. */
-function fromSeamCookie(c) {
-    return {
-        name: c.name,
-        value: c.value,
-        domain: c.domain,
-        path: c.path,
-        expires: c.expires,
-        httpOnly: c.httpOnly,
-        secure: c.secure,
-        sameSite: c.sameSite,
     };
 }
 //# sourceMappingURL=playwright-launch-transport.js.map

package/dist/playwright-launch-transport.js.map

@@ -1 +1 @@
-{"version":3,"file":"playwright-launch-transport.js","sourceRoot":"","sources":["../src/playwright-launch-transport.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,IAAI,EAAC,MAAM,kBAAkB,CAAC;AACtC,OAAO,EACN,QAAQ,EACR,MAAM,IAAI,QAAQ,GAGlB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAC,yBAAyB,EAAE,mBAAmB,EAAC,MAAM,aAAa,CAAC;AAC3E,OAAO,EACN,sBAAsB,GAEtB,MAAM,uBAAuB,CAAC;AAY/B;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,yBAAyB;IAC5B,SAAS,CAAyB;IAE3C;;;;OAIG;IACH,YAAY,WAAmC,EAAE;QAChD,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;IAC3B,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,MAAkB;QAC5B,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CACd,mDAAmD;gBAClD,IAAI,MAAM,CAAC,IAAI,qCAAqC,CACrD,CAAC;QACH,CAAC;QAED,MAAM,GAAG,GAAG,sBAAsB,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QAEnE,0EAA0E;QAC1E,oEAAoE;QACpE,wEAAwE;QACxE,0EAA0E;QAC1E,wEAAwE;QACxE,WAAW;QACX,IAAI,CAAC,CAAC,MAAM,mBAAmB,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC;YAClD,MAAM,IAAI,mBAAmB,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC;QAC5D,CAAC;QAED,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,KAAK,IAAI,CAAC;QAExC,IAAI,OAAuB,CAAC;QAC5B,IAAI,CAAC;YACJ,OAAO,GAAG,MAAM,QAAQ,CAAC,uBAAuB,CAAC,GAAG,CAAC,UAAU,EAAE;gBAChE,QAAQ;aACR,CAAC,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,IAAI,sBAAsB,CAAC,KAAK,CAAC,EAAE,CAAC;gBACnC,MAAM,IAAI,yBAAyB,CAAC,UAAU,EAAE,SAAS,EAAE,EAAC,KAAK,EAAC,CAAC,CAAC;YACrE,CAAC;YACD,MAAM,KAAK,CAAC;QACb,CAAC;QAED,0EAA0E;QAC1E,2EAA2E;QAC3E,yCAAyC;QACzC,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;QAC/D,OAAO,WAAW,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IACrC,CAAC;CACD;AAED,iDAAiD;AACjD,KAAK,UAAU,mBAAmB,CAAC,IAAY;IAC9C,IAAI,CAAC;QACJ,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC;QAC3B,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC;IACxB,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,KAAK,CAAC;IACd,CAAC;AACF,CAAC;AAED;;;;;GAKG;AACH,SAAS,sBAAsB,CAAC,KAAc;IAC7C,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;IAC7E,OAAO,CACN,2BAA2B,CAAC,IAAI,CAAC,OAAO,CAAC;QACzC,4DAA4D,CAAC,IAAI,CAChE,OAAO,CACP;QACD,qBAAqB,CAAC,IAAI,CAAC,OAAO,CAAC,CACnC,CAAC;AACH,CAAC;AAED,iFAAiF;AACjF,SAAS,WAAW,CAAC,OAAuB,EAAE,MAAc;IAC3D,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,MAAM,UAAU,GAAG,GAAG,EAAE;QACvB,IAAI,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC;QACtC,CAAC;IACF,CAAC,CAAC;IAEF,MAAM,IAAI,GAAS;QAClB,KAAK,CAAC,QAAQ,CAAC,GAAW;YACzB,UAAU,EAAE,CAAC;YACb,gEAAgE;YAChE,uEAAuE;YACvE,8DAA8D;YAC9D,gEAAgE;YAChE,wEAAwE;YACxE,wEAAwE;YACxE,yEAAyE;YACzE,aAAa;YACb,MAAM,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,EAAC,SAAS,EAAE,MAAM,EAAC,CAAC,CAAC;QAC7C,CAAC;QACD,KAAK,CAAC,QAAQ,CAAC,OAAyB;YACvC,UAAU,EAAE,CAAC;YACb,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,EAAE,CAAC;YACzB,IAAI,OAAO,EAAE,IAAI,KAAK,IAAI,EAAE,CAAC;gBAC5B,uEAAuE;gBACvE,uEAAuE;gBACvE,yDAAyD;gBACzD,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,QAAQ,CACpC,GAAG,EAAE,CAAC,QAAQ,CAAC,eAAe,CAAC,SAAS,CACxC,CAAC;gBACF,OAAO,EAAC,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAC,CAAC;YACrC,CAAC;YACD,yEAAyE;YACzE,sEAAsE;YACtE,oEAAoE;YACpE,wEAAwE;YACxE,uEAAuE;YACvE,oEAAoE;YACpE,+DAA+D;YAC/D,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,EAAC,IAAI,EAAE,IAAI,EAAC,CAAC,CAAC;YACxD,OAAO,EAAC,GAAG,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAC,CAAC;QAC9C,CAAC;QACD,KAAK,CAAC,KAAK,CAAC,CAAC;YACZ,UAAU,EAAE,CAAC;YACb,MAAM,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;QAC/B,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,CAAC,EAAE,IAAI;YACjB,UAAU,EAAE,CAAC;YACb,MAAM,cAAc,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC5C,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,UAAkB;YAC5B,UAAU,EAAE,CAAC;YACb,0EAA0E;YAC1E,mEAAmE;YACnE,wEAAwE;YACxE,sEAAsE;YACtE,yEAAyE;YACzE,kEAAkE;YAClE,0EAA0E;YAC1E,yEAAyE;YACzE,2EAA2E;YAC3E,uEAAuE;YACvE,qEAAqE;YACrE,oEAAoE;YACpE,uEAAuE;YACvE,OAAO,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;QACpC,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,SAAwB;YAClC,UAAU,EAAE,CAAC;YACb,MAAM,OAAO,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;QAClC,CAAC;QACD,KAAK,CAAC,OAAO;YACZ,UAAU,EAAE,CAAC;YACb,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;YACpC,OAAO,GAAG,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;QAC9B,CAAC;QACD,KAAK,CAAC,UAAU,CAAC,OAAO;YACvB,UAAU,EAAE,CAAC;YACb,MAAM,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC;QACvD,CAAC;KACD,CAAC;IAEF,OAAO;QACN,IAAI;QACJ,KAAK,CAAC,KAAK;YACV,IAAI,MAAM;gBAAE,OAAO;YACnB,MAAM,GAAG,IAAI,CAAC;YACd,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC;QACvB,CAAC;KACD,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAC5B,IAAY,EACZ,SAAwB;IAExB,QAAQ,SAAS,CAAC,IAAI,EAAE,CAAC;QACxB,KAAK,SAAS;YACb,MAAM,IAAI,CAAC,cAAc,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;YACxC,OAAO;QACR,KAAK,SAAS;YACb,MAAM,cAAc,CAAC,IAAI,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,CAAC;YACvD,OAAO;QACR,KAAK,YAAY;YAChB,4DAA4D;YAC5D,MAAM,IAAI,CAAC,iBAAiB,EAAE,CAAC;YAC/B,OAAO;IACT,CAAC;AACF,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,UAAkB;IAC9D,uCAAuC;IACvC,MAAM,OAAO,GAAG,IAAI,QAAQ,CAAC,MAAM,EAAE,GAAG,EAAE,WAAW,UAAU,IAAI,CAGjC,CAAC;IACnC,OAAO,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AAC5B,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,uBAAuB,GAAG,KAAK,CAAC;AAEtC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CACjC,IAAY,EACZ,UAAkB;IAElB,MAAM,MAAM,GAAG,cAAc,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IAChD,IAAI,CAAC;QACJ,MAAM,MAAM,CAAC,KAAK,CAAC,EAAC,OAAO,EAAE,uBAAuB,EAAC,CAAC,CAAC;IACxD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,IAAI,CAAC,CAAC,KAAK,YAAY,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;YAC/C,MAAM,KAAK,CAAC;QACb,CAAC;QACD,yEAAyE;QACzE,0EAA0E;QAC1E,MAAM,MAAM,CAAC,aAAa,CAAC,OAAO,EAAE,EAAC,OAAO,EAAE,uBAAuB,EAAC,CAAC,CAAC;IACzE,CAAC;AACF,CAAC;AAED,4EAA4E;AAC5E,SAAS,YAAY,CAAC,CASrB;IACA,OAAO;QACN,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,OAAO,EAAE,CAAC,CAAC,OAAO;QAClB,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,QAAQ,EAAE,CAAC,CAAC,QAAQ;KACpB,CAAC;AACH,CAAC;AAED,8DAA8D;AAC9D,SAAS,cAAc,CAAC,CAAS;IAChC,OAAO;QACN,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,OAAO,EAAE,CAAC,CAAC,OAAO;QAClB,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,QAAQ,EAAE,CAAC,CAAC,QAAQ;KACpB,CAAC;AACH,CAAC"}
+{"version":3,"file":"playwright-launch-transport.js","sourceRoot":"","sources":["../src/playwright-launch-transport.ts"],"names":[],"mappings":"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"}

package/dist/remote-session.d.ts

@@ -4,7 +4,7 @@ import type { Session } from './seam.js';
  * long-lived `serve` process over HTTP (ADR-0005).
  *
  * Each `webhands <verb>` is a thin client: it cannot hold a JS
- * reference to the server's live page, so this proxy turns every {@link Page}
+ * reference to the server's live page, so this proxy turns every {@link WebHandsPage}
  * verb into a session-RPC call to the running server (see `session-rpc.ts`) and
  * returns the result. The verb command code is UNCHANGED — it still calls
  * `provider(target)` then runs verbs against the returned `Session.page` then
@@ -17,6 +17,16 @@ import type { Session } from './seam.js';
  * (`stop`), exactly as ADR-0005 requires. This is the whole reason cross-
  * invocation persistence works: the page state survives because the client's
  * `close()` does not reach across to the server's session.
+ *
+ * THIRD-PARTY HAND VERBS (Phase 2, Model B; ADR-0007). Pass the NAMES of the
+ * hand verbs the served process loaded as `handVerbs`; each is attached to the
+ * returned `page` as a dynamic method forwarding over the RPC via
+ * {@link callHandVerb}, so the agent gains those tools WITHOUT ever holding a
+ * live page handle. They are NOT on the seam `WebHandsPage` type (the seam knows only
+ * the eight built-ins), so a caller reaches them through a cast, exactly as a
+ * third-party hand verb is reached on the in-process composed page. The result
+ * crosses the wire as a serializable value and a page/in-hand throw rejects
+ * faithfully, the same contract as the built-in verbs.
  */
-export declare function connectRemoteSession(baseUrl: string): Session;
+export declare function connectRemoteSession(baseUrl: string, handVerbs?: readonly string[]): Session;
 //# sourceMappingURL=remote-session.d.ts.map

package/dist/remote-session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"remote-session.d.ts","sourceRoot":"","sources":["../src/remote-session.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,WAAW,CAAC;AAEvC;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAsC7D"}
+{"version":3,"file":"remote-session.d.ts","sourceRoot":"","sources":["../src/remote-session.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,WAAW,CAAC;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,oBAAoB,CACnC,OAAO,EAAE,MAAM,EACf,SAAS,GAAE,SAAS,MAAM,EAAO,GAC/B,OAAO,CA8DT"}

package/dist/remote-session.js

@@ -1,10 +1,10 @@
-import { makeRpcPage, SESSION_RPC_PATH, } from './session-rpc.js';
+import { callHandVerb, makeRpcPage, SESSION_RPC_PATH, } from './session-rpc.js';
 /**
  * A client-side {@link Session} that drives a session living in a SEPARATE
  * long-lived `serve` process over HTTP (ADR-0005).
  *
  * Each `webhands <verb>` is a thin client: it cannot hold a JS
- * reference to the server's live page, so this proxy turns every {@link Page}
+ * reference to the server's live page, so this proxy turns every {@link WebHandsPage}
  * verb into a session-RPC call to the running server (see `session-rpc.ts`) and
  * returns the result. The verb command code is UNCHANGED — it still calls
  * `provider(target)` then runs verbs against the returned `Session.page` then
@@ -17,8 +17,18 @@ import { makeRpcPage, SESSION_RPC_PATH, } from './session-rpc.js';
  * (`stop`), exactly as ADR-0005 requires. This is the whole reason cross-
  * invocation persistence works: the page state survives because the client's
  * `close()` does not reach across to the server's session.
+ *
+ * THIRD-PARTY HAND VERBS (Phase 2, Model B; ADR-0007). Pass the NAMES of the
+ * hand verbs the served process loaded as `handVerbs`; each is attached to the
+ * returned `page` as a dynamic method forwarding over the RPC via
+ * {@link callHandVerb}, so the agent gains those tools WITHOUT ever holding a
+ * live page handle. They are NOT on the seam `WebHandsPage` type (the seam knows only
+ * the eight built-ins), so a caller reaches them through a cast, exactly as a
+ * third-party hand verb is reached on the in-process composed page. The result
+ * crosses the wire as a serializable value and a page/in-hand throw rejects
+ * faithfully, the same contract as the built-in verbs.
  */
-export function connectRemoteSession(baseUrl) {
+export function connectRemoteSession(baseUrl, handVerbs = []) {
     const endpoint = new URL(SESSION_RPC_PATH, baseUrl).toString();
     const send = async (request) => {
         let res;
@@ -46,11 +56,32 @@ export function connectRemoteSession(baseUrl) {
         // process boundary.
         throw new Error(reply.error);
     };
+    let resolveClosed;
+    const closedSignal = new Promise((resolve) => {
+        resolveClosed = resolve;
+    });
+    const page = makeRpcPage(send);
+    // Attach each loaded hand verb as a dynamic method that forwards over the same
+    // RPC `send`. The seam `WebHandsPage` type names only the built-ins, so these live on
+    // the runtime object alongside them (mirroring how a hand verb composes into
+    // the in-process page object); callers reach them through a cast.
+    const pageWithHands = page;
+    for (const name of handVerbs) {
+        pageWithHands[name] = (...args) => callHandVerb(send, name, ...args);
+    }
     return {
-        page: makeRpcPage(send),
+        page,
         async close() {
-            // Intentionally a no-op: the served process owns the session's lifetime
-            // (see this module's overview). Teardown is the explicit `stop` verb.
+            // Intentionally a no-op against the SERVER: the served process owns the
+            // session's lifetime (see this module's overview). Teardown is the
+            // explicit `stop` verb. We still resolve the local close signal so a
+            // caller awaiting waitForClose() on this client handle unblocks.
+            resolveClosed();
+        },
+        waitForClose() {
+            // A client never waits on the user closing the window — that is the
+            // server's concern; this resolves on a local close() call.
+            return closedSignal;
         },
     };
 }

package/dist/remote-session.js.map

@@ -1 +1 @@
-{"version":3,"file":"remote-session.js","sourceRoot":"","sources":["../src/remote-session.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,WAAW,EACX,gBAAgB,GAGhB,MAAM,kBAAkB,CAAC;AAG1B;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAe;IACnD,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,gBAAgB,EAAE,OAAO,CAAC,CAAC,QAAQ,EAAE,CAAC;IAE/D,MAAM,IAAI,GAAG,KAAK,EAAE,OAA0B,EAAoB,EAAE;QACnE,IAAI,GAAa,CAAC;QAClB,IAAI,CAAC;YACJ,GAAG,GAAG,MAAM,KAAK,CAAC,QAAQ,EAAE;gBAC3B,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE,EAAC,cAAc,EAAE,kBAAkB,EAAC;gBAC7C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;aAC7B,CAAC,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,qEAAqE;YACrE,yEAAyE;YACzE,wEAAwE;YACxE,mEAAmE;YACnE,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACvE,MAAM,IAAI,KAAK,CACd,yCAAyC,OAAO,KAAK,OAAO,EAAE,CAC9D,CAAC;QACH,CAAC;QACD,MAAM,KAAK,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAuB,CAAC;QACvD,IAAI,KAAK,CAAC,EAAE,EAAE,CAAC;YACd,OAAO,KAAK,CAAC,KAAK,CAAC;QACpB,CAAC;QACD,4EAA4E;QAC5E,0EAA0E;QAC1E,oBAAoB;QACpB,MAAM,IAAI,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC9B,CAAC,CAAC;IAEF,OAAO;QACN,IAAI,EAAE,WAAW,CAAC,IAAI,CAAC;QACvB,KAAK,CAAC,KAAK;YACV,wEAAwE;YACxE,sEAAsE;QACvE,CAAC;KACD,CAAC;AACH,CAAC"}
+{"version":3,"file":"remote-session.js","sourceRoot":"","sources":["../src/remote-session.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,YAAY,EACZ,WAAW,EACX,gBAAgB,GAGhB,MAAM,kBAAkB,CAAC;AAG1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,UAAU,oBAAoB,CACnC,OAAe,EACf,YAA+B,EAAE;IAEjC,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,gBAAgB,EAAE,OAAO,CAAC,CAAC,QAAQ,EAAE,CAAC;IAE/D,MAAM,IAAI,GAAG,KAAK,EAAE,OAA0B,EAAoB,EAAE;QACnE,IAAI,GAAa,CAAC;QAClB,IAAI,CAAC;YACJ,GAAG,GAAG,MAAM,KAAK,CAAC,QAAQ,EAAE;gBAC3B,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE,EAAC,cAAc,EAAE,kBAAkB,EAAC;gBAC7C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;aAC7B,CAAC,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,qEAAqE;YACrE,yEAAyE;YACzE,wEAAwE;YACxE,mEAAmE;YACnE,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACvE,MAAM,IAAI,KAAK,CACd,yCAAyC,OAAO,KAAK,OAAO,EAAE,CAC9D,CAAC;QACH,CAAC;QACD,MAAM,KAAK,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAuB,CAAC;QACvD,IAAI,KAAK,CAAC,EAAE,EAAE,CAAC;YACd,OAAO,KAAK,CAAC,KAAK,CAAC;QACpB,CAAC;QACD,4EAA4E;QAC5E,0EAA0E;QAC1E,oBAAoB;QACpB,MAAM,IAAI,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC9B,CAAC,CAAC;IAEF,IAAI,aAA0B,CAAC;IAC/B,MAAM,YAAY,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QAClD,aAAa,GAAG,OAAO,CAAC;IACzB,CAAC,CAAC,CAAC;IAEH,MAAM,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IAC/B,+EAA+E;IAC/E,sFAAsF;IACtF,6EAA6E;IAC7E,kEAAkE;IAClE,MAAM,aAAa,GAAG,IAA0C,CAAC;IACjE,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;QAC9B,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,IAAwB,EAAoB,EAAE,CACvE,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC,CAAC;IACpC,CAAC;IAED,OAAO;QACN,IAAI;QACJ,KAAK,CAAC,KAAK;YACV,wEAAwE;YACxE,mEAAmE;YACnE,qEAAqE;YACrE,iEAAiE;YACjE,aAAa,EAAE,CAAC;QACjB,CAAC;QACD,YAAY;YACX,oEAAoE;YACpE,2DAA2D;YAC3D,OAAO,YAAY,CAAC;QACrB,CAAC;KACD,CAAC;AACH,CAAC"}

package/dist/seam.d.ts

@@ -65,7 +65,7 @@ export interface Cookie {
     readonly secure?: boolean;
     readonly sameSite?: 'Strict' | 'Lax' | 'None';
 }
-/** What to wait for in the {@link Page.wait} verb. */
+/** What to wait for in the {@link WebHandsPage.wait} verb. */
 export type WaitCondition = {
     readonly kind: 'timeout';
     readonly ms: number;
@@ -87,7 +87,7 @@ export type WaitCondition = {
  *   `needsAnswers` Q3): default is the accessibility view, `--full` is raw DOM.
  */
 export type SnapshotView = 'accessibility' | 'full';
-/** Options for the {@link Page.snapshot} verb. */
+/** Options for the {@link WebHandsPage.snapshot} verb. */
 export interface SnapshotOptions {
     /**
      * When `true`, return the raw DOM (`view: 'full'`) instead of the default
@@ -124,7 +124,7 @@ export interface Snapshot {
  * The page-level verb surface. One method per verb in the domain glossary.
  * All element addressing flows through {@link LocatorString}.
  */
-export interface Page {
+export interface WebHandsPage {
     /** Navigate the active page to a URL and let it settle. */
     navigate(url: string): Promise<void>;
     /**
@@ -187,16 +187,24 @@ export interface Page {
     setCookies(cookies: readonly Cookie[]): Promise<void>;
 }
 /**
- * A live browser session owning one active {@link Page}. The session lifetime
+ * A live browser session owning one active {@link WebHandsPage}. The session lifetime
  * spans from {@link Transport.open} to {@link Session.close}; it is the unit a
  * long-lived controller process keeps between CLI invocations (PRD
  * "session/daemon question").
  */
 export interface Session {
     /** The active page the verbs act on. */
-    readonly page: Page;
+    readonly page: WebHandsPage;
     /** Tear down the session and release the underlying browser resources. */
     close(): Promise<void>;
+    /**
+     * Resolve when the session is closed — either by the USER closing the browser
+     * window/context, or by a {@link Session.close} call. This is what lets a
+     * headed flow (notably `setup-profile`) HOLD the window open and block until
+     * the human is done, instead of tearing it down immediately. Resolves once
+     * (idempotent); resolves immediately if the session is already closed.
+     */
+    waitForClose(): Promise<void>;
 }
 /**
  * The transport seam. A `Transport` (a.k.a. driver) knows how to OPEN a

package/dist/seam.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"seam.d.ts","sourceRoot":"","sources":["../src/seam.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"seam.d.ts","sourceRoot":"","sources":["../src/seam.ts"],"names":[],"mappings":"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"}