npm - @webhands/core - Versions diffs - 0.1.0 - Mend

@webhands/core 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (76) hide show

package/dist/cookies-export.d.ts +56 -0
package/dist/cookies-export.d.ts.map +1 -0
package/dist/cookies-export.js +69 -0
package/dist/cookies-export.js.map +1 -0
package/dist/errors.d.ts +126 -0
package/dist/errors.d.ts.map +1 -0
package/dist/errors.js +135 -0
package/dist/errors.js.map +1 -0
package/dist/index.d.ts +16 -0
package/dist/index.d.ts.map +1 -0
package/dist/index.js +15 -0
package/dist/index.js.map +1 -0
package/dist/playwright-attach-transport.d.ts +28 -0
package/dist/playwright-attach-transport.d.ts.map +1 -0
package/dist/playwright-attach-transport.js +175 -0
package/dist/playwright-attach-transport.js.map +1 -0
package/dist/playwright-launch-transport.d.ts +90 -0
package/dist/playwright-launch-transport.d.ts.map +1 -0
package/dist/playwright-launch-transport.js +305 -0
package/dist/playwright-launch-transport.js.map +1 -0
package/dist/profile-location.d.ts +61 -0
package/dist/profile-location.d.ts.map +1 -0
package/dist/profile-location.js +61 -0
package/dist/profile-location.js.map +1 -0
package/dist/remote-session.d.ts +22 -0
package/dist/remote-session.d.ts.map +1 -0
package/dist/remote-session.js +57 -0
package/dist/remote-session.js.map +1 -0
package/dist/seam.d.ts +212 -0
package/dist/seam.d.ts.map +1 -0
package/dist/seam.js +25 -0
package/dist/seam.js.map +1 -0
package/dist/session-endpoint.d.ts +53 -0
package/dist/session-endpoint.d.ts.map +1 -0
package/dist/session-endpoint.js +75 -0
package/dist/session-endpoint.js.map +1 -0
package/dist/session-rpc.d.ts +82 -0
package/dist/session-rpc.d.ts.map +1 -0
package/dist/session-rpc.js +107 -0
package/dist/session-rpc.js.map +1 -0
package/dist/session-server.d.ts +79 -0
package/dist/session-server.d.ts.map +1 -0
package/dist/session-server.js +141 -0
package/dist/session-server.js.map +1 -0
package/dist/setup-profile.d.ts +84 -0
package/dist/setup-profile.d.ts.map +1 -0
package/dist/setup-profile.js +52 -0
package/dist/setup-profile.js.map +1 -0
package/dist/stub-transport.d.ts +26 -0
package/dist/stub-transport.d.ts.map +1 -0
package/dist/stub-transport.js +76 -0
package/dist/stub-transport.js.map +1 -0
package/dist/test-fixtures/fixture-pages.d.ts +12 -0
package/dist/test-fixtures/fixture-pages.d.ts.map +1 -0
package/dist/test-fixtures/fixture-pages.js +204 -0
package/dist/test-fixtures/fixture-pages.js.map +1 -0
package/dist/test-fixtures/fixture-server.d.ts +19 -0
package/dist/test-fixtures/fixture-server.d.ts.map +1 -0
package/dist/test-fixtures/fixture-server.js +41 -0
package/dist/test-fixtures/fixture-server.js.map +1 -0
package/package.json +34 -0
package/src/cookies-export.ts +91 -0
package/src/errors.ts +185 -0
package/src/index.ts +89 -0
package/src/playwright-attach-transport.ts +214 -0
package/src/playwright-launch-transport.ts +363 -0
package/src/profile-location.ts +92 -0
package/src/remote-session.ts +66 -0
package/src/seam.ts +222 -0
package/src/session-endpoint.ts +104 -0
package/src/session-rpc.ts +143 -0
package/src/session-server.ts +231 -0
package/src/setup-profile.ts +134 -0
package/src/stub-transport.ts +100 -0
package/src/test-fixtures/fixture-pages.ts +210 -0
package/src/test-fixtures/fixture-server.ts +54 -0

package/dist/test-fixtures/fixture-pages.js ADDED Viewed

