@webhands/core 0.2.0 → 0.3.0

package/README.md

@@ -97,6 +97,71 @@ deliberately local and single-session by design.
 In short: this is for reading and acting on web apps **you already have an account
 on**, from **your own browser**, the way you could by hand.
 
+## Optional: stealth launch (opt-in, default OFF)
+
+Standard Playwright drives Chromium over CDP and calls `Runtime.enable` at
+startup. That emits a side-effect a few lines of page JS can detect, and some
+anti-bot WAFs (Imperva/Cloudflare/DataDome) use it to serve an "Access Denied"
+block page *before the page even renders* — even on a real residential IP, even
+headed. `@webhands/core` can optionally launch via
+[Patchright](https://github.com/Kaliiiiiiiiii-Vinyzu/patchright) (an
+API-compatible Playwright fork that patches exactly these CDP leaks) to remove
+that one tell.
+
+This is **off by default** — vanilla Playwright stays the default. To enable it:
+
+1. Install the optional dependency (it is NOT pulled in unless you ask for it):
+
+   ```sh
+   pnpm add patchright
+   # if you do NOT pass --use-system-browser chrome, also fetch its browser:
+   #   pnpm exec patchright install chromium
+   ```
+
+2. Bring the session up with `--stealth`. The realistic recipe also drives your
+   installed system browser (`--use-system-browser chrome`), headed, against a
+   **warmed, logged-in profile**:
+
+   ```sh
+   # serve consumes these (it is where the browser is launched, ADR-0005):
+   npx webhands serve --headed --stealth --use-system-browser chrome
+   ```
+
+   `--use-system-browser` is independent of `--stealth`: you can drive real
+   Chrome with or without the Patchright path, and stealth with or without a
+   system browser. Other channel names work too (e.g. `msedge`).
+
+Programmatic equivalent (the `--stealth` / `--use-system-browser` flags map onto
+these transport options):
+
+```ts
+import {PlaywrightLaunchTransport} from '@webhands/core';
+
+const transport = new PlaywrightLaunchTransport(
+  {}, // profile location (omit for ~/.webhands)
+  [], // extra hands
+  {stealth: true, systemBrowser: 'chrome'},
+);
+// Stealth + headed + a real logged-in profile is the strongest recipe:
+const session = await transport.open({
+  mode: 'launch',
+  profile: 'default',
+  headed: true,
+});
+```
+
+If stealth is enabled but `patchright` is not installed, the open throws a typed
+`MissingStealthDependencyError` (the CLI prints `pnpm add patchright` as the fix).
+It **never silently falls back** to vanilla Playwright, because that would put
+the tell back without telling you.
+
+**Honest caveat.** Stealth addresses ONLY the CDP `Runtime.enable` automation
+tell. It is **necessary-but-not-sufficient**: IP reputation and session/profile
+reputation still matter. The realistic recipe is stealth +
+`systemBrowser: 'chrome'` + headed + a warmed, logged-in profile + a residential
+IP (see
+[`docs/adr/0002`](docs/adr/0002-real-session-over-fingerprint-spoofing.md)).
+
 ## Security note (the `serve` endpoint runs arbitrary code)
 
 The page verbs execute caller-supplied expressions: `eval` runs a JS expression

package/dist/errors.d.ts

@@ -15,7 +15,7 @@
  * 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';
+export type ControllerErrorCode = 'missing-browser-binary' | 'missing-stealth-dependency' | '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}.
  *
@@ -45,6 +45,29 @@ export declare class MissingBrowserBinaryError extends ControllerError {
         cause?: unknown;
     });
 }
