@webhands/core 0.1.0

package/dist/playwright-attach-transport.js

@@ -0,0 +1,175 @@
+import { chromium, } from 'playwright';
+import { AttachNoContextError, AttachNotChromiumError } from './errors.js';
+import { clickLocator, resolveLocator, waitFor, } from './playwright-launch-transport.js';
+/**
+ * The `attach` concrete transport: connect (`chromium.connectOverCDP`) to a
+ * browser the USER already started with remote debugging enabled, and reuse the
+ * user's EXISTING authenticated context — `browser.contexts()[0]`, never
+ * `newContext()` — so the controller drives the live, logged-in tabs on the
+ * user's real fingerprint and IP (PRD "Solution, attach"; ADR-0002).
+ *
+ * CDP-attach is Chromium-only (ADR-0003: Firefox attaches via a different
+ * mechanism). That constraint is SURFACED as a typed `core` error
+ * ({@link AttachNotChromiumError}) rather than leaking any CDP/Chromium-only
+ * type into the seam: the Playwright/CDP types are confined to this module and
+ * the seam stays transport-neutral (ADR-0003).
+ *
+ * It handles ONLY `mode: 'attach'`. `mode: 'launch'` is a SEPARATE transport
+ * ({@link PlaywrightLaunchTransport}); calling `open` with `mode: 'launch'`
+ * here throws, because mixing the two open mechanisms in one transport is what
+ * ADR-0003's seam exists to avoid.
+ *
+ * There is NO browser-relaunch helper: a settled PRD decision is that the user
+ * starts their own browser with `--remote-debugging-port` and supplies the
+ * resulting endpoint (PRD "needsAnswers" #5). This transport only connects to a
+ * running one.
+ */
+export class PlaywrightAttachTransport {
+    async open(target) {
+        if (target.mode !== 'attach') {
+            throw new Error(`PlaywrightAttachTransport only handles 'attach'; ` +
+                `'${target.mode}' is owned by the launch transport.`);
+        }
+        // `endpoint` is the opaque, transport-resolved remote-debugging endpoint
+        // (e.g. `http://127.0.0.1:9222`). The seam keeps it a plain string so no
+        // CDP type leaks (ADR-0003); this transport interprets it as a CDP URL.
+        const browser = await chromium.connectOverCDP(target.endpoint);
+        try {
+            // CDP-attach is Chromium-only. If the reached engine is not Chromium,
+            // refuse with a typed condition instead of driving an unsupported
+            // browser (Firefox attaches differently — ADR-0003).
+            const engine = browser.browserType().name();
+            if (engine !== 'chromium') {
+                throw new AttachNotChromiumError(engine);
+            }
+            // Reuse the EXISTING authenticated context, never `newContext()`
+            // (ADR-0002): a fresh context would discard the user's live login.
+            const context = browser.contexts()[0];
+            if (context === undefined) {
+                throw new AttachNoContextError(target.endpoint);
+            }
+            // Drive the context's existing active page; open one only if the
+            // 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);
+        }
+        catch (cause) {
+            // On any open-time refusal, disconnect from the user's browser without
+            // closing it (a CDP connection close detaches; it does not kill the
+            // browser the user started).
+            await browser.close().catch(() => { });
+            throw cause;
+        }
+    }
+}
+/**
+ * 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.
+ */
+function makeAttachedSession(browser, pwPage) {
+    const context = pwPage.context();
+    let closed = false;
+    const ensureOpen = () => {
+        if (closed) {
+            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));
+        },
+    };
+    return {
+        page,
+        async close() {
+            if (closed)
+                return;
+            closed = true;
+            // Detach from the user's browser; do NOT terminate it.
+            await browser.close();
+        },
+    };
+}
+/** 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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,90 @@
+import { type Page as PwPage } from 'playwright';
+import { type ProfileLocationOptions } from './profile-location.js';
+import type { OpenTarget, Session, Transport, WaitCondition } from './seam.js';
+/**
+ * The v1 concrete transport: a Playwright browser the controller LAUNCHES
+ * against a dedicated, persistent profile directory it owns (PRD "Solution,
+ * launch"; ADR-0002). It implements the `core` {@link Transport}/`Driver` seam
+ * with NO Playwright/CDP types in its public surface (ADR-0003): the
+ * Playwright types are confined to this module.
+ *
+ * It handles ONLY `mode: 'launch'`. The `attach` mode (`connectOverCDP`) is a
+ * SEPARATE transport (task `attach-transport-cdp-chromium`); calling `open`
+ * with `mode: 'attach'` here throws, because mixing the two launch mechanisms
+ * in one transport is what ADR-0003's seam exists to avoid.
+ *
+ * Profile location is resolved from the constructor options (or the
+ * `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.
+ */
+export declare class PlaywrightLaunchTransport implements Transport {
+    #private;
+    /**
+     * @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.
+     */
+    constructor(location?: ProfileLocationOptions);
+    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

@@ -0,0 +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"}

package/dist/playwright-launch-transport.js

@@ -0,0 +1,305 @@
+import { stat } from 'node:fs/promises';
+import { chromium, errors as pwErrors, } from 'playwright';
+import { MissingBrowserBinaryError, MissingProfileError } from './errors.js';
+import { resolveProfileLocation, } from './profile-location.js';
+/**
+ * The v1 concrete transport: a Playwright browser the controller LAUNCHES
+ * against a dedicated, persistent profile directory it owns (PRD "Solution,
+ * launch"; ADR-0002). It implements the `core` {@link Transport}/`Driver` seam
+ * with NO Playwright/CDP types in its public surface (ADR-0003): the
+ * Playwright types are confined to this module.
+ *
+ * It handles ONLY `mode: 'launch'`. The `attach` mode (`connectOverCDP`) is a
+ * SEPARATE transport (task `attach-transport-cdp-chromium`); calling `open`
+ * with `mode: 'attach'` here throws, because mixing the two launch mechanisms
+ * in one transport is what ADR-0003's seam exists to avoid.
+ *
+ * Profile location is resolved from the constructor options (or the
+ * `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.
+ */
+export class PlaywrightLaunchTransport {
+    #location;
+    /**
+     * @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.
+     */
+    constructor(location = {}) {
+        this.#location = location;
+    }
+    async open(target) {
+        if (target.mode !== 'launch') {
+            throw new Error(`PlaywrightLaunchTransport only handles 'launch'; ` +
+                `'${target.mode}' is owned by the attach transport.`);
+        }
+        const loc = resolveProfileLocation(target.profile, this.#location);
+        // A profile is "set up" iff its dedicated dir exists on disk. Creating it
+        // is the headed `setup-profile` flow's job (a later task); `launch`
+        // against a missing profile is the typed MissingProfileError so the CLI
+        // can tell the user to run `setup-profile` first (PRD story 17). We never
+        // create the dir here, so a `launch` typo cannot silently spawn a blank
+        // profile.
+        if (!(await isExistingDirectory(loc.profileDir))) {
+            throw new MissingProfileError(loc.profile, loc.profileDir);
+        }
+        const headless = target.headed !== true;
+        let context;
+        try {
+            context = await chromium.launchPersistentContext(loc.profileDir, {
+                headless,
+            });
+        }
+        catch (cause) {
+            if (isMissingBrowserBinary(cause)) {
+                throw new MissingBrowserBinaryError('chromium', undefined, { cause });
+            }
+            throw cause;
+        }
+        // launchPersistentContext always opens with exactly one page; reuse it as
+        // 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);
+    }
+}
+/** True iff `path` exists and is a directory. */
+async function isExistingDirectory(path) {
+    try {
+        const s = await stat(path);
+        return s.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Recognise Playwright's "browser executable doesn't exist" failure. Playwright
+ * 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.
+ */
+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));
+}
+/** Wrap a live Playwright persistent context into the seam's {@link Session}. */
+function makeSession(context, pwPage) {
+    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));
+        },
+    };
+    return {
+        page,
+        async close() {
+            if (closed)
+                return;
+            closed = true;
+            await context.close();
+        },
+    };
+}
+/**
+ * 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

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

package/dist/profile-location.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Where the controller's dedicated profiles (and other config state) live.
+ *
+ * This is a SHARED/GLOBAL, per-user location: by default
+ * `~/.webhands`. Profiles are dedicated browser user-data dirs
+ * under `<root>/profiles/<name>` (PRD "Profile management"; ADR-0002: never the
+ * OS default Chrome profile). The endpoint file from ADR-0005 also lives under
+ * this root, owned by a later task.
+ *
+ * Because writing here touches a real, shared location, TESTS MUST override the
+ * root to a scratch dir and assert the real one is untouched. The override is
+ * the {@link CONTROLLER_HOME_ENV} environment variable (or an explicit
+ * `root` passed to {@link resolveProfileLocation}); nothing else points a
+ * launch at the real home.
+ */
+/** The directory name appended to the user's home for the default root. */
+export declare const DEFAULT_HOME_DIRNAME = ".webhands";
+/**
+ * Environment variable that overrides the controller home root. Set this (to a
+ * temp dir) in tests, or to relocate state in production. When set to a
+ * non-empty value it fully replaces the `~/.webhands` default.
+ */
+export declare const CONTROLLER_HOME_ENV = "WEBHANDS_HOME";
+/** The subdirectory under the home root that holds dedicated profiles. */
+export declare const PROFILES_DIRNAME = "profiles";
+/** Inputs that influence where a profile resolves (all optional, for tests). */
+export interface ProfileLocationOptions {
+    /**
+     * Explicit home root, highest precedence. When omitted, falls back to the
+     * {@link CONTROLLER_HOME_ENV} env var, then `~/.webhands`.
+     */
+    readonly root?: string;
+    /** Environment to read the override from. Defaults to `process.env`. */
+    readonly env?: NodeJS.ProcessEnv;
+}
+/** A resolved set of controller paths for a given profile name. */
+export interface ProfileLocation {
+    /** The controller home root (e.g. `~/.webhands`). */
+    readonly homeRoot: string;
+    /** The directory holding all dedicated profiles (`<homeRoot>/profiles`). */
+    readonly profilesRoot: string;
+    /** The dedicated user-data dir for this profile (`<profilesRoot>/<name>`). */
+    readonly profileDir: string;
+    /** The profile name that was resolved. */
+    readonly profile: string;
+}
+/**
+ * Resolve the controller home root. Precedence:
+ * 1. an explicit `options.root`,
+ * 2. the {@link CONTROLLER_HOME_ENV} env var (if non-empty),
+ * 3. `~/.webhands`.
+ */
+export declare function resolveHomeRoot(options?: ProfileLocationOptions): string;
+/**
+ * Resolve every path for a named profile. Does NOT touch the filesystem (no
+ * dir is created or checked here) so it is pure and safe to call freely; the
+ * transport decides what to do when the dir is absent (raise
+ * `MissingProfileError`) or present.
+ */
+export declare function resolveProfileLocation(profile: string, options?: ProfileLocationOptions): ProfileLocation;
+//# sourceMappingURL=profile-location.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"profile-location.d.ts","sourceRoot":"","sources":["../src/profile-location.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;GAcG;AAEH,2EAA2E;AAC3E,eAAO,MAAM,oBAAoB,cAAc,CAAC;AAEhD;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,kBAAkB,CAAC;AAEnD,0EAA0E;AAC1E,eAAO,MAAM,gBAAgB,aAAa,CAAC;AAE3C,gFAAgF;AAChF,MAAM,WAAW,sBAAsB;IACtC;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,wEAAwE;IACxE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACjC;AAED,mEAAmE;AACnE,MAAM,WAAW,eAAe;IAC/B,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,4EAA4E;IAC5E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,0CAA0C;IAC1C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,sBAA2B,GAAG,MAAM,CAU5E;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACrC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,sBAA2B,GAClC,eAAe,CASjB"}