@@ -0,0 +1,204 @@
+/**
+ * The controlled static fixture pages served by {@link startFixtureServer}.
+ *
+ * Kept as in-module strings (rather than separate `.html` assets) so they
+ * survive `tsc` compilation into `dist` without a copy step, and so the
+ * deterministic verb tests have a single source of truth for the markup they
+ * assert against. Later verb-behaviour tasks extend these pages with whatever
+ * controlled elements they need; the seam scaffold ships a minimal index page.
+ */
+const INDEX = `<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<title>webhands fixture</title>
+	</head>
+	<body>
+		<h1 id="heading">Fixture Page</h1>
+		<p id="status">ready</p>
+		<input id="query" type="text" aria-label="Query" />
+		<button id="search" type="button">Search</button>
+	</body>
+</html>
+`;
+/**
+ * A page whose content is rendered LATE, client-side: the "Loaded" heading and a
+ * marker element are injected by script ~150ms after the `load` event fires, the
+ * way an XHR-rendered price or a hydrated result list appears AFTER the document
+ * itself has settled. So the `load`-settled `goto` returns BEFORE this content
+ * exists, and only `wait({kind: 'locator'})` (PRD story 10) makes a reader block
+ * until it does. The delay is deterministic (driven by `setTimeout` against the
+ * fixture's own clock, not a network round-trip), so the wait-for-selector test
+ * is not flaky.
+ */
+const DELAYED_CONTENT = `<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<title>delayed content fixture</title>
+	</head>
+	<body>
+		<h1 id="heading">Loading…</h1>
+		<div id="results"></div>
+		<script>
+			window.setTimeout(function () {
+				document.getElementById('heading').textContent = 'Loaded';
+				var el = document.createElement('p');
+				el.id = 'late';
+				el.setAttribute('aria-label', 'Late Content');
+				el.textContent = 'late content rendered';
+				document.getElementById('results').appendChild(el);
+			}, 150);
+		</script>
+	</body>
+</html>
+`;
+/**
+ * A page exercising the `click` and `type` verbs (PRD story 8).
+ *
+ * - `#search` is a VISIBLE button; clicking it runs its handler, which writes
+ *   `clicked` into `#status`. A normal `click()` (actionability-checked)
+ *   handles this path.
+ * - `#query` is a VISIBLE text input the `type` verb fills.
+ * - `#hidden-toggle` is a HIDDEN custom control (`display:none`), the case the
+ *   prd calls out: a normal `click()` AUTO-WAITS for the element to become
+ *   visible/actionable and TIMES OUT, because it never does. The verb's escape
+ *   path DISPATCHES a click event (no actionability check); the handler then
+ *   sets `#hidden-state` to `toggled`, so the test can assert the dispatch path
+ *   actually fired the element's behaviour (not merely that it did not throw).
+ */
+const CLICK_TYPE = `<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<title>click + type fixture</title>
+	</head>
+	<body>
+		<h1 id="heading">Click + Type Fixture</h1>
+		<p id="status">idle</p>
+		<input id="query" type="text" aria-label="Query" />
+		<button id="search" type="button">Search</button>
+		<!-- A hidden custom control: a normal click times out (never actionable);
+		     only a dispatched click fires its handler. -->
+		<div id="hidden-toggle" role="button" aria-label="Hidden Toggle" style="display: none"></div>
+		<p id="hidden-state">untoggled</p>
+		<script>
+			document.getElementById('search').addEventListener('click', function () {
+				document.getElementById('status').textContent = 'clicked';
+			});
+			document
+				.getElementById('hidden-toggle')
+				.addEventListener('click', function () {
+					document.getElementById('hidden-state').textContent = 'toggled';
+				});
+		</script>
+	</body>
+</html>
+`;
+/**
+ * A page that NAVIGATES itself to `index.html` ~150ms after load, the way a
+ * landing/redirect page bounces to the real destination. `goto` here settles on
+ * THIS page's `load`; only `wait({kind: 'navigation'})` (PRD story 10) blocks
+ * until the subsequent navigation has settled, after which a reader is on
+ * `index.html`. Deterministic (a `setTimeout`-driven `location.assign`), so the
+ * wait-for-navigation test is not flaky.
+ */
+const REDIRECTING = `<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<title>redirecting fixture</title>
+	</head>
+	<body>
+		<h1 id="heading">Redirecting…</h1>
+		<script>
+			window.setTimeout(function () {
+				window.location.assign('/index.html');
+			}, 150);
+		</script>
+	</body>
+</html>
+`;
+/**
+ * A page carrying controlled, deterministic state for the `eval` verb (PRD
+ * story 9) to read back. The escape-hatch tests evaluate expressions against
+ * THIS fixture's own state and assert the serialized result, never against
+ * third-party DOM (PRD "Testing Decisions"):
+ *
+ * - `#marker` holds a known text the verb can read.
+ * - `window.__fixture` is a known object graph (a number, a string, a nested
+ *   array) so an object result can be asserted by value.
+ * - `window.__fixtureAsync()` resolves to a known value after a tick, so the
+ *   Promise-awaiting behaviour of `eval` is exercised on the fixture's own
+ *   clock (deterministic, not a network round-trip).
+ * - `window.__fixtureCircular` is a circular structure, the controlled case for
+ *   asserting that the transport's structured clone PRESERVES circular refs (a
+ *   `[Circular]` marker) rather than throwing, unlike a JSON-based encoding.
+ */
+const EVAL = `<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<title>eval fixture</title>
+	</head>
+	<body>
+		<h1 id="heading">Eval Fixture</h1>
+		<p id="marker">marker-value</p>
+		<script>
+			window.__fixture = {
+				count: 42,
+				label: 'fixture-label',
+				nested: [1, 2, 3],
+			};
+			window.__fixtureAsync = function () {
+				return new Promise(function (resolve) {
+					window.setTimeout(function () {
+						resolve('async-resolved');
+					}, 10);
+				});
+			};
+			var circular = {};
+			circular.self = circular;
+			window.__fixtureCircular = circular;
+		</script>
+	</body>
+</html>
+`;
+/**
+ * A page that SETS its own cookies client-side on load (PRD story 11), so the
+ * `cookies export`/`cookies import` round-trip exports cookies the PAGE
+ * created (not only ones seeded through the seam) and re-imports them into a
+ * fresh context. Two cookies make the round-trip meaningful: a session-like
+ * value and a second name, so the test asserts the whole set crosses, not just
+ * one. `document.cookie` writes are visible to the browser context's cookie
+ * store, which is exactly what the seam's `cookies()` reads.
+ */
+const COOKIES = `<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<title>cookies fixture</title>
+	</head>
+	<body>
+		<h1 id="heading">Cookies Fixture</h1>
+		<p id="status">setting cookies</p>
+		<script>
+			document.cookie = 'mbc_session=session-value-123; path=/';
+			document.cookie = 'mbc_pref=dark-mode; path=/';
+			document.getElementById('status').textContent = 'cookies set';
+		</script>
+	</body>
+</html>
+`;
+/** Map of request path (relative to root, no leading slash) to page markup. */
+export const FIXTURE_PAGES = {
+    'index.html': INDEX,
+    'click-type.html': CLICK_TYPE,
+    'delayed.html': DELAYED_CONTENT,
+    'redirecting.html': REDIRECTING,
+    'eval.html': EVAL,
+    'cookies.html': COOKIES,
+};
+//# sourceMappingURL=fixture-pages.js.map

