@olimsaidov/icdp 0.1.0

package/dist/host/index.d.mts

@@ -0,0 +1,99 @@
+import { CdpError, FrameInfo, TargetSummary } from "../protocol.mjs";
+
+//#region src/host/index.d.ts
+/** Minimal structural view of an iframe, so tests can fake it. */
+type FrameElementLike = {
+  contentWindow: {
+    postMessage: (message: unknown, targetOrigin: string, transfer?: Transferable[]) => void;
+  } | null;
+  addEventListener: (type: "load", listener: () => void) => void;
+  removeEventListener: (type: "load", listener: () => void) => void;
+};
+/** Minimal structural view of the parent window, so tests can fake it. */
+type WindowLike = {
+  addEventListener: (type: "message", listener: (event: MessageEvent) => void) => void;
+  removeEventListener: (type: "message", listener: (event: MessageEvent) => void) => void;
+};
+type PairOptions = {
+  /** Stable Target id for this Pairing. Survives reloads and navigations. */targetId: string;
+  /**
+   * Frame origins allowed to pair into this slot, or "*" to accept whatever
+   * the iframe element currently hosts.
+   */
+  origins: string[] | "*";
+};
+type LocalSession = {
+  send(method: string, params?: Record<string, unknown>): Promise<unknown>;
+  onEvent(listener: (method: string, params: Record<string, unknown>) => void): () => void;
+  detach(): void;
+};
+type TargetEvent = {
+  kind: "targetCreated";
+  target: TargetSummary;
+} | {
+  kind: "targetDestroyed";
+  targetId: string;
+} | {
+  kind: "targetInfoChanged";
+  target: TargetSummary;
+};
+type PendingCall = {
+  consumerKey: string;
+  settle: (result: unknown, error?: CdpError) => void;
+};
+type Pairing = {
+  targetId: string;
+  iframe: FrameElementLike;
+  origins: string[] | "*";
+  port: MessagePort | null;
+  connected: boolean;
+  info: FrameInfo;
+  nextCommandId: number;
+  pending: Map<number, PendingCall>; /** domain -> consumer keys that currently have it enabled */
+  enables: Map<string, Set<string>>;
+  localSessions: Map<string, LocalSessionState>;
+  onLoad: () => void;
+};
+type LocalSessionState = {
+  key: string;
+  listeners: Set<(method: string, params: Record<string, unknown>) => void>;
+};
+type RelayUplinkOptions = {
+  /** Bridge WebSocket URL on the Relay, e.g. ws://host/icdp/host */url: string;
+  reconnectDelayMs?: number;
+  webSocketFactory?: (url: string) => WebSocket;
+};
+declare class IcdpHost {
+  private readonly win;
+  private readonly pairings;
+  private readonly targetListeners;
+  private nextLocalSession;
+  private uplink;
+  private readonly onWindowMessage;
+  constructor(win?: 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. */
+  unpair(targetId: string): void;
+  targets(): TargetSummary[];
+  onTargets(listener: (event: TargetEvent) => void): () => void;
+  /** Attach a local consumer (e.g. a console panel) to a Target — no server involved. */
+  attach(targetId: string): LocalSession;
+  /** Connect the Relay uplink. Structurally just another consumer of this hub. */
+  connectRelay(options: RelayUplinkOptions): () => void;
+  destroy(): void;
+  private summary;
+  private emitTargetEvent;
+  private probe;
+  private handleWindowMessage;
+  private handleFrameMessage;
+  private failPending;
+  /** Route one command from a consumer to the Frame Agent, with enable ref-counting. */
+  dispatch(pairing: Pairing, consumerKey: string, method: string, params: Record<string, unknown>, settle: (result: unknown, error?: CdpError) => void): void;
+  dispatchTo(targetId: string, consumerKey: string, method: string, params: Record<string, unknown>, settle: (result: unknown, error?: CdpError) => void): void;
+  /** Drop a consumer's enable refs; send disables to the frame for domains it held last. */
+  releaseEnables(pairing: Pairing, consumerKey: string): void;
+  releaseEnablesFor(targetId: string, consumerKey: string): void;
+}
+//#endregion
+export { FrameElementLike, IcdpHost, LocalSession, PairOptions, RelayUplinkOptions, TargetEvent, WindowLike };

package/dist/host/index.mjs

@@ -0,0 +1,328 @@
+import { CDP_SERVER_ERROR, isHandshakeMessage, parseJson } from "../protocol.mjs";
+//#region src/host/index.ts
+const TARGET_NOT_CONNECTED = "Target is not connected: the Frame Agent has not paired yet.";
+function methodDomain(method) {
+	return method.split(".")[0] ?? method;
+}
+var IcdpHost = class {
+	win;
+	pairings = /* @__PURE__ */ new Map();
+	targetListeners = /* @__PURE__ */ new Set();
+	nextLocalSession = 1;
+	uplink = null;
+	onWindowMessage = (event) => this.handleWindowMessage(event);
+	constructor(win = window) {
+		this.win = win;
+		win.addEventListener("message", this.onWindowMessage);
+	}
+	/** Register an iframe slot as a Target. The Pairing owns target identity. */
+	pair(iframe, options) {
+		if (this.pairings.has(options.targetId)) throw new Error(`Target "${options.targetId}" is already paired`);
+		const pairing = {
+			targetId: options.targetId,
+			iframe,
+			origins: options.origins,
+			port: null,
+			connected: false,
+			info: {
+				title: options.targetId,
+				url: ""
+			},
+			nextCommandId: 1,
+			pending: /* @__PURE__ */ new Map(),
+			enables: /* @__PURE__ */ new Map(),
+			localSessions: /* @__PURE__ */ new Map(),
+			onLoad: () => this.probe(pairing)
+		};
+		this.pairings.set(options.targetId, pairing);
+		iframe.addEventListener("load", pairing.onLoad);
+		this.probe(pairing);
+		this.emitTargetEvent({
+			kind: "targetCreated",
+			target: this.summary(pairing)
+		});
+	}
+	/** Destroy a Pairing. This is the only way a Target dies. */
+	unpair(targetId) {
+		const pairing = this.pairings.get(targetId);
+		if (!pairing) return;
+		this.pairings.delete(targetId);
+		pairing.iframe.removeEventListener("load", pairing.onLoad);
+		this.failPending(pairing, "Target destroyed");
+		pairing.port?.close();
+		pairing.port = null;
+		this.emitTargetEvent({
+			kind: "targetDestroyed",
+			targetId
+		});
+	}
+	targets() {
+		return Array.from(this.pairings.values(), (pairing) => this.summary(pairing));
+	}
+	onTargets(listener) {
+		this.targetListeners.add(listener);
+		return () => this.targetListeners.delete(listener);
+	}
+	/** Attach a local consumer (e.g. a console panel) to a Target — no server involved. */
+	attach(targetId) {
+		const pairing = this.pairings.get(targetId);
+		if (!pairing) throw new Error(`Unknown target "${targetId}"`);
+		const state = {
+			key: `local-${this.nextLocalSession++}`,
+			listeners: /* @__PURE__ */ new Set()
+		};
+		pairing.localSessions.set(state.key, state);
+		return {
+			send: (method, params = {}) => new Promise((resolve, reject) => {
+				this.dispatch(pairing, state.key, method, params, (result, error) => {
+					if (error) reject(Object.assign(new Error(error.message), { code: error.code }));
+					else resolve(result);
+				});
+			}),
+			onEvent: (listener) => {
+				state.listeners.add(listener);
+				return () => state.listeners.delete(listener);
+			},
+			detach: () => {
+				pairing.localSessions.delete(state.key);
+				this.releaseEnables(pairing, state.key);
+			}
+		};
+	}
+	/** Connect the Relay uplink. Structurally just another consumer of this hub. */
+	connectRelay(options) {
+		this.uplink?.close();
+		this.uplink = new RelayUplink(this, options);
+		return () => {
+			this.uplink?.close();
+			this.uplink = null;
+		};
+	}
+	destroy() {
+		this.uplink?.close();
+		this.uplink = null;
+		for (const targetId of Array.from(this.pairings.keys())) this.unpair(targetId);
+		this.win.removeEventListener("message", this.onWindowMessage);
+	}
+	summary(pairing) {
+		return {
+			targetId: pairing.targetId,
+			...pairing.info
+		};
+	}
+	emitTargetEvent(event) {
+		for (const listener of this.targetListeners) listener(event);
+		this.uplink?.handleTargetEvent(event);
+	}
+	probe(pairing) {
+		pairing.iframe.contentWindow?.postMessage({
+			icdp: "probe",
+			v: 1
+		}, "*");
+	}
+	handleWindowMessage(event) {
+		if (!isHandshakeMessage(event.data) || event.data.icdp !== "hello") return;
+		const pairing = Array.from(this.pairings.values()).find((candidate) => candidate.iframe.contentWindow !== null && candidate.iframe.contentWindow === event.source);
+		if (!pairing) return;
+		if (pairing.origins !== "*" && !pairing.origins.includes(event.origin)) return;
+		if (pairing.port) {
+			this.failPending(pairing, "Target reloaded");
+			pairing.port.close();
+		}
+		const channel = new MessageChannel();
+		pairing.port = channel.port1;
+		pairing.connected = true;
+		pairing.info = {
+			title: event.data.title,
+			url: event.data.url
+		};
+		pairing.enables.clear();
+		channel.port1.onmessage = (portEvent) => this.handleFrameMessage(pairing, String(portEvent.data));
+		pairing.iframe.contentWindow?.postMessage({
+			icdp: "welcome",
+			v: 1
+		}, event.origin === "null" ? "*" : event.origin, [channel.port2]);
+		this.emitTargetEvent({
+			kind: "targetInfoChanged",
+			target: this.summary(pairing)
+		});
+	}
+	handleFrameMessage(pairing, raw) {
+		const message = parseJson(raw);
+		if (!message) return;
+		if (message.id != null) {
+			const call = pairing.pending.get(Number(message.id));
+			if (!call) return;
+			pairing.pending.delete(Number(message.id));
+			call.settle(message.result ?? {}, message.error);
+			return;
+		}
+		if (!message.method) return;
+		const params = message.params ?? {};
+		for (const session of pairing.localSessions.values()) for (const listener of session.listeners) listener(message.method, params);
+		this.uplink?.handleFrameEvent(pairing.targetId, message.method, params);
+	}
+	failPending(pairing, reason) {
+		for (const [id, call] of pairing.pending) {
+			pairing.pending.delete(id);
+			call.settle(void 0, {
+				code: CDP_SERVER_ERROR,
+				message: reason
+			});
+		}
+	}
+	/** Route one command from a consumer to the Frame Agent, with enable ref-counting. */
+	dispatch(pairing, consumerKey, method, params, settle) {
+		const domain = methodDomain(method);
+		if (method.endsWith(".disable")) {
+			const holders = pairing.enables.get(domain);
+			holders?.delete(consumerKey);
+			if (holders && holders.size > 0) {
+				settle({});
+				return;
+			}
+		}
+		if (!pairing.port) {
+			settle(void 0, {
+				code: CDP_SERVER_ERROR,
+				message: TARGET_NOT_CONNECTED
+			});
+			return;
+		}
+		if (method.endsWith(".enable")) {
+			let holders = pairing.enables.get(domain);
+			if (!holders) {
+				holders = /* @__PURE__ */ new Set();
+				pairing.enables.set(domain, holders);
+			}
+			holders.add(consumerKey);
+		}
+		const commandId = pairing.nextCommandId++;
+		pairing.pending.set(commandId, {
+			consumerKey,
+			settle
+		});
+		pairing.port.postMessage(JSON.stringify({
+			id: commandId,
+			method,
+			params
+		}));
+	}
+	dispatchTo(targetId, consumerKey, method, params, settle) {
+		const pairing = this.pairings.get(targetId);
+		if (!pairing) {
+			settle(void 0, {
+				code: CDP_SERVER_ERROR,
+				message: `Unknown target "${targetId}"`
+			});
+			return;
+		}
+		this.dispatch(pairing, consumerKey, method, params, settle);
+	}
+	/** Drop a consumer's enable refs; send disables to the frame for domains it held last. */
+	releaseEnables(pairing, consumerKey) {
+		for (const [domain, holders] of pairing.enables) {
+			if (!holders.delete(consumerKey)) continue;
+			if (holders.size === 0 && pairing.port) {
+				const commandId = pairing.nextCommandId++;
+				pairing.pending.set(commandId, {
+					consumerKey,
+					settle: () => {}
+				});
+				pairing.port.postMessage(JSON.stringify({
+					id: commandId,
+					method: `${domain}.disable`,
+					params: {}
+				}));
+			}
+		}
+	}
+	releaseEnablesFor(targetId, consumerKey) {
+		const pairing = this.pairings.get(targetId);
+		if (pairing) this.releaseEnables(pairing, consumerKey);
+	}
+};
+var RelayUplink = class {
+	host;
+	options;
+	socket = null;
+	closed = false;
+	reconnectTimer;
+	constructor(host, options) {
+		this.host = host;
+		this.options = options;
+		this.connect();
+	}
+	connect() {
+		if (this.closed) return;
+		const socket = (this.options.webSocketFactory ?? ((url) => new WebSocket(url)))(this.options.url);
+		this.socket = socket;
+		socket.addEventListener("open", () => {
+			this.send({
+				kind: "ready",
+				v: 1,
+				targets: this.host.targets()
+			});
+		});
+		socket.addEventListener("message", (event) => {
+			const message = parseJson(String(event.data));
+			if (message) this.handleRelayMessage(message);
+		});
+		socket.addEventListener("close", () => {
+			if (this.socket === socket) this.socket = null;
+			this.scheduleReconnect();
+		});
+		socket.addEventListener("error", () => socket.close());
+	}
+	scheduleReconnect() {
+		if (this.closed || this.reconnectTimer !== void 0) return;
+		this.reconnectTimer = setTimeout(() => {
+			this.reconnectTimer = void 0;
+			this.connect();
+		}, this.options.reconnectDelayMs ?? 500);
+	}
+	close() {
+		this.closed = true;
+		if (this.reconnectTimer !== void 0) clearTimeout(this.reconnectTimer);
+		this.socket?.close();
+		this.socket = null;
+	}
+	send(message) {
+		if (this.socket?.readyState === WebSocket.OPEN) this.socket.send(JSON.stringify(message));
+	}
+	handleRelayMessage(message) {
+		if (message.kind === "command") this.host.dispatchTo(message.targetId, `relay-${message.sessionId}`, message.method, message.params, (result, error) => {
+			this.send({
+				kind: "response",
+				sessionId: message.sessionId,
+				id: message.id,
+				...error ? { error } : { result }
+			});
+		});
+		else if (message.kind === "detached") this.host.releaseEnablesFor(message.targetId, `relay-${message.sessionId}`);
+	}
+	handleFrameEvent(targetId, method, params) {
+		this.send({
+			kind: "event",
+			targetId,
+			method,
+			params
+		});
+	}
+	handleTargetEvent(event) {
+		if (event.kind === "targetCreated") this.send({
+			kind: "targetCreated",
+			target: event.target
+		});
+		else if (event.kind === "targetDestroyed") this.send({
+			kind: "targetDestroyed",
+			targetId: event.targetId
+		});
+		else this.send({
+			kind: "targetInfoChanged",
+			target: event.target
+		});
+	}
+};
+//#endregion
+export { IcdpHost };

package/dist/protocol.d.mts

@@ -0,0 +1,102 @@
+import Protocol from "devtools-protocol";
+
+//#region src/protocol.d.ts
+declare const PROTOCOL_VERSION = 1;
+type CdpId = Protocol.integer | string;
+/** A raw CDP message: command, response, or event. */
+type CdpMessage = {
+  id?: CdpId;
+  method?: string;
+  params?: Record<string, unknown>;
+  sessionId?: string;
+  result?: unknown;
+  error?: CdpError;
+};
+type CdpError = {
+  code: number;
+  message: string;
+};
+declare const CDP_SERVER_ERROR = -32000;
+declare const CDP_METHOD_NOT_FOUND = -32601;
+/** Metadata a Frame Agent reports about its document. */
+type FrameInfo = {
+  title: string;
+  url: string;
+};
+/** Target metadata as the Host reports it to the Relay. */
+type TargetSummary = FrameInfo & {
+  targetId: string;
+};
+/** Sent by the Frame Agent to window.parent when it boots (and on probe). */
+type HelloMessage = {
+  icdp: "hello";
+  v: number;
+} & FrameInfo;
+/** Sent by the Host to an iframe it doesn't yet have a channel for. */
+type ProbeMessage = {
+  icdp: "probe";
+  v: number;
+};
+/** Sent by the Host in reply to hello, transferring a MessagePort. */
+type WelcomeMessage = {
+  icdp: "welcome";
+  v: number;
+};
+type HandshakeMessage = HelloMessage | ProbeMessage | WelcomeMessage;
+declare function isHandshakeMessage(data: unknown): data is HandshakeMessage;
+/** Host -> Relay: announces itself and its current targets. New-wins: the Relay drops any previous Host. */
+type BridgeReady = {
+  kind: "ready";
+  v: number;
+  targets: TargetSummary[];
+};
+/** Host -> Relay: a Pairing appeared. */
+type BridgeTargetCreated = {
+  kind: "targetCreated";
+  target: TargetSummary;
+};
+/** Host -> Relay: a Pairing was destroyed by the Host. */
+type BridgeTargetDestroyed = {
+  kind: "targetDestroyed";
+  targetId: string;
+};
+/** Host -> Relay: a Target's document changed (reload / navigation under a stable targetId). */
+type BridgeTargetInfoChanged = {
+  kind: "targetInfoChanged";
+  target: TargetSummary;
+};
+/** Relay -> Host: a Client command routed to one session. */
+type BridgeCommand = {
+  kind: "command";
+  sessionId: string;
+  targetId: string;
+  id: number;
+  method: string;
+  params: Record<string, unknown>;
+};
+/** Host -> Relay: the response to a BridgeCommand. */
+type BridgeResponse = {
+  kind: "response";
+  sessionId: string;
+  id: number;
+  result?: unknown;
+  error?: CdpError;
+};
+/** Host -> Relay: a CDP event from a Target; the Relay fans it out to every session attached to it. */
+type BridgeEvent = {
+  kind: "event";
+  targetId: string;
+  method: string;
+  params: Record<string, unknown>;
+};
+/** Relay -> Host: a session detached (Client disconnected or detached explicitly). */
+type BridgeDetached = {
+  kind: "detached";
+  sessionId: string;
+  targetId: string;
+};
+type HostToRelayMessage = BridgeReady | BridgeTargetCreated | BridgeTargetDestroyed | BridgeTargetInfoChanged | BridgeResponse | BridgeEvent;
+type RelayToHostMessage = BridgeCommand | BridgeDetached;
+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 };

