@shadow-js/devtools 0.0.0-stage → 1.0.1

package/dist/dev/transport.js

@@ -0,0 +1,394 @@
+import "./protocol.js";
+import { InspectorModel } from "./model.js";
+//#region src/transport.ts
+/**
+* The `channel` field every devtools message carries. It lets the messages share a `postMessage`
+* or `BroadcastChannel` with other traffic: anything without this value is ignored.
+*
+* @example
+* import { CHANNEL } from "@shadow-js/devtools";
+* window.addEventListener("message", (event: MessageEvent) => {
+*   if (event.data?.channel === CHANNEL) console.log("devtools message", event.data.type);
+* });
+* @since 1.0.0
+*/
+const CHANNEL = "shadowjs-devtools";
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+function isEnvelope(value, from) {
+	return isRecord(value) && value["channel"] === "shadowjs-devtools" && value["from"] === from && typeof value["v"] === "number" && typeof value["type"] === "string";
+}
+/**
+* True for a well-formed message sent by an agent. Anything else on the channel is ignored. The check
+* covers the envelope (`channel`, `from`, `v`, `type`) and the fields each message type needs. It does
+* not validate every event inside an `events` message.
+*
+* @param value A received message.
+* @returns True when `value` is an {@link AgentMessage}.
+* @example
+* import { CHANNEL, isAgentMessage } from "@shadow-js/devtools";
+* isAgentMessage({ channel: CHANNEL, v: 1, from: "agent", type: "hello" }); // true
+* isAgentMessage({ channel: CHANNEL, v: 1, from: "panel", type: "hello" }); // false
+* @since 1.0.0
+*/
+function isAgentMessage(value) {
+	if (!isEnvelope(value, "agent")) return false;
+	switch (value["type"]) {
+		case "hello": return true;
+		case "events": return Array.isArray(value["events"]);
+		case "response": return typeof value["id"] === "number" && isRecord(value["response"]);
+		default: return false;
+	}
+}
+/**
+* True for a well-formed message sent by a panel. Anything else on the channel is ignored. The check
+* covers the envelope and the fields each message type needs, including the request's `type`.
+*
+* @param value A received message.
+* @returns True when `value` is a {@link PanelMessage}.
+* @example
+* import { CHANNEL, isPanelMessage } from "@shadow-js/devtools";
+* isPanelMessage({ channel: CHANNEL, v: 1, from: "panel", type: "hello" }); // true
+* isPanelMessage({ channel: CHANNEL, v: 1, from: "agent", type: "hello" }); // false
+* @since 1.0.0
+*/
+function isPanelMessage(value) {
+	if (!isEnvelope(value, "panel")) return false;
+	switch (value["type"]) {
+		case "hello": return true;
+		case "request": return typeof value["id"] === "number" && isRecord(value["request"]) && typeof value["request"]["type"] === "string";
+		default: return false;
+	}
+}
+/**
+* Two connected in-memory transports, for tests and for connecting an agent and a panel inside one
+* page. Messages are structured-cloned, so anything that is not plain serializable data fails here
+* exactly as it would over `postMessage`. Closing either end closes both.
+*
+* @returns `[agentSide, panelSide]`.
+* @example
+* import { connectRemote, createAgent, createMemoryTransportPair, serveAgent } from "@shadow-js/devtools";
+* const [agentSide, panelSide] = createMemoryTransportPair();
+* const stop = serveAgent(createAgent(), agentSide);
+* const backend = connectRemote(panelSide);
+* await backend.ready;
+* stop();
+* @since 1.0.0
+*/
+function createMemoryTransportPair() {
+	const handlers = [/* @__PURE__ */ new Set(), /* @__PURE__ */ new Set()];
+	let closed = false;
+	const side = (index) => ({
+		send(message) {
+			if (closed) return;
+			const copy = structuredClone(message);
+			for (const handler of [...handlers[index === 0 ? 1 : 0]]) handler(copy);
+		},
+		listen(handler) {
+			handlers[index].add(handler);
+			return () => {
+				handlers[index].delete(handler);
+			};
+		},
+		close() {
+			closed = true;
+			handlers[0].clear();
+			handlers[1].clear();
+		}
+	});
+	return [side(0), side(1)];
+}
+/**
+* A transport over a `MessagePort`: a `MessageChannel` end, a worker port or an extension port.
+* Incoming messages reach the listeners registered with `listen`. `close` closes the port when it
+* supports closing.
+*
+* @param port The port.
+* @returns The transport.
+* @example
+* import { connectRemote, createAgent, createPortTransport, serveAgent } from "@shadow-js/devtools";
+* const channel = new MessageChannel();
+* serveAgent(createAgent(), createPortTransport(channel.port1));
+* const backend = connectRemote(createPortTransport(channel.port2));
+* await backend.ready;
+* @since 1.0.0
+*/
+function createPortTransport(port) {
+	return {
+		send(message) {
+			port.postMessage(message);
+		},
+		listen(handler) {
+			const listener = (event) => handler(event.data);
+			port.addEventListener("message", listener);
+			port.start?.();
+			return () => port.removeEventListener("message", listener);
+		},
+		close() {
+			port.close?.();
+		}
+	};
+}
+/**
+* A transport over `window.postMessage` between a page and a panel in another window or frame (a
+* DevTools extension page, a popup). Both sides call it, each naming the other window and its origin.
+* Messages are sent only to `target`, with `origin` as the target origin. Incoming messages are
+* delivered only when their origin equals `origin` and their source is `target`; all others are
+* ignored.
+*
+* @param options Target window, its origin and the receiving window.
+* @returns The transport.
+* @throws {TypeError} When `origin` is `"*"`: the messages would reach any origin.
+* @example
+* import { createAgent, createWindowTransport, serveAgent } from "@shadow-js/devtools";
+* const frame = document.querySelector("iframe");
+* if (frame?.contentWindow) {
+*   const transport = createWindowTransport({ target: frame.contentWindow, origin: "https://panel.example" });
+*   serveAgent(createAgent(), transport);
+* }
+* @since 1.0.0
+*/
+function createWindowTransport(options) {
+	if (options.origin === "*") throw new TypeError("createWindowTransport: pass the real origin, not \"*\".");
+	const receiver = options.receiver ?? globalThis;
+	return {
+		send(message) {
+			options.target.postMessage(message, options.origin);
+		},
+		listen(handler) {
+			const listener = (event) => {
+				if (event.origin !== options.origin) return;
+				if (event.source !== options.target) return;
+				handler(event.data);
+			};
+			receiver.addEventListener("message", listener);
+			return () => receiver.removeEventListener("message", listener);
+		},
+		close() {}
+	};
+}
+/**
+* A transport over a `BroadcastChannel`, for a panel in another tab or window of the same origin.
+* Several panels can listen to one agent; each message goes to all of them.
+*
+* @param name Channel name. Both sides use the same.
+* @param factory Creates the channel (default `new BroadcastChannel(name)`).
+* @returns The transport.
+* @example
+* import { connectRemote, createBroadcastChannelTransport } from "@shadow-js/devtools";
+* const backend = connectRemote(createBroadcastChannelTransport("shadowjs-devtools"));
+* await backend.ready;
+* @since 1.0.0
+*/
+function createBroadcastChannelTransport(name, factory = (n) => new BroadcastChannel(n)) {
+	const channel = factory(name);
+	return {
+		send(message) {
+			channel.postMessage(message);
+		},
+		listen(handler) {
+			const listener = (event) => handler(event.data);
+			channel.addEventListener("message", listener);
+			return () => channel.removeEventListener("message", listener);
+		},
+		close() {
+			channel.close();
+		}
+	};
+}
+/**
+* Exposes an agent over a transport: forwards its event stream to the panel and answers the panel's
+* requests. The agent keeps recording while no panel listens, and the stream is sent regardless. What
+* happens to events nobody receives depends on the transport. A `highlight` request is passed to
+* `options.highlight` and answered without reaching the agent. Stop serving with the returned function.
+*
+* @param agent The agent in the inspected page.
+* @param transport The channel to the panel.
+* @param options Page-side behavior (highlight overlay) and batch size.
+* @returns A function that stops serving.
+* @example
+* import { createAgent, createMemoryTransportPair, serveAgent } from "@shadow-js/devtools";
+* const [pageSide] = createMemoryTransportPair();
+* const stop = serveAgent(createAgent(), pageSide, { highlight: (id) => console.log("highlight", id) });
+* stop();
+* @since 1.0.0
+*/
+function serveAgent(agent, transport, options = {}) {
+	const limit = options.batch ?? 2e3;
+	const send = (message) => transport.send(message);
+	const stopListening = transport.listen((raw) => {
+		if (!isPanelMessage(raw)) return;
+		if (raw.type === "hello") {
+			send({
+				channel: CHANNEL,
+				v: 1,
+				from: "agent",
+				type: "hello"
+			});
+			return;
+		}
+		const { request } = raw;
+		let response;
+		if (request.type === "highlight") {
+			options.highlight?.(request.id);
+			response = {
+				ok: true,
+				result: null
+			};
+		} else response = agent.handle(request);
+		send({
+			channel: CHANNEL,
+			v: 1,
+			from: "agent",
+			type: "response",
+			id: raw.id,
+			response
+		});
+	});
+	const stopStreaming = agent.subscribe((events) => {
+		for (let i = 0; i < events.length; i += limit) send({
+			channel: CHANNEL,
+			v: 1,
+			from: "agent",
+			type: "events",
+			events: events.slice(i, i + limit)
+		});
+	});
+	return () => {
+		stopListening();
+		stopStreaming();
+	};
+}
+/**
+* Connects a panel to a remote agent: asks for the complete state, then applies the event stream
+* to a local model. Events that arrive before the state are buffered, and the ones the state already
+* contains are skipped (sequence numbers), so no event is lost or applied twice. Disposing the backend
+* closes the transport.
+*
+* @param transport The channel to the agent.
+* @param options Model limits.
+* @returns A {@link Backend}.
+* @example
+* import { connectRemote, createBroadcastChannelTransport } from "@shadow-js/devtools";
+* const backend = connectRemote(createBroadcastChannelTransport("shadowjs-devtools"));
+* await backend.ready;
+* @since 1.0.0
+*/
+function connectRemote(transport, options = {}) {
+	const model = new InspectorModel(options.limits);
+	const listeners = /* @__PURE__ */ new Set();
+	const waiting = /* @__PURE__ */ new Map();
+	let buffered = [];
+	let synced = false;
+	let nextRequest = 1;
+	let disposed = false;
+	let notifyScheduled = false;
+	let resolveReady = () => void 0;
+	const ready = new Promise((resolve) => {
+		resolveReady = resolve;
+	});
+	const notify = () => {
+		if (notifyScheduled) return;
+		notifyScheduled = true;
+		queueMicrotask(() => {
+			notifyScheduled = false;
+			if (disposed) return;
+			for (const listener of listeners) listener();
+		});
+	};
+	const send = (message) => transport.send(message);
+	const applyState = (state) => {
+		model.importState(state);
+		synced = true;
+		const pending = buffered;
+		buffered = [];
+		for (const event of pending) model.apply(event);
+		resolveReady();
+		notify();
+	};
+	const request = (req) => {
+		if (disposed) return Promise.reject(/* @__PURE__ */ new Error("The devtools backend was disposed."));
+		const id = nextRequest;
+		nextRequest += 1;
+		return new Promise((resolve, reject) => {
+			waiting.set(id, {
+				resolve,
+				reject
+			});
+			send({
+				channel: CHANNEL,
+				v: 1,
+				from: "panel",
+				type: "request",
+				id,
+				request: req
+			});
+		});
+	};
+	const stop = transport.listen((raw) => {
+		if (!isAgentMessage(raw)) return;
+		if (raw.v !== 1) return;
+		if (raw.type === "events") {
+			if (!synced) {
+				buffered.push(...raw.events);
+				return;
+			}
+			for (const event of raw.events) model.apply(event);
+			notify();
+			return;
+		}
+		if (raw.type === "response") {
+			const entry = waiting.get(raw.id);
+			if (entry === void 0) return;
+			waiting.delete(raw.id);
+			entry.resolve(raw.response);
+		}
+	});
+	const sync = () => {
+		request({ type: "snapshot" }).then((response) => {
+			if (response.ok) applyState(response.result);
+		}, () => {
+			synced = false;
+		});
+	};
+	send({
+		channel: CHANNEL,
+		v: 1,
+		from: "panel",
+		type: "hello"
+	});
+	sync();
+	return {
+		model,
+		ready,
+		subscribe(listener) {
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		},
+		request(req) {
+			if (req.type === "clear") return request(req).then((response) => {
+				if (response.ok) {
+					synced = false;
+					sync();
+				}
+				return response;
+			});
+			return request(req);
+		},
+		dispose() {
+			disposed = true;
+			stop();
+			listeners.clear();
+			for (const entry of waiting.values()) entry.reject(/* @__PURE__ */ new Error("The devtools backend was disposed."));
+			waiting.clear();
+			transport.close();
+		}
+	};
+}
+//#endregion
+export { CHANNEL, connectRemote, createBroadcastChannelTransport, createMemoryTransportPair, createPortTransport, createWindowTransport, isAgentMessage, isPanelMessage, serveAgent };
+
+//# sourceMappingURL=transport.js.map

package/dist/dev/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","names":[],"sources":["../../src/transport.ts"],"sourcesContent":["import type { Agent, AgentRequest, AgentResponse } from \"./agent\";\nimport type { Backend, PageHooks } from \"./backend\";\nimport { InspectorModel, type ModelLimits, type ModelState } from \"./model\";\nimport { PROTOCOL_VERSION, type WireEvent } from \"./protocol\";\n\n/**\n * The `channel` field every devtools message carries. It lets the messages share a `postMessage`\n * or `BroadcastChannel` with other traffic: anything without this value is ignored.\n *\n * @example\n * import { CHANNEL } from \"@shadow-js/devtools\";\n * window.addEventListener(\"message\", (event: MessageEvent) => {\n *   if (event.data?.channel === CHANNEL) console.log(\"devtools message\", event.data.type);\n * });\n * @since 1.0.0\n */\nexport const CHANNEL = \"shadowjs-devtools\";\n\n/**\n * A message the agent side sends to the panel: the answer to a `hello`, a batch of events, or the\n * answer to a request. All fields are plain data.\n *\n * @since 1.0.0\n */\nexport type AgentMessage =\n  | { channel: typeof CHANNEL; v: number; from: \"agent\"; type: \"hello\" }\n  | { channel: typeof CHANNEL; v: number; from: \"agent\"; type: \"events\"; events: WireEvent[] }\n  | {\n      channel: typeof CHANNEL;\n      v: number;\n      from: \"agent\";\n      type: \"response\";\n      id: number;\n      response: AgentResponse;\n    };\n\n/**\n * A message the panel side sends to the agent: a `hello`, or a request. The agent answers a request\n * with a `response` that carries the same `id`. All fields are plain data.\n *\n * @since 1.0.0\n */\nexport type PanelMessage =\n  | { channel: typeof CHANNEL; v: number; from: \"panel\"; type: \"hello\" }\n  | {\n      channel: typeof CHANNEL;\n      v: number;\n      from: \"panel\";\n      type: \"request\";\n      id: number;\n      request: AgentRequest;\n    };\n\n/**\n * A duplex channel of plain messages. Implementations must deliver messages in order; they need not\n * be synchronous. `postMessage`, `MessagePort` and `BroadcastChannel` adapters are provided.\n *\n * @since 1.0.0\n */\nexport interface Transport {\n  /**\n   * Sends a message to the other end. The message must be plain data that can be structured-cloned.\n   */\n  send(message: unknown): void;\n  /**\n   * Starts delivering incoming messages to `handler`, in order.\n   *\n   * @returns A function that stops this listener.\n   */\n  listen(handler: (message: unknown) => void): () => void;\n  /**\n   * Releases what the transport holds. Closing a port or a `BroadcastChannel` closes it; a window\n   * transport holds nothing and does nothing.\n   */\n  close(): void;\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null;\n}\n\nfunction isEnvelope(value: unknown, from: \"agent\" | \"panel\"): value is Record<string, unknown> {\n  return (\n    isRecord(value) &&\n    value[\"channel\"] === CHANNEL &&\n    value[\"from\"] === from &&\n    typeof value[\"v\"] === \"number\" &&\n    typeof value[\"type\"] === \"string\"\n  );\n}\n\n/**\n * True for a well-formed message sent by an agent. Anything else on the channel is ignored. The check\n * covers the envelope (`channel`, `from`, `v`, `type`) and the fields each message type needs. It does\n * not validate every event inside an `events` message.\n *\n * @param value A received message.\n * @returns True when `value` is an {@link AgentMessage}.\n * @example\n * import { CHANNEL, isAgentMessage } from \"@shadow-js/devtools\";\n * isAgentMessage({ channel: CHANNEL, v: 1, from: \"agent\", type: \"hello\" }); // true\n * isAgentMessage({ channel: CHANNEL, v: 1, from: \"panel\", type: \"hello\" }); // false\n * @since 1.0.0\n */\nexport function isAgentMessage(value: unknown): value is AgentMessage {\n  if (!isEnvelope(value, \"agent\")) return false;\n  switch (value[\"type\"]) {\n    case \"hello\":\n      return true;\n    case \"events\":\n      return Array.isArray(value[\"events\"]);\n    case \"response\":\n      return typeof value[\"id\"] === \"number\" && isRecord(value[\"response\"]);\n    default:\n      return false;\n  }\n}\n\n/**\n * True for a well-formed message sent by a panel. Anything else on the channel is ignored. The check\n * covers the envelope and the fields each message type needs, including the request's `type`.\n *\n * @param value A received message.\n * @returns True when `value` is a {@link PanelMessage}.\n * @example\n * import { CHANNEL, isPanelMessage } from \"@shadow-js/devtools\";\n * isPanelMessage({ channel: CHANNEL, v: 1, from: \"panel\", type: \"hello\" }); // true\n * isPanelMessage({ channel: CHANNEL, v: 1, from: \"agent\", type: \"hello\" }); // false\n * @since 1.0.0\n */\nexport function isPanelMessage(value: unknown): value is PanelMessage {\n  if (!isEnvelope(value, \"panel\")) return false;\n  switch (value[\"type\"]) {\n    case \"hello\":\n      return true;\n    case \"request\":\n      return (\n        typeof value[\"id\"] === \"number\" &&\n        isRecord(value[\"request\"]) &&\n        typeof value[\"request\"][\"type\"] === \"string\"\n      );\n    default:\n      return false;\n  }\n}\n\n/**\n * Two connected in-memory transports, for tests and for connecting an agent and a panel inside one\n * page. Messages are structured-cloned, so anything that is not plain serializable data fails here\n * exactly as it would over `postMessage`. Closing either end closes both.\n *\n * @returns `[agentSide, panelSide]`.\n * @example\n * import { connectRemote, createAgent, createMemoryTransportPair, serveAgent } from \"@shadow-js/devtools\";\n * const [agentSide, panelSide] = createMemoryTransportPair();\n * const stop = serveAgent(createAgent(), agentSide);\n * const backend = connectRemote(panelSide);\n * await backend.ready;\n * stop();\n * @since 1.0.0\n */\nexport function createMemoryTransportPair(): [Transport, Transport] {\n  const handlers: [Set<(message: unknown) => void>, Set<(message: unknown) => void>] = [\n    new Set(),\n    new Set(),\n  ];\n  let closed = false;\n  const side = (index: 0 | 1): Transport => ({\n    send(message): void {\n      if (closed) return;\n      const copy = structuredClone(message);\n      for (const handler of [...handlers[index === 0 ? 1 : 0]]) handler(copy);\n    },\n    listen(handler): () => void {\n      handlers[index].add(handler);\n      return () => {\n        handlers[index].delete(handler);\n      };\n    },\n    close(): void {\n      closed = true;\n      handlers[0].clear();\n      handlers[1].clear();\n    },\n  });\n  return [side(0), side(1)];\n}\n\n/**\n * The part of a `MessagePort` the adapter uses. A `MessageChannel` end, a worker port and an\n * extension port all fit this shape.\n *\n * @since 1.0.0\n */\nexport interface MessagePortLike {\n  /**\n   * Posts a message to the other end of the port.\n   */\n  postMessage(message: unknown): void;\n  /**\n   * Adds a listener for incoming messages.\n   */\n  addEventListener(type: \"message\", listener: (event: { data: unknown }) => void): void;\n  /**\n   * Removes a listener added with `addEventListener`.\n   */\n  removeEventListener(type: \"message\", listener: (event: { data: unknown }) => void): void;\n  /**\n   * Starts the port. The adapter calls it after it adds a listener. Optional.\n   */\n  start?(): void;\n  /**\n   * Closes the port. Optional.\n   */\n  close?(): void;\n}\n\n/**\n * A transport over a `MessagePort`: a `MessageChannel` end, a worker port or an extension port.\n * Incoming messages reach the listeners registered with `listen`. `close` closes the port when it\n * supports closing.\n *\n * @param port The port.\n * @returns The transport.\n * @example\n * import { connectRemote, createAgent, createPortTransport, serveAgent } from \"@shadow-js/devtools\";\n * const channel = new MessageChannel();\n * serveAgent(createAgent(), createPortTransport(channel.port1));\n * const backend = connectRemote(createPortTransport(channel.port2));\n * await backend.ready;\n * @since 1.0.0\n */\nexport function createPortTransport(port: MessagePortLike): Transport {\n  return {\n    send(message): void {\n      port.postMessage(message);\n    },\n    listen(handler): () => void {\n      const listener = (event: { data: unknown }): void => handler(event.data);\n      port.addEventListener(\"message\", listener);\n      port.start?.();\n      return () => port.removeEventListener(\"message\", listener);\n    },\n    close(): void {\n      port.close?.();\n    },\n  };\n}\n\n/**\n * The part of a `Window` the adapter uses: its `postMessage`. A `WindowProxy` such as\n * `iframe.contentWindow` fits this shape.\n *\n * @since 1.0.0\n */\nexport interface WindowLike {\n  /**\n   * Posts a message to the window. The adapter always passes a real origin as `targetOrigin`.\n   */\n  postMessage(message: unknown, targetOrigin: string): void;\n}\n\n/**\n * The part of the receiving window the adapter uses: its `message` listeners. `globalThis` in a page\n * or a frame fits this shape.\n *\n * @since 1.0.0\n */\nexport interface WindowEvents {\n  /**\n   * Adds a listener for `message` events.\n   */\n  addEventListener(type: \"message\", listener: (event: MessageEvent) => void): void;\n  /**\n   * Removes a listener added with `addEventListener`.\n   */\n  removeEventListener(type: \"message\", listener: (event: MessageEvent) => void): void;\n}\n\n/**\n * Options of {@link createWindowTransport}.\n *\n * @since 1.0.0\n */\nexport interface WindowTransportOptions {\n  /**\n   * The window to talk to: the page being inspected, or the panel's frame.\n   */\n  target: WindowLike;\n  /**\n   * The origin of `target`. It is used as `targetOrigin` and to check where messages come from. Never\n   * `\"*\"`: {@link createWindowTransport} refuses it.\n   */\n  origin: string;\n  /**\n   * Where messages arrive.\n   *\n   * @default globalThis\n   */\n  receiver?: WindowEvents;\n}\n\n/**\n * A transport over `window.postMessage` between a page and a panel in another window or frame (a\n * DevTools extension page, a popup). Both sides call it, each naming the other window and its origin.\n * Messages are sent only to `target`, with `origin` as the target origin. Incoming messages are\n * delivered only when their origin equals `origin` and their source is `target`; all others are\n * ignored.\n *\n * @param options Target window, its origin and the receiving window.\n * @returns The transport.\n * @throws {TypeError} When `origin` is `\"*\"`: the messages would reach any origin.\n * @example\n * import { createAgent, createWindowTransport, serveAgent } from \"@shadow-js/devtools\";\n * const frame = document.querySelector(\"iframe\");\n * if (frame?.contentWindow) {\n *   const transport = createWindowTransport({ target: frame.contentWindow, origin: \"https://panel.example\" });\n *   serveAgent(createAgent(), transport);\n * }\n * @since 1.0.0\n */\nexport function createWindowTransport(options: WindowTransportOptions): Transport {\n  if (options.origin === \"*\")\n    throw new TypeError('createWindowTransport: pass the real origin, not \"*\".');\n  const receiver: WindowEvents = options.receiver ?? (globalThis as unknown as WindowEvents);\n  return {\n    send(message): void {\n      options.target.postMessage(message, options.origin);\n    },\n    listen(handler): () => void {\n      const listener = (event: MessageEvent): void => {\n        if (event.origin !== options.origin) return;\n        if ((event.source as unknown) !== options.target) return;\n        handler(event.data);\n      };\n      receiver.addEventListener(\"message\", listener);\n      return () => receiver.removeEventListener(\"message\", listener);\n    },\n    close(): void {\n      // The window belongs to the page; nothing to release.\n    },\n  };\n}\n\n/**\n * The part of `BroadcastChannel` the adapter uses.\n *\n * @since 1.0.0\n */\nexport interface BroadcastChannelLike {\n  /**\n   * Posts a message to every other channel object with the same name.\n   */\n  postMessage(message: unknown): void;\n  /**\n   * Adds a listener for incoming messages.\n   */\n  addEventListener(type: \"message\", listener: (event: { data: unknown }) => void): void;\n  /**\n   * Removes a listener added with `addEventListener`.\n   */\n  removeEventListener(type: \"message\", listener: (event: { data: unknown }) => void): void;\n  /**\n   * Closes the channel object.\n   */\n  close(): void;\n}\n\n/**\n * A transport over a `BroadcastChannel`, for a panel in another tab or window of the same origin.\n * Several panels can listen to one agent; each message goes to all of them.\n *\n * @param name Channel name. Both sides use the same.\n * @param factory Creates the channel (default `new BroadcastChannel(name)`).\n * @returns The transport.\n * @example\n * import { connectRemote, createBroadcastChannelTransport } from \"@shadow-js/devtools\";\n * const backend = connectRemote(createBroadcastChannelTransport(\"shadowjs-devtools\"));\n * await backend.ready;\n * @since 1.0.0\n */\nexport function createBroadcastChannelTransport(\n  name: string,\n  factory: (name: string) => BroadcastChannelLike = (n) => new BroadcastChannel(n),\n): Transport {\n  const channel = factory(name);\n  return {\n    send(message): void {\n      channel.postMessage(message);\n    },\n    listen(handler): () => void {\n      const listener = (event: { data: unknown }): void => handler(event.data);\n      channel.addEventListener(\"message\", listener);\n      return () => channel.removeEventListener(\"message\", listener);\n    },\n    close(): void {\n      channel.close();\n    },\n  };\n}\n\n/**\n * Options of {@link serveAgent}: the page-side hooks and the batch size.\n *\n * @since 1.0.0\n */\nexport interface ServeOptions extends PageHooks {\n  /**\n   * Largest event batch sent in one message.\n   *\n   * @default 2000\n   */\n  batch?: number;\n}\n\n/**\n * Exposes an agent over a transport: forwards its event stream to the panel and answers the panel's\n * requests. The agent keeps recording while no panel listens, and the stream is sent regardless. What\n * happens to events nobody receives depends on the transport. A `highlight` request is passed to\n * `options.highlight` and answered without reaching the agent. Stop serving with the returned function.\n *\n * @param agent The agent in the inspected page.\n * @param transport The channel to the panel.\n * @param options Page-side behavior (highlight overlay) and batch size.\n * @returns A function that stops serving.\n * @example\n * import { createAgent, createMemoryTransportPair, serveAgent } from \"@shadow-js/devtools\";\n * const [pageSide] = createMemoryTransportPair();\n * const stop = serveAgent(createAgent(), pageSide, { highlight: (id) => console.log(\"highlight\", id) });\n * stop();\n * @since 1.0.0\n */\nexport function serveAgent(\n  agent: Agent,\n  transport: Transport,\n  options: ServeOptions = {},\n): () => void {\n  const limit = options.batch ?? 2000;\n  const send = (message: AgentMessage): void => transport.send(message);\n  const stopListening = transport.listen((raw) => {\n    if (!isPanelMessage(raw)) return;\n    if (raw.type === \"hello\") {\n      send({ channel: CHANNEL, v: PROTOCOL_VERSION, from: \"agent\", type: \"hello\" });\n      return;\n    }\n    const { request } = raw;\n    let response: AgentResponse;\n    if (request.type === \"highlight\") {\n      options.highlight?.(request.id);\n      response = { ok: true, result: null };\n    } else {\n      response = agent.handle(request);\n    }\n    send({\n      channel: CHANNEL,\n      v: PROTOCOL_VERSION,\n      from: \"agent\",\n      type: \"response\",\n      id: raw.id,\n      response,\n    });\n  });\n  const stopStreaming = agent.subscribe((events) => {\n    for (let i = 0; i < events.length; i += limit) {\n      send({\n        channel: CHANNEL,\n        v: PROTOCOL_VERSION,\n        from: \"agent\",\n        type: \"events\",\n        events: events.slice(i, i + limit) as WireEvent[],\n      });\n    }\n  });\n  return () => {\n    stopListening();\n    stopStreaming();\n  };\n}\n\n/**\n * Options of {@link connectRemote}.\n *\n * @since 1.0.0\n */\nexport interface RemoteOptions {\n  /**\n   * Capacities of the panel's copy of the model (see {@link ModelLimits}). Fields that are not set keep\n   * their defaults.\n   */\n  limits?: Partial<ModelLimits>;\n}\n\n/**\n * Connects a panel to a remote agent: asks for the complete state, then applies the event stream\n * to a local model. Events that arrive before the state are buffered, and the ones the state already\n * contains are skipped (sequence numbers), so no event is lost or applied twice. Disposing the backend\n * closes the transport.\n *\n * @param transport The channel to the agent.\n * @param options Model limits.\n * @returns A {@link Backend}.\n * @example\n * import { connectRemote, createBroadcastChannelTransport } from \"@shadow-js/devtools\";\n * const backend = connectRemote(createBroadcastChannelTransport(\"shadowjs-devtools\"));\n * await backend.ready;\n * @since 1.0.0\n */\nexport function connectRemote(transport: Transport, options: RemoteOptions = {}): Backend {\n  const model = new InspectorModel(options.limits);\n  const listeners = new Set<() => void>();\n  const waiting = new Map<\n    number,\n    { resolve: (response: AgentResponse) => void; reject: (error: Error) => void }\n  >();\n  let buffered: WireEvent[] = [];\n  let synced = false;\n  let nextRequest = 1;\n  let disposed = false;\n  let notifyScheduled = false;\n  let resolveReady: () => void = () => undefined;\n  const ready = new Promise<void>((resolve) => {\n    resolveReady = resolve;\n  });\n\n  const notify = (): void => {\n    if (notifyScheduled) return;\n    notifyScheduled = true;\n    queueMicrotask(() => {\n      notifyScheduled = false;\n      if (disposed) return;\n      for (const listener of listeners) listener();\n    });\n  };\n\n  const send = (message: PanelMessage): void => transport.send(message);\n\n  const applyState = (state: ModelState): void => {\n    model.importState(state);\n    synced = true;\n    const pending = buffered;\n    buffered = [];\n    for (const event of pending) model.apply(event);\n    resolveReady();\n    notify();\n  };\n\n  const request = (req: AgentRequest): Promise<AgentResponse> => {\n    if (disposed) return Promise.reject(new Error(\"The devtools backend was disposed.\"));\n    const id = nextRequest;\n    nextRequest += 1;\n    return new Promise<AgentResponse>((resolve, reject) => {\n      waiting.set(id, { resolve, reject });\n      send({\n        channel: CHANNEL,\n        v: PROTOCOL_VERSION,\n        from: \"panel\",\n        type: \"request\",\n        id,\n        request: req,\n      });\n    });\n  };\n\n  const stop = transport.listen((raw) => {\n    if (!isAgentMessage(raw)) return;\n    if (raw.v !== PROTOCOL_VERSION) return;\n    if (raw.type === \"events\") {\n      if (!synced) {\n        buffered.push(...raw.events);\n        return;\n      }\n      for (const event of raw.events) model.apply(event);\n      notify();\n      return;\n    }\n    if (raw.type === \"response\") {\n      const entry = waiting.get(raw.id);\n      if (entry === undefined) return;\n      waiting.delete(raw.id);\n      entry.resolve(raw.response);\n    }\n  });\n\n  const sync = (): void => {\n    void request({ type: \"snapshot\" }).then(\n      (response) => {\n        if (response.ok) applyState(response.result as ModelState);\n      },\n      () => {\n        // The only rejection is dispose(): there is nothing left to synchronize.\n        synced = false;\n      },\n    );\n  };\n\n  send({ channel: CHANNEL, v: PROTOCOL_VERSION, from: \"panel\", type: \"hello\" });\n  sync();\n\n  return {\n    model,\n    ready,\n    subscribe(listener): () => void {\n      listeners.add(listener);\n      return () => {\n        listeners.delete(listener);\n      };\n    },\n    request(req): Promise<AgentResponse> {\n      if (req.type === \"clear\") {\n        // A clear empties the agent; the panel's copy must follow.\n        return request(req).then((response) => {\n          if (response.ok) {\n            synced = false;\n            sync();\n          }\n          return response;\n        });\n      }\n      return request(req);\n    },\n    dispose(): void {\n      disposed = true;\n      stop();\n      listeners.clear();\n      for (const entry of waiting.values())\n        entry.reject(new Error(\"The devtools backend was disposed.\"));\n      waiting.clear();\n      transport.close();\n    },\n  };\n}\n"],"mappings":"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"}