package/dist/test-fixtures/fixture-pages.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"fixture-pages.js","sourceRoot":"","sources":["../../src/test-fixtures/fixture-pages.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,KAAK,GAAG;;;;;;;;;;;;;CAab,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,eAAe,GAAG;;;;;;;;;;;;;;;;;;;;;CAqBvB,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6BlB,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;CAenB,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,IAAI,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4BZ,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,OAAO,GAAG;;;;;;;;;;;;;;;;CAgBf,CAAC;AAEF,+EAA+E;AAC/E,MAAM,CAAC,MAAM,aAAa,GAAqC;IAC9D,YAAY,EAAE,KAAK;IACnB,iBAAiB,EAAE,UAAU;IAC7B,cAAc,EAAE,eAAe;IAC/B,kBAAkB,EAAE,WAAW;IAC/B,WAAW,EAAE,IAAI;IACjB,cAAc,EAAE,OAAO;CACvB,CAAC"}

package/dist/test-fixtures/fixture-server.d.ts ADDED Viewed

@@ -0,0 +1,19 @@
+/** A running fixture server, with the base URL to point a browser at. */
+export interface FixtureServer {
+    /** The base URL, e.g. `http://127.0.0.1:52831`. */
+    readonly url: string;
+    /** Stop the server and release the port. */
+    close(): Promise<void>;
+}
+/**
+ * Start a local HTTP server that serves the controlled static fixture pages
+ * from {@link FIXTURE_PAGES}. This is the DETERMINISTIC target for later
+ * verb-behaviour tests (navigate / snapshot / click / type / eval / wait /
+ * cookies): those tests drive a real browser against this server instead of a
+ * third-party site, so they never rot on someone else's DOM.
+ *
+ * Binds to `127.0.0.1` on an OS-assigned ephemeral port (pass a fixed `port`
+ * only if a test needs one). `/` serves `index.html`.
+ */
+export declare function startFixtureServer(port?: number): Promise<FixtureServer>;
+//# sourceMappingURL=fixture-server.d.ts.map

