@webhands/core 0.1.0

package/dist/cookies-export.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 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 declare const COOKIES_EXPORT_VERSION: 1;
+/**
+ * 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 declare 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
+ * 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 declare function deserializeCookies(text: string): readonly Cookie[];
+//# sourceMappingURL=cookies-export.d.ts.map

package/dist/cookies-export.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cookies-export.d.ts","sourceRoot":"","sources":["../src/cookies-export.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,WAAW,CAAC;AAEtC;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,EAAG,CAAU,CAAC;AAEjD;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC7B,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,OAAO,sBAAsB,CAAC;IAChD,qFAAqF;IACrF,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAMnE;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAyBlE"}

package/dist/cookies-export.js

@@ -0,0 +1,69 @@
+/**
+ * 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.
+ */
+/**
+ * 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;
+/**
+ * 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) {
+    const payload = {
+        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) {
+    let parsed;
+    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;
+    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;
+}
+//# sourceMappingURL=cookies-export.js.map

package/dist/cookies-export.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cookies-export.js","sourceRoot":"","sources":["../src/cookies-export.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAU,CAAC;AAcjD;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAA0B;IAC1D,MAAM,OAAO,GAAkB;QAC9B,OAAO,EAAE,sBAAsB;QAC/B,OAAO;KACP,CAAC;IACF,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,GAAG,IAAI,CAAC;AACnD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC9C,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACJ,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,wCAAwC,EAAE,EAAC,KAAK,EAAC,CAAC,CAAC;IACpE,CAAC;IAED,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACnD,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;IAC1E,CAAC;IAED,MAAM,QAAQ,GAAG,MAAgD,CAAC;IAClE,IAAI,QAAQ,CAAC,OAAO,KAAK,sBAAsB,EAAE,CAAC;QACjD,MAAM,IAAI,KAAK,CACd,8CAA8C,MAAM,CACnD,QAAQ,CAAC,OAAO,CAChB,cAAc,sBAAsB,GAAG,CACxC,CAAC;IACH,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;IACzE,CAAC;IAED,OAAO,QAAQ,CAAC,OAA4B,CAAC;AAC9C,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,126 @@
+/**
+ * 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 declare 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;
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * 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 declare 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, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * 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 declare 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, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * 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 declare 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, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * 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 declare class AttachNoContextError extends ControllerError {
+    readonly code = "attach-no-context";
+    /** The endpoint that exposed no reusable context. */
+    readonly endpoint: string;
+    constructor(endpoint: string, message?: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * 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 declare class NoLiveServerError extends ControllerError {
+    readonly code = "no-live-server";
+    constructor(message?: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * 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 declare class SessionAlreadyActiveError extends ControllerError {
+    readonly code = "session-already-active";
+    constructor(message?: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * 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 declare function isControllerError(value: unknown): value is ControllerError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,8DAA8D;AAC9D,MAAM,MAAM,mBAAmB,GAC5B,wBAAwB,GACxB,iBAAiB,GACjB,qBAAqB,GACrB,mBAAmB,GACnB,gBAAgB,GAChB,wBAAwB,CAAC;AAE5B;;;;;;GAMG;AACH,8BAAsB,eAAgB,SAAQ,KAAK;IAClD,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IAC5C,8EAA8E;IAC9E,QAAQ,CAAC,iBAAiB,EAAG,IAAI,CAAU;gBAE/B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAC;CAMxD;AAED;;;;GAIG;AACH,qBAAa,yBAA0B,SAAQ,eAAe;IAC7D,QAAQ,CAAC,IAAI,4BAA4B;IACzC,6DAA6D;IAC7D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAGxB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,MAA0D,EACnE,OAAO,CAAC,EAAE;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAC;CAK5B;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,SAAQ,eAAe;IACvD,QAAQ,CAAC,IAAI,qBAAqB;IAClC,kDAAkD;IAClD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kEAAkE;IAClE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAG3B,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,MAA0F,EACnG,OAAO,CAAC,EAAE;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAC;CAM5B;AAED;;;;;;GAMG;AACH,qBAAa,sBAAuB,SAAQ,eAAe;IAC1D,QAAQ,CAAC,IAAI,yBAAyB;IACtC,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAGxB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,MAAuJ,EAChK,OAAO,CAAC,EAAE;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAC;CAK5B;AAED;;;;;GAKG;AACH,qBAAa,oBAAqB,SAAQ,eAAe;IACxD,QAAQ,CAAC,IAAI,uBAAuB;IACpC,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAGzB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,MAA+H,EACxI,OAAO,CAAC,EAAE;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAC;CAK5B;AAED;;;;;;;GAOG;AACH,qBAAa,iBAAkB,SAAQ,eAAe;IACrD,QAAQ,CAAC,IAAI,oBAAoB;gBAGhC,OAAO,GAAE,MAAoF,EAC7F,OAAO,CAAC,EAAE;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAC;CAI5B;AAED;;;;;GAKG;AACH,qBAAa,yBAA0B,SAAQ,eAAe;IAC7D,QAAQ,CAAC,IAAI,4BAA4B;gBAGxC,OAAO,GAAE,MAAmE,EAC5E,OAAO,CAAC,EAAE;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAC;CAI5B;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAO1E"}

package/dist/errors.js

@@ -0,0 +1,135 @@
+/**
+ * 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.
+ */
+/**
+ * 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 class ControllerError extends Error {
+    /** Brand so {@link isControllerError} can narrow across bundle boundaries. */
+    isControllerError = true;
+    constructor(message, options) {
+        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 {
+    code = 'missing-browser-binary';
+    /** The browser whose binary is missing (e.g. `chromium`). */
+    browser;
+    constructor(browser, message = `The ${browser} browser binary is not installed.`, options) {
+        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 {
+    code = 'missing-profile';
+    /** The name of the profile that is not set up. */
+    profile;
+    /** The dedicated profile directory that was expected to exist. */
+    profileDir;
+    constructor(profile, profileDir, message = `The "${profile}" profile is not set up (no profile directory at ${profileDir}).`, options) {
+        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 {
+    code = 'attach-not-chromium';
+    /** The browser engine actually reached at the endpoint (e.g. `firefox`). */
+    browser;
+    constructor(browser, message = `attach is Chromium-only; the endpoint exposes a "${browser}" browser. Start Chromium/Chrome with --remote-debugging-port and attach to that.`, options) {
+        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 {
+    code = 'attach-no-context';
+    /** The endpoint that exposed no reusable context. */
+    endpoint;
+    constructor(endpoint, message = `attach found no existing browser context at ${endpoint} to reuse. Open a window/tab in the browser before attaching.`, options) {
+        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 {
+    code = 'no-live-server';
+    constructor(message = 'No live webhands session server is running. Start one with `serve` first.', options) {
+        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 {
+    code = 'session-already-active';
+    constructor(message = 'A session is already active; stop it first (run `stop`).', options) {
+        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) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value.isControllerError === true &&
+        typeof value.code === 'string');
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAWH;;;;;;GAMG;AACH,MAAM,OAAgB,eAAgB,SAAQ,KAAK;IAGlD,8EAA8E;IACrE,iBAAiB,GAAG,IAAa,CAAC;IAE3C,YAAY,OAAe,EAAE,OAA2B;QACvD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,sEAAsE;QACtE,yCAAyC;QACzC,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;IAC7B,CAAC;CACD;AAED;;;;GAIG;AACH,MAAM,OAAO,yBAA0B,SAAQ,eAAe;IACpD,IAAI,GAAG,wBAAwB,CAAC;IACzC,6DAA6D;IACpD,OAAO,CAAS;IAEzB,YACC,OAAe,EACf,UAAkB,OAAO,OAAO,mCAAmC,EACnE,OAA2B;QAE3B,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACxB,CAAC;CACD;AAED;;;;;GAKG;AACH,MAAM,OAAO,mBAAoB,SAAQ,eAAe;IAC9C,IAAI,GAAG,iBAAiB,CAAC;IAClC,kDAAkD;IACzC,OAAO,CAAS;IACzB,kEAAkE;IACzD,UAAU,CAAS;IAE5B,YACC,OAAe,EACf,UAAkB,EAClB,UAAkB,QAAQ,OAAO,oDAAoD,UAAU,IAAI,EACnG,OAA2B;QAE3B,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC9B,CAAC;CACD;AAED;;;;;;GAMG;AACH,MAAM,OAAO,sBAAuB,SAAQ,eAAe;IACjD,IAAI,GAAG,qBAAqB,CAAC;IACtC,4EAA4E;IACnE,OAAO,CAAS;IAEzB,YACC,OAAe,EACf,UAAkB,oDAAoD,OAAO,mFAAmF,EAChK,OAA2B;QAE3B,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACxB,CAAC;CACD;AAED;;;;;GAKG;AACH,MAAM,OAAO,oBAAqB,SAAQ,eAAe;IAC/C,IAAI,GAAG,mBAAmB,CAAC;IACpC,qDAAqD;IAC5C,QAAQ,CAAS;IAE1B,YACC,QAAgB,EAChB,UAAkB,+CAA+C,QAAQ,+DAA+D,EACxI,OAA2B;QAE3B,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC1B,CAAC;CACD;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,iBAAkB,SAAQ,eAAe;IAC5C,IAAI,GAAG,gBAAgB,CAAC;IAEjC,YACC,UAAkB,2EAA2E,EAC7F,OAA2B;QAE3B,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACzB,CAAC;CACD;AAED;;;;;GAKG;AACH,MAAM,OAAO,yBAA0B,SAAQ,eAAe;IACpD,IAAI,GAAG,wBAAwB,CAAC;IAEzC,YACC,UAAkB,0DAA0D,EAC5E,OAA2B;QAE3B,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACzB,CAAC;CACD;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC/C,OAAO,CACN,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACb,KAAuC,CAAC,iBAAiB,KAAK,IAAI;QACnE,OAAQ,KAA0B,CAAC,IAAI,KAAK,QAAQ,CACpD,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+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';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACX,MAAM,EACN,MAAM,EACN,aAAa,EACb,UAAU,EACV,IAAI,EACJ,OAAO,EACP,QAAQ,EACR,eAAe,EACf,YAAY,EACZ,SAAS,EACT,aAAa,GACb,MAAM,WAAW,CAAC;AACnB,OAAO,EAAC,OAAO,EAAC,MAAM,WAAW,CAAC;AAElC,OAAO,EACN,gBAAgB,EAChB,kBAAkB,EAClB,sBAAsB,EACtB,KAAK,aAAa,GAClB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAC,aAAa,EAAE,KAAK,QAAQ,EAAC,MAAM,qBAAqB,CAAC;AAEjE,OAAO,EAAC,yBAAyB,EAAC,MAAM,kCAAkC,CAAC;AAE3E,OAAO,EAAC,yBAAyB,EAAC,MAAM,kCAAkC,CAAC;AAE3E,OAAO,EACN,YAAY,EACZ,WAAW,EACX,KAAK,UAAU,EACf,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,GACvB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACN,eAAe,EACf,yBAAyB,EACzB,mBAAmB,EACnB,sBAAsB,EACtB,oBAAoB,EACpB,iBAAiB,EACjB,yBAAyB,EACzB,iBAAiB,EACjB,KAAK,mBAAmB,GACxB,MAAM,aAAa,CAAC;AAErB,OAAO,EACN,0BAA0B,EAC1B,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,yBAAyB,EACzB,KAAK,eAAe,GACpB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACN,kBAAkB,EAClB,oBAAoB,EACpB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,GACzB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAC,oBAAoB,EAAC,MAAM,qBAAqB,CAAC;AAEzD,OAAO,EACN,gBAAgB,EAChB,eAAe,EACf,WAAW,EACX,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,GACvB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACN,eAAe,EACf,sBAAsB,EACtB,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EAChB,KAAK,eAAe,EACpB,KAAK,sBAAsB,GAC3B,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACN,kBAAkB,EAClB,KAAK,aAAa,GAClB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAC,aAAa,EAAC,MAAM,kCAAkC,CAAC"}

package/dist/index.js

@@ -0,0 +1,15 @@
+export { locator } from './seam.js';
+export { serializeCookies, deserializeCookies, COOKIES_EXPORT_VERSION, } from './cookies-export.js';
+export { StubTransport } from './stub-transport.js';
+export { PlaywrightLaunchTransport } from './playwright-launch-transport.js';
+export { PlaywrightAttachTransport } from './playwright-attach-transport.js';
+export { setupProfile, buildPrompt, } from './setup-profile.js';
+export { ControllerError, MissingBrowserBinaryError, MissingProfileError, AttachNotChromiumError, AttachNoContextError, NoLiveServerError, SessionAlreadyActiveError, isControllerError, } from './errors.js';
+export { resolveSessionEndpointPath, writeSessionEndpoint, readSessionEndpoint, clearSessionEndpoint, SESSION_ENDPOINT_FILENAME, } from './session-endpoint.js';
+export { startSessionServer, sessionAlreadyActive, } from './session-server.js';
+export { connectRemoteSession } from './remote-session.js';
+export { SESSION_RPC_PATH, applySessionRpc, makeRpcPage, } from './session-rpc.js';
+export { resolveHomeRoot, resolveProfileLocation, CONTROLLER_HOME_ENV, DEFAULT_HOME_DIRNAME, PROFILES_DIRNAME, } from './profile-location.js';
+export { startFixtureServer, } from './test-fixtures/fixture-server.js';
+export { FIXTURE_PAGES } from './test-fixtures/fixture-pages.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAaA,OAAO,EAAC,OAAO,EAAC,MAAM,WAAW,CAAC;AAElC,OAAO,EACN,gBAAgB,EAChB,kBAAkB,EAClB,sBAAsB,GAEtB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAC,aAAa,EAAgB,MAAM,qBAAqB,CAAC;AAEjE,OAAO,EAAC,yBAAyB,EAAC,MAAM,kCAAkC,CAAC;AAE3E,OAAO,EAAC,yBAAyB,EAAC,MAAM,kCAAkC,CAAC;AAE3E,OAAO,EACN,YAAY,EACZ,WAAW,GAIX,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACN,eAAe,EACf,yBAAyB,EACzB,mBAAmB,EACnB,sBAAsB,EACtB,oBAAoB,EACpB,iBAAiB,EACjB,yBAAyB,EACzB,iBAAiB,GAEjB,MAAM,aAAa,CAAC;AAErB,OAAO,EACN,0BAA0B,EAC1B,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,yBAAyB,GAEzB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACN,kBAAkB,EAClB,oBAAoB,GAGpB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAC,oBAAoB,EAAC,MAAM,qBAAqB,CAAC;AAEzD,OAAO,EACN,gBAAgB,EAChB,eAAe,EACf,WAAW,GAGX,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACN,eAAe,EACf,sBAAsB,EACtB,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,GAGhB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACN,kBAAkB,GAElB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAC,aAAa,EAAC,MAAM,kCAAkC,CAAC"}

package/dist/playwright-attach-transport.d.ts

@@ -0,0 +1,28 @@
+import type { OpenTarget, Session, Transport } from './seam.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 declare class PlaywrightAttachTransport implements Transport {
+    open(target: OpenTarget): Promise<Session>;
+}
+//# sourceMappingURL=playwright-attach-transport.d.ts.map

package/dist/playwright-attach-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playwright-attach-transport.d.ts","sourceRoot":"","sources":["../src/playwright-attach-transport.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAEX,UAAU,EAEV,OAAO,EAGP,SAAS,EAET,MAAM,WAAW,CAAC;AAEnB;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,yBAA0B,YAAW,SAAS;IACpD,IAAI,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC;CA0ChD"}