@olimsaidov/icdp 0.1.1 → 0.2.0

package/README.md

@@ -52,6 +52,26 @@ const disconnect = host.connectRelay({ url: "ws://localhost:9222/icdp/host" });
 
 Target identity belongs to the Pairing: reloads and navigations keep the same `targetId` (Clients see `Page.frameNavigated`); commands in flight when a document dies fail fast with `-32000`. The Relay uplink is just another consumer of the same hub — events broadcast to all attached sessions, domain enables are ref-counted.
 
+#### Client-driven target lifecycle (optional)
+
+By default only the Host creates Targets (via `pair()`), so a Client's `Target.createTarget` is rejected and `Target.closeTarget` is a no-op. Pass `onCreateTarget` / `onCloseTarget` to let a Client open and close Targets itself:
+
+```ts
+const host = new IcdpHost({
+  onCreateTarget: ({ url }) => {
+    const iframe = document.createElement("iframe");
+    iframe.src = url ?? "about:blank";
+    document.body.append(iframe);
+    const targetId = crypto.randomUUID();
+    host.pair(iframe, { targetId, origins: ["https://app.example.com"] });
+    return targetId; // string | Promise<string>
+  },
+  onCloseTarget: (targetId) => host.unpair(targetId), // + remove the iframe you made
+});
+```
+
+The Host advertises which of these it handles, so the Relay forwards only those and keeps its defaults for any hook you leave unset (existing Hosts are unaffected). `createTarget` resolves **only once the new Target completes its handshake**, so the Client's first command can't race the not-connected gate; a Target that never connects (timeout or early destroy) is torn down rather than left as a zombie. A bare `new IcdpHost(window)` is still accepted for back-compat.
+
 ### Relay — the server
 
 ```ts
@@ -68,7 +88,7 @@ One Host per Relay, new-wins: a newly connecting Host replaces a stale one, with
 
 ## Protocol shape
 
-- **Flat sessions only.** Clients connect to the single browser-level endpoint and use `Target.getTargets` / `Target.attachToTarget` (or `Target.setAutoAttach`) + `sessionId` routing. There are no per-target WebSocket URLs. Session-scoped `Target.*`/`Browser.*` housekeeping (e.g. agent-browser's session-scoped `Target.setAutoAttach`) is answered by the Relay; the Frame Agent never sees it.
+- **Flat sessions only.** Clients connect to the single browser-level endpoint and use `Target.getTargets` / `Target.attachToTarget` (or `Target.setAutoAttach`) + `sessionId` routing. There are no per-target WebSocket URLs. Session-scoped `Target.*`/`Browser.*` housekeeping (e.g. agent-browser's session-scoped `Target.setAutoAttach`) is answered by the Relay; the Frame Agent never sees it. Registry methods (`getTargets`/`attachToTarget`/`setAutoAttach`) are always Relay-owned; only the `Target.createTarget`/`Target.closeTarget` lifecycle can be delegated to the Host (see [Client-driven target lifecycle](#client-driven-target-lifecycle-optional)).
 - **Compatibility bar: agent-browser.** The supported command surface is the prior art's support matrix (AX-tree snapshots, semantic locators, click/fill/type, eval, waits, console, SPA history). Screenshots, PDF, file uploads, drag-and-drop, dialogs, and real network interception are intentionally out — page JavaScript cannot provide them. Raw Playwright over `connectOverCDP` is best-effort, not promised.
 
 ## Driving an icdp target with agent-browser

package/dist/host/index.d.mts

@@ -63,14 +63,33 @@ type RelayUplinkOptions = {
   reconnectDelayMs?: number;
   webSocketFactory?: (url: string) => WebSocket;
 };
+/** Params of a CDP Target.createTarget request handed to onCreateTarget. */
+type CreateTargetParams = {
+  url?: string;
+} & Record<string, unknown>;
+type IcdpHostOptions = {
+  /** The window to listen on (defaults to the global `window`). */window?: WindowLike;
+  /**
+   * Handle a Client's `Target.createTarget`: create + `pair()` an iframe and
+   * return its `targetId`. The Relay's response resolves only after the new
+   * Target connects, so the Client's first commands land. Throw to reject.
+   */
+  onCreateTarget?: (params: CreateTargetParams) => string | Promise<string>;
+  /**
+   * Handle a Client's `Target.closeTarget`: tear the Target down (e.g.
+   * `unpair()` + remove the iframe). Throw to reject.
+   */
+  onCloseTarget?: (targetId: string) => void | Promise<void>;
+};
 declare class IcdpHost {
-  private readonly win;
   private readonly pairings;
   private readonly targetListeners;
   private nextLocalSession;
   private uplink;
+  private readonly win;
+  private readonly options;
   private readonly onWindowMessage;
-  constructor(win?: WindowLike);
+  constructor(optionsOrWindow?: IcdpHostOptions | WindowLike);
   /** Register an iframe slot as a Target. The Pairing owns target identity. */
   pair(iframe: FrameElementLike, options: PairOptions): void;
   /** Destroy a Pairing. This is the only way a Target dies. */
@@ -81,6 +100,16 @@ declare class IcdpHost {
   attach(targetId: string): LocalSession;
   /** Connect the Relay uplink. Structurally just another consumer of this hub. */
   connectRelay(options: RelayUplinkOptions): () => void;
+  /** Browser-level methods this Host handles, advertised to the Relay so it
+   *  forwards them instead of using its built-in default. */
+  handledMethods(): string[];
+  /** Run a browser-level method the Host advertised (invoked by the Relay
+   *  uplink). The resolved value, or a thrown error, becomes the Client's
+   *  response. createTarget resolves only once the new Target connects. */
+  handleBrowserRequest(method: string, params: Record<string, unknown>): Promise<unknown>;
+  /** Resolve once a paired Target completes its handshake (targetInfoChanged);
+   *  reject if it is destroyed first or does not connect within the timeout. */
+  private whenConnected;
   destroy(): void;
   private summary;
   private emitTargetEvent;
@@ -96,4 +125,4 @@ declare class IcdpHost {
   releaseEnablesFor(targetId: string, consumerKey: string): void;
 }
 //#endregion
-export { FrameElementLike, IcdpHost, LocalSession, PairOptions, RelayUplinkOptions, TargetEvent, WindowLike };
+export { CreateTargetParams, FrameElementLike, IcdpHost, IcdpHostOptions, LocalSession, PairOptions, RelayUplinkOptions, TargetEvent, WindowLike };

package/dist/host/index.mjs

@@ -5,15 +5,17 @@ function methodDomain(method) {
 	return method.split(".")[0] ?? method;
 }
 var IcdpHost = class {
-	win;
 	pairings = /* @__PURE__ */ new Map();
 	targetListeners = /* @__PURE__ */ new Set();
 	nextLocalSession = 1;
 	uplink = null;
+	win;
+	options;
 	onWindowMessage = (event) => this.handleWindowMessage(event);
-	constructor(win = window) {
-		this.win = win;
-		win.addEventListener("message", this.onWindowMessage);
+	constructor(optionsOrWindow = {}) {
+		this.options = "addEventListener" in optionsOrWindow ? { window: optionsOrWindow } : optionsOrWindow;
+		this.win = this.options.window ?? window;
+		this.win.addEventListener("message", this.onWindowMessage);
 	}
 	/** Register an iframe slot as a Target. The Pairing owns target identity. */
 	pair(iframe, options) {
@@ -98,6 +100,61 @@ var IcdpHost = class {
 			this.uplink = null;
 		};
 	}
+	/** Browser-level methods this Host handles, advertised to the Relay so it
+	*  forwards them instead of using its built-in default. */
+	handledMethods() {
+		const methods = [];
+		if (this.options.onCreateTarget) methods.push("Target.createTarget");
+		if (this.options.onCloseTarget) methods.push("Target.closeTarget");
+		return methods;
+	}
+	/** Run a browser-level method the Host advertised (invoked by the Relay
+	*  uplink). The resolved value, or a thrown error, becomes the Client's
+	*  response. createTarget resolves only once the new Target connects. */
+	async handleBrowserRequest(method, params) {
+		if (method === "Target.createTarget") {
+			if (!this.options.onCreateTarget) throw new Error(`${method} is not handled by this Host`);
+			const targetId = await this.options.onCreateTarget(params);
+			try {
+				await this.whenConnected(targetId);
+			} catch (error) {
+				this.unpair(targetId);
+				throw error;
+			}
+			return { targetId };
+		}
+		if (method === "Target.closeTarget") {
+			if (!this.options.onCloseTarget) throw new Error(`${method} is not handled by this Host`);
+			await this.options.onCloseTarget(String(params.targetId ?? ""));
+			return { success: true };
+		}
+		throw new Error(`Unhandled browser method: ${method}`);
+	}
+	/** Resolve once a paired Target completes its handshake (targetInfoChanged);
+	*  reject if it is destroyed first or does not connect within the timeout. */
+	whenConnected(targetId, timeoutMs = 1e4) {
+		const pairing = this.pairings.get(targetId);
+		if (!pairing) return Promise.reject(/* @__PURE__ */ new Error(`Unknown target "${targetId}"`));
+		if (pairing.connected) return Promise.resolve();
+		return new Promise((resolve, reject) => {
+			let timer;
+			const off = this.onTargets((event) => {
+				if (event.kind === "targetInfoChanged" && event.target.targetId === targetId) {
+					clearTimeout(timer);
+					off();
+					resolve();
+				} else if (event.kind === "targetDestroyed" && event.targetId === targetId) {
+					clearTimeout(timer);
+					off();
+					reject(/* @__PURE__ */ new Error(`Target "${targetId}" was destroyed before connecting`));
+				}
+			});
+			timer = setTimeout(() => {
+				off();
+				reject(/* @__PURE__ */ new Error(`Target "${targetId}" did not connect within ${timeoutMs}ms`));
+			}, timeoutMs);
+		});
+	}
 	destroy() {
 		this.uplink?.close();
 		this.uplink = null;
@@ -261,7 +318,8 @@ var RelayUplink = class {
 			this.send({
 				kind: "ready",
 				v: 1,
-				targets: this.host.targets()
+				targets: this.host.targets(),
+				handles: this.host.handledMethods()
 			});
 		});
 		socket.addEventListener("message", (event) => {
@@ -300,6 +358,18 @@ var RelayUplink = class {
 			});
 		});
 		else if (message.kind === "detached") this.host.releaseEnablesFor(message.targetId, `relay-${message.sessionId}`);
+		else if (message.kind === "browserRequest") this.host.handleBrowserRequest(message.method, message.params).then((result) => this.send({
+			kind: "browserResult",
+			id: message.id,
+			result
+		}), (error) => this.send({
+			kind: "browserResult",
+			id: message.id,
+			error: {
+				code: CDP_SERVER_ERROR,
+				message: error instanceof Error ? error.message : String(error)
+			}
+		}));
 	}
 	handleFrameEvent(targetId, method, params) {
 		this.send({

package/dist/protocol.d.mts

@@ -49,6 +49,10 @@ type BridgeReady = {
   kind: "ready";
   v: number;
   targets: TargetSummary[];
+  /** Browser-level methods (e.g. "Target.createTarget") the Host handles itself.
+   *  The Relay forwards these as a BridgeBrowserRequest instead of using its
+   *  built-in default; omitted/empty means the Relay keeps its defaults. */
+  handles?: string[];
 };
 /** Host -> Relay: a Pairing appeared. */
 type BridgeTargetCreated = {
@@ -95,8 +99,23 @@ type BridgeDetached = {
   sessionId: string;
   targetId: string;
 };
-type HostToRelayMessage = BridgeReady | BridgeTargetCreated | BridgeTargetDestroyed | BridgeTargetInfoChanged | BridgeResponse | BridgeEvent;
-type RelayToHostMessage = BridgeCommand | BridgeDetached;
+/** Relay -> Host: a browser-level method the Host advertised it handles
+ *  (e.g. Target.createTarget / Target.closeTarget). Not session-scoped. */
+type BridgeBrowserRequest = {
+  kind: "browserRequest";
+  id: number;
+  method: string;
+  params: Record<string, unknown>;
+};
+/** Host -> Relay: the response to a BridgeBrowserRequest. */
+type BridgeBrowserResult = {
+  kind: "browserResult";
+  id: number;
+  result?: unknown;
+  error?: CdpError;
+};
+type HostToRelayMessage = BridgeReady | BridgeTargetCreated | BridgeTargetDestroyed | BridgeTargetInfoChanged | BridgeResponse | BridgeEvent | BridgeBrowserResult;
+type RelayToHostMessage = BridgeCommand | BridgeDetached | BridgeBrowserRequest;
 declare function parseJson<T>(raw: string | Buffer | ArrayBuffer | Uint8Array): T | null;
 //#endregion
-export { BridgeCommand, BridgeDetached, BridgeEvent, BridgeReady, BridgeResponse, BridgeTargetCreated, BridgeTargetDestroyed, BridgeTargetInfoChanged, CDP_METHOD_NOT_FOUND, CDP_SERVER_ERROR, CdpError, CdpId, CdpMessage, FrameInfo, HandshakeMessage, HelloMessage, HostToRelayMessage, PROTOCOL_VERSION, ProbeMessage, RelayToHostMessage, TargetSummary, WelcomeMessage, isHandshakeMessage, parseJson };
+export { BridgeBrowserRequest, BridgeBrowserResult, BridgeCommand, BridgeDetached, BridgeEvent, BridgeReady, BridgeResponse, BridgeTargetCreated, BridgeTargetDestroyed, BridgeTargetInfoChanged, CDP_METHOD_NOT_FOUND, CDP_SERVER_ERROR, CdpError, CdpId, CdpMessage, FrameInfo, HandshakeMessage, HelloMessage, HostToRelayMessage, PROTOCOL_VERSION, ProbeMessage, RelayToHostMessage, TargetSummary, WelcomeMessage, isHandshakeMessage, parseJson };

package/dist/relay/core.d.mts

@@ -9,6 +9,9 @@ type SocketLike = {
 type RelayCoreOptions = {
   /** Reported by Browser.getVersion and /json/version. */product?: string; /** Absolute WebSocket URL of the browser endpoint, for /json payloads. */
   browserWsUrl?: string;
+  /** How long to wait for the Host to answer a forwarded browser-level request
+   *  before failing the Client. Backstops a silent or hung Host. */
+  browserRequestTimeoutMs?: number;
 };
 declare class RelayCore {
   private readonly product;
@@ -18,6 +21,11 @@ declare class RelayCore {
   private readonly sessions;
   private readonly targets;
   private readonly pending;
+  /** Browser-level requests forwarded to the Host, awaiting a result. */
+  private readonly browserPending;
+  /** Browser-level methods the Host advertised it handles (from the ready message). */
+  private readonly hostHandles;
+  private readonly browserRequestTimeoutMs;
   private nextBridgeId;
   private nextSessionId;
   constructor(options?: RelayCoreOptions);
@@ -38,6 +46,11 @@ declare class RelayCore {
   private targetInfo;
   private sendToClient;
   private sendToHost;
+  private failBrowserPending;
+  /** Bound a forwarded browser request so a silent or hung Host can't pin a
+   *  Client's command open forever (and leak the pending entry). */
+  private armBrowserTimeout;
+  private expireBrowserPending;
   private broadcastTargetEvent;
   private addTarget;
   private removeTarget;

package/dist/relay/core.mjs

@@ -2,6 +2,10 @@ import { CDP_METHOD_NOT_FOUND, CDP_SERVER_ERROR, parseJson } from "../protocol.m
 //#region src/relay/core.ts
 /** Sentinel: the method was handled and a response was already sent. */
 const RESPONDED = Symbol("responded");
+/** Browser-domain methods a Host may take ownership of via the ready `handles`.
+*  Registry methods (getTargets/attachToTarget/setAutoAttach/...) stay relay-owned:
+*  they read the Relay's own session/target state, so the Host can't answer them. */
+const FORWARDABLE_BROWSER_METHODS = new Set(["Target.createTarget", "Target.closeTarget"]);
 var RelayCore = class {
 	product;
 	browserWsUrl;
@@ -10,11 +14,17 @@ var RelayCore = class {
 	sessions = /* @__PURE__ */ new Map();
 	targets = /* @__PURE__ */ new Map();
 	pending = /* @__PURE__ */ new Map();
+	/** Browser-level requests forwarded to the Host, awaiting a result. */
+	browserPending = /* @__PURE__ */ new Map();
+	/** Browser-level methods the Host advertised it handles (from the ready message). */
+	hostHandles = /* @__PURE__ */ new Set();
+	browserRequestTimeoutMs;
 	nextBridgeId = 1;
 	nextSessionId = 1;
 	constructor(options = {}) {
 		this.product = options.product ?? "icdp/0.1";
 		this.browserWsUrl = options.browserWsUrl ?? "";
+		this.browserRequestTimeoutMs = options.browserRequestTimeoutMs ?? 3e4;
 	}
 	/** A Host bridge connected. New-wins: any previous Host is dropped. */
 	hostConnected(socket) {
@@ -31,6 +41,8 @@ var RelayCore = class {
 	hostDisconnected(socket) {
 		if (this.hostSocket !== socket) return;
 		this.hostSocket = null;
+		this.hostHandles.clear();
+		this.failBrowserPending("Host disconnected");
 		this.dropAllTargets("Host disconnected");
 	}
 	hostMessage(socket, raw) {
@@ -40,6 +52,8 @@ var RelayCore = class {
 		switch (message.kind) {
 			case "ready":
 				this.dropAllTargets("Host re-announced");
+				this.hostHandles.clear();
+				for (const handled of message.handles ?? []) if (FORWARDABLE_BROWSER_METHODS.has(handled)) this.hostHandles.add(handled);
 				for (const target of message.targets) this.addTarget(target);
 				return;
 			case "targetCreated":
@@ -74,6 +88,18 @@ var RelayCore = class {
 					});
 				}
 				return;
+			case "browserResult": {
+				const call = this.browserPending.get(message.id);
+				if (!call) return;
+				this.browserPending.delete(message.id);
+				clearTimeout(call.timer);
+				this.sendToClient(call.client, {
+					id: call.clientId,
+					...call.sessionId ? { sessionId: call.sessionId } : {},
+					...message.error ? { error: message.error } : { result: message.result ?? {} }
+				});
+				return;
+			}
 		}
 	}
 	clientConnected(socket) {
@@ -89,12 +115,33 @@ var RelayCore = class {
 		if (!client) return;
 		this.clients.delete(socket);
 		for (const sessionId of client.sessions) this.endSession(sessionId, { notifyClient: false });
+		for (const [id, call] of this.browserPending) {
+			if (call.client !== client) continue;
+			this.browserPending.delete(id);
+			clearTimeout(call.timer);
+		}
 	}
 	clientMessage(socket, raw) {
 		const client = this.clients.get(socket);
 		if (!client) return;
 		const message = parseJson(raw);
 		if (!message) return;
+		if (message.method && this.hostHandles.has(message.method) && this.hostSocket) {
+			const bridgeId = this.nextBridgeId++;
+			this.browserPending.set(bridgeId, {
+				client,
+				clientId: message.id,
+				sessionId: message.sessionId,
+				timer: this.armBrowserTimeout(bridgeId)
+			});
+			this.sendToHost({
+				kind: "browserRequest",
+				id: bridgeId,
+				method: message.method,
+				params: message.params ?? {}
+			});
+			return;
+		}
 		if (message.sessionId) {
 			this.routeSessionCommand(client, message);
 			return;
@@ -164,6 +211,40 @@ var RelayCore = class {
 			this.hostSocket?.send(JSON.stringify(message));
 		} catch {}
 	}
+	failBrowserPending(reason) {
+		for (const [id, call] of this.browserPending) {
+			this.browserPending.delete(id);
+			clearTimeout(call.timer);
+			this.sendToClient(call.client, {
+				id: call.clientId,
+				...call.sessionId ? { sessionId: call.sessionId } : {},
+				error: {
+					code: CDP_SERVER_ERROR,
+					message: reason
+				}
+			});
+		}
+	}
+	/** Bound a forwarded browser request so a silent or hung Host can't pin a
+	*  Client's command open forever (and leak the pending entry). */
+	armBrowserTimeout(bridgeId) {
+		const timer = setTimeout(() => this.expireBrowserPending(bridgeId), this.browserRequestTimeoutMs);
+		timer.unref?.();
+		return timer;
+	}
+	expireBrowserPending(bridgeId) {
+		const call = this.browserPending.get(bridgeId);
+		if (!call) return;
+		this.browserPending.delete(bridgeId);
+		this.sendToClient(call.client, {
+			id: call.clientId,
+			...call.sessionId ? { sessionId: call.sessionId } : {},
+			error: {
+				code: CDP_SERVER_ERROR,
+				message: "Host did not respond to the browser-level request in time"
+			}
+		});
+	}
 	broadcastTargetEvent(method, params) {
 		for (const client of this.clients.values()) {
 			if (!client.discoverTargets) continue;
@@ -342,8 +423,8 @@ var RelayCore = class {
 			case "Browser.setWindowBounds":
 			case "Security.setIgnoreCertificateErrors":
 			case "Target.setRemoteLocations":
-			case "Target.activateTarget":
-			case "Target.closeTarget": return {};
+			case "Target.activateTarget": return {};
+			case "Target.closeTarget": return { success: true };
 			case "Schema.getDomains": return { domains: [] };
 			case "Target.getTargets": return { targetInfos: Array.from(this.targets.values(), (target) => this.targetInfo(target)) };
 			case "Target.getTargetInfo": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olimsaidov/icdp",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Chrome DevTools Protocol over an iframe boundary: drive and inspect embedded (including cross-origin) apps with CDP tools, without a real browser debugging session.",
   "homepage": "https://github.com/olimsaidov/icdp#readme",
   "bugs": "https://github.com/olimsaidov/icdp/issues",

package/src/host/index.ts

@@ -86,15 +86,40 @@ function methodDomain(method: string): string {
   return method.split(".")[0] ?? method;
 }
 
+/** Params of a CDP Target.createTarget request handed to onCreateTarget. */
+export type CreateTargetParams = { url?: string } & Record<string, unknown>;
+
+export type IcdpHostOptions = {
+  /** The window to listen on (defaults to the global `window`). */
+  window?: WindowLike;
+  /**
+   * Handle a Client's `Target.createTarget`: create + `pair()` an iframe and
+   * return its `targetId`. The Relay's response resolves only after the new
+   * Target connects, so the Client's first commands land. Throw to reject.
+   */
+  onCreateTarget?: (params: CreateTargetParams) => string | Promise<string>;
+  /**
+   * Handle a Client's `Target.closeTarget`: tear the Target down (e.g.
+   * `unpair()` + remove the iframe). Throw to reject.
+   */
+  onCloseTarget?: (targetId: string) => void | Promise<void>;
+};
+
 export class IcdpHost {
   private readonly pairings = new Map<string, Pairing>();
   private readonly targetListeners = new Set<(event: TargetEvent) => void>();
   private nextLocalSession = 1;
   private uplink: RelayUplink | null = null;
+  private readonly win: WindowLike;
+  private readonly options: IcdpHostOptions;
   private readonly onWindowMessage = (event: MessageEvent) => this.handleWindowMessage(event);
 
-  constructor(private readonly win: WindowLike = window) {
-    win.addEventListener("message", this.onWindowMessage);
+  constructor(optionsOrWindow: IcdpHostOptions | WindowLike = {}) {
+    // Back-compat: a bare WindowLike (has addEventListener) is still accepted.
+    this.options =
+      "addEventListener" in optionsOrWindow ? { window: optionsOrWindow } : optionsOrWindow;
+    this.win = this.options.window ?? window;
+    this.win.addEventListener("message", this.onWindowMessage);
   }
 
   /** Register an iframe slot as a Target. The Pairing owns target identity. */
@@ -181,6 +206,67 @@ export class IcdpHost {
     };
   }
 
+  /** Browser-level methods this Host handles, advertised to the Relay so it
+   *  forwards them instead of using its built-in default. */
+  handledMethods(): string[] {
+    const methods: string[] = [];
+    if (this.options.onCreateTarget) methods.push("Target.createTarget");
+    if (this.options.onCloseTarget) methods.push("Target.closeTarget");
+    return methods;
+  }
+
+  /** Run a browser-level method the Host advertised (invoked by the Relay
+   *  uplink). The resolved value, or a thrown error, becomes the Client's
+   *  response. createTarget resolves only once the new Target connects. */
+  async handleBrowserRequest(method: string, params: Record<string, unknown>): Promise<unknown> {
+    if (method === "Target.createTarget") {
+      if (!this.options.onCreateTarget) throw new Error(`${method} is not handled by this Host`);
+      const targetId = await this.options.onCreateTarget(params as CreateTargetParams);
+      try {
+        await this.whenConnected(targetId);
+      } catch (error) {
+        // The Target never materialised (timed out, or destroyed mid-handshake).
+        // Tear down the half-created Pairing so it doesn't linger as a zombie in
+        // the Host, the Relay, and Target.getTargets. unpair() is idempotent.
+        this.unpair(targetId);
+        throw error;
+      }
+      return { targetId };
+    }
+    if (method === "Target.closeTarget") {
+      if (!this.options.onCloseTarget) throw new Error(`${method} is not handled by this Host`);
+      await this.options.onCloseTarget(String(params.targetId ?? ""));
+      return { success: true };
+    }
+    throw new Error(`Unhandled browser method: ${method}`);
+  }
+
+  /** Resolve once a paired Target completes its handshake (targetInfoChanged);
+   *  reject if it is destroyed first or does not connect within the timeout. */
+  private whenConnected(targetId: string, timeoutMs = 10_000): Promise<void> {
+    const pairing = this.pairings.get(targetId);
+    if (!pairing) return Promise.reject(new Error(`Unknown target "${targetId}"`));
+    if (pairing.connected) return Promise.resolve();
+    return new Promise<void>((resolve, reject) => {
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      const off = this.onTargets((event) => {
+        if (event.kind === "targetInfoChanged" && event.target.targetId === targetId) {
+          clearTimeout(timer);
+          off();
+          resolve();
+        } else if (event.kind === "targetDestroyed" && event.targetId === targetId) {
+          clearTimeout(timer);
+          off();
+          reject(new Error(`Target "${targetId}" was destroyed before connecting`));
+        }
+      });
+      timer = setTimeout(() => {
+        off();
+        reject(new Error(`Target "${targetId}" did not connect within ${timeoutMs}ms`));
+      }, timeoutMs);
+    });
+  }
+
   destroy(): void {
     this.uplink?.close();
     this.uplink = null;
@@ -354,7 +440,12 @@ class RelayUplink {
     const socket = factory(this.options.url);
     this.socket = socket;
     socket.addEventListener("open", () => {
-      this.send({ kind: "ready", v: PROTOCOL_VERSION, targets: this.host.targets() });
+      this.send({
+        kind: "ready",
+        v: PROTOCOL_VERSION,
+        targets: this.host.targets(),
+        handles: this.host.handledMethods(),
+      });
     });
     socket.addEventListener("message", (event) => {
       const message = parseJson<RelayToHostMessage>(String(event.data));
@@ -406,6 +497,19 @@ class RelayUplink {
       );
     } else if (message.kind === "detached") {
       this.host.releaseEnablesFor(message.targetId, `relay-${message.sessionId}`);
+    } else if (message.kind === "browserRequest") {
+      this.host.handleBrowserRequest(message.method, message.params).then(
+        (result) => this.send({ kind: "browserResult", id: message.id, result }),
+        (error: unknown) =>
+          this.send({
+            kind: "browserResult",
+            id: message.id,
+            error: {
+              code: CDP_SERVER_ERROR,
+              message: error instanceof Error ? error.message : String(error),
+            },
+          }),
+      );
     }
   }
 

package/src/protocol.ts

@@ -70,7 +70,15 @@ export function isHandshakeMessage(data: unknown): data is HandshakeMessage {
 // ---------------------------------------------------------------------------
 
 /** Host -> Relay: announces itself and its current targets. New-wins: the Relay drops any previous Host. */
-export type BridgeReady = { kind: "ready"; v: number; targets: TargetSummary[] };
+export type BridgeReady = {
+  kind: "ready";
+  v: number;
+  targets: TargetSummary[];
+  /** Browser-level methods (e.g. "Target.createTarget") the Host handles itself.
+   *  The Relay forwards these as a BridgeBrowserRequest instead of using its
+   *  built-in default; omitted/empty means the Relay keeps its defaults. */
+  handles?: string[];
+};
 /** Host -> Relay: a Pairing appeared. */
 export type BridgeTargetCreated = { kind: "targetCreated"; target: TargetSummary };
 /** Host -> Relay: a Pairing was destroyed by the Host. */
@@ -103,6 +111,21 @@ export type BridgeEvent = {
 };
 /** Relay -> Host: a session detached (Client disconnected or detached explicitly). */
 export type BridgeDetached = { kind: "detached"; sessionId: string; targetId: string };
+/** Relay -> Host: a browser-level method the Host advertised it handles
+ *  (e.g. Target.createTarget / Target.closeTarget). Not session-scoped. */
+export type BridgeBrowserRequest = {
+  kind: "browserRequest";
+  id: number;
+  method: string;
+  params: Record<string, unknown>;
+};
+/** Host -> Relay: the response to a BridgeBrowserRequest. */
+export type BridgeBrowserResult = {
+  kind: "browserResult";
+  id: number;
+  result?: unknown;
+  error?: CdpError;
+};
 
 export type HostToRelayMessage =
   | BridgeReady
@@ -110,9 +133,10 @@ export type HostToRelayMessage =
   | BridgeTargetDestroyed
   | BridgeTargetInfoChanged
   | BridgeResponse
-  | BridgeEvent;
+  | BridgeEvent
+  | BridgeBrowserResult;
 
-export type RelayToHostMessage = BridgeCommand | BridgeDetached;
+export type RelayToHostMessage = BridgeCommand | BridgeDetached | BridgeBrowserRequest;
 
 export function parseJson<T>(raw: string | Buffer | ArrayBuffer | Uint8Array): T | null {
   try {

package/src/relay/core.ts

@@ -21,6 +21,9 @@ export type RelayCoreOptions = {
   product?: string;
   /** Absolute WebSocket URL of the browser endpoint, for /json payloads. */
   browserWsUrl?: string;
+  /** How long to wait for the Host to answer a forwarded browser-level request
+   *  before failing the Client. Backstops a silent or hung Host. */
+  browserRequestTimeoutMs?: number;
 };
 
 type ClientState = {
@@ -45,6 +48,11 @@ type PendingCommand = {
 /** Sentinel: the method was handled and a response was already sent. */
 const RESPONDED = Symbol("responded");
 
+/** Browser-domain methods a Host may take ownership of via the ready `handles`.
+ *  Registry methods (getTargets/attachToTarget/setAutoAttach/...) stay relay-owned:
+ *  they read the Relay's own session/target state, so the Host can't answer them. */
+const FORWARDABLE_BROWSER_METHODS = new Set(["Target.createTarget", "Target.closeTarget"]);
+
 export class RelayCore {
   private readonly product: string;
   private readonly browserWsUrl: string;
@@ -53,12 +61,27 @@ export class RelayCore {
   private readonly sessions = new Map<string, SessionState>();
   private readonly targets = new Map<string, TargetSummary>();
   private readonly pending = new Map<number, PendingCommand>();
+  /** Browser-level requests forwarded to the Host, awaiting a result. */
+  private readonly browserPending = new Map<
+    number,
+    {
+      client: ClientState;
+      clientId: CdpId | undefined;
+      /** Echoed back if the Client scoped the request to a session. */
+      sessionId: string | undefined;
+      timer: ReturnType<typeof setTimeout>;
+    }
+  >();
+  /** Browser-level methods the Host advertised it handles (from the ready message). */
+  private readonly hostHandles = new Set<string>();
+  private readonly browserRequestTimeoutMs: number;
   private nextBridgeId = 1;
   private nextSessionId = 1;
 
   constructor(options: RelayCoreOptions = {}) {
     this.product = options.product ?? "icdp/0.1";
     this.browserWsUrl = options.browserWsUrl ?? "";
+    this.browserRequestTimeoutMs = options.browserRequestTimeoutMs ?? 30_000;
   }
 
   // -- adapter wiring ---------------------------------------------------------
@@ -79,6 +102,8 @@ export class RelayCore {
   hostDisconnected(socket: SocketLike): void {
     if (this.hostSocket !== socket) return;
     this.hostSocket = null;
+    this.hostHandles.clear();
+    this.failBrowserPending("Host disconnected");
     this.dropAllTargets("Host disconnected");
   }
 
@@ -89,6 +114,9 @@ export class RelayCore {
     switch (message.kind) {
       case "ready":
         this.dropAllTargets("Host re-announced");
+        this.hostHandles.clear();
+        for (const handled of message.handles ?? [])
+          if (FORWARDABLE_BROWSER_METHODS.has(handled)) this.hostHandles.add(handled);
         for (const target of message.targets) this.addTarget(target);
         return;
       case "targetCreated":
@@ -127,6 +155,18 @@ export class RelayCore {
         }
         return;
       }
+      case "browserResult": {
+        const call = this.browserPending.get(message.id);
+        if (!call) return;
+        this.browserPending.delete(message.id);
+        clearTimeout(call.timer);
+        this.sendToClient(call.client, {
+          id: call.clientId,
+          ...(call.sessionId ? { sessionId: call.sessionId } : {}),
+          ...(message.error ? { error: message.error } : { result: message.result ?? {} }),
+        });
+        return;
+      }
     }
   }
 
@@ -144,6 +184,12 @@ export class RelayCore {
     if (!client) return;
     this.clients.delete(socket);
     for (const sessionId of client.sessions) this.endSession(sessionId, { notifyClient: false });
+    // Drop any browser-level request still in flight for this gone Client.
+    for (const [id, call] of this.browserPending) {
+      if (call.client !== client) continue;
+      this.browserPending.delete(id);
+      clearTimeout(call.timer);
+    }
   }
 
   clientMessage(socket: SocketLike, raw: string): void {
@@ -152,6 +198,27 @@ export class RelayCore {
     const message = parseJson<CdpMessage>(raw);
     if (!message) return;
 
+    // Browser-domain lifecycle methods the Host advertised it handles → forward
+    // and await its result, instead of using the relay's built-in default below.
+    // These are not session-scoped, so we honour them whether or not the Client
+    // attached a sessionId (any sessionId is only echoed back on the response).
+    if (message.method && this.hostHandles.has(message.method) && this.hostSocket) {
+      const bridgeId = this.nextBridgeId++;
+      this.browserPending.set(bridgeId, {
+        client,
+        clientId: message.id,
+        sessionId: message.sessionId,
+        timer: this.armBrowserTimeout(bridgeId),
+      });
+      this.sendToHost({
+        kind: "browserRequest",
+        id: bridgeId,
+        method: message.method,
+        params: message.params ?? {},
+      });
+      return;
+    }
+
     if (message.sessionId) {
       this.routeSessionCommand(client, message);
       return;
@@ -234,6 +301,44 @@ export class RelayCore {
     } catch {}
   }
 
+  private failBrowserPending(reason: string): void {
+    for (const [id, call] of this.browserPending) {
+      this.browserPending.delete(id);
+      clearTimeout(call.timer);
+      this.sendToClient(call.client, {
+        id: call.clientId,
+        ...(call.sessionId ? { sessionId: call.sessionId } : {}),
+        error: { code: CDP_SERVER_ERROR, message: reason },
+      });
+    }
+  }
+
+  /** Bound a forwarded browser request so a silent or hung Host can't pin a
+   *  Client's command open forever (and leak the pending entry). */
+  private armBrowserTimeout(bridgeId: number): ReturnType<typeof setTimeout> {
+    const timer = setTimeout(
+      () => this.expireBrowserPending(bridgeId),
+      this.browserRequestTimeoutMs,
+    );
+    // Don't keep a Node event loop alive just for this backstop.
+    (timer as { unref?: () => void }).unref?.();
+    return timer;
+  }
+
+  private expireBrowserPending(bridgeId: number): void {
+    const call = this.browserPending.get(bridgeId);
+    if (!call) return;
+    this.browserPending.delete(bridgeId);
+    this.sendToClient(call.client, {
+      id: call.clientId,
+      ...(call.sessionId ? { sessionId: call.sessionId } : {}),
+      error: {
+        code: CDP_SERVER_ERROR,
+        message: "Host did not respond to the browser-level request in time",
+      },
+    });
+  }
+
   private broadcastTargetEvent(method: string, params: Record<string, unknown>): void {
     for (const client of this.clients.values()) {
       if (!client.discoverTargets) continue;
@@ -421,8 +526,11 @@ export class RelayCore {
       case "Security.setIgnoreCertificateErrors":
       case "Target.setRemoteLocations":
       case "Target.activateTarget":
-      case "Target.closeTarget":
         return {};
+      // CDP's Target.closeTarget returns { success }. This default applies only
+      // when no Host advertised the method (otherwise it's forwarded above).
+      case "Target.closeTarget":
+        return { success: true };
       case "Schema.getDomains":
         return { domains: [] };
       case "Target.getTargets":