package/dist/test-fixtures/fixture-server.d.ts.map ADDED Viewed

	@@ -0,0 +1 @@
1	+ {"version":3,"file":"fixture-server.d.ts","sourceRoot":"","sources":["../../src/test-fixtures/fixture-server.ts"],"names":[],"mappings":"AAGA,yEAAyE;AACzE,MAAM,WAAW,aAAa;IAC7B,mDAAmD;IACnD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,4CAA4C;IAC5C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,SAAI,GAAG,OAAO,CAAC,aAAa,CAAC,CAgCzE"}

package/dist/test-fixtures/fixture-server.js ADDED Viewed

@@ -0,0 +1,41 @@
+import { createServer } from 'node:http';
+import { FIXTURE_PAGES } from './fixture-pages.js';
+/**
+ * Start a local HTTP server that serves the controlled static fixture pages
+ * from {@link FIXTURE_PAGES}. This is the DETERMINISTIC target for later
+ * verb-behaviour tests (navigate / snapshot / click / type / eval / wait /
+ * cookies): those tests drive a real browser against this server instead of a
+ * third-party site, so they never rot on someone else's DOM.
+ *
+ * Binds to `127.0.0.1` on an OS-assigned ephemeral port (pass a fixed `port`
+ * only if a test needs one). `/` serves `index.html`.
+ */
+export async function startFixtureServer(port = 0) {
+    const server = createServer((req, res) => {
+        const rawPath = (req.url ?? '/').split('?')[0];
+        const key = rawPath === '/' ? 'index.html' : rawPath.replace(/^\/+/, '');
+        const body = FIXTURE_PAGES[key];
+        if (body === undefined) {
+            res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
+            res.end('not found');
+            return;
+        }
+        res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
+        res.end(body);
+    });
+    await new Promise((resolve) => server.listen(port, '127.0.0.1', resolve));
+    const address = server.address();
+    if (address === null || typeof address === 'string') {
+        await new Promise((resolve) => server.close(() => resolve()));
+        throw new Error('fixture server failed to bind to a TCP port');
+    }
+    return {
+        url: `http://127.0.0.1:${address.port}`,
+        close() {
+            return new Promise((resolve, reject) => {
+                server.close((err) => (err ? reject(err) : resolve()));
+            });
+        },
+    };
+}
+//# sourceMappingURL=fixture-server.js.map

package/dist/test-fixtures/fixture-server.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"fixture-server.js","sourceRoot":"","sources":["../../src/test-fixtures/fixture-server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,YAAY,EAAc,MAAM,WAAW,CAAC;AACpD,OAAO,EAAC,aAAa,EAAC,MAAM,oBAAoB,CAAC;AAUjD;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,IAAI,GAAG,CAAC;IAChD,MAAM,MAAM,GAAW,YAAY,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;QAChD,MAAM,OAAO,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAC/C,MAAM,GAAG,GAAG,OAAO,KAAK,GAAG,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACzE,MAAM,IAAI,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;QAChC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACxB,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,EAAC,cAAc,EAAE,2BAA2B,EAAC,CAAC,CAAC;YAClE,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;YACrB,OAAO;QACR,CAAC;QACD,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,EAAC,cAAc,EAAE,0BAA0B,EAAC,CAAC,CAAC;QACjE,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACf,CAAC,CAAC,CAAC;IAEH,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CACnC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,CAAC,CACzC,CAAC;IAEF,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;IACjC,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QACrD,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QACpE,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;IAChE,CAAC;IAED,OAAO;QACN,GAAG,EAAE,oBAAoB,OAAO,CAAC,IAAI,EAAE;QACvC,KAAK;YACJ,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;gBAC5C,MAAM,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;YACxD,CAAC,CAAC,CAAC;QACJ,CAAC;KACD,CAAC;AACH,CAAC"}

