@webhands/core 0.1.0

package/dist/profile-location.js

@@ -0,0 +1,61 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/**
+ * 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 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 const CONTROLLER_HOME_ENV = 'WEBHANDS_HOME';
+/** The subdirectory under the home root that holds dedicated profiles. */
+export const PROFILES_DIRNAME = 'profiles';
+/**
+ * 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 function resolveHomeRoot(options = {}) {
+    if (options.root !== undefined && options.root !== '') {
+        return options.root;
+    }
+    const env = options.env ?? process.env;
+    const fromEnv = env[CONTROLLER_HOME_ENV];
+    if (fromEnv !== undefined && fromEnv !== '') {
+        return fromEnv;
+    }
+    return join(homedir(), DEFAULT_HOME_DIRNAME);
+}
+/**
+ * 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 function resolveProfileLocation(profile, options = {}) {
+    const homeRoot = resolveHomeRoot(options);
+    const profilesRoot = join(homeRoot, PROFILES_DIRNAME);
+    return {
+        homeRoot,
+        profilesRoot,
+        profileDir: join(profilesRoot, profile),
+        profile,
+    };
+}
+//# sourceMappingURL=profile-location.js.map

package/dist/profile-location.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile-location.js","sourceRoot":"","sources":["../src/profile-location.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,OAAO,EAAC,MAAM,SAAS,CAAC;AAChC,OAAO,EAAC,IAAI,EAAC,MAAM,WAAW,CAAC;AAE/B;;;;;;;;;;;;;;GAcG;AAEH,2EAA2E;AAC3E,MAAM,CAAC,MAAM,oBAAoB,GAAG,WAAW,CAAC;AAEhD;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,eAAe,CAAC;AAEnD,0EAA0E;AAC1E,MAAM,CAAC,MAAM,gBAAgB,GAAG,UAAU,CAAC;AAyB3C;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,UAAkC,EAAE;IACnE,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,IAAI,OAAO,CAAC,IAAI,KAAK,EAAE,EAAE,CAAC;QACvD,OAAO,OAAO,CAAC,IAAI,CAAC;IACrB,CAAC;IACD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IACvC,MAAM,OAAO,GAAG,GAAG,CAAC,mBAAmB,CAAC,CAAC;IACzC,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,EAAE,EAAE,CAAC;QAC7C,OAAO,OAAO,CAAC;IAChB,CAAC;IACD,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,oBAAoB,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CACrC,OAAe,EACf,UAAkC,EAAE;IAEpC,MAAM,QAAQ,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IAC1C,MAAM,YAAY,GAAG,IAAI,CAAC,QAAQ,EAAE,gBAAgB,CAAC,CAAC;IACtD,OAAO;QACN,QAAQ;QACR,YAAY;QACZ,UAAU,EAAE,IAAI,CAAC,YAAY,EAAE,OAAO,CAAC;QACvC,OAAO;KACP,CAAC;AACH,CAAC"}

package/dist/remote-session.d.ts

@@ -0,0 +1,22 @@
+import type { Session } from './seam.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}
+ * 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
+ * calls `Session.close()`; only WHAT the session is changes.
+ *
+ * The critical difference from a local session: {@link Session.close} here is a
+ * NO-OP. The served process owns the single live session's lifetime; a thin
+ * client closing after one verb must NOT tear down the shared browser, or the
+ * next verb invocation would have nothing to drive. Teardown is explicit
+ * (`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.
+ */
+export declare function connectRemoteSession(baseUrl: string): Session;
+//# sourceMappingURL=remote-session.d.ts.map

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

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

package/dist/remote-session.js

