@webhands/core 0.1.0 → 1.0.0

package/src/playwright-launch-transport.ts

@@ -1,25 +1,12 @@
 import {stat} from 'node:fs/promises';
-import {
-	chromium,
-	errors as pwErrors,
-	type BrowserContext,
-	type Page as PwPage,
-} from 'playwright';
+import {chromium, type BrowserContext, type Page} from 'playwright';
 import {MissingBrowserBinaryError, MissingProfileError} from './errors.js';
+import {composeWithHands, type Hand, type HandContext} from './hand-host.js';
 import {
 	resolveProfileLocation,
 	type ProfileLocationOptions,
 } from './profile-location.js';
-import type {
-	Cookie,
-	OpenTarget,
-	Page,
-	Session,
-	Snapshot,
-	SnapshotOptions,
-	Transport,
-	WaitCondition,
-} from './seam.js';
+import type {OpenTarget, Session, Transport} from './seam.js';
 
 /**
  * The v1 concrete transport: a Playwright browser the controller LAUNCHES
@@ -40,14 +27,23 @@ import type {
  */
 export class PlaywrightLaunchTransport implements Transport {
 	readonly #location: ProfileLocationOptions;
+	readonly #hands: readonly Hand[];
 
 	/**
 	 * @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[] = [],
+	) {
 		this.#location = location;
+		this.#hands = hands;
 	}
 
 	async open(target: OpenTarget): Promise<Session> {
@@ -88,7 +84,7 @@ export class PlaywrightLaunchTransport implements Transport {
 		// 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);
 	}
 }
 
@@ -119,8 +115,22 @@ function isMissingBrowserBinary(cause: unknown): boolean {
 	);
 }
 
-/** Wrap a live Playwright persistent context into the seam's {@link Session}. */
-function makeSession(context: BrowserContext, pwPage: PwPage): Session {
+/**
+ * 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: BrowserContext,
+	pwPage: Page,
+	extraHands: readonly Hand[],
+): Session {
 	let closed = false;
 	const ensureOpen = () => {
 		if (closed) {
@@ -128,236 +138,45 @@ function makeSession(context: BrowserContext, pwPage: PwPage): Session {
 		}
 	};
 
-	const page: Page = {
-		async navigate(url: string): Promise<void> {
-			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?: SnapshotOptions): Promise<Snapshot> {
-			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): Promise<void> {
-			ensureOpen();
-			await clickLocator(pwPage, t);
-		},
-		async type(t, text): Promise<void> {
-			ensureOpen();
-			await resolveLocator(pwPage, t).fill(text);
-		},
-		async eval(expression: string): Promise<unknown> {
-			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: WaitCondition): Promise<void> {
-			ensureOpen();
-			await waitFor(pwPage, condition);
-		},
-		async cookies(): Promise<readonly Cookie[]> {
-			ensureOpen();
-			const raw = await context.cookies();
-			return raw.map(toSeamCookie);
-		},
-		async setCookies(cookies): Promise<void> {
-			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!: () => void;
+	const closedSignal = new Promise<void>((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: HandContext = {pwPage, context, ensureOpen};
+	const {page, dispose: disposeHands} = composeWithHands(
+		handContext,
+		extraHands,
+	);
 
 	return {
 		page,
 		async close(): Promise<void> {
-			if (closed) return;
-			closed = true;
+			if (closed) {
+				return;
+			}
+			// 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(): Promise<void> {
+			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: PwPage,
-	condition: WaitCondition,
-): Promise<void> {
-	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: PwPage, expression: string) {
-	// eslint-disable-next-line no-new-func
-	const factory = new Function('page', 'p', `return (${expression});`) as (
-		page: PwPage,
-		p: PwPage,
-	) => ReturnType<PwPage['locator']>;
-	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: PwPage,
-	expression: string,
-): Promise<void> {
-	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: {
-	name: string;
-	value: string;
-	domain?: string;
-	path?: string;
-	expires?: number;
-	httpOnly?: boolean;
-	secure?: boolean;
-	sameSite?: 'Strict' | 'Lax' | 'None';
-}): Cookie {
-	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: Cookie) {
-	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,
 	};
 }

package/src/remote-session.ts

@@ -1,4 +1,5 @@
 import {
+	callHandVerb,
 	makeRpcPage,
 	SESSION_RPC_PATH,
 	type SessionRpcRequest,
@@ -11,7 +12,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
@@ -24,8 +25,21 @@ 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 function connectRemoteSession(baseUrl: string): Session {
+export function connectRemoteSession(
+	baseUrl: string,
+	handVerbs: readonly string[] = [],
+): Session {
 	const endpoint = new URL(SESSION_RPC_PATH, baseUrl).toString();
 
 	const send = async (request: SessionRpcRequest): Promise<unknown> => {
@@ -56,11 +70,35 @@ export function connectRemoteSession(baseUrl: string): Session {
 		throw new Error(reply.error);
 	};
 
+	let resolveClosed!: () => void;
+	const closedSignal = new Promise<void>((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 as unknown as Record<string, unknown>;
+	for (const name of handVerbs) {
+		pageWithHands[name] = (...args: readonly unknown[]): Promise<unknown> =>
+			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(): Promise<void> {
+			// 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/src/seam.ts

@@ -74,7 +74,7 @@ export interface Cookie {
 	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}
 	| {readonly kind: 'locator'; readonly target: LocatorString}
@@ -93,7 +93,7 @@ export type WaitCondition =
  */
 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
@@ -132,7 +132,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>;
 	/**
@@ -196,16 +196,24 @@ export interface Page {
 }
 
 /**
- * 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>;
 }
 
 /**