package/package.json ADDED Viewed

@@ -0,0 +1,34 @@
+{
+  "name": "@webhands/core",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "playwright": "1.61.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.0",
+    "as-soon": "^0.1.5",
+    "tsx": "^4.21.0",
+    "typescript": "^5.3.3",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "as-soon -w src pnpm build",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/src/cookies-export.ts ADDED Viewed

@@ -0,0 +1,91 @@
+/**
+ * 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
+ * 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
+ * `Cookie[]` is written to (and read back from) an export file.
+ *
+ * The format is deliberately transport-neutral JSON of the seam's own
+ * {@link Cookie} type (no CDP/Playwright type, ADR-0003): a small envelope
+ * (`{version, cookies}`) so the file is self-describing and a future format
+ * change can be detected rather than silently mis-parsed. Both the CLI verb and
+ * the round-trip test share THIS one source of truth for the format, so the
+ * thing a user backs up and the thing import reads back can never drift apart.
+ */
+import type {Cookie} from './seam.js';
+/**
+ * The current export-file schema version. Bumped only on a
+ * backwards-INCOMPATIBLE format change; {@link deserializeCookies} rejects an
+ * unknown version rather than guessing.
+ */
+export const COOKIES_EXPORT_VERSION = 1 as const;
+/**
+ * The on-disk shape of an exported session: a versioned envelope around the
+ * transport-neutral {@link Cookie} list. Self-describing so import can verify
+ * it is reading a format it understands.
+ */
+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. */
+	readonly cookies: readonly Cookie[];
+}
+/**
+ * Serialize the cookies read from the seam ({@link Page.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
+ * file in its own temp dir.
+ */
+export function serializeCookies(cookies: readonly Cookie[]): string {
+	const payload: CookiesExport = {
+		version: COOKIES_EXPORT_VERSION,
+		cookies,
+	};
+	return JSON.stringify(payload, null, '\t') + '\n';
+}
+/**
+ * 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
+ * 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.
+ *
+ * @throws Error if the text is not valid JSON, not the expected envelope shape,
+ *   or carries an unknown {@link COOKIES_EXPORT_VERSION}.
+ */
+export function deserializeCookies(text: string): readonly Cookie[] {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(text);
+	} catch (cause) {
+		throw new Error('cookies import: file is not valid JSON', {cause});
+	}
+	if (typeof parsed !== 'object' || parsed === null) {
+		throw new Error('cookies import: file is not a cookies export envelope');
+	}
+	const envelope = parsed as {version?: unknown; cookies?: unknown};
+	if (envelope.version !== COOKIES_EXPORT_VERSION) {
+		throw new Error(
+			`cookies import: unsupported export version ${String(
+				envelope.version,
+			)} (expected ${COOKIES_EXPORT_VERSION})`,
+		);
+	}
+	if (!Array.isArray(envelope.cookies)) {
+		throw new Error('cookies import: export envelope has no cookies array');
+	}
+	return envelope.cookies as readonly Cookie[];
+}

package/src/errors.ts ADDED Viewed