@@ -0,0 +1,57 @@
+import { 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}
+ * 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
+ * calls `Session.close()`; only WHAT the session is changes.
+ *
+ * The critical difference from a local session: {@link Session.close} here is a
+ * NO-OP. The served process owns the single live session's lifetime; a thin
+ * client closing after one verb must NOT tear down the shared browser, or the
+ * next verb invocation would have nothing to drive. Teardown is explicit
+ * (`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.
+ */
+export function connectRemoteSession(baseUrl) {
+    const endpoint = new URL(SESSION_RPC_PATH, baseUrl).toString();
+    const send = async (request) => {
+        let res;
+        try {
+            res = await fetch(endpoint, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify(request),
+            });
+        }
+        catch (cause) {
+            // The advertised server is unreachable (it died without clearing its
+            // endpoint file, say). Surface a plain Error; the CLI maps the discovery
+            // MISS (no endpoint file) to "run serve first", but a stale-but-present
+            // endpoint that no longer answers is a genuine connection failure.
+            const message = cause instanceof Error ? cause.message : String(cause);
+            throw new Error(`could not reach the session server at ${baseUrl}: ${message}`);
+        }
+        const reply = (await res.json());
+        if (reply.ok) {
+            return reply.value;
+        }
+        // Re-throw a faithful Error so a page-side throw REJECTS on the client too,
+        // preserving the seam's `eval` "a page throw rejects" contract across the
+        // process boundary.
+        throw new Error(reply.error);
+    };
+    return {
+        page: makeRpcPage(send),
+        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.
+        },
+    };
+}
+//# sourceMappingURL=remote-session.js.map

package/dist/remote-session.js.map

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

package/dist/seam.d.ts

@@ -0,0 +1,212 @@
+/**
+ * The verb-level transport seam.
+ *
+ * This is the highest test seam and the internal structure boundary of
+ * `core` (see PRD "Testing Decisions" and `docs/adr/0003`). It is expressed
+ * purely in terms of high-level VERBS (navigate, snapshot, click, type, eval,
+ * wait, cookies), NOT in terms of CDP or Playwright primitives, so that a
+ * future browser-extension transport or a non-Chromium (Firefox) transport
+ * can implement it without changing the verb surface.
+ *
+ * RULES (load-bearing, do not relax without an ADR):
+ * - No CDP / Chromium-only types may appear in this public surface
+ *   (`docs/adr/0003`).
+ * - Element addressing is a RAW PLAYWRIGHT LOCATOR STRING the active
+ *   transport resolves (`docs/adr/0004`): "transport-neutral" means
+ *   Playwright-equivalent addressing, not a reduced selector subset and not a
+ *   structured JSON locator. We deliberately type it as a branded `string`
+ *   rather than importing any Playwright `Locator` type, so no Playwright
+ *   type leaks across the seam.
+ */
+/**
+ * A raw Playwright locator string, e.g. `getByRole('button', { name: 'Search' })`.
+ *
+ * It is a plain `string` at runtime; the brand exists only so call sites are
+ * explicit that this is a locator EXPRESSION the transport resolves (a sibling
+ * to the `eval` escape hatch), not an opaque CSS selector or a structured
+ * locator. Construct one with {@link locator}.
+ */
+export type LocatorString = string & {
+    readonly __brand: 'PlaywrightLocatorString';
+};
+/** Tag a raw Playwright locator string as a {@link LocatorString}. */
+export declare function locator(expression: string): LocatorString;
+/**
+ * How a {@link Transport} should obtain a browser session.
+ *
+ * Expressed in domain terms (a profile to launch, or a target to attach to),
+ * never in CDP/Playwright terms. Concrete transports map these to their own
+ * mechanism (Playwright `launchPersistentContext` / `connectOverCDP`, an
+ * extension bridge, ...).
+ */
+export type OpenTarget = {
+    readonly mode: 'launch';
+    /** Name of the dedicated profile the controller owns. */
+    readonly profile: string;
+    /** Whether the browser is visible. Defaults are a transport concern. */
+    readonly headed?: boolean;
+} | {
+    readonly mode: 'attach';
+    /**
+     * Opaque, transport-resolved endpoint of an already-running browser
+     * (e.g. a remote-debugging URL). Kept as a plain string so no
+     * CDP type leaks across the seam.
+     */
+    readonly endpoint: string;
+};
+/** A single browser cookie, in transport-neutral terms. */
+export interface Cookie {
+    readonly name: string;
+    readonly value: string;
+    readonly domain?: string;
+    readonly path?: string;
+    readonly expires?: number;
+    readonly httpOnly?: boolean;
+    readonly secure?: boolean;
+    readonly sameSite?: 'Strict' | 'Lax' | 'None';
+}
+/** What to wait for in the {@link Page.wait} verb. */
+export type WaitCondition = {
+    readonly kind: 'timeout';
+    readonly ms: number;
+} | {
+    readonly kind: 'locator';
+    readonly target: LocatorString;
+} | {
+    readonly kind: 'navigation';
+};
+/**
+ * Which page view a {@link Snapshot} carries.
+ *
+ * - `'accessibility'` — the DEFAULT, token-cheap structured view: the
+ *   accessibility tree (roles + names) plus visible text, with stable element
+ *   refs (see {@link Snapshot.content}). This is the cheap view an agent reads
+ *   to decide what to act on WITHOUT parsing raw HTML.
+ * - `'full'` — the raw DOM (serialized outer HTML), returned when the verb is
+ *   called with {@link SnapshotOptions.full}. A settled PRD decision (story 7,
+ *   `needsAnswers` Q3): default is the accessibility view, `--full` is raw DOM.
+ */
+export type SnapshotView = 'accessibility' | 'full';
+/** Options for the {@link Page.snapshot} verb. */
+export interface SnapshotOptions {
+    /**
+     * When `true`, return the raw DOM (`view: 'full'`) instead of the default
+     * accessibility-tree + visible-text view. Maps to the CLI `--full` flag.
+     */
+    readonly full?: boolean;
+}
+/**
+ * A structured, token-cheap view of the current page with stable element refs.
+ *
+ * In the default `'accessibility'` view, {@link Snapshot.content} is the
+ * accessibility tree (roles + accessible names) plus visible text, with each
+ * actionable node carrying a stable `[ref=...]` element reference. The refs
+ * are stable for an unchanged page (re-snapshotting yields the same refs), so
+ * an agent can read the cheap view, pick a ref, and address that element
+ * later. Snapshot refs and the raw Playwright-locator addressing (ADR-0004)
+ * are COMPLEMENTARY ways to address elements, not competitors.
+ *
+ * The `content` string is a transport-neutral, human/agent-readable text
+ * serialization (no CDP/Playwright types cross the seam, per ADR-0003). Its
+ * concrete grammar is a transport detail; callers treat it as opaque,
+ * token-cheap text to read, and parse refs out of it only by the documented
+ * `[ref=...]` convention.
+ */
+export interface Snapshot {
+    /** The page URL at snapshot time. */
+    readonly url: string;
+    /** Which view this snapshot carries (default vs `--full` raw DOM). */
+    readonly view: SnapshotView;
+    /** Human/agent-readable structured page content (see {@link Snapshot}). */
+    readonly content: string;
+}
+/**
+ * The page-level verb surface. One method per verb in the domain glossary.
+ * All element addressing flows through {@link LocatorString}.
+ */
+export interface Page {
+    /** Navigate the active page to a URL and let it settle. */
+    navigate(url: string): Promise<void>;
+    /**
+     * Return a structured, token-cheap view of the page. Defaults to the
+     * accessibility-tree + visible-text view with stable refs; pass
+     * `{full: true}` to get the raw DOM instead (PRD story 7).
+     */
+    snapshot(options?: SnapshotOptions): Promise<Snapshot>;
+    /** Click the element addressed by a raw Playwright locator string. */
+    click(target: LocatorString): Promise<void>;
+    /** Type text into the element addressed by a raw Playwright locator string. */
+    type(target: LocatorString, text: string): Promise<void>;
+    /**
+     * Run a JavaScript EXPRESSION in the active page's context and return its
+     * result, the `eval` escape hatch for cases no other verb covers (PRD story
+     * 9). It sits naturally beside the raw-locator addressing (ADR-0004): both are
+     * page-context expressions the transport resolves.
+     *
+     * `expression` is evaluated AS AN EXPRESSION (not a function body), so its
+     * value is the result: `'1 + 2'` yields `3`, `"document.title"` yields the
+     * title. If it evaluates to a Promise, the transport awaits it and returns the
+     * resolved value.
+     *
+     * SERIALIZATION CONTRACT (the load-bearing part). The result must cross the
+     * seam by VALUE: it is structurally cloned out of the page context, not
+     * handed back as a live reference. The transport, not this verb, owns the
+     * serialization, and its behaviour is the documented contract callers rely
+     * on. It is RICHER than `JSON.stringify` (do not reason about it as JSON):
+     * - Primitives, plain objects, and arrays round-trip faithfully, including
+     *   nested structures.
+     * - `undefined` round-trips as `undefined`; `null` as `null`.
+     * - Non-finite numbers (`NaN`, `Infinity`, `-0`) and `BigInt` are PRESERVED
+     *   as their real JS values (unlike JSON, which would lose them).
+     * - A circular structure is PRESERVED, with each back-reference replaced by a
+     *   `[Circular]` marker (it does NOT throw).
+     * - Values with no transferable form (functions, symbols) come back as
+     *   `undefined`; a `Date` comes back as a `Date`; `Map`/`Set` come back as an
+     *   empty object `{}` (their entries do not survive the clone).
+     * - Live host objects (a DOM node, `window`) come back as an OPAQUE PREVIEW
+     *   STRING, NOT the live object: it cannot cross the process boundary, so the
+     *   escape hatch hands back a readable stand-in rather than a broken handle.
+     *   An agent that needs a DOM value reads a serializable property of it
+     *   (`...textContent`, `...value`) inside the expression, exactly as the
+     *   tests do.
+     * - An expression that THROWS in the page REJECTS with a transport-neutral
+     *   `Error` carrying the page-side message (no CDP/Playwright type leaks
+     *   across the seam, ADR-0003).
+     *
+     * The return type is `unknown` because the page decides the shape; callers
+     * narrow it. This is deliberately a thin passthrough to the transport's
+     * serialize-and-return: `eval` does not re-encode or wrap the result, so an
+     * agent gets exactly what the page produced.
+     */
+    eval(expression: string): Promise<unknown>;
+    /** Pace actions by waiting for a condition. */
+    wait(condition: WaitCondition): Promise<void>;
+    /** Read the session's cookies. */
+    cookies(): Promise<readonly Cookie[]>;
+    /** Seed the session's cookies. */
+    setCookies(cookies: readonly Cookie[]): Promise<void>;
+}
+/**
+ * A live browser session owning one active {@link Page}. 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;
+    /** Tear down the session and release the underlying browser resources. */
+    close(): Promise<void>;
+}
+/**
+ * The transport seam. A `Transport` (a.k.a. driver) knows how to OPEN a
+ * {@link Session} for a given {@link OpenTarget}. v1 concrete transport is
+ * Playwright (built in a later task); an extension or Firefox transport can
+ * implement the same interface.
+ */
+export interface Transport {
+    open(target: OpenTarget): Promise<Session>;
+}
+/** Alias: the seam is referred to as the `Driver` in the domain glossary. */
+export type Driver = Transport;
+//# sourceMappingURL=seam.d.ts.map

package/dist/seam.d.ts.map

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

package/dist/seam.js

@@ -0,0 +1,25 @@
+/**
+ * The verb-level transport seam.
+ *
+ * This is the highest test seam and the internal structure boundary of
+ * `core` (see PRD "Testing Decisions" and `docs/adr/0003`). It is expressed
+ * purely in terms of high-level VERBS (navigate, snapshot, click, type, eval,
+ * wait, cookies), NOT in terms of CDP or Playwright primitives, so that a
+ * future browser-extension transport or a non-Chromium (Firefox) transport
+ * can implement it without changing the verb surface.
+ *
+ * RULES (load-bearing, do not relax without an ADR):
+ * - No CDP / Chromium-only types may appear in this public surface
+ *   (`docs/adr/0003`).
+ * - Element addressing is a RAW PLAYWRIGHT LOCATOR STRING the active
+ *   transport resolves (`docs/adr/0004`): "transport-neutral" means
+ *   Playwright-equivalent addressing, not a reduced selector subset and not a
+ *   structured JSON locator. We deliberately type it as a branded `string`
+ *   rather than importing any Playwright `Locator` type, so no Playwright
+ *   type leaks across the seam.
+ */
+/** Tag a raw Playwright locator string as a {@link LocatorString}. */
+export function locator(expression) {
+    return expression;
+}
+//# sourceMappingURL=seam.js.map

package/dist/seam.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"seam.js","sourceRoot":"","sources":["../src/seam.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAcH,sEAAsE;AACtE,MAAM,UAAU,OAAO,CAAC,UAAkB;IACzC,OAAO,UAA2B,CAAC;AACpC,CAAC"}

package/dist/session-endpoint.d.ts

@@ -0,0 +1,53 @@
+import { type ProfileLocationOptions } from './profile-location.js';
+/**
+ * Cross-invocation session DISCOVERY (ADR-0005).
+ *
+ * The long-lived `incur serve` process owns the one live browser session; each
+ * `webhands <verb>` is a thin client that must FIND that running
+ * server. The server advertises itself by writing a small endpoint file under
+ * the controller home root (the same SHARED location profiles live under, see
+ * {@link resolveHomeRoot}); client verbs read it to learn where to send their
+ * verb calls. When no endpoint file exists, no server is live, and a verb errors
+ * with "run `serve` first" rather than auto-spawning a browser (ADR-0005:
+ * lifecycle is EXPLICIT in v1).
+ *
+ * Because this writes under the real `~/.webhands` by default,
+ * TESTS MUST override the root to a temp dir (via {@link ProfileLocationOptions})
+ * and assert the real location is untouched, exactly as the profile location
+ * does.
+ */
+/** The endpoint file name under the controller home root. */
+export declare const SESSION_ENDPOINT_FILENAME = "session-endpoint.json";
+/**
+ * What the served process advertises about itself for client discovery. Kept
+ * deliberately small: the base `url` a client posts verb calls to, plus the
+ * `pid` so a human/test can confirm or signal the owning process.
+ */
+export interface SessionEndpoint {
+    /** The base HTTP URL the served session listens on (e.g. `http://127.0.0.1:53113`). */
+    readonly url: string;
+    /** The PID of the served process, for confirmation / signalling. */
+    readonly pid: number;
+}
+/**
+ * Resolve the absolute path of the endpoint file for a given home root. Pure
+ * (touches no filesystem); precedence matches {@link resolveHomeRoot} so the
+ * endpoint file always sits beside the profiles dir under the same root.
+ */
+export declare function resolveSessionEndpointPath(options?: ProfileLocationOptions): string;
+/**
+ * Advertise a live served session by writing its endpoint file (creating the
+ * home root if absent). Overwrites any stale file; the server owns this file's
+ * lifetime and clears it on stop.
+ */
+export declare function writeSessionEndpoint(endpoint: SessionEndpoint, options?: ProfileLocationOptions): Promise<string>;
+/**
+ * Read the advertised endpoint, or `undefined` when no server is live (the file
+ * is absent or unreadable). Discovery is best-effort: a malformed file is
+ * treated as "no live server" so a client falls through to the clear
+ * "run `serve` first" error rather than crashing on a partial write.
+ */
+export declare function readSessionEndpoint(options?: ProfileLocationOptions): Promise<SessionEndpoint | undefined>;
+/** Remove the endpoint file (teardown). Absent file is not an error. */
+export declare function clearSessionEndpoint(options?: ProfileLocationOptions): Promise<void>;
+//# sourceMappingURL=session-endpoint.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session-endpoint.d.ts","sourceRoot":"","sources":["../src/session-endpoint.ts"],"names":[],"mappings":"AAEA,OAAO,EAEN,KAAK,sBAAsB,EAC3B,MAAM,uBAAuB,CAAC;AAE/B;;;;;;;;;;;;;;;;GAgBG;AAEH,6DAA6D;AAC7D,eAAO,MAAM,yBAAyB,0BAA0B,CAAC;AAEjE;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC/B,uFAAuF;IACvF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACzC,OAAO,GAAE,sBAA2B,GAClC,MAAM,CAER;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CACzC,QAAQ,EAAE,eAAe,EACzB,OAAO,GAAE,sBAA2B,GAClC,OAAO,CAAC,MAAM,CAAC,CAKjB;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACxC,OAAO,GAAE,sBAA2B,GAClC,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CAqBtC;AAED,wEAAwE;AACxE,wBAAsB,oBAAoB,CACzC,OAAO,GAAE,sBAA2B,GAClC,OAAO,CAAC,IAAI,CAAC,CAGf"}