+/**
+ * Stealth launch was REQUESTED (the opt-in is on) but the optional `patchright`
+ * dependency is not installed/importable. Patchright is an OPTIONAL dependency
+ * of `@webhands/core` imported lazily only when stealth is enabled, so a user
+ * who never opts in is not forced to install it (ADR-0002: stealth is one extra
+ * layer, not the default). When it IS opted into and missing, we refuse LOUDLY
+ * with this typed condition rather than silently falling back to vanilla
+ * Playwright, because a silent fallback would re-introduce the exact CDP
+ * automation tell the user asked us to remove WITHOUT telling them.
+ *
+ * Mirrors {@link MissingBrowserBinaryError}: a stable typed error whose brittle
+ * detection (the dynamic-import failure) is confined to one spot in the launch
+ * transport. The CLI can render the exact `pnpm add patchright` fix command by
+ * branching on {@link code}.
+ */
+export declare class MissingStealthDependencyError extends ControllerError {
+    readonly code = "missing-stealth-dependency";
+    /** The optional package that must be installed to use stealth. */
+    readonly dependency: string;
+    constructor(dependency?: 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`

package/dist/errors.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,8DAA8D;AAC9D,MAAM,MAAM,mBAAmB,GAC5B,wBAAwB,GACxB,4BAA4B,GAC5B,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;;;;;;;;;;;;;;GAcG;AACH,qBAAa,6BAA8B,SAAQ,eAAe;IACjE,QAAQ,CAAC,IAAI,gCAAgC;IAC7C,kEAAkE;IAClE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAG3B,UAAU,SAAe,EACzB,OAAO,GAAE,MAA+Q,EACxR,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

@@ -45,6 +45,30 @@ export class MissingBrowserBinaryError extends ControllerError {
         this.browser = browser;
     }
 }
+/**
+ * Stealth launch was REQUESTED (the opt-in is on) but the optional `patchright`
+ * dependency is not installed/importable. Patchright is an OPTIONAL dependency
+ * of `@webhands/core` imported lazily only when stealth is enabled, so a user
+ * who never opts in is not forced to install it (ADR-0002: stealth is one extra
+ * layer, not the default). When it IS opted into and missing, we refuse LOUDLY
+ * with this typed condition rather than silently falling back to vanilla
+ * Playwright, because a silent fallback would re-introduce the exact CDP
+ * automation tell the user asked us to remove WITHOUT telling them.
+ *
+ * Mirrors {@link MissingBrowserBinaryError}: a stable typed error whose brittle
+ * detection (the dynamic-import failure) is confined to one spot in the launch
+ * transport. The CLI can render the exact `pnpm add patchright` fix command by
+ * branching on {@link code}.
+ */
+export class MissingStealthDependencyError extends ControllerError {
+    code = 'missing-stealth-dependency';
+    /** The optional package that must be installed to use stealth. */
+    dependency;
+    constructor(dependency = 'patchright', message = `Stealth launch is enabled but the optional "${dependency}" dependency is not installed. Install it with \`pnpm add ${dependency}\` (and \`${dependency} install chromium\` if you do not use channel: 'chrome'), or construct the transport without {stealth: true}.`, options) {
+        super(message, options);
+        this.dependency = dependency;
+    }
+}
 /**
  * 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`

package/dist/errors.js.map

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

package/dist/index.d.ts

@@ -4,10 +4,10 @@ export { serializeCookies, deserializeCookies, COOKIES_EXPORT_VERSION, type Cook
 export { StubTransport, type StubCall } from './stub-transport.js';
 export type { Hand, HandContext, HandContribution } from './hand-host.js';
 export { readHandsConfig, normalizeConfig, loadHands, HandLoadError, HANDS_CONFIG_FILENAME, type HandEntry, type HandsConfig, type LoadedHand, type LoadHandsOptions, } from './hand-loading.js';
-export { PlaywrightLaunchTransport } from './playwright-launch-transport.js';
+export { PlaywrightLaunchTransport, type PlaywrightLaunchTransportOptions, type StealthChromiumImporter, } 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 { ControllerError, MissingBrowserBinaryError, MissingStealthDependencyError, 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';

package/dist/index.d.ts.map

@@ -1 +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,YAAY,EACZ,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,YAAY,EAAC,IAAI,EAAE,WAAW,EAAE,gBAAgB,EAAC,MAAM,gBAAgB,CAAC;AAExE,OAAO,EACN,eAAe,EACf,eAAe,EACf,SAAS,EACT,aAAa,EACb,qBAAqB,EACrB,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,gBAAgB,GACrB,MAAM,mBAAmB,CAAC;AAE3B,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,YAAY,EACZ,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,qBAAqB,EAC1B,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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACX,MAAM,EACN,MAAM,EACN,aAAa,EACb,UAAU,EACV,YAAY,EACZ,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,YAAY,EAAC,IAAI,EAAE,WAAW,EAAE,gBAAgB,EAAC,MAAM,gBAAgB,CAAC;AAExE,OAAO,EACN,eAAe,EACf,eAAe,EACf,SAAS,EACT,aAAa,EACb,qBAAqB,EACrB,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,gBAAgB,GACrB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACN,yBAAyB,EACzB,KAAK,gCAAgC,EACrC,KAAK,uBAAuB,GAC5B,MAAM,kCAAkC,CAAC;AAE1C,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,6BAA6B,EAC7B,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,YAAY,EACZ,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,qBAAqB,EAC1B,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

@@ -2,10 +2,10 @@ export { locator } from './seam.js';
 export { serializeCookies, deserializeCookies, COOKIES_EXPORT_VERSION, } from './cookies-export.js';
 export { StubTransport } from './stub-transport.js';
 export { readHandsConfig, normalizeConfig, loadHands, HandLoadError, HANDS_CONFIG_FILENAME, } from './hand-loading.js';
-export { PlaywrightLaunchTransport } from './playwright-launch-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 { ControllerError, MissingBrowserBinaryError, MissingStealthDependencyError, 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';

package/dist/index.js.map

@@ -1 +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;AAIjE,OAAO,EACN,eAAe,EACf,eAAe,EACf,SAAS,EACT,aAAa,EACb,qBAAqB,GAKrB,MAAM,mBAAmB,CAAC;AAE3B,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,EACX,YAAY,GAKZ,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"}
+{"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;AAIjE,OAAO,EACN,eAAe,EACf,eAAe,EACf,SAAS,EACT,aAAa,EACb,qBAAqB,GAKrB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACN,yBAAyB,GAGzB,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EAAC,yBAAyB,EAAC,MAAM,kCAAkC,CAAC;AAE3E,OAAO,EACN,YAAY,EACZ,WAAW,GAIX,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACN,eAAe,EACf,yBAAyB,EACzB,6BAA6B,EAC7B,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,EACX,YAAY,GAKZ,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-launch-transport.d.ts

@@ -1,6 +1,68 @@
+import { chromium } from 'playwright';
 import { type Hand } from './hand-host.js';
 import { type ProfileLocationOptions } from './profile-location.js';
 import type { OpenTarget, Session, Transport } from './seam.js';
+/**
+ * The subset of Playwright's `chromium` browser type the launch transport uses.
+ *
+ * Patchright is an API-compatible Playwright fork, so its `chromium` has the
+ * SAME shape (ADR-0003 stays intact: this structural type, like Playwright's
+ * own types, is confined to this module and never crosses the seam). We type the
+ * lazily-imported stealth chromium against THIS rather than importing any
+ * Patchright type, so the dependency stays optional at the type level too.
+ */
+type ChromiumLauncher = Pick<typeof chromium, 'launchPersistentContext'>;
+/** The shape `await import('patchright')` is expected to expose. */
+interface StealthModule {
+    readonly chromium: ChromiumLauncher;
+}
+/**
+ * How the transport obtains the stealth (`patchright`) chromium. This is an
+ * INTERNAL test seam, not a public API: tests inject a fake module (or a
+ * rejecting importer) here so no real browser/Patchright is needed, exactly as
+ * production uses the default lazy `import('patchright')`. It is deliberately
+ * NOT on {@link OpenTarget} (ADR-0003: the seam stays free of Playwright/CDP/
+ * Patchright concerns).
+ */
+export type StealthChromiumImporter = () => Promise<StealthModule>;
+/**
+ * Construction-time policy for {@link PlaywrightLaunchTransport}.
+ *
+ * Stealth is a TRANSPORT-CONSTRUCTION policy (which browser engine + launch
+ * flags to use), not a per-open target detail, so it lives here and NOT on
+ * {@link OpenTarget} (which stays Playwright/CDP-free per ADR-0003).
+ */
+export interface PlaywrightLaunchTransportOptions {
+    /**
+     * Opt-in Patchright-backed stealth launch. Default `false` (vanilla
+     * Playwright). When `true`, the transport launches via the lazily-imported
+     * optional `patchright` package, which patches the CDP `Runtime.enable`
+     * automation tell that anti-bot WAFs detect (ADR-0002 keeps this as one extra
+     * layer, not a replacement for a real profile/IP). If `patchright` is not
+     * installed it throws {@link MissingStealthDependencyError}; it NEVER silently
+     * falls back to vanilla.
+     */
+    readonly stealth?: boolean;
+    /**
+     * Drive a browser ALREADY INSTALLED ON THE SYSTEM instead of the bundled
+     * Chromium, named by its install identity (e.g. `'chrome'` to drive the system
+     * Google Chrome, Patchright's recommended setup; also `'msedge'`,
+     * `'chrome-beta'`, ...). Applies to BOTH stealth and vanilla launches when set.
+     * When omitted, Playwright/Patchright's bundled Chromium is used.
+     *
+     * Maps to Playwright's `channel` launch option internally; we name it
+     * `systemBrowser` so the public surface speaks domain language ("use a browser
+     * I already have installed") rather than the Playwright term (ADR-0003 keeps
+     * Playwright vocabulary out of the public surface).
+     */
+    readonly systemBrowser?: string;
+    /**
+     * INTERNAL test seam: override how the stealth chromium is imported. Omit in
+     * production (defaults to `import('patchright')`). See
+     * {@link StealthChromiumImporter}.
+     */
+    readonly importStealthChromium?: StealthChromiumImporter;
+}
 /**
  * The v1 concrete transport: a Playwright browser the controller LAUNCHES
  * against a dedicated, persistent profile directory it owns (PRD "Solution,
@@ -17,6 +79,13 @@ import type { OpenTarget, Session, Transport } from './seam.js';
  * `WEBHANDS_HOME` env var, or `~/.webhands`). See
  * {@link resolveProfileLocation}. Because that is a SHARED location, tests pass
  * a temp `root` (or set the env var) and assert the real home is untouched.
+ *
+ * STEALTH (opt-in, default OFF): the third constructor arg can enable a
+ * Patchright-backed launch ({@link PlaywrightLaunchTransportOptions}). Patchright
+ * is an OPTIONAL dependency imported lazily only when stealth is enabled; if it
+ * is absent the transport throws {@link MissingStealthDependencyError} rather
+ * than falling back to vanilla. This addresses ONLY the CDP `Runtime.enable`
+ * automation tell; a real profile/IP/session reputation still matter (ADR-0002).
  */
 export declare class PlaywrightLaunchTransport implements Transport {
     #private;
@@ -28,8 +97,13 @@ export declare class PlaywrightLaunchTransport implements Transport {
      *   built-ins (Phase 2, ADR-0007). These come from {@link loadHands} against
      *   the operator's explicit config; the transport does NOT discover them. Omit
      *   for the built-ins-only surface.
+     * @param options transport-construction policy, notably the opt-in `stealth`
+     *   toggle and optional `systemBrowser` (see
+     *   {@link PlaywrightLaunchTransportOptions}). Defaults to vanilla Playwright,
+     *   bundled Chromium, stealth OFF.
      */
-    constructor(location?: ProfileLocationOptions, hands?: readonly Hand[]);
+    constructor(location?: ProfileLocationOptions, hands?: readonly Hand[], options?: PlaywrightLaunchTransportOptions);
     open(target: OpenTarget): Promise<Session>;
 }
+export {};
 //# sourceMappingURL=playwright-launch-transport.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"playwright-launch-transport.d.ts","sourceRoot":"","sources":["../src/playwright-launch-transport.ts"],"names":[],"mappings":"AAGA,OAAO,EAAmB,KAAK,IAAI,EAAmB,MAAM,gBAAgB,CAAC;AAC7E,OAAO,EAEN,KAAK,sBAAsB,EAC3B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAC,UAAU,EAAE,OAAO,EAAE,SAAS,EAAC,MAAM,WAAW,CAAC;AAE9D;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,yBAA0B,YAAW,SAAS;;IAI1D;;;;;;;;OAQG;gBAEF,QAAQ,GAAE,sBAA2B,EACrC,KAAK,GAAE,SAAS,IAAI,EAAO;IAMtB,IAAI,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC;CAwChD"}
+{"version":3,"file":"playwright-launch-transport.d.ts","sourceRoot":"","sources":["../src/playwright-launch-transport.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,QAAQ,EAAiC,MAAM,YAAY,CAAC;AAMpE,OAAO,EAAmB,KAAK,IAAI,EAAmB,MAAM,gBAAgB,CAAC;AAC7E,OAAO,EAEN,KAAK,sBAAsB,EAC3B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAC,UAAU,EAAE,OAAO,EAAE,SAAS,EAAC,MAAM,WAAW,CAAC;AAE9D;;;;;;;;GAQG;AACH,KAAK,gBAAgB,GAAG,IAAI,CAAC,OAAO,QAAQ,EAAE,yBAAyB,CAAC,CAAC;AAEzE,oEAAoE;AACpE,UAAU,aAAa;IACtB,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;CACpC;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,uBAAuB,GAAG,MAAM,OAAO,CAAC,aAAa,CAAC,CAAC;AAEnE;;;;;;GAMG;AACH,MAAM,WAAW,gCAAgC;IAChD;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,qBAAqB,CAAC,EAAE,uBAAuB,CAAC;CACzD;AAmBD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,yBAA0B,YAAW,SAAS;;IAO1D;;;;;;;;;;;;OAYG;gBAEF,QAAQ,GAAE,sBAA2B,EACrC,KAAK,GAAE,SAAS,IAAI,EAAO,EAC3B,OAAO,GAAE,gCAAqC;IAUzC,IAAI,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC;CA8FhD"}

package/dist/playwright-launch-transport.js

@@ -1,8 +1,23 @@
 import { stat } from 'node:fs/promises';
 import { chromium } from 'playwright';
-import { MissingBrowserBinaryError, MissingProfileError } from './errors.js';
+import { MissingBrowserBinaryError, MissingProfileError, MissingStealthDependencyError, } from './errors.js';
 import { composeWithHands } from './hand-host.js';
 import { resolveProfileLocation, } from './profile-location.js';
+/**
+ * The package name of the optional stealth dependency. Kept as a runtime value
+ * (not an `import('patchright')` literal) so TypeScript does NOT try to resolve
+ * its types at build time, since it is an OPTIONAL dependency that is legitimately
+ * absent when stealth is never enabled.
+ */
+const STEALTH_PACKAGE = 'patchright';
+/** The default lazy import of the OPTIONAL `patchright` dependency. */
+const defaultStealthImporter = async () => {
+    // Indirect (non-literal specifier) so tsc/bundlers do not resolve the
+    // optional dep eagerly, and the module load never fails when it is absent;
+    // the import only runs when stealth is opted in.
+    const specifier = STEALTH_PACKAGE;
+    return (await import(specifier));
+};
 /**
  * The v1 concrete transport: a Playwright browser the controller LAUNCHES
  * against a dedicated, persistent profile directory it owns (PRD "Solution,
@@ -19,10 +34,20 @@ import { resolveProfileLocation, } from './profile-location.js';
  * `WEBHANDS_HOME` env var, or `~/.webhands`). See
  * {@link resolveProfileLocation}. Because that is a SHARED location, tests pass
  * a temp `root` (or set the env var) and assert the real home is untouched.
+ *
+ * STEALTH (opt-in, default OFF): the third constructor arg can enable a
+ * Patchright-backed launch ({@link PlaywrightLaunchTransportOptions}). Patchright
+ * is an OPTIONAL dependency imported lazily only when stealth is enabled; if it
+ * is absent the transport throws {@link MissingStealthDependencyError} rather
+ * than falling back to vanilla. This addresses ONLY the CDP `Runtime.enable`
+ * automation tell; a real profile/IP/session reputation still matter (ADR-0002).
  */
 export class PlaywrightLaunchTransport {
     #location;
     #hands;
+    #stealth;
+    #systemBrowser;
+    #importStealthChromium;
     /**
      * @param location overrides for where profiles live (a `root` dir and/or an
      *   `env`). Omit in production to use `~/.webhands`; pass a temp
@@ -31,10 +56,18 @@ export class PlaywrightLaunchTransport {
      *   built-ins (Phase 2, ADR-0007). These come from {@link loadHands} against
      *   the operator's explicit config; the transport does NOT discover them. Omit
      *   for the built-ins-only surface.
+     * @param options transport-construction policy, notably the opt-in `stealth`
+     *   toggle and optional `systemBrowser` (see
+     *   {@link PlaywrightLaunchTransportOptions}). Defaults to vanilla Playwright,
+     *   bundled Chromium, stealth OFF.
      */
-    constructor(location = {}, hands = []) {
+    constructor(location = {}, hands = [], options = {}) {
         this.#location = location;
         this.#hands = hands;
+        this.#stealth = options.stealth === true;
+        this.#systemBrowser = options.systemBrowser;
+        this.#importStealthChromium =
+            options.importStealthChromium ?? defaultStealthImporter;
     }
     async open(target) {
         if (target.mode !== 'launch') {
@@ -52,15 +85,35 @@ export class PlaywrightLaunchTransport {
             throw new MissingProfileError(loc.profile, loc.profileDir);
         }
         const headless = target.headed !== true;
+        // Pick the engine: the lazily-imported stealth (Patchright) chromium when
+        // opted in, else vanilla Playwright's. Resolving the stealth module is where
+        // an absent optional dependency surfaces as the typed
+        // MissingStealthDependencyError (we never fall back to vanilla silently).
+        const launcher = this.#stealth
+            ? await this.#resolveStealthLauncher()
+            : chromium;
+        // Launch options: forward headless, the optional systemBrowser (Playwright's
+        // `channel`, e.g. 'chrome' to drive system Chrome, Patchright's recommended
+        // setup), and for stealth drop Playwright's automation-flavoured default
+        // args so they cannot re-add the fingerprint Patchright just removed.
+        const launchOptions = { headless };
+        if (this.#systemBrowser !== undefined) {
+            launchOptions.channel = this.#systemBrowser;
+        }
+        if (this.#stealth) {
+            launchOptions.ignoreDefaultArgs = ['--enable-automation'];
+        }
         let context;
         try {
-            context = await chromium.launchPersistentContext(loc.profileDir, {
-                headless,
-            });
+            context = await launcher.launchPersistentContext(loc.profileDir, launchOptions);
         }
         catch (cause) {
             if (isMissingBrowserBinary(cause)) {
-                throw new MissingBrowserBinaryError('chromium', undefined, { cause });
+                // With systemBrowser set (e.g. 'chrome') the "binary missing" failure
+                // means the SYSTEM browser is absent, not the bundled Chromium; name
+                // what is actually missing so the CLI's fix message is accurate.
+                const browser = this.#systemBrowser ?? 'chromium';
+                throw new MissingBrowserBinaryError(browser, undefined, { cause });
             }
             throw cause;
         }
@@ -70,6 +123,31 @@ export class PlaywrightLaunchTransport {
         const pwPage = context.pages()[0] ?? (await context.newPage());
         return makeSession(context, pwPage, this.#hands);
     }
+    /**
+     * Resolve the stealth (`patchright`) chromium via the injected lazy importer.
+     *
+     * Confines the brittle "optional dependency absent" detection to ONE spot
+     * (mirroring {@link isMissingBrowserBinary}): any failure to import the
+     * optional package becomes the typed {@link MissingStealthDependencyError}, so
+     * the caller never silently degrades to vanilla Playwright.
+     */
+    async #resolveStealthLauncher() {
+        let mod;
+        try {
+            mod = await this.#importStealthChromium();
+        }
+        catch (cause) {
+            throw new MissingStealthDependencyError('patchright', undefined, {
+                cause,
+            });
+        }
+        if (mod === null ||
+            typeof mod !== 'object' ||
+            typeof mod.chromium?.launchPersistentContext !== 'function') {
+            throw new MissingStealthDependencyError('patchright');
+        }
+        return mod.chromium;
+    }
 }
 /** True iff `path` exists and is a directory. */
 async function isExistingDirectory(path) {
@@ -86,12 +164,20 @@ async function isExistingDirectory(path) {
  * does not export a typed error for this, so we detect on the message (it
  * instructs the user to run `playwright install`). We confine that brittle
  * string match to this one spot and re-raise as a stable typed error.
+ *
+ * This also covers the `channel: 'chrome'` case, where the missing binary is the
+ * SYSTEM Chrome, not the bundled Chromium. Playwright phrases that as the
+ * channel/distribution not being found; we match those variants too so the
+ * stealth+system-Chrome path still yields the typed MissingBrowserBinaryError.
  */
 function isMissingBrowserBinary(cause) {
     const message = cause instanceof Error ? cause.message : String(cause ?? '');
     return (/Executable doesn't exist/i.test(message) ||
         /please run the following command to download new browsers/i.test(message) ||
-        /playwright install/i.test(message));
+        /playwright install/i.test(message) ||
+        // channel: 'chrome' (or other system channels) not installed on the host.
+        /Chromium distribution '.*' is not found/i.test(message) ||
+        /No "?(chrome|msedge|chromium)"? .* found/i.test(message));
 }
 /**
  * Wrap a live Playwright persistent context into the seam's {@link Session}.

package/dist/playwright-launch-transport.js.map

@@ -1 +1 @@
-{"version":3,"file":"playwright-launch-transport.js","sourceRoot":"","sources":["../src/playwright-launch-transport.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"playwright-launch-transport.js","sourceRoot":"","sources":["../src/playwright-launch-transport.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,IAAI,EAAC,MAAM,kBAAkB,CAAC;AACtC,OAAO,EAAC,QAAQ,EAAiC,MAAM,YAAY,CAAC;AACpE,OAAO,EACN,yBAAyB,EACzB,mBAAmB,EACnB,6BAA6B,GAC7B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAC,gBAAgB,EAA8B,MAAM,gBAAgB,CAAC;AAC7E,OAAO,EACN,sBAAsB,GAEtB,MAAM,uBAAuB,CAAC;AAoE/B;;;;;GAKG;AACH,MAAM,eAAe,GAAG,YAAY,CAAC;AAErC,uEAAuE;AACvE,MAAM,sBAAsB,GAA4B,KAAK,IAAI,EAAE;IAClE,sEAAsE;IACtE,2EAA2E;IAC3E,iDAAiD;IACjD,MAAM,SAAS,GAAG,eAAe,CAAC;IAClC,OAAO,CAAC,MAAM,MAAM,CAAC,SAAS,CAAC,CAA6B,CAAC;AAC9D,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,OAAO,yBAAyB;IAC5B,SAAS,CAAyB;IAClC,MAAM,CAAkB;IACxB,QAAQ,CAAU;IAClB,cAAc,CAAqB;IACnC,sBAAsB,CAA0B;IAEzD;;;;;;;;;;;;OAYG;IACH,YACC,WAAmC,EAAE,EACrC,QAAyB,EAAE,EAC3B,UAA4C,EAAE;QAE9C,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;QAC1B,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;QACpB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,OAAO,KAAK,IAAI,CAAC;QACzC,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;QAC5C,IAAI,CAAC,sBAAsB;YAC1B,OAAO,CAAC,qBAAqB,IAAI,sBAAsB,CAAC;IAC1D,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,MAAkB;QAC5B,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CACd,mDAAmD;gBAClD,IAAI,MAAM,CAAC,IAAI,qCAAqC,CACrD,CAAC;QACH,CAAC;QAED,MAAM,GAAG,GAAG,sBAAsB,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QAEnE,0EAA0E;QAC1E,oEAAoE;QACpE,wEAAwE;QACxE,0EAA0E;QAC1E,wEAAwE;QACxE,WAAW;QACX,IAAI,CAAC,CAAC,MAAM,mBAAmB,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC;YAClD,MAAM,IAAI,mBAAmB,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC;QAC5D,CAAC;QAED,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,KAAK,IAAI,CAAC;QAExC,0EAA0E;QAC1E,6EAA6E;QAC7E,sDAAsD;QACtD,0EAA0E;QAC1E,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ;YAC7B,CAAC,CAAC,MAAM,IAAI,CAAC,uBAAuB,EAAE;YACtC,CAAC,CAAC,QAAQ,CAAC;QAEZ,6EAA6E;QAC7E,4EAA4E;QAC5E,yEAAyE;QACzE,sEAAsE;QACtE,MAAM,aAAa,GAEZ,EAAC,QAAQ,EAAC,CAAC;QAClB,IAAI,IAAI,CAAC,cAAc,KAAK,SAAS,EAAE,CAAC;YACvC,aAAa,CAAC,OAAO,GAAG,IAAI,CAAC,cAAc,CAAC;QAC7C,CAAC;QACD,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnB,aAAa,CAAC,iBAAiB,GAAG,CAAC,qBAAqB,CAAC,CAAC;QAC3D,CAAC;QAED,IAAI,OAAuB,CAAC;QAC5B,IAAI,CAAC;YACJ,OAAO,GAAG,MAAM,QAAQ,CAAC,uBAAuB,CAC/C,GAAG,CAAC,UAAU,EACd,aAAa,CACb,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,IAAI,sBAAsB,CAAC,KAAK,CAAC,EAAE,CAAC;gBACnC,sEAAsE;gBACtE,qEAAqE;gBACrE,iEAAiE;gBACjE,MAAM,OAAO,GAAG,IAAI,CAAC,cAAc,IAAI,UAAU,CAAC;gBAClD,MAAM,IAAI,yBAAyB,CAAC,OAAO,EAAE,SAAS,EAAE,EAAC,KAAK,EAAC,CAAC,CAAC;YAClE,CAAC;YACD,MAAM,KAAK,CAAC;QACb,CAAC;QAED,0EAA0E;QAC1E,2EAA2E;QAC3E,yCAAyC;QACzC,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;QAC/D,OAAO,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IAClD,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,uBAAuB;QAC5B,IAAI,GAAkB,CAAC;QACvB,IAAI,CAAC;YACJ,GAAG,GAAG,MAAM,IAAI,CAAC,sBAAsB,EAAE,CAAC;QAC3C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,MAAM,IAAI,6BAA6B,CAAC,YAAY,EAAE,SAAS,EAAE;gBAChE,KAAK;aACL,CAAC,CAAC;QACJ,CAAC;QACD,IACC,GAAG,KAAK,IAAI;YACZ,OAAO,GAAG,KAAK,QAAQ;YACvB,OAAO,GAAG,CAAC,QAAQ,EAAE,uBAAuB,KAAK,UAAU,EAC1D,CAAC;YACF,MAAM,IAAI,6BAA6B,CAAC,YAAY,CAAC,CAAC;QACvD,CAAC;QACD,OAAO,GAAG,CAAC,QAAQ,CAAC;IACrB,CAAC;CACD;AAED,iDAAiD;AACjD,KAAK,UAAU,mBAAmB,CAAC,IAAY;IAC9C,IAAI,CAAC;QACJ,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC;QAC3B,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC;IACxB,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,KAAK,CAAC;IACd,CAAC;AACF,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAS,sBAAsB,CAAC,KAAc;IAC7C,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;IAC7E,OAAO,CACN,2BAA2B,CAAC,IAAI,CAAC,OAAO,CAAC;QACzC,4DAA4D,CAAC,IAAI,CAChE,OAAO,CACP;QACD,qBAAqB,CAAC,IAAI,CAAC,OAAO,CAAC;QACnC,0EAA0E;QAC1E,0CAA0C,CAAC,IAAI,CAAC,OAAO,CAAC;QACxD,2CAA2C,CAAC,IAAI,CAAC,OAAO,CAAC,CACzD,CAAC;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAS,WAAW,CACnB,OAAuB,EACvB,MAAY,EACZ,UAA2B;IAE3B,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,MAAM,UAAU,GAAG,GAAG,EAAE;QACvB,IAAI,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC;QACtC,CAAC;IACF,CAAC,CAAC;IAEF,4EAA4E;IAC5E,yEAAyE;IACzE,yEAAyE;IACzE,mDAAmD;IACnD,IAAI,aAA0B,CAAC;IAC/B,MAAM,YAAY,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QAClD,aAAa,GAAG,OAAO,CAAC;IACzB,CAAC,CAAC,CAAC;IACH,MAAM,UAAU,GAAG,GAAG,EAAE;QACvB,IAAI,MAAM;YAAE,OAAO;QACnB,MAAM,GAAG,IAAI,CAAC;QACd,aAAa,EAAE,CAAC;IACjB,CAAC,CAAC;IACF,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IAEhC,2EAA2E;IAC3E,8EAA8E;IAC9E,mEAAmE;IACnE,MAAM,WAAW,GAAgB,EAAC,MAAM,EAAE,OAAO,EAAE,UAAU,EAAC,CAAC;IAC/D,MAAM,EAAC,IAAI,EAAE,OAAO,EAAE,YAAY,EAAC,GAAG,gBAAgB,CACrD,WAAW,EACX,UAAU,CACV,CAAC;IAEF,OAAO;QACN,IAAI;QACJ,KAAK,CAAC,KAAK;YACV,IAAI,MAAM,EAAE,CAAC;gBACZ,OAAO;YACR,CAAC;YACD,uEAAuE;YACvE,mEAAmE;YACnE,2DAA2D;YAC3D,MAAM,YAAY,EAAE,CAAC;YACrB,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC;YACtB,UAAU,EAAE,CAAC;QACd,CAAC;QACD,YAAY;YACX,OAAO,YAAY,CAAC;QACrB,CAAC;KACD,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webhands/core",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Core library for webhands: drives a real, persistent browser via Playwright.",
   "keywords": [
     "browser",
@@ -37,6 +37,9 @@
   "dependencies": {
     "playwright": "1.61.1"
   },
+  "optionalDependencies": {
+    "patchright": "1.61.1"
+  },
   "devDependencies": {
     "@types/node": "^25.2.0",
     "as-soon": "^0.1.5",

package/src/errors.ts

@@ -18,6 +18,7 @@
 /** The closed set of identifiable `core` error conditions. */
 export type ControllerErrorCode =
 	| 'missing-browser-binary'
+	| 'missing-stealth-dependency'
 	| 'missing-profile'
 	| 'attach-not-chromium'
 	| 'attach-no-context'
@@ -65,6 +66,36 @@ export class MissingBrowserBinaryError extends ControllerError {
 	}
 }
 
+/**
+ * Stealth launch was REQUESTED (the opt-in is on) but the optional `patchright`
+ * dependency is not installed/importable. Patchright is an OPTIONAL dependency
+ * of `@webhands/core` imported lazily only when stealth is enabled, so a user
+ * who never opts in is not forced to install it (ADR-0002: stealth is one extra
+ * layer, not the default). When it IS opted into and missing, we refuse LOUDLY
+ * with this typed condition rather than silently falling back to vanilla
+ * Playwright, because a silent fallback would re-introduce the exact CDP
+ * automation tell the user asked us to remove WITHOUT telling them.
+ *
+ * Mirrors {@link MissingBrowserBinaryError}: a stable typed error whose brittle
+ * detection (the dynamic-import failure) is confined to one spot in the launch
+ * transport. The CLI can render the exact `pnpm add patchright` fix command by
+ * branching on {@link code}.
+ */
+export class MissingStealthDependencyError extends ControllerError {
+	readonly code = 'missing-stealth-dependency';
+	/** The optional package that must be installed to use stealth. */
+	readonly dependency: string;
+
+	constructor(
+		dependency = 'patchright',
+		message: string = `Stealth launch is enabled but the optional "${dependency}" dependency is not installed. Install it with \`pnpm add ${dependency}\` (and \`${dependency} install chromium\` if you do not use channel: 'chrome'), or construct the transport without {stealth: true}.`,
+		options?: {cause?: unknown},
+	) {
+		super(message, options);
+		this.dependency = dependency;
+	}
+}
+
 /**
  * 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`

package/src/index.ts

@@ -36,7 +36,11 @@ export {
 	type LoadHandsOptions,
 } from './hand-loading.js';
 
-export {PlaywrightLaunchTransport} from './playwright-launch-transport.js';
+export {
+	PlaywrightLaunchTransport,
+	type PlaywrightLaunchTransportOptions,
+	type StealthChromiumImporter,
+} from './playwright-launch-transport.js';
 
 export {PlaywrightAttachTransport} from './playwright-attach-transport.js';
 
@@ -51,6 +55,7 @@ export {
 export {
 	ControllerError,
 	MissingBrowserBinaryError,
+	MissingStealthDependencyError,
 	MissingProfileError,
 	AttachNotChromiumError,
 	AttachNoContextError,

package/src/playwright-launch-transport.ts

@@ -1,6 +1,10 @@
 import {stat} from 'node:fs/promises';
 import {chromium, type BrowserContext, type Page} from 'playwright';
-import {MissingBrowserBinaryError, MissingProfileError} from './errors.js';
+import {
+	MissingBrowserBinaryError,
+	MissingProfileError,
+	MissingStealthDependencyError,
+} from './errors.js';
 import {composeWithHands, type Hand, type HandContext} from './hand-host.js';
 import {
 	resolveProfileLocation,
@@ -8,6 +12,88 @@ import {
 } from './profile-location.js';
 import type {OpenTarget, Session, Transport} from './seam.js';
 
+/**
+ * The subset of Playwright's `chromium` browser type the launch transport uses.
+ *
+ * Patchright is an API-compatible Playwright fork, so its `chromium` has the
+ * SAME shape (ADR-0003 stays intact: this structural type, like Playwright's
+ * own types, is confined to this module and never crosses the seam). We type the
+ * lazily-imported stealth chromium against THIS rather than importing any
+ * Patchright type, so the dependency stays optional at the type level too.
+ */
+type ChromiumLauncher = Pick<typeof chromium, 'launchPersistentContext'>;
+
+/** The shape `await import('patchright')` is expected to expose. */
+interface StealthModule {
+	readonly chromium: ChromiumLauncher;
+}
+
+/**
+ * How the transport obtains the stealth (`patchright`) chromium. This is an
+ * INTERNAL test seam, not a public API: tests inject a fake module (or a
+ * rejecting importer) here so no real browser/Patchright is needed, exactly as
+ * production uses the default lazy `import('patchright')`. It is deliberately
+ * NOT on {@link OpenTarget} (ADR-0003: the seam stays free of Playwright/CDP/
+ * Patchright concerns).
+ */
+export type StealthChromiumImporter = () => Promise<StealthModule>;
+
+/**
+ * Construction-time policy for {@link PlaywrightLaunchTransport}.
+ *
+ * Stealth is a TRANSPORT-CONSTRUCTION policy (which browser engine + launch
+ * flags to use), not a per-open target detail, so it lives here and NOT on
+ * {@link OpenTarget} (which stays Playwright/CDP-free per ADR-0003).
+ */
+export interface PlaywrightLaunchTransportOptions {
+	/**
+	 * Opt-in Patchright-backed stealth launch. Default `false` (vanilla
+	 * Playwright). When `true`, the transport launches via the lazily-imported
+	 * optional `patchright` package, which patches the CDP `Runtime.enable`
+	 * automation tell that anti-bot WAFs detect (ADR-0002 keeps this as one extra
+	 * layer, not a replacement for a real profile/IP). If `patchright` is not
+	 * installed it throws {@link MissingStealthDependencyError}; it NEVER silently
+	 * falls back to vanilla.
+	 */
+	readonly stealth?: boolean;
+	/**
+	 * Drive a browser ALREADY INSTALLED ON THE SYSTEM instead of the bundled
+	 * Chromium, named by its install identity (e.g. `'chrome'` to drive the system
+	 * Google Chrome, Patchright's recommended setup; also `'msedge'`,
+	 * `'chrome-beta'`, ...). Applies to BOTH stealth and vanilla launches when set.
+	 * When omitted, Playwright/Patchright's bundled Chromium is used.
+	 *
+	 * Maps to Playwright's `channel` launch option internally; we name it
+	 * `systemBrowser` so the public surface speaks domain language ("use a browser
+	 * I already have installed") rather than the Playwright term (ADR-0003 keeps
+	 * Playwright vocabulary out of the public surface).
+	 */
+	readonly systemBrowser?: string;
+	/**
+	 * INTERNAL test seam: override how the stealth chromium is imported. Omit in
+	 * production (defaults to `import('patchright')`). See
+	 * {@link StealthChromiumImporter}.
+	 */
+	readonly importStealthChromium?: StealthChromiumImporter;
+}
+
+/**
+ * The package name of the optional stealth dependency. Kept as a runtime value
+ * (not an `import('patchright')` literal) so TypeScript does NOT try to resolve
+ * its types at build time, since it is an OPTIONAL dependency that is legitimately
+ * absent when stealth is never enabled.
+ */
+const STEALTH_PACKAGE = 'patchright';
+
+/** The default lazy import of the OPTIONAL `patchright` dependency. */
+const defaultStealthImporter: StealthChromiumImporter = async () => {
+	// Indirect (non-literal specifier) so tsc/bundlers do not resolve the
+	// optional dep eagerly, and the module load never fails when it is absent;
+	// the import only runs when stealth is opted in.
+	const specifier = STEALTH_PACKAGE;
+	return (await import(specifier)) as unknown as StealthModule;
+};
+
 /**
  * The v1 concrete transport: a Playwright browser the controller LAUNCHES
  * against a dedicated, persistent profile directory it owns (PRD "Solution,
@@ -24,10 +110,20 @@ import type {OpenTarget, Session, Transport} from './seam.js';
  * `WEBHANDS_HOME` env var, or `~/.webhands`). See
  * {@link resolveProfileLocation}. Because that is a SHARED location, tests pass
  * a temp `root` (or set the env var) and assert the real home is untouched.
+ *
+ * STEALTH (opt-in, default OFF): the third constructor arg can enable a
+ * Patchright-backed launch ({@link PlaywrightLaunchTransportOptions}). Patchright
+ * is an OPTIONAL dependency imported lazily only when stealth is enabled; if it
+ * is absent the transport throws {@link MissingStealthDependencyError} rather
+ * than falling back to vanilla. This addresses ONLY the CDP `Runtime.enable`
+ * automation tell; a real profile/IP/session reputation still matter (ADR-0002).
  */
 export class PlaywrightLaunchTransport implements Transport {
 	readonly #location: ProfileLocationOptions;
 	readonly #hands: readonly Hand[];
+	readonly #stealth: boolean;
+	readonly #systemBrowser: string | undefined;
+	readonly #importStealthChromium: StealthChromiumImporter;
 
 	/**
 	 * @param location overrides for where profiles live (a `root` dir and/or an
@@ -37,13 +133,22 @@ export class PlaywrightLaunchTransport implements Transport {
 	 *   built-ins (Phase 2, ADR-0007). These come from {@link loadHands} against
 	 *   the operator's explicit config; the transport does NOT discover them. Omit
 	 *   for the built-ins-only surface.
+	 * @param options transport-construction policy, notably the opt-in `stealth`
+	 *   toggle and optional `systemBrowser` (see
+	 *   {@link PlaywrightLaunchTransportOptions}). Defaults to vanilla Playwright,
+	 *   bundled Chromium, stealth OFF.
 	 */
 	constructor(
 		location: ProfileLocationOptions = {},
 		hands: readonly Hand[] = [],
+		options: PlaywrightLaunchTransportOptions = {},
 	) {
 		this.#location = location;
 		this.#hands = hands;
+		this.#stealth = options.stealth === true;
+		this.#systemBrowser = options.systemBrowser;
+		this.#importStealthChromium =
+			options.importStealthChromium ?? defaultStealthImporter;
 	}
 
 	async open(target: OpenTarget): Promise<Session> {
@@ -68,14 +173,41 @@ export class PlaywrightLaunchTransport implements Transport {
 
 		const headless = target.headed !== true;
 
+		// Pick the engine: the lazily-imported stealth (Patchright) chromium when
+		// opted in, else vanilla Playwright's. Resolving the stealth module is where
+		// an absent optional dependency surfaces as the typed
+		// MissingStealthDependencyError (we never fall back to vanilla silently).
+		const launcher = this.#stealth
+			? await this.#resolveStealthLauncher()
+			: chromium;
+
+		// Launch options: forward headless, the optional systemBrowser (Playwright's
+		// `channel`, e.g. 'chrome' to drive system Chrome, Patchright's recommended
+		// setup), and for stealth drop Playwright's automation-flavoured default
+		// args so they cannot re-add the fingerprint Patchright just removed.
+		const launchOptions: Parameters<
+			typeof chromium.launchPersistentContext
+		>[1] = {headless};
+		if (this.#systemBrowser !== undefined) {
+			launchOptions.channel = this.#systemBrowser;
+		}
+		if (this.#stealth) {
+			launchOptions.ignoreDefaultArgs = ['--enable-automation'];
+		}
+
 		let context: BrowserContext;
 		try {
-			context = await chromium.launchPersistentContext(loc.profileDir, {
-				headless,
-			});
+			context = await launcher.launchPersistentContext(
+				loc.profileDir,
+				launchOptions,
+			);
 		} catch (cause) {
 			if (isMissingBrowserBinary(cause)) {
-				throw new MissingBrowserBinaryError('chromium', undefined, {cause});
+				// With systemBrowser set (e.g. 'chrome') the "binary missing" failure
+				// means the SYSTEM browser is absent, not the bundled Chromium; name
+				// what is actually missing so the CLI's fix message is accurate.
+				const browser = this.#systemBrowser ?? 'chromium';
+				throw new MissingBrowserBinaryError(browser, undefined, {cause});
 			}
 			throw cause;
 		}
@@ -86,6 +218,33 @@ export class PlaywrightLaunchTransport implements Transport {
 		const pwPage = context.pages()[0] ?? (await context.newPage());
 		return makeSession(context, pwPage, this.#hands);
 	}
+
+	/**
+	 * Resolve the stealth (`patchright`) chromium via the injected lazy importer.
+	 *
+	 * Confines the brittle "optional dependency absent" detection to ONE spot
+	 * (mirroring {@link isMissingBrowserBinary}): any failure to import the
+	 * optional package becomes the typed {@link MissingStealthDependencyError}, so
+	 * the caller never silently degrades to vanilla Playwright.
+	 */
+	async #resolveStealthLauncher(): Promise<ChromiumLauncher> {
+		let mod: StealthModule;
+		try {
+			mod = await this.#importStealthChromium();
+		} catch (cause) {
+			throw new MissingStealthDependencyError('patchright', undefined, {
+				cause,
+			});
+		}
+		if (
+			mod === null ||
+			typeof mod !== 'object' ||
+			typeof mod.chromium?.launchPersistentContext !== 'function'
+		) {
+			throw new MissingStealthDependencyError('patchright');
+		}
+		return mod.chromium;
+	}
 }
 
 /** True iff `path` exists and is a directory. */
@@ -103,6 +262,11 @@ async function isExistingDirectory(path: string): Promise<boolean> {
  * does not export a typed error for this, so we detect on the message (it
  * instructs the user to run `playwright install`). We confine that brittle
  * string match to this one spot and re-raise as a stable typed error.
+ *
+ * This also covers the `channel: 'chrome'` case, where the missing binary is the
+ * SYSTEM Chrome, not the bundled Chromium. Playwright phrases that as the
+ * channel/distribution not being found; we match those variants too so the
+ * stealth+system-Chrome path still yields the typed MissingBrowserBinaryError.
  */
 function isMissingBrowserBinary(cause: unknown): boolean {
 	const message = cause instanceof Error ? cause.message : String(cause ?? '');
@@ -111,7 +275,10 @@ function isMissingBrowserBinary(cause: unknown): boolean {
 		/please run the following command to download new browsers/i.test(
 			message,
 		) ||
-		/playwright install/i.test(message)
+		/playwright install/i.test(message) ||
+		// channel: 'chrome' (or other system channels) not installed on the host.
+		/Chromium distribution '.*' is not found/i.test(message) ||
+		/No "?(chrome|msedge|chromium)"? .* found/i.test(message)
 	);
 }