@@ -0,0 +1,185 @@
+/**
+ * Typed, identifiable `core` error conditions.
+ *
+ * These are raised by the concrete transports (the v1 Playwright launch
+ * transport, and later `attach`/`setup-profile`) so that the `cli` package
+ * (`cli-incur-wiring-and-errors`, PRD story 17) can render the EXACT
+ * fix-command message without re-detecting the condition. This module OWNS the
+ * typed condition; the CLI owns the user-facing message text.
+ *
+ * The discriminator is the string-literal {@link ControllerError.code}. A
+ * caller branches on `code` (a stable, machine-readable tag) rather than
+ * matching on a message string, which is presentation and may change. Each
+ * error also carries the structured context the CLI needs to compose its fix
+ * command (e.g. the profile name, the resolved profile dir) so the CLI never
+ * has to re-derive paths.
+ */
+/** The closed set of identifiable `core` error conditions. */
+export type ControllerErrorCode =
+	| 'missing-browser-binary'
+	| 'missing-profile'
+	| 'attach-not-chromium'
+	| 'attach-no-context'
+	| 'no-live-server'
+	| 'session-already-active';
+/**
+ * Base class for every identifiable `core` error. Branch on {@link code}.
+ *
+ * Use {@link isControllerError} to narrow an `unknown` caught value to this
+ * type across a package/bundle boundary (where `instanceof` can be unreliable);
+ * the `code` tag is the contract, not the class identity.
+ */
+export abstract class ControllerError extends Error {
+	/** Machine-readable discriminator; stable across versions. */
+	abstract readonly code: ControllerErrorCode;
+	/** Brand so {@link isControllerError} can narrow across bundle boundaries. */
+	readonly isControllerError = true as const;
+	constructor(message: string, options?: {cause?: unknown}) {
+		super(message, options);
+		// Preserve the concrete subclass name (Error's constructor sets it to
+		// `Error` under some transpile targets).
+		this.name = new.target.name;
+	}
+}
+/**
+ * The browser binary Playwright needs is not installed (e.g.
+ * `playwright install chromium` was never run). Surfaced so the CLI can tell
+ * the user the exact install command.
+ */
+export class MissingBrowserBinaryError extends ControllerError {
+	readonly code = 'missing-browser-binary';
+	/** The browser whose binary is missing (e.g. `chromium`). */
+	readonly browser: string;
+	constructor(
+		browser: string,
+		message: string = `The ${browser} browser binary is not installed.`,
+		options?: {cause?: unknown},
+	) {
+		super(message, options);
+		this.browser = browser;
+	}
+}
+/**
+ * The named profile has not been set up yet: its dedicated profile directory
+ * does not exist on disk. A profile is created by the headed `setup-profile`
+ * flow; `launch` against a not-yet-set-up profile raises this so the CLI can
+ * tell the user to run `setup-profile` first.
+ */
+export class MissingProfileError extends ControllerError {
+	readonly code = 'missing-profile';
+	/** The name of the profile that is not set up. */
+	readonly profile: string;
+	/** The dedicated profile directory that was expected to exist. */
+	readonly profileDir: string;
+	constructor(
+		profile: string,
+		profileDir: string,
+		message: string = `The "${profile}" profile is not set up (no profile directory at ${profileDir}).`,
+		options?: {cause?: unknown},
+	) {
+		super(message, options);
+		this.profile = profile;
+		this.profileDir = profileDir;
+	}
+}
+/**
+ * The `attach` transport connected to a browser that is NOT Chromium. CDP-attach
+ * (`connectOverCDP`) is Chromium-only (ADR-0002/0003: Firefox attaches via a
+ * different mechanism), so attaching to anything else cannot reuse the live
+ * context and is refused. Surfaced as a typed condition so the CLI can tell the
+ * user attach is Chromium-only WITHOUT the seam ever naming CDP/Chromium types.
+ */
+export class AttachNotChromiumError extends ControllerError {
+	readonly code = 'attach-not-chromium';
+	/** The browser engine actually reached at the endpoint (e.g. `firefox`). */
+	readonly browser: string;
+	constructor(
+		browser: string,
+		message: string = `attach is Chromium-only; the endpoint exposes a "${browser}" browser. Start Chromium/Chrome with --remote-debugging-port and attach to that.`,
+		options?: {cause?: unknown},
+	) {
+		super(message, options);
+		this.browser = browser;
+	}
+}
+/**
+ * The browser reached at the attach endpoint exposes no browser context to
+ * reuse. attach deliberately reuses the user's EXISTING authenticated context
+ * (`contexts()[0]`) and never opens a fresh one (ADR-0002), so a browser with
+ * zero contexts is a refusal, not a silent `newContext()`.
+ */
+export class AttachNoContextError extends ControllerError {
+	readonly code = 'attach-no-context';
+	/** The endpoint that exposed no reusable context. */
+	readonly endpoint: string;
+	constructor(
+		endpoint: string,
+		message: string = `attach found no existing browser context at ${endpoint} to reuse. Open a window/tab in the browser before attaching.`,
+		options?: {cause?: unknown},
+	) {
+		super(message, options);
+		this.endpoint = endpoint;
+	}
+}
+/**
+ * No long-lived served session is running (no endpoint file under the config
+ * dir), so a thin-client verb has nothing to drive (ADR-0005). Surfaced so the
+ * CLI can tell the user to run `serve` first rather than auto-spawning a browser
+ * (lifecycle is EXPLICIT in v1). This is the cross-invocation analogue of
+ * {@link MissingProfileError}: a precondition the user resolves with one named
+ * command.
+ */
+export class NoLiveServerError extends ControllerError {
+	readonly code = 'no-live-server';
+	constructor(
+		message: string = 'No live webhands session server is running. Start one with `serve` first.',
+		options?: {cause?: unknown},
+	) {
+		super(message, options);
+	}
+}
+/**
+ * A second `serve`/`launch`/`attach` was requested while one session is already
+ * live. v1 holds EXACTLY ONE session (ADR-0005, single session); a concurrent
+ * open is a clear refusal, not a second browser. Surfaced so the CLI can tell
+ * the user to stop the active session first.
+ */
+export class SessionAlreadyActiveError extends ControllerError {
+	readonly code = 'session-already-active';
+	constructor(
+		message: string = 'A session is already active; stop it first (run `stop`).',
+		options?: {cause?: unknown},
+	) {
+		super(message, options);
+	}
+}
+/**
+ * Narrow an unknown caught value to a {@link ControllerError}. Prefer this over
+ * `instanceof` at package boundaries: it checks the {@link ControllerError.isControllerError}
+ * brand and a known {@link ControllerErrorCode}, so it survives duplicate
+ * copies of this module in different bundles.
+ */
+export function isControllerError(value: unknown): value is ControllerError {
+	return (
+		typeof value === 'object' &&
+		value !== null &&
+		(value as {isControllerError?: unknown}).isControllerError === true &&
+		typeof (value as {code?: unknown}).code === 'string'
+	);
+}

