@webhands/core 0.1.0 → 0.2.0

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

@@ -1 +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"}
+{"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,YAAY,EAAC,MAAM,WAAW,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,6EAA6E;AAC7E,eAAO,MAAM,gBAAgB,kBAAkB,CAAC;AAEhD,8DAA8D;AAC9D,MAAM,MAAM,iBAAiB,GAC1B,wBAAwB,GACxB,qBAAqB,CAAC;AAEzB;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GACjC;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;;;;;;;;;;GAUG;AACH,MAAM,WAAW,qBAAqB;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,SAAS,OAAO,EAAE,CAAC;CAClC;AAED;;;;;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,YAAY,EAClB,OAAO,EAAE,iBAAiB,GACxB,OAAO,CAAC,OAAO,CAAC,CA0BlB;AAmCD;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAC1B,IAAI,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,OAAO,CAAC,GACpD,YAAY,CA8Bd;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,YAAY,CACjC,IAAI,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,OAAO,CAAC,EACtD,IAAI,EAAE,MAAM,EACZ,GAAG,IAAI,EAAE,SAAS,OAAO,EAAE,GACzB,OAAO,CAAC,OAAO,CAAC,CAElB"}

package/dist/session-rpc.js

@@ -2,7 +2,7 @@ import { locator, } 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
+ * The served process holds ONE live {@link WebHandsPage} 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
@@ -10,16 +10,40 @@ import { locator, } from './seam.js';
  * 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.