package/dist/session-endpoint.js

@@ -0,0 +1,75 @@
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { resolveHomeRoot, } from './profile-location.js';
+/**
+ * Cross-invocation session DISCOVERY (ADR-0005).
+ *
+ * The long-lived `incur serve` process owns the one live browser session; each
+ * `webhands <verb>` is a thin client that must FIND that running
+ * server. The server advertises itself by writing a small endpoint file under
+ * the controller home root (the same SHARED location profiles live under, see
+ * {@link resolveHomeRoot}); client verbs read it to learn where to send their
+ * verb calls. When no endpoint file exists, no server is live, and a verb errors
+ * with "run `serve` first" rather than auto-spawning a browser (ADR-0005:
+ * lifecycle is EXPLICIT in v1).
+ *
+ * Because this writes under the real `~/.webhands` by default,
+ * TESTS MUST override the root to a temp dir (via {@link ProfileLocationOptions})
+ * and assert the real location is untouched, exactly as the profile location
+ * does.
+ */
+/** The endpoint file name under the controller home root. */
+export const SESSION_ENDPOINT_FILENAME = 'session-endpoint.json';
+/**
+ * Resolve the absolute path of the endpoint file for a given home root. Pure
+ * (touches no filesystem); precedence matches {@link resolveHomeRoot} so the
+ * endpoint file always sits beside the profiles dir under the same root.
+ */
+export function resolveSessionEndpointPath(options = {}) {
+    return join(resolveHomeRoot(options), SESSION_ENDPOINT_FILENAME);
+}
+/**
+ * Advertise a live served session by writing its endpoint file (creating the
+ * home root if absent). Overwrites any stale file; the server owns this file's
+ * lifetime and clears it on stop.
+ */
+export async function writeSessionEndpoint(endpoint, options = {}) {
+    const path = resolveSessionEndpointPath(options);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, JSON.stringify(endpoint, null, 2), 'utf8');
+    return path;
+}
+/**
+ * Read the advertised endpoint, or `undefined` when no server is live (the file
+ * is absent or unreadable). Discovery is best-effort: a malformed file is
+ * treated as "no live server" so a client falls through to the clear
+ * "run `serve` first" error rather than crashing on a partial write.
+ */
+export async function readSessionEndpoint(options = {}) {
+    const path = resolveSessionEndpointPath(options);
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(text);
+        if (typeof parsed.url === 'string' &&
+            parsed.url !== '' &&
+            typeof parsed.pid === 'number') {
+            return { url: parsed.url, pid: parsed.pid };
+        }
+    }
+    catch {
+        // fall through
+    }
+    return undefined;
+}
+/** Remove the endpoint file (teardown). Absent file is not an error. */
+export async function clearSessionEndpoint(options = {}) {
+    const path = resolveSessionEndpointPath(options);
+    await rm(path, { force: true });
+}
+//# sourceMappingURL=session-endpoint.js.map

