@webhands/core 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1,7 +1,9 @@
-export type { Cookie, Driver, LocatorString, OpenTarget, Page, Session, Snapshot, SnapshotOptions, SnapshotView, Transport, WaitCondition, } from './seam.js';
+export type { Cookie, Driver, LocatorString, OpenTarget, WebHandsPage, Session, Snapshot, SnapshotOptions, SnapshotView, Transport, WaitCondition, } from './seam.js';
 export { locator } from './seam.js';
 export { serializeCookies, deserializeCookies, COOKIES_EXPORT_VERSION, type CookiesExport, } from './cookies-export.js';
 export { StubTransport, type StubCall } from './stub-transport.js';
+export type { Hand, HandContext, HandContribution } from './hand-host.js';
+export { readHandsConfig, normalizeConfig, loadHands, HandLoadError, HANDS_CONFIG_FILENAME, type HandEntry, type HandsConfig, type LoadedHand, type LoadHandsOptions, } from './hand-loading.js';
 export { PlaywrightLaunchTransport } from './playwright-launch-transport.js';
 export { PlaywrightAttachTransport } from './playwright-attach-transport.js';
 export { setupProfile, buildPrompt, type PromptSink, type SetupProfileOptions, type SetupProfileResult, } from './setup-profile.js';
@@ -9,7 +11,7 @@ export { ControllerError, MissingBrowserBinaryError, MissingProfileError, Attach
 export { resolveSessionEndpointPath, writeSessionEndpoint, readSessionEndpoint, clearSessionEndpoint, SESSION_ENDPOINT_FILENAME, type SessionEndpoint, } from './session-endpoint.js';
 export { startSessionServer, sessionAlreadyActive, type SessionServerOptions, type RunningSessionServer, } from './session-server.js';
 export { connectRemoteSession } from './remote-session.js';
-export { SESSION_RPC_PATH, applySessionRpc, makeRpcPage, type SessionRpcRequest, type SessionRpcResponse, } from './session-rpc.js';
+export { SESSION_RPC_PATH, applySessionRpc, makeRpcPage, callHandVerb, type SessionRpcRequest, type SessionRpcBuiltInRequest, type SessionRpcHandRequest, type SessionRpcResponse, } from './session-rpc.js';
 export { resolveHomeRoot, resolveProfileLocation, CONTROLLER_HOME_ENV, DEFAULT_HOME_DIRNAME, PROFILES_DIRNAME, type ProfileLocation, type ProfileLocationOptions, } from './profile-location.js';
 export { startFixtureServer, type FixtureServer, } from './test-fixtures/fixture-server.js';
 export { FIXTURE_PAGES } from './test-fixtures/fixture-pages.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACX,MAAM,EACN,MAAM,EACN,aAAa,EACb,UAAU,EACV,IAAI,EACJ,OAAO,EACP,QAAQ,EACR,eAAe,EACf,YAAY,EACZ,SAAS,EACT,aAAa,GACb,MAAM,WAAW,CAAC;AACnB,OAAO,EAAC,OAAO,EAAC,MAAM,WAAW,CAAC;AAElC,OAAO,EACN,gBAAgB,EAChB,kBAAkB,EAClB,sBAAsB,EACtB,KAAK,aAAa,GAClB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAC,aAAa,EAAE,KAAK,QAAQ,EAAC,MAAM,qBAAqB,CAAC;AAEjE,OAAO,EAAC,yBAAyB,EAAC,MAAM,kCAAkC,CAAC;AAE3E,OAAO,EAAC,yBAAyB,EAAC,MAAM,kCAAkC,CAAC;AAE3E,OAAO,EACN,YAAY,EACZ,WAAW,EACX,KAAK,UAAU,EACf,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,GACvB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACN,eAAe,EACf,yBAAyB,EACzB,mBAAmB,EACnB,sBAAsB,EACtB,oBAAoB,EACpB,iBAAiB,EACjB,yBAAyB,EACzB,iBAAiB,EACjB,KAAK,mBAAmB,GACxB,MAAM,aAAa,CAAC;AAErB,OAAO,EACN,0BAA0B,EAC1B,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,yBAAyB,EACzB,KAAK,eAAe,GACpB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACN,kBAAkB,EAClB,oBAAoB,EACpB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,GACzB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAC,oBAAoB,EAAC,MAAM,qBAAqB,CAAC;AAEzD,OAAO,EACN,gBAAgB,EAChB,eAAe,EACf,WAAW,EACX,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,GACvB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACN,eAAe,EACf,sBAAsB,EACtB,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EAChB,KAAK,eAAe,EACpB,KAAK,sBAAsB,GAC3B,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACN,kBAAkB,EAClB,KAAK,aAAa,GAClB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAC,aAAa,EAAC,MAAM,kCAAkC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACX,MAAM,EACN,MAAM,EACN,aAAa,EACb,UAAU,EACV,YAAY,EACZ,OAAO,EACP,QAAQ,EACR,eAAe,EACf,YAAY,EACZ,SAAS,EACT,aAAa,GACb,MAAM,WAAW,CAAC;AACnB,OAAO,EAAC,OAAO,EAAC,MAAM,WAAW,CAAC;AAElC,OAAO,EACN,gBAAgB,EAChB,kBAAkB,EAClB,sBAAsB,EACtB,KAAK,aAAa,GAClB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAC,aAAa,EAAE,KAAK,QAAQ,EAAC,MAAM,qBAAqB,CAAC;AAEjE,YAAY,EAAC,IAAI,EAAE,WAAW,EAAE,gBAAgB,EAAC,MAAM,gBAAgB,CAAC;AAExE,OAAO,EACN,eAAe,EACf,eAAe,EACf,SAAS,EACT,aAAa,EACb,qBAAqB,EACrB,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,gBAAgB,GACrB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAC,yBAAyB,EAAC,MAAM,kCAAkC,CAAC;AAE3E,OAAO,EAAC,yBAAyB,EAAC,MAAM,kCAAkC,CAAC;AAE3E,OAAO,EACN,YAAY,EACZ,WAAW,EACX,KAAK,UAAU,EACf,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,GACvB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACN,eAAe,EACf,yBAAyB,EACzB,mBAAmB,EACnB,sBAAsB,EACtB,oBAAoB,EACpB,iBAAiB,EACjB,yBAAyB,EACzB,iBAAiB,EACjB,KAAK,mBAAmB,GACxB,MAAM,aAAa,CAAC;AAErB,OAAO,EACN,0BAA0B,EAC1B,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,yBAAyB,EACzB,KAAK,eAAe,GACpB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACN,kBAAkB,EAClB,oBAAoB,EACpB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,GACzB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAC,oBAAoB,EAAC,MAAM,qBAAqB,CAAC;AAEzD,OAAO,EACN,gBAAgB,EAChB,eAAe,EACf,WAAW,EACX,YAAY,EACZ,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,GACvB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACN,eAAe,EACf,sBAAsB,EACtB,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EAChB,KAAK,eAAe,EACpB,KAAK,sBAAsB,GAC3B,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACN,kBAAkB,EAClB,KAAK,aAAa,GAClB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAC,aAAa,EAAC,MAAM,kCAAkC,CAAC"}

package/dist/index.js

@@ -1,6 +1,7 @@
 export { locator } from './seam.js';
 export { serializeCookies, deserializeCookies, COOKIES_EXPORT_VERSION, } from './cookies-export.js';
 export { StubTransport } from './stub-transport.js';
+export { readHandsConfig, normalizeConfig, loadHands, HandLoadError, HANDS_CONFIG_FILENAME, } from './hand-loading.js';
 export { PlaywrightLaunchTransport } from './playwright-launch-transport.js';
 export { PlaywrightAttachTransport } from './playwright-attach-transport.js';
 export { setupProfile, buildPrompt, } from './setup-profile.js';
@@ -8,7 +9,7 @@ export { ControllerError, MissingBrowserBinaryError, MissingProfileError, Attach
 export { resolveSessionEndpointPath, writeSessionEndpoint, readSessionEndpoint, clearSessionEndpoint, SESSION_ENDPOINT_FILENAME, } from './session-endpoint.js';
 export { startSessionServer, sessionAlreadyActive, } from './session-server.js';
 export { connectRemoteSession } from './remote-session.js';
-export { SESSION_RPC_PATH, applySessionRpc, makeRpcPage, } from './session-rpc.js';
+export { SESSION_RPC_PATH, applySessionRpc, makeRpcPage, callHandVerb, } from './session-rpc.js';
 export { resolveHomeRoot, resolveProfileLocation, CONTROLLER_HOME_ENV, DEFAULT_HOME_DIRNAME, PROFILES_DIRNAME, } from './profile-location.js';
 export { startFixtureServer, } from './test-fixtures/fixture-server.js';
 export { FIXTURE_PAGES } from './test-fixtures/fixture-pages.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAaA,OAAO,EAAC,OAAO,EAAC,MAAM,WAAW,CAAC;AAElC,OAAO,EACN,gBAAgB,EAChB,kBAAkB,EAClB,sBAAsB,GAEtB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAC,aAAa,EAAgB,MAAM,qBAAqB,CAAC;AAEjE,OAAO,EAAC,yBAAyB,EAAC,MAAM,kCAAkC,CAAC;AAE3E,OAAO,EAAC,yBAAyB,EAAC,MAAM,kCAAkC,CAAC;AAE3E,OAAO,EACN,YAAY,EACZ,WAAW,GAIX,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACN,eAAe,EACf,yBAAyB,EACzB,mBAAmB,EACnB,sBAAsB,EACtB,oBAAoB,EACpB,iBAAiB,EACjB,yBAAyB,EACzB,iBAAiB,GAEjB,MAAM,aAAa,CAAC;AAErB,OAAO,EACN,0BAA0B,EAC1B,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,yBAAyB,GAEzB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACN,kBAAkB,EAClB,oBAAoB,GAGpB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAC,oBAAoB,EAAC,MAAM,qBAAqB,CAAC;AAEzD,OAAO,EACN,gBAAgB,EAChB,eAAe,EACf,WAAW,GAGX,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACN,eAAe,EACf,sBAAsB,EACtB,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,GAGhB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACN,kBAAkB,GAElB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAC,aAAa,EAAC,MAAM,kCAAkC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAaA,OAAO,EAAC,OAAO,EAAC,MAAM,WAAW,CAAC;AAElC,OAAO,EACN,gBAAgB,EAChB,kBAAkB,EAClB,sBAAsB,GAEtB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAC,aAAa,EAAgB,MAAM,qBAAqB,CAAC;AAIjE,OAAO,EACN,eAAe,EACf,eAAe,EACf,SAAS,EACT,aAAa,EACb,qBAAqB,GAKrB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAC,yBAAyB,EAAC,MAAM,kCAAkC,CAAC;AAE3E,OAAO,EAAC,yBAAyB,EAAC,MAAM,kCAAkC,CAAC;AAE3E,OAAO,EACN,YAAY,EACZ,WAAW,GAIX,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACN,eAAe,EACf,yBAAyB,EACzB,mBAAmB,EACnB,sBAAsB,EACtB,oBAAoB,EACpB,iBAAiB,EACjB,yBAAyB,EACzB,iBAAiB,GAEjB,MAAM,aAAa,CAAC;AAErB,OAAO,EACN,0BAA0B,EAC1B,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,yBAAyB,GAEzB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACN,kBAAkB,EAClB,oBAAoB,GAGpB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAC,oBAAoB,EAAC,MAAM,qBAAqB,CAAC;AAEzD,OAAO,EACN,gBAAgB,EAChB,eAAe,EACf,WAAW,EACX,YAAY,GAKZ,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACN,eAAe,EACf,sBAAsB,EACtB,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,GAGhB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACN,kBAAkB,GAElB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAC,aAAa,EAAC,MAAM,kCAAkC,CAAC"}

package/dist/playwright-attach-transport.d.ts

@@ -1,3 +1,4 @@
+import { type Hand } from './hand-host.js';
 import type { OpenTarget, Session, Transport } from './seam.js';
 /**
  * The `attach` concrete transport: connect (`chromium.connectOverCDP`) to a
@@ -23,6 +24,14 @@ import type { OpenTarget, Session, Transport } from './seam.js';
  * running one.
  */
 export declare class PlaywrightAttachTransport implements Transport {
+    #private;
+    /**
+     * @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.
+     */
+    constructor(hands?: readonly Hand[]);
     open(target: OpenTarget): Promise<Session>;
 }
 //# sourceMappingURL=playwright-attach-transport.d.ts.map

package/dist/playwright-attach-transport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"playwright-attach-transport.d.ts","sourceRoot":"","sources":["../src/playwright-attach-transport.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAEX,UAAU,EAEV,OAAO,EAGP,SAAS,EAET,MAAM,WAAW,CAAC;AAEnB;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,yBAA0B,YAAW,SAAS;IACpD,IAAI,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC;CA0ChD"}
+{"version":3,"file":"playwright-attach-transport.d.ts","sourceRoot":"","sources":["../src/playwright-attach-transport.ts"],"names":[],"mappings":"AAOA,OAAO,EAAmB,KAAK,IAAI,EAAmB,MAAM,gBAAgB,CAAC;AAC7E,OAAO,KAAK,EAAC,UAAU,EAAE,OAAO,EAAE,SAAS,EAAC,MAAM,WAAW,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,yBAA0B,YAAW,SAAS;;IAG1D;;;;;OAKG;gBACS,KAAK,GAAE,SAAS,IAAI,EAAO;IAIjC,IAAI,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC;CA0ChD"}

package/dist/playwright-attach-transport.js

@@ -1,6 +1,6 @@
 import { chromium, } from 'playwright';
 import { AttachNoContextError, AttachNotChromiumError } from './errors.js';
-import { clickLocator, resolveLocator, waitFor, } from './playwright-launch-transport.js';
+import { composeWithHands } from './hand-host.js';
 /**
  * The `attach` concrete transport: connect (`chromium.connectOverCDP`) to a
  * browser the USER already started with remote debugging enabled, and reuse the
@@ -25,6 +25,16 @@ import { clickLocator, resolveLocator, waitFor, } from './playwright-launch-tran
  * running one.
  */
 export class PlaywrightAttachTransport {
+    #hands;
+    /**
+     * @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.
+     */
+    constructor(hands = []) {
+        this.#hands = hands;
+    }
     async open(target) {
         if (target.mode !== 'attach') {
             throw new Error(`PlaywrightAttachTransport only handles 'attach'; ` +
@@ -52,7 +62,7 @@ export class PlaywrightAttachTransport {
             // browser exposes a context with no page yet (single active session in
             // v1, PRD Out of Scope).
             const pwPage = context.pages()[0] ?? (await context.newPage());
-            return makeAttachedSession(browser, pwPage);
+            return makeAttachedSession(browser, pwPage, this.#hands);
         }
         catch (cause) {
             // On any open-time refusal, disconnect from the user's browser without
@@ -66,13 +76,19 @@ export class PlaywrightAttachTransport {
 /**
  * Wrap a CDP-attached browser into the seam's {@link Session}.
  *
- * `close()` DISCONNECTS the controller from the user's browser; it must not
- * kill the browser the user started (`Browser.close()` on a `connectOverCDP`
- * connection detaches rather than terminating the remote process). We resolve
- * cookies through the reused context so they reflect the live, authenticated
- * session.
+ * The VERB surface comes from the shared hand-host ({@link composeBuiltInPage}),
+ * the SAME single composition the launch transport uses (no duplicated
+ * page-object literal). Cookies resolve through the reused context (derived here
+ * via `pwPage.context()`) so they reflect the live, authenticated session.
+ *
+ * Only the SESSION LIFECYCLE is per-transport: this transport listens on the
+ * browser's `'disconnected'` event and its `close()` calls `browser.close()`,
+ * which DISCONNECTS the controller from the user's browser WITHOUT killing it
+ * (a `connectOverCDP` connection detaches rather than terminating the remote
+ * process, ADR-0002) — the opposite of the launch transport, which kills the
+ * browser it spawned.
  */
-function makeAttachedSession(browser, pwPage) {
+function makeAttachedSession(browser, pwPage, extraHands) {
     const context = pwPage.context();
     let closed = false;
     const ensureOpen = () => {
@@ -80,96 +96,42 @@ function makeAttachedSession(browser, pwPage) {
             throw new Error('session is closed');
         }
     };
-    const page = {
-        async navigate(url) {
-            ensureOpen();
-            // "Settled" = the `load` event; XHR/JS-rendered content that appears
-            // after load is the `wait` verb's job. Same rationale (and the
-            // no-`networkidle` reasoning) as the launch transport's `navigate`.
-            await pwPage.goto(url, { waitUntil: 'load' });
-        },
-        async snapshot(options) {
-            ensureOpen();
-            const url = pwPage.url();
-            if (options?.full === true) {
-                const content = await pwPage.evaluate(() => document.documentElement.outerHTML);
-                return { url, view: 'full', content };
-            }
-            // Default: the token-cheap accessibility tree + visible text with stable
-            // `[ref=...]` refs (see the launch transport and `Snapshot` for the
-            // rationale; the string crosses the seam as opaque, transport-neutral
-            // text, ADR-0003).
-            const content = await pwPage.ariaSnapshot({ mode: 'ai' });
-            return { url, view: 'accessibility', content };
-        },
-        // `resolveLocator`/`clickLocator`/`waitFor` are imported from the launch
-        // transport so both transports resolve locators and run the verbs through
-        // ONE path (no parallel addressing scheme; the forward-note).
-        async click(t) {
-            ensureOpen();
-            // Shared `clickLocator`: normal actionability-checked click with the
-            // hidden-element dispatch fallback (PRD story 8), identical to launch.
-            await clickLocator(pwPage, t);
-        },
-        async type(t, text) {
-            ensureOpen();
-            await resolveLocator(pwPage, t).fill(text);
-        },
-        async eval(expression) {
-            ensureOpen();
-            return pwPage.evaluate(expression);
-        },
-        async wait(condition) {
-            ensureOpen();
-            // Identical to the launch transport (shared `waitFor`): selector /
-            // navigation / timeout, so the verb behaves the same on both.
-            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 when the session ends: either the user's browser goes away
+    // (Playwright fires 'disconnected' on a connectOverCDP browser) or our own
+    // close() disconnects. Lets a caller block until the session is gone.
+    let resolveClosed;
+    const closedSignal = new Promise((resolve) => {
+        resolveClosed = resolve;
+    });
+    const markClosed = () => {
+        if (closed)
+            return;
+        closed = true;
+        resolveClosed();
     };
+    browser.on('disconnected', markClosed);
+    // Build the verb surface from the built-in hands over a live hand-context —
+    // the same shared host the launch transport uses, so the verbs behave
+    // identically across both transports. The live `pwPage`/`context` stay
+    // in-process and never cross the seam (ADR-0003).
+    const handContext = { pwPage, context, ensureOpen };
+    const { page, dispose: disposeHands } = composeWithHands(handContext, extraHands);
     return {
         page,
         async close() {
-            if (closed)
+            if (closed) {
                 return;
-            closed = true;
-            // Detach from the user's browser; do NOT terminate it.
+            }
+            // Dispose the hands first (their in-process resources), THEN detach from
+            // the user's browser without terminating it. browser.close() fires
+            // 'disconnected', which runs markClosed.
+            await disposeHands();
             await browser.close();
+            markClosed();
+        },
+        waitForClose() {
+            return closedSignal;
         },
-    };
-}
-/** 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-attach-transport.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"playwright-attach-transport.js","sourceRoot":"","sources":["../src/playwright-attach-transport.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,QAAQ,GAIR,MAAM,YAAY,CAAC;AACpB,OAAO,EAAC,oBAAoB,EAAE,sBAAsB,EAAC,MAAM,aAAa,CAAC;AACzE,OAAO,EACN,YAAY,EACZ,cAAc,EACd,OAAO,GACP,MAAM,kCAAkC,CAAC;AAY1C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,OAAO,yBAAyB;IACrC,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,yEAAyE;QACzE,yEAAyE;QACzE,wEAAwE;QACxE,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,cAAc,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAE/D,IAAI,CAAC;YACJ,sEAAsE;YACtE,kEAAkE;YAClE,qDAAqD;YACrD,MAAM,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC;YAC5C,IAAI,MAAM,KAAK,UAAU,EAAE,CAAC;gBAC3B,MAAM,IAAI,sBAAsB,CAAC,MAAM,CAAC,CAAC;YAC1C,CAAC;YAED,iEAAiE;YACjE,mEAAmE;YACnE,MAAM,OAAO,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC;YACtC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC3B,MAAM,IAAI,oBAAoB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YACjD,CAAC;YAED,iEAAiE;YACjE,uEAAuE;YACvE,yBAAyB;YACzB,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;YAC/D,OAAO,mBAAmB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC7C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,uEAAuE;YACvE,oEAAoE;YACpE,6BAA6B;YAC7B,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;YACtC,MAAM,KAAK,CAAC;QACb,CAAC;IACF,CAAC;CACD;AAED;;;;;;;;GAQG;AACH,SAAS,mBAAmB,CAAC,OAAgB,EAAE,MAAc;IAC5D,MAAM,OAAO,GAAmB,MAAM,CAAC,OAAO,EAAE,CAAC;IACjD,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,qEAAqE;YACrE,+DAA+D;YAC/D,oEAAoE;YACpE,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,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,oEAAoE;YACpE,sEAAsE;YACtE,mBAAmB;YACnB,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,yEAAyE;QACzE,0EAA0E;QAC1E,8DAA8D;QAC9D,KAAK,CAAC,KAAK,CAAC,CAAC;YACZ,UAAU,EAAE,CAAC;YACb,qEAAqE;YACrE,uEAAuE;YACvE,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,OAAO,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;QACpC,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,SAAwB;YAClC,UAAU,EAAE,CAAC;YACb,mEAAmE;YACnE,8DAA8D;YAC9D,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,uDAAuD;YACvD,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC;QACvB,CAAC;KACD,CAAC;AACH,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-attach-transport.js","sourceRoot":"","sources":["../src/playwright-attach-transport.ts"],"names":[],"mappings":"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"}

package/dist/playwright-launch-transport.d.ts

@@ -1,6 +1,6 @@
-import { type Page as PwPage } from 'playwright';
+import { type Hand } from './hand-host.js';
 import { type ProfileLocationOptions } from './profile-location.js';
-import type { OpenTarget, Session, Transport, WaitCondition } from './seam.js';
+import type { OpenTarget, Session, Transport } from './seam.js';
 /**
  * The v1 concrete transport: a Playwright browser the controller LAUNCHES
  * against a dedicated, persistent profile directory it owns (PRD "Solution,
@@ -24,67 +24,12 @@ export declare class PlaywrightLaunchTransport implements Transport {
      * @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.
      */
-    constructor(location?: ProfileLocationOptions);
+    constructor(location?: ProfileLocationOptions, hands?: readonly Hand[]);
     open(target: OpenTarget): Promise<Session>;
 }
-/**
- * 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 declare function waitFor(page: PwPage, condition: WaitCondition): Promise<void>;
-/**
- * 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 declare function resolveLocator(page: PwPage, expression: string): import("playwright").Locator;
-/**
- * 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 declare function clickLocator(page: PwPage, expression: string): Promise<void>;
 //# sourceMappingURL=playwright-launch-transport.d.ts.map

package/dist/playwright-launch-transport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"playwright-launch-transport.d.ts","sourceRoot":"","sources":["../src/playwright-launch-transport.ts"],"names":[],"mappings":"AACA,OAAO,EAIN,KAAK,IAAI,IAAI,MAAM,EACnB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAEN,KAAK,sBAAsB,EAC3B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAEX,UAAU,EAEV,OAAO,EAGP,SAAS,EACT,aAAa,EACb,MAAM,WAAW,CAAC;AAEnB;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,yBAA0B,YAAW,SAAS;;IAG1D;;;;OAIG;gBACS,QAAQ,GAAE,sBAA2B;IAI3C,IAAI,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC;CAwChD;AA2HD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,OAAO,CAC5B,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,aAAa,GACtB,OAAO,CAAC,IAAI,CAAC,CAaf;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,gCAO9D;AAcD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,YAAY,CACjC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAYf"}
+{"version":3,"file":"playwright-launch-transport.d.ts","sourceRoot":"","sources":["../src/playwright-launch-transport.ts"],"names":[],"mappings":"AAGA,OAAO,EAAmB,KAAK,IAAI,EAAmB,MAAM,gBAAgB,CAAC;AAC7E,OAAO,EAEN,KAAK,sBAAsB,EAC3B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAC,UAAU,EAAE,OAAO,EAAE,SAAS,EAAC,MAAM,WAAW,CAAC;AAE9D;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,yBAA0B,YAAW,SAAS;;IAI1D;;;;;;;;OAQG;gBAEF,QAAQ,GAAE,sBAA2B,EACrC,KAAK,GAAE,SAAS,IAAI,EAAO;IAMtB,IAAI,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC;CAwChD"}