package/dist/protocol.mjs

@@ -0,0 +1,16 @@
+//#region src/protocol.ts
+const PROTOCOL_VERSION = 1;
+const CDP_SERVER_ERROR = -32e3;
+const CDP_METHOD_NOT_FOUND = -32601;
+function isHandshakeMessage(data) {
+	return typeof data === "object" && data !== null && "icdp" in data && (data.icdp === "hello" || data.icdp === "probe" || data.icdp === "welcome");
+}
+function parseJson(raw) {
+	try {
+		return JSON.parse(typeof raw === "string" ? raw : new TextDecoder().decode(raw));
+	} catch {
+		return null;
+	}
+}
+//#endregion
+export { CDP_METHOD_NOT_FOUND, CDP_SERVER_ERROR, PROTOCOL_VERSION, isHandshakeMessage, parseJson };

package/dist/relay/core.d.mts

@@ -0,0 +1,54 @@
+import { TargetSummary } from "../protocol.mjs";
+
+//#region src/relay/core.d.ts
+/** Minimal socket surface the adapter must provide for each connection. */
+type SocketLike = {
+  send(data: string): void;
+  close(code?: number, reason?: string): void;
+};
+type RelayCoreOptions = {
+  /** Reported by Browser.getVersion and /json/version. */product?: string; /** Absolute WebSocket URL of the browser endpoint, for /json payloads. */
+  browserWsUrl?: string;
+};
+declare class RelayCore {
+  private readonly product;
+  private readonly browserWsUrl;
+  private hostSocket;
+  private readonly clients;
+  private readonly sessions;
+  private readonly targets;
+  private readonly pending;
+  private nextBridgeId;
+  private nextSessionId;
+  constructor(options?: RelayCoreOptions);
+  /** A Host bridge connected. New-wins: any previous Host is dropped. */
+  hostConnected(socket: SocketLike): void;
+  hostDisconnected(socket: SocketLike): void;
+  hostMessage(socket: SocketLike, raw: string): void;
+  clientConnected(socket: SocketLike): void;
+  clientDisconnected(socket: SocketLike): void;
+  clientMessage(socket: SocketLike, raw: string): void;
+  jsonVersion(): Record<string, unknown>;
+  jsonList(): Array<Record<string, unknown>>;
+  status(): {
+    hostConnected: boolean;
+    targets: TargetSummary[];
+    clients: number;
+  };
+  private targetInfo;
+  private sendToClient;
+  private sendToHost;
+  private broadcastTargetEvent;
+  private addTarget;
+  private removeTarget;
+  private dropAllTargets;
+  private startSession;
+  private endSession;
+  private routeSessionCommand;
+  /** Session-scoped methods the Relay answers itself; undefined = forward to the frame. */
+  private sessionLevelResult;
+  /** Browser-level methods the Relay answers itself; undefined = not local. */
+  private browserLevelResult;
+}
+//#endregion
+export { RelayCore, RelayCoreOptions, SocketLike };