package/dist/session-endpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-endpoint.js","sourceRoot":"","sources":["../src/session-endpoint.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,EAAE,SAAS,EAAC,MAAM,kBAAkB,CAAC;AAChE,OAAO,EAAC,OAAO,EAAE,IAAI,EAAC,MAAM,WAAW,CAAC;AACxC,OAAO,EACN,eAAe,GAEf,MAAM,uBAAuB,CAAC;AAE/B;;;;;;;;;;;;;;;;GAgBG;AAEH,6DAA6D;AAC7D,MAAM,CAAC,MAAM,yBAAyB,GAAG,uBAAuB,CAAC;AAcjE;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CACzC,UAAkC,EAAE;IAEpC,OAAO,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,EAAE,yBAAyB,CAAC,CAAC;AAClE,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACzC,QAAyB,EACzB,UAAkC,EAAE;IAEpC,MAAM,IAAI,GAAG,0BAA0B,CAAC,OAAO,CAAC,CAAC;IACjD,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAC,SAAS,EAAE,IAAI,EAAC,CAAC,CAAC;IAC9C,MAAM,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IACjE,OAAO,IAAI,CAAC;AACb,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACxC,UAAkC,EAAE;IAEpC,MAAM,IAAI,GAAG,0BAA0B,CAAC,OAAO,CAAC,CAAC;IACjD,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACJ,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACrC,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,SAAS,CAAC;IAClB,CAAC;IACD,IAAI,CAAC;QACJ,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAA6B,CAAC;QAC5D,IACC,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ;YAC9B,MAAM,CAAC,GAAG,KAAK,EAAE;YACjB,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ,EAC7B,CAAC;YACF,OAAO,EAAC,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAC,CAAC;QAC3C,CAAC;IACF,CAAC;IAAC,MAAM,CAAC;QACR,eAAe;IAChB,CAAC;IACD,OAAO,SAAS,CAAC;AAClB,CAAC;AAED,wEAAwE;AACxE,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACzC,UAAkC,EAAE;IAEpC,MAAM,IAAI,GAAG,0BAA0B,CAAC,OAAO,CAAC,CAAC;IACjD,MAAM,EAAE,CAAC,IAAI,EAAE,EAAC,KAAK,EAAE,IAAI,EAAC,CAAC,CAAC;AAC/B,CAAC"}