+ * It is a thin transport detail, NOT a second verb surface: every built-in
+ * request maps 1:1 to a {@link WebHandsPage} 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.
+ *
+ * THIRD-PARTY HAND VERBS (Phase 2, Model B of the "hands" prd; ADR-0007). The
+ * eight built-in verbs stay a CLOSED union (the 1:1 source of truth above). A
+ * dynamically-loaded hand contributes a verb whose name `core` does NOT know at
+ * compile time, so it cannot be a named member of that closed union without
+ * re-meaning "closed". Instead it crosses as a SINGLE generic
+ * {@link SessionRpcHandRequest} variant (`{verb: 'hand', name, args}`) that
+ * names the contributed verb at runtime and carries its arguments. This is the
+ * exact wire parallel of how a hand verb composes into the page object: by name,
+ * dynamically, alongside the typed built-ins. The agent thereby gains a new tool
+ * over the wire WITHOUT ever holding a live page handle.
+ *
+ * SERIALIZATION BOUNDARY (the load-bearing rule; prd's resolved Q3). A hand
+ * verb's result crosses this RPC, so it MUST be serializable under the same
+ * structured-clone contract `eval` documents (see {@link WebHandsPage.eval}): richer
+ * than JSON, but a value with no transferable form does not round-trip. This is
+ * enforced by CONVENTION + TYPES (a hand author returns serializable values),
+ * NOT a blanket runtime clone here — a blanket clone would corrupt legitimate
+ * in-process (Model A) returns, where a hand may pass/return live Playwright
+ * handles within a single in-process call chain. A host-side runtime clone of
+ * agent-verb results is available HARDENING for untrusted hands, not built here.
+ * A page/in-hand throw REJECTS faithfully on the client exactly as the `eval`
+ * path already does (the server maps it to an `ok: false` reply carrying the
+ * message; the client re-throws a faithful `Error`).
  */
 /** The path the session RPC is served under, below the server's base URL. */
 export const SESSION_RPC_PATH = '/session/call';
 /**
- * Run one {@link SessionRpcRequest} against a live {@link Page}, returning the
+ * Run one {@link SessionRpcRequest} against a live {@link WebHandsPage}, 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.
@@ -51,10 +75,36 @@ export async function applySessionRpc(page, request) {
         case 'setCookies':
             await page.setCookies(request.cookies);
             return undefined;
+        case 'hand':
+            return applyHandVerb(page, request);
     }
 }
 /**
- * A {@link Page} whose verbs forward to a server via the supplied transport.
+ * Invoke a dynamically-loaded hand verb by name against the live composed page.
+ *
+ * The composed {@link WebHandsPage} carries the hand's verbs at runtime (the host merged
+ * them in by name alongside the built-ins, see `composePage`), even though the
+ * seam `WebHandsPage` TYPE only names the eight built-ins. We therefore look the verb up
+ * on the page object as a runtime method and invoke it with the request's args.
+ * An unknown name is a faithful error (the hand was not loaded / named that
+ * verb), surfaced the same way a page-side throw is so the client rejects.
+ *
+ * The result is returned as-is: the serializable-only boundary is enforced by
+ * convention + types on the hand author, NOT a runtime clone here (a blanket
+ * clone would corrupt legitimate in-process Model A returns; see this module's
+ * overview). What the hand returns is what the wire carries back; the JSON
+ * framing in the server handler is the only encoding applied.
+ */
+async function applyHandVerb(page, request) {
+    const verb = page[request.name];
+    if (typeof verb !== 'function') {
+        throw new Error(`no such hand verb '${request.name}' on the live page ` +
+            `(is the hand loaded and named in config?)`);
+    }
+    return verb.call(page, ...request.args);
+}
+/**
+ * A {@link WebHandsPage} 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
@@ -93,6 +143,24 @@ export function makeRpcPage(send) {
         },
     };
 }
+/**
+ * Invoke a dynamically-loaded hand verb over the session RPC by name (Phase 2,
+ * Model B; ADR-0007). The client-side mirror of {@link applyHandVerb}: it builds
+ * the single generic {@link SessionRpcHandRequest} and hands it to the SAME
+ * `send` the built-in verbs use, so request/response shapes cannot drift.
+ *
+ * This is how the agent gains a new tool over the wire WITHOUT holding a live
+ * page handle: it names the contributed verb and passes serializable args; the
+ * server runs the hand against its own live page and returns a serializable
+ * result. A page/in-hand throw rejects faithfully (the `send` re-throws the
+ * server's error message), exactly as the `eval` path does.
+ *
+ * The result type is `unknown` because the hand decides the shape; callers
+ * narrow it (mirrors {@link WebHandsPage.eval}).
+ */
+export async function callHandVerb(send, name, ...args) {
+    return send({ verb: 'hand', name, args });
+}
 /**
  * Re-brand a {@link WaitCondition} that arrived as plain JSON: only the
  * `locator` form carries a branded string, which JSON flattens to a plain

package/dist/session-rpc.js.map

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

package/dist/stub-transport.d.ts

@@ -1,9 +1,9 @@
-import type { OpenTarget, Page, Session, Transport } from './seam.js';
+import type { OpenTarget, WebHandsPage, Session, Transport } from './seam.js';
 /**
  * A record of one verb call against the stub, for assertions in seam tests.
  */
 export interface StubCall {
-    readonly verb: keyof Page;
+    readonly verb: keyof WebHandsPage;
     readonly args: readonly unknown[];
 }
 /**

package/dist/stub-transport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stub-transport.d.ts","sourceRoot":"","sources":["../src/stub-transport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEX,UAAU,EACV,IAAI,EACJ,OAAO,EAGP,SAAS,EAET,MAAM,WAAW,CAAC;AAEnB;;GAEG;AACH,MAAM,WAAW,QAAQ;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,IAAI,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,SAAS,OAAO,EAAE,CAAC;CAClC;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,aAAc,YAAW,SAAS;IAC9C,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,EAAE,QAAQ,EAAE,CAAM;IAE1B,IAAI,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC;CAgEhD"}
+{"version":3,"file":"stub-transport.d.ts","sourceRoot":"","sources":["../src/stub-transport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEX,UAAU,EACV,YAAY,EACZ,OAAO,EAGP,SAAS,EAET,MAAM,WAAW,CAAC;AAEnB;;GAEG;AACH,MAAM,WAAW,QAAQ;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,YAAY,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,SAAS,OAAO,EAAE,CAAC;CAClC;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,aAAc,YAAW,SAAS;IAC9C,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,EAAE,QAAQ,EAAE,CAAM;IAE1B,IAAI,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC;CA4EhD"}

package/dist/stub-transport.js

@@ -16,6 +16,10 @@ export class StubTransport {
     async open(target) {
         const calls = this.calls;
         let closed = false;
+        let resolveClosed;
+        const closedSignal = new Promise((resolve) => {
+            resolveClosed = resolve;
+        });
         const ensureOpen = () => {
             if (closed) {
                 throw new Error('session is closed');
@@ -68,7 +72,14 @@ export class StubTransport {
         return {
             page,
             async close() {
+                if (closed) {
+                    return;
+                }
                 closed = true;
+                resolveClosed();
+            },
+            waitForClose() {
+                return closedSignal;
             },
         };
     }

package/dist/stub-transport.js.map

@@ -1 +1 @@
-{"version":3,"file":"stub-transport.js","sourceRoot":"","sources":["../src/stub-transport.ts"],"names":[],"mappings":"AAmBA;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,aAAa;IACzB,4EAA4E;IACnE,KAAK,GAAe,EAAE,CAAC;IAEhC,KAAK,CAAC,IAAI,CAAC,MAAkB;QAC5B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACzB,IAAI,MAAM,GAAG,KAAK,CAAC;QAEnB,MAAM,UAAU,GAAG,GAAG,EAAE;YACvB,IAAI,MAAM,EAAE,CAAC;gBACZ,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC;YACtC,CAAC;QACF,CAAC,CAAC;QAEF,MAAM,GAAG,GACR,MAAM,CAAC,IAAI,KAAK,QAAQ;YACvB,CAAC,CAAC,iBAAiB,MAAM,CAAC,OAAO,EAAE;YACnC,CAAC,CAAC,iBAAiB,MAAM,CAAC,QAAQ,EAAE,CAAC;QAEvC,MAAM,IAAI,GAAS;YAClB,KAAK,CAAC,QAAQ,CAAC,EAAU;gBACxB,UAAU,EAAE,CAAC;gBACb,KAAK,CAAC,IAAI,CAAC,EAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,EAAC,CAAC,CAAC;YAC5C,CAAC;YACD,KAAK,CAAC,QAAQ,CAAC,OAAyB;gBACvC,UAAU,EAAE,CAAC;gBACb,KAAK,CAAC,IAAI,CAAC,EAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,OAAO,CAAC,EAAC,CAAC,CAAC;gBAChD,OAAO;oBACN,GAAG;oBACH,IAAI,EAAE,OAAO,EAAE,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,eAAe;oBACvD,OAAO,EAAE,EAAE;iBACX,CAAC;YACH,CAAC;YACD,KAAK,CAAC,KAAK,CAAC,CAAC;gBACZ,UAAU,EAAE,CAAC;gBACb,KAAK,CAAC,IAAI,CAAC,EAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAC,CAAC,CAAC;YACxC,CAAC;YACD,KAAK,CAAC,IAAI,CAAC,CAAC,EAAE,IAAI;gBACjB,UAAU,EAAE,CAAC;gBACb,KAAK,CAAC,IAAI,CAAC,EAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,IAAI,CAAC,EAAC,CAAC,CAAC;YAC7C,CAAC;YACD,KAAK,CAAC,IAAI,CAAC,UAAkB;gBAC5B,UAAU,EAAE,CAAC;gBACb,KAAK,CAAC,IAAI,CAAC,EAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,UAAU,CAAC,EAAC,CAAC,CAAC;gBAC/C,OAAO,SAAS,CAAC;YAClB,CAAC;YACD,KAAK,CAAC,IAAI,CAAC,SAAwB;gBAClC,UAAU,EAAE,CAAC;gBACb,KAAK,CAAC,IAAI,CAAC,EAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,SAAS,CAAC,EAAC,CAAC,CAAC;YAC/C,CAAC;YACD,KAAK,CAAC,OAAO;gBACZ,UAAU,EAAE,CAAC;gBACb,KAAK,CAAC,IAAI,CAAC,EAAC,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,EAAC,CAAC,CAAC;gBACxC,OAAO,EAAE,CAAC;YACX,CAAC;YACD,KAAK,CAAC,UAAU,CAAC,OAAO;gBACvB,UAAU,EAAE,CAAC;gBACb,KAAK,CAAC,IAAI,CAAC,EAAC,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,OAAO,CAAC,EAAC,CAAC,CAAC;YACnD,CAAC;SACD,CAAC;QAEF,OAAO;YACN,IAAI;YACJ,KAAK,CAAC,KAAK;gBACV,MAAM,GAAG,IAAI,CAAC;YACf,CAAC;SACD,CAAC;IACH,CAAC;CACD"}
+{"version":3,"file":"stub-transport.js","sourceRoot":"","sources":["../src/stub-transport.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,23 @@
 {
   "name": "@webhands/core",
-  "version": "0.1.0",
+  "version": "0.2.0",
+  "description": "Core library for webhands: drives a real, persistent browser via Playwright.",
+  "keywords": [
+    "browser",
+    "playwright",
+    "automation"
+  ],
+  "license": "AGPL-3.0-or-later",
+  "author": "wighawag",
+  "homepage": "https://github.com/wighawag/webhands#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wighawag/webhands.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/wighawag/webhands/issues"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -13,7 +30,9 @@
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "README.md",
+    "LICENSE"
   ],
   "dependencies": {
     "playwright": "1.61.1"

package/src/cookies-export.ts

@@ -2,8 +2,8 @@
  * The `cookies export` / `cookies import` verb's FILE FORMAT (PRD story 11).
  *
  * The seam already carries the transport-neutral cookie primitives:
- * {@link Page.cookies} reads the active context's cookies and
- * {@link Page.setCookies} loads cookies into it. The export/import VERB is built
+ * {@link WebHandsPage.cookies} reads the active context's cookies and
+ * {@link WebHandsPage.setCookies} loads cookies into it. The export/import VERB is built
  * ON TOP of those two methods (the forward-note: refine the existing seam,
  * do NOT add a parallel cookie path). What this module adds is only the
  * SERIALIZATION the verb needs to move a session to/from disk: how a
@@ -34,12 +34,12 @@ export const COOKIES_EXPORT_VERSION = 1 as const;
 export interface CookiesExport {
 	/** Format version (see {@link COOKIES_EXPORT_VERSION}). */
 	readonly version: typeof COOKIES_EXPORT_VERSION;
-	/** The exported cookies, exactly as the seam's {@link Page.cookies} returns them. */
+	/** The exported cookies, exactly as the seam's {@link WebHandsPage.cookies} returns them. */
 	readonly cookies: readonly Cookie[];
 }
 
 /**
- * Serialize the cookies read from the seam ({@link Page.cookies}) into the
+ * Serialize the cookies read from the seam ({@link WebHandsPage.cookies}) into the
  * export file's text. Pretty-printed JSON so a human can read/diff a backed-up
  * session. This is pure: it does NO disk I/O, so the caller (the CLI verb, a
  * test) owns WHERE the file lands — which is what lets a test keep its export
@@ -55,7 +55,7 @@ export function serializeCookies(cookies: readonly Cookie[]): string {
 
 /**
  * Parse an export file's text back into the cookies to hand to the seam's
- * {@link Page.setCookies} ({@link parse} is pure; the caller does the disk read
+ * {@link WebHandsPage.setCookies} ({@link parse} is pure; the caller does the disk read
  * and the `setCookies` call). Rejects anything that is not a recognised export
  * envelope so a corrupt or wrong-version file surfaces as a clear error rather
  * than silently importing nothing or a half-parsed list.