package/src/index.ts ADDED Viewed

@@ -0,0 +1,89 @@
+export type {
+	Cookie,
+	Driver,
+	LocatorString,
+	OpenTarget,
+	Page,
+	Session,
+	Snapshot,
+	SnapshotOptions,
+	SnapshotView,
+	Transport,
+	WaitCondition,
+} from './seam.js';
+export {locator} from './seam.js';
+export {
+	serializeCookies,
+	deserializeCookies,
+	COOKIES_EXPORT_VERSION,
+	type CookiesExport,
+} from './cookies-export.js';
+export {StubTransport, type StubCall} from './stub-transport.js';
+export {PlaywrightLaunchTransport} from './playwright-launch-transport.js';
+export {PlaywrightAttachTransport} from './playwright-attach-transport.js';
+export {
+	setupProfile,
+	buildPrompt,
+	type PromptSink,
+	type SetupProfileOptions,
+	type SetupProfileResult,
+} from './setup-profile.js';
+export {
+	ControllerError,
+	MissingBrowserBinaryError,
+	MissingProfileError,
+	AttachNotChromiumError,
+	AttachNoContextError,
+	NoLiveServerError,
+	SessionAlreadyActiveError,
+	isControllerError,
+	type ControllerErrorCode,
+} from './errors.js';
+export {
+	resolveSessionEndpointPath,
+	writeSessionEndpoint,
+	readSessionEndpoint,
+	clearSessionEndpoint,
+	SESSION_ENDPOINT_FILENAME,
+	type SessionEndpoint,
+} from './session-endpoint.js';
+export {
+	startSessionServer,
+	sessionAlreadyActive,
+	type SessionServerOptions,
+	type RunningSessionServer,
+} from './session-server.js';
+export {connectRemoteSession} from './remote-session.js';
+export {
+	SESSION_RPC_PATH,
+	applySessionRpc,
+	makeRpcPage,
+	type SessionRpcRequest,
+	type SessionRpcResponse,
+} from './session-rpc.js';
+export {
+	resolveHomeRoot,
+	resolveProfileLocation,
+	CONTROLLER_HOME_ENV,
+	DEFAULT_HOME_DIRNAME,
+	PROFILES_DIRNAME,
+	type ProfileLocation,
+	type ProfileLocationOptions,
+} from './profile-location.js';
+export {
+	startFixtureServer,
+	type FixtureServer,
+} from './test-fixtures/fixture-server.js';
+export {FIXTURE_PAGES} from './test-fixtures/fixture-pages.js';