package/dist/session-rpc.d.ts

@@ -0,0 +1,82 @@
+import { type Cookie, type WaitCondition } from './seam.js';
+import type { Page } from './seam.js';
+/**
+ * The wire protocol for driving the long-lived session over HTTP (ADR-0005).
+ *
+ * The served process holds ONE live {@link Page} in memory; a thin client verb
+ * cannot hold a JS reference to it across the process boundary, so each verb
+ * call is sent as a small JSON request to the server, which runs it against its
+ * live page and returns the result. This module is the SINGLE source of truth
+ * for that request/response shape, imported by BOTH the server handler and the
+ * client proxy so they cannot drift (mirrors how `serializeCookies` is shared
+ * by the cookies verb and its test).
+ *
+ * It is a thin transport detail, NOT a second verb surface: every request maps
+ * 1:1 to a {@link Page} method, and the seam's verb semantics (ADR-0003/0004)
+ * are unchanged. The {@link LocatorString} brand and the structured
+ * {@link WaitCondition} cross as plain JSON and are re-branded on the server
+ * with {@link locator}; no Playwright/CDP type is ever named here.
+ */
+/** The path the session RPC is served under, below the server's base URL. */
+export declare const SESSION_RPC_PATH = "/session/call";
+/** A single verb call to run against the served live page. */
+export type SessionRpcRequest = {
+    readonly verb: 'navigate';
+    readonly url: string;
+} | {
+    readonly verb: 'snapshot';
+    readonly full?: boolean;
+} | {
+    readonly verb: 'click';
+    readonly locator: string;
+} | {
+    readonly verb: 'type';
+    readonly locator: string;
+    readonly text: string;
+} | {
+    readonly verb: 'eval';
+    readonly expression: string;
+} | {
+    readonly verb: 'wait';
+    readonly condition: WaitCondition;
+} | {
+    readonly verb: 'cookies';
+} | {
+    readonly verb: 'setCookies';
+    readonly cookies: readonly Cookie[];
+};
+/**
+ * The server's reply to a {@link SessionRpcRequest}. `ok: true` carries the
+ * verb's return value (for verbs that return data); `ok: false` carries the
+ * page-side error message so the client can re-throw a faithful `Error` (a
+ * page throw must REJECT on the client too, per the seam's `eval` contract).
+ */
+export type SessionRpcResponse = {
+    readonly ok: true;
+    readonly value?: unknown;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/**
+ * Run one {@link SessionRpcRequest} against a live {@link Page}, returning the
+ * value the wire should carry back. The server's HTTP handler is just this plus
+ * JSON framing; keeping the dispatch here (not inline in the handler) means the
+ * verb-to-page mapping is in one place and unit-testable without HTTP.
+ *
+ * The locator string and wait condition arrive as plain JSON; we re-brand the
+ * locator with {@link locator} before handing it to the page so the seam's
+ * branded-string contract holds.
+ */
+export declare function applySessionRpc(page: Page, request: SessionRpcRequest): Promise<unknown>;
+/**
+ * A {@link Page} whose verbs forward to a server via the supplied transport.
+ *
+ * Used by the client-side proxy (see `remote-session.ts`): each verb builds a
+ * {@link SessionRpcRequest}, hands it to `send`, and shapes the reply back into
+ * the verb's return type. The `send` function owns the actual HTTP; this keeps
+ * the verb-to-request mapping (the other half of {@link applySessionRpc}) in
+ * one place so request and response shapes cannot drift between the two sides.
+ */
+export declare function makeRpcPage(send: (request: SessionRpcRequest) => Promise<unknown>): Page;
+//# sourceMappingURL=session-rpc.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session-rpc.d.ts","sourceRoot":"","sources":["../src/session-rpc.ts"],"names":[],"mappings":"AAAA,OAAO,EAEN,KAAK,MAAM,EAEX,KAAK,aAAa,EAClB,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,WAAW,CAAC;AAEpC;;;;;;;;;;;;;;;;GAgBG;AAEH,6EAA6E;AAC7E,eAAO,MAAM,gBAAgB,kBAAkB,CAAC;AAEhD,8DAA8D;AAC9D,MAAM,MAAM,iBAAiB,GAC1B;IAAC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAC,GACjD;IAAC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAC,GACpD;IAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAC,GAClD;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAC,GACxE;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAAC,GACpD;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAA;CAAC,GAC1D;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAC,GAC1B;IAAC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;CAAC,CAAC;AAEtE;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAC3B;IAAC,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAC,GAC7C;IAAC,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAC,CAAC;AAEhD;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CACpC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,iBAAiB,GACxB,OAAO,CAAC,OAAO,CAAC,CAwBlB;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAC1B,IAAI,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,OAAO,CAAC,GACpD,IAAI,CA8BN"}