@shadow-js/devtools 0.0.0-stage → 1.0.1

package/dist/dev/transport.d.ts

@@ -0,0 +1,347 @@
+import { WireEvent } from "./protocol.js";
+import { ModelLimits } from "./model.js";
+import { Agent, AgentRequest, AgentResponse } from "./agent.js";
+import { Backend, PageHooks } from "./backend.js";
+//#region src/transport.d.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
+ */
+export declare const CHANNEL = "shadowjs-devtools";
+/**
+ * A message the agent side sends to the panel: the answer to a `hello`, a batch of events, or the
+ * answer to a request. All fields are plain data.
+ *
+ * @since 1.0.0
+ */
+export type AgentMessage = {
+  channel: typeof CHANNEL;
+  v: number;
+  from: "agent";
+  type: "hello";
+} | {
+  channel: typeof CHANNEL;
+  v: number;
+  from: "agent";
+  type: "events";
+  events: WireEvent[];
+} | {
+  channel: typeof CHANNEL;
+  v: number;
+  from: "agent";
+  type: "response";
+  id: number;
+  response: AgentResponse;
+};
+/**
+ * A message the panel side sends to the agent: a `hello`, or a request. The agent answers a request
+ * with a `response` that carries the same `id`. All fields are plain data.
+ *
+ * @since 1.0.0
+ */
+export type PanelMessage = {
+  channel: typeof CHANNEL;
+  v: number;
+  from: "panel";
+  type: "hello";
+} | {
+  channel: typeof CHANNEL;
+  v: number;
+  from: "panel";
+  type: "request";
+  id: number;
+  request: AgentRequest;
+};
+/**
+ * A duplex channel of plain messages. Implementations must deliver messages in order; they need not
+ * be synchronous. `postMessage`, `MessagePort` and `BroadcastChannel` adapters are provided.
+ *
+ * @since 1.0.0
+ */
+export interface Transport {
+  /**
+   * Sends a message to the other end. The message must be plain data that can be structured-cloned.
+   */
+  send(message: unknown): void;
+  /**
+   * Starts delivering incoming messages to `handler`, in order.
+   *
+   * @returns A function that stops this listener.
+   */
+  listen(handler: (message: unknown) => void): () => void;
+  /**
+   * Releases what the transport holds. Closing a port or a `BroadcastChannel` closes it; a window
+   * transport holds nothing and does nothing.
+   */
+  close(): void;
+}
+/**
+ * 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
+ */
+export declare function isAgentMessage(value: unknown): value is AgentMessage;
+/**
+ * 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
+ */
+export declare function isPanelMessage(value: unknown): value is PanelMessage;
+/**
+ * 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
+ */
+export declare function createMemoryTransportPair(): [Transport, Transport];
+/**
+ * The part of a `MessagePort` the adapter uses. A `MessageChannel` end, a worker port and an
+ * extension port all fit this shape.
+ *
+ * @since 1.0.0
+ */
+export interface MessagePortLike {
+  /**
+   * Posts a message to the other end of the port.
+   */
+  postMessage(message: unknown): void;
+  /**
+   * Adds a listener for incoming messages.
+   */
+  addEventListener(type: "message", listener: (event: {
+    data: unknown;
+  }) => void): void;
+  /**
+   * Removes a listener added with `addEventListener`.
+   */
+  removeEventListener(type: "message", listener: (event: {
+    data: unknown;
+  }) => void): void;
+  /**
+   * Starts the port. The adapter calls it after it adds a listener. Optional.
+   */
+  start?(): void;
+  /**
+   * Closes the port. Optional.
+   */
+  close?(): void;
+}
+/**
+ * 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
+ */
+export declare function createPortTransport(port: MessagePortLike): Transport;
+/**
+ * The part of a `Window` the adapter uses: its `postMessage`. A `WindowProxy` such as
+ * `iframe.contentWindow` fits this shape.
+ *
+ * @since 1.0.0
+ */
+export interface WindowLike {
+  /**
+   * Posts a message to the window. The adapter always passes a real origin as `targetOrigin`.
+   */
+  postMessage(message: unknown, targetOrigin: string): void;
+}
+/**
+ * The part of the receiving window the adapter uses: its `message` listeners. `globalThis` in a page
+ * or a frame fits this shape.
+ *
+ * @since 1.0.0
+ */
+export interface WindowEvents {
+  /**
+   * Adds a listener for `message` events.
+   */
+  addEventListener(type: "message", listener: (event: MessageEvent) => void): void;
+  /**
+   * Removes a listener added with `addEventListener`.
+   */
+  removeEventListener(type: "message", listener: (event: MessageEvent) => void): void;
+}
+/**
+ * Options of {@link createWindowTransport}.
+ *
+ * @since 1.0.0
+ */
+export interface WindowTransportOptions {
+  /**
+   * The window to talk to: the page being inspected, or the panel's frame.
+   */
+  target: WindowLike;
+  /**
+   * The origin of `target`. It is used as `targetOrigin` and to check where messages come from. Never
+   * `"*"`: {@link createWindowTransport} refuses it.
+   */
+  origin: string;
+  /**
+   * Where messages arrive.
+   *
+   * @default globalThis
+   */
+  receiver?: WindowEvents;
+}
+/**
+ * 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
+ */
+export declare function createWindowTransport(options: WindowTransportOptions): Transport;
+/**
+ * The part of `BroadcastChannel` the adapter uses.
+ *
+ * @since 1.0.0
+ */
+export interface BroadcastChannelLike {
+  /**
+   * Posts a message to every other channel object with the same name.
+   */
+  postMessage(message: unknown): void;
+  /**
+   * Adds a listener for incoming messages.
+   */
+  addEventListener(type: "message", listener: (event: {
+    data: unknown;
+  }) => void): void;
+  /**
+   * Removes a listener added with `addEventListener`.
+   */
+  removeEventListener(type: "message", listener: (event: {
+    data: unknown;
+  }) => void): void;
+  /**
+   * Closes the channel object.
+   */
+  close(): void;
+}
+/**
+ * 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
+ */
+export declare function createBroadcastChannelTransport(name: string, factory?: (name: string) => BroadcastChannelLike): Transport;
+/**
+ * Options of {@link serveAgent}: the page-side hooks and the batch size.
+ *
+ * @since 1.0.0
+ */
+export interface ServeOptions extends PageHooks {
+  /**
+   * Largest event batch sent in one message.
+   *
+   * @default 2000
+   */
+  batch?: number;
+}
+/**
+ * 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
+ */
+export declare function serveAgent(agent: Agent, transport: Transport, options?: ServeOptions): () => void;
+/**
+ * Options of {@link connectRemote}.
+ *
+ * @since 1.0.0
+ */
+export interface RemoteOptions {
+  /**
+   * Capacities of the panel's copy of the model (see {@link ModelLimits}). Fields that are not set keep
+   * their defaults.
+   */
+  limits?: Partial<ModelLimits>;
+}
+/**
+ * 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
+ */
+export declare function connectRemote(transport: Transport, options?: RemoteOptions): Backend;
+//#endregion
+//# sourceMappingURL=transport.d.ts.map