@unbound-app/debugger-protocol 1.0.2 → 2.0.1

package/dist/controller.d.mts

@@ -1,6 +1,10 @@
-import { l as EvalResult, m as PushedAddonKind, o as DeviceInfo, p as PluginPushResult } from "./index-DdSiZNoR.mjs";
+import { g as PushedAddonKind, h as PushResult, s as DeviceInfo, u as EvalResult } from "./index-DwVwBIbm.mjs";
 import { PushedManifest } from "@unbound-app/types";
-type PluginPush = {
+/**
+ * The controller half of the bridge: dials the `?mcp` endpoint and settles id-correlated evals
+ * against the results the bridge routes back. Reconnects so it outlives bridge restarts.
+ */
+type AddonPush = {
   addonId: string;
   kind?: PushedAddonKind;
   bundle: string;
@@ -10,6 +14,7 @@ type PluginPush = {
 };
 export declare class ControllerClient {
   private ws;
+  /** Each pending eval keeps the console output seen since its dispatch, so side effects surface too. */
   private readonly pending;
   private readonly pendingPushes;
   private deviceConnected;
@@ -21,7 +26,6 @@ export declare class ControllerClient {
   connect(): void;
   /** @description Tears the client down and fails any in-flight evals. Twin of {@link connect}. */
   close(): void;
-  /** @description Whether a device is currently connected to the bridge. */
   get isDeviceConnected(): boolean;
   /** @description What the connected device reported about itself in its hello, once it has said hello. */
   get device(): DeviceInfo | undefined;
@@ -37,9 +41,9 @@ export declare class ControllerClient {
    * @description Pushes a freshly built plugin or theme to the device via the bridge and resolves with the
    * device's reload outcome. Fails fast if the socket isn't open or the bridge doesn't answer in time.
    * @param push The addon id plus the built bundle and manifest to swap in.
-   * @returns The device's {@link PluginPushResult}.
+   * @returns The device's {@link PushResult}.
    */
-  pushPlugin(push: PluginPush): Promise<PluginPushResult>;
+  pushAddon(push: AddonPush): Promise<PushResult>;
   private onMessage;
   private onClose;
 }

package/dist/controller.mjs

@@ -1,13 +1,12 @@
-import { MAX_EVAL_TIMEOUT_MS, parseMessage, serializeMessage } from "./index.mjs";
+import { c as resolveEvalTimeout, l as serializeMessage, o as PUSH_TIMEOUT_MS, s as parseMessage, t as BRIDGE_REPLY_GRACE_MS } from "./src-D0Oi4NXs.mjs";
+import { PendingRequests } from "./pending-requests.mjs";
 // src/controller.ts
-const EVAL_RESULT_GRACE_MS = 5e3;
-const PLUGIN_PUSH_TIMEOUT_MS = 75e3;
-/** How long to wait between reconnection attempts when the bridge is unreachable. */
 const RECONNECT_DELAY_MS = 1e3;
 var ControllerClient = class {
 	ws = null;
-	pending = /* @__PURE__ */ new Map();
-	pendingPushes = /* @__PURE__ */ new Map();
+	/** Each pending eval keeps the console output seen since its dispatch, so side effects surface too. */
+	pending = new PendingRequests();
+	pendingPushes = new PendingRequests();
 	deviceConnected = false;
 	deviceInfo;
 	closed = false;
@@ -27,29 +26,21 @@ var ControllerClient = class {
 	close() {
 		this.closed = true;
 		this.ws?.close();
-		for (const [id, entry] of this.pending) {
-			clearTimeout(entry.timer);
-			entry.resolve({
-				type: "eval-result",
-				id,
-				ok: false,
-				error: "Debugger client shut down.",
-				logs: entry.logs
-			});
-		}
-		for (const [id, entry] of this.pendingPushes) {
-			clearTimeout(entry.timer);
-			entry.resolve({
-				type: "plugin-push-result",
-				id,
-				ok: false,
-				error: "Debugger client shut down."
-			});
-		}
-		this.pending.clear();
-		this.pendingPushes.clear();
+		this.pending.failAll((id) => ({
+			type: "eval-result",
+			id,
+			ok: false,
+			error: "Debugger client shut down.",
+			code: "shut-down"
+		}));
+		this.pendingPushes.failAll((id) => ({
+			type: "plugin-push-result",
+			id,
+			ok: false,
+			error: "Debugger client shut down.",
+			code: "shut-down"
+		}));
 	}
-	/** @description Whether a device is currently connected to the bridge. */
 	get isDeviceConnected() {
 		return this.deviceConnected;
 	}
@@ -72,26 +63,27 @@ var ControllerClient = class {
 					type: "eval-result",
 					id,
 					ok: false,
-					error: "Not connected to the debugger bridge."
+					error: "Not connected to the debugger bridge.",
+					code: "bridge-unreachable"
 				});
 				return;
 			}
 			const logs = [];
-			const limit = Math.min(timeout ?? 1e4, MAX_EVAL_TIMEOUT_MS);
-			const timer = setTimeout(() => {
-				this.pending.delete(id);
-				resolve({
+			const limit = resolveEvalTimeout(timeout);
+			this.pending.add(id, {
+				settle: (result) => resolve({
+					...result,
+					logs
+				}),
+				timeoutMs: limit + BRIDGE_REPLY_GRACE_MS,
+				onTimeout: () => ({
 					type: "eval-result",
 					id,
 					ok: false,
 					error: `Evaluation timed out after ${limit}ms.`,
-					logs
-				});
-			}, limit + EVAL_RESULT_GRACE_MS);
-			this.pending.set(id, {
-				resolve,
-				timer,
-				logs
+					code: "timeout"
+				}),
+				meta: logs
 			});
 			this.ws.send(serializeMessage(timeout === void 0 ? {
 				type: "eval",
@@ -109,9 +101,9 @@ var ControllerClient = class {
 	* @description Pushes a freshly built plugin or theme to the device via the bridge and resolves with the
 	* device's reload outcome. Fails fast if the socket isn't open or the bridge doesn't answer in time.
 	* @param push The addon id plus the built bundle and manifest to swap in.
-	* @returns The device's {@link PluginPushResult}.
+	* @returns The device's {@link PushResult}.
 	*/
-	pushPlugin(push) {
+	pushAddon(push) {
 		const id = crypto.randomUUID();
 		return new Promise((resolve) => {
 			if (this.ws?.readyState !== WebSocket.OPEN) {
@@ -119,22 +111,22 @@ var ControllerClient = class {
 					type: "plugin-push-result",
 					id,
 					ok: false,
-					error: "Not connected to the debugger bridge."
+					error: "Not connected to the debugger bridge.",
+					code: "bridge-unreachable"
 				});
 				return;
 			}
-			const timer = setTimeout(() => {
-				this.pendingPushes.delete(id);
-				resolve({
+			this.pendingPushes.add(id, {
+				settle: resolve,
+				timeoutMs: PUSH_TIMEOUT_MS + BRIDGE_REPLY_GRACE_MS,
+				onTimeout: () => ({
 					type: "plugin-push-result",
 					id,
 					ok: false,
-					error: `Plugin push timed out after ${PLUGIN_PUSH_TIMEOUT_MS}ms.`
-				});
-			}, PLUGIN_PUSH_TIMEOUT_MS);
-			this.pendingPushes.set(id, {
-				resolve,
-				timer
+					error: `Push timed out after ${PUSH_TIMEOUT_MS}ms.`,
+					code: "timeout"
+				}),
+				meta: void 0
 			});
 			this.ws.send(serializeMessage({
 				type: "plugin-push",
@@ -152,26 +144,15 @@ var ControllerClient = class {
 			return;
 		}
 		if (message.type === "log") {
-			for (const entry of this.pending.values()) entry.logs.push(message);
+			for (const logs of this.pending.metas()) logs.push(message);
 			return;
 		}
 		if (message.type === "eval-result") {
-			const entry = this.pending.get(message.id);
-			if (!entry) return;
-			clearTimeout(entry.timer);
-			this.pending.delete(message.id);
-			entry.resolve({
-				...message,
-				logs: entry.logs
-			});
+			this.pending.resolve(message.id, message);
 			return;
 		}
 		if (message.type !== "plugin-push-result") return;
-		const entry = this.pendingPushes.get(message.id);
-		if (!entry) return;
-		clearTimeout(entry.timer);
-		this.pendingPushes.delete(message.id);
-		entry.resolve(message);
+		this.pendingPushes.resolve(message.id, message);
 	}
 	onClose() {
 		this.ws = null;

package/dist/index-DwVwBIbm.d.mts

@@ -0,0 +1,234 @@
+import { PushedManifest } from "@unbound-app/types";
+/**
+ * React DevTools over the debugger socket: the device's backend and the frontend (the DevTools app's
+ * controller) swap React DevTools' own `{ event, payload }` messages, each wrapped in one frame.
+ */
+/** Device ↔ bridge ↔ the frontend controller: one React DevTools message. */
+type ReactDevtoolsFrame = {
+  type: 'react-devtools';
+  event: string;
+  payload?: unknown;
+};
+/** The payload of {@link REACT_DEVTOOLS_STATUS_EVENT}. */
+type ReactDevtoolsStatus = {
+  connected: boolean;
+  /** Why the backend is unavailable, such as the loader not having run it. */
+  error?: string;
+};
+/**
+ * The event the device sends the frontend, with a {@link ReactDevtoolsStatus}, when its backend
+ * starts a session, cannot start one, or ends one.
+ */
+declare const REACT_DEVTOOLS_STATUS_EVENT = "unbound:backend-status";
+/** React DevTools' own event that ends a backend session; the bridge sends it when the frontend leaves. */
+declare const REACT_DEVTOOLS_SHUTDOWN_EVENT = "shutdown";
+/**
+ * The view finder's frames: a controller asks the device for one level of its native view tree at a
+ * time, and names the view the device should outline on screen.
+ */
+/** A rectangle in screen coordinates, in dp on Android and points on iOS. */
+type ViewFrame = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+};
+/** One native view, with only its top-level properties. */
+type ViewNode = {
+  /** The device's id for the view, valid until the next request for the roots. */
+  id: string;
+  /** The fully qualified Java class name, or the Objective-C class name. */
+  className: string;
+  /** The Android resource entry name of the view's id, or the iOS accessibility identifier. */
+  resourceName: string | null;
+  frame: ViewFrame;
+  visibility: 'visible' | 'invisible' | 'gone';
+  /** The view's opacity from 0 to 1, or `null` when the platform did not report it. */
+  alpha: number | null;
+  /** The text a text view shows, cut to a few hundred characters. */
+  text: string | null;
+  /** How many direct children the view has. */
+  childCount: number;
+};
+/** Controller → bridge → device: list the children of `parent`, or the root views when it is omitted. */
+type ViewsRequest = {
+  type: 'views-request';
+  /** Correlation id echoed back on the matching {@link ViewsResult}. */
+  id: string;
+  parent?: string;
+};
+/** The answer to a {@link ViewsRequest}, sent device → bridge → the controller that asked. */
+type ViewsResult = {
+  type: 'views-result';
+  /** The `id` of the {@link ViewsRequest} this answers. */
+  id: string;
+} & ({
+  ok: true;
+  nodes: ViewNode[];
+} | {
+  ok: false;
+  error: string;
+});
+/** Controller → bridge → device: outline the view with this id on screen, or clear the outline when `null`. */
+type ViewHighlight = {
+  type: 'view-highlight';
+  node: string | null;
+};
+/**
+ * The wire protocol shared by the bridge, the device and controllers: every frame is a JSON-encoded
+ * {@link BridgeMessage}. Dependency-free at runtime so the React Native client can bundle it.
+ */
+/** A request to evaluate code on the device, sent controller → bridge → device. */
+type EvalRequest = {
+  type: 'eval';
+  /** Correlation id echoed back on the matching {@link EvalResult}. */
+  id: string;
+  code: string;
+  timeout?: number;
+};
+/**
+ * Why a request failed before the device answered it, so callers branch on a code instead of the error text.
+ */
+type RequestFailureCode =
+/** The bridge has no device. */
+'no-device' |
+/** The device dropped mid-request. */
+'device-disconnected' | 'timeout' |
+/** The controller has no socket to the bridge. */
+'bridge-unreachable' |
+/** The controller closed. */
+'shut-down';
+/** The outcome of an {@link EvalRequest}, sent device → bridge → the one waiting controller. */
+type EvalResult = {
+  type: 'eval-result';
+  /** The `id` of the {@link EvalRequest} this answers. */
+  id: string;
+  /**
+   * Console output captured during this eval, so callers see its side effects too. Populated by
+   * the controller that owns the request, not sent by the device.
+   */
+  logs?: LogMessage[];
+} & ({
+  ok: true;
+  /** The inspected return value. */
+  value: string;
+} | {
+  ok: false;
+  /** The inspected error. */
+  error: string;
+  /** Set when the bridge or controller failed the eval; absent when the code itself threw on the device. */
+  code?: RequestFailureCode;
+});
+/** The addon managers a push can reload into. */
+type PushedAddonKind = 'plugin' | 'theme';
+/**
+ * A request to hot-reload a plugin or theme on the device, sent controller → bridge → device. Carries
+ * the freshly built bundle and manifest so the device swaps them in without a re-fetch.
+ */
+type PushRequest = {
+  type: 'plugin-push';
+  /** Correlation id echoed back on the matching {@link PushResult}. */
+  id: string;
+  addonId: string;
+  /** Which manager reloads the addon; a plugin when omitted, as pushes from older CLIs are. */
+  kind?: PushedAddonKind;
+  bundle: string;
+  /** The manifest as authored; the device validates it before swapping anything in. */
+  manifest: PushedManifest;
+  /** The bundle compiled to Hermes bytecode, base64-encoded, by bytecode version; its digests are in `manifest.bytecode`. */
+  bytecode?: Record<string, string>;
+  /** Each extra file the manifest lists beside the bundle, such as an image, base64-encoded, by path. */
+  files?: Record<string, string>;
+};
+/** The outcome of a {@link PushRequest}, sent device → bridge → the one waiting controller. */
+type PushResult = {
+  type: 'plugin-push-result';
+  /** The `id` of the {@link PushRequest} this answers. */
+  id: string;
+} & ({
+  ok: true;
+} | {
+  ok: false;
+  /** The reload failure, inspected. */
+  error: string;
+  /** Set when the bridge or controller failed the push; absent when the device's reload failed. */
+  code?: RequestFailureCode;
+});
+/** A `console.*` / `nativeLoggingHook` line, streamed device → bridge → all controllers. */
+type LogMessage = {
+  type: 'log';
+  /** 1 = log/gray, 2 = warn/yellow, 3 = error/red. */
+  level: 1 | 2 | 3;
+  message: string;
+};
+/** What a device reports about itself when it connects. */
+type DeviceInfo = {
+  platform: string;
+  discordVersion: string;
+  loaderVersion: string;
+  clientVersion: string;
+};
+/** Device → bridge, once its socket opens, so the bridge can say which device is attached. */
+type DeviceHello = {
+  type: 'hello';
+  device: DeviceInfo;
+};
+/** Bridge → controller, once on attach and whenever the device connects, drops or says hello. */
+type DeviceStatus = {
+  type: 'device-status';
+} & ({
+  connected: false;
+} | {
+  connected: true;
+  /** Present once the connected device has said hello. */
+  device?: DeviceInfo;
+});
+/** Every framed message on the wire. */
+type BridgeMessage = EvalRequest | EvalResult | PushRequest | PushResult | LogMessage | DeviceHello | DeviceStatus | ViewsRequest | ViewsResult | ViewHighlight | ReactDevtoolsFrame;
+/** The default port the bridge listens on and controllers dial. */
+declare const DEFAULT_BRIDGE_PORT = 9090;
+declare const DEFAULT_EVAL_TIMEOUT_MS = 10000;
+declare const MAX_EVAL_TIMEOUT_MS = 86400000;
+/** How long the bridge waits for the device to reload a pushed addon. */
+declare const PUSH_TIMEOUT_MS = 60000;
+/**
+ * How much longer a controller waits than the bridge, so the bridge's own timeout reply always
+ * arrives before the controller gives up on its own.
+ */
+declare const BRIDGE_REPLY_GRACE_MS = 5000;
+/**
+ * @description Picks how long an eval may run: the requested timeout when it is a positive number of
+ * milliseconds, capped at {@link MAX_EVAL_TIMEOUT_MS}, otherwise {@link DEFAULT_EVAL_TIMEOUT_MS}.
+ * @param requested The timeout the controller asked for, if any.
+ * @returns The timeout to apply, in milliseconds.
+ */
+declare function resolveEvalTimeout(requested: number | undefined): number;
+/** The query marker a controller appends to its URL so the bridge routes it as a controller, not a device. */
+declare const CONTROLLER_ENDPOINT_MARKER = "mcp";
+/**
+ * @description Safely parses a raw wire frame into a {@link BridgeMessage}, guarding against invalid
+ * JSON and unknown shapes so both ends can trust what they route.
+ * @param raw The JSON string received off the socket.
+ * @returns The parsed message, or `undefined` if it isn't a recognised frame.
+ */
+declare function parseMessage(raw: string): BridgeMessage | undefined;
+/**
+ * @description Serialises a {@link BridgeMessage} into its wire form. Inverse of {@link parseMessage}.
+ * @param message The message to frame.
+ * @returns The JSON string to send over the socket.
+ */
+declare function serializeMessage(message: BridgeMessage): string;
+declare const _default: {
+  DEFAULT_BRIDGE_PORT: number;
+  DEFAULT_EVAL_TIMEOUT_MS: number;
+  MAX_EVAL_TIMEOUT_MS: number;
+  PUSH_TIMEOUT_MS: number;
+  BRIDGE_REPLY_GRACE_MS: number;
+  CONTROLLER_ENDPOINT_MARKER: string;
+  REACT_DEVTOOLS_SHUTDOWN_EVENT: string;
+  REACT_DEVTOOLS_STATUS_EVENT: string;
+  resolveEvalTimeout: typeof resolveEvalTimeout;
+  parseMessage: typeof parseMessage;
+  serializeMessage: typeof serializeMessage;
+};
+export { ReactDevtoolsStatus as A, ViewHighlight as C, REACT_DEVTOOLS_SHUTDOWN_EVENT as D, ViewsResult as E, REACT_DEVTOOLS_STATUS_EVENT as O, ViewFrame as S, ViewsRequest as T, RequestFailureCode as _, DEFAULT_EVAL_TIMEOUT_MS as a, resolveEvalTimeout as b, DeviceStatus as c, LogMessage as d, MAX_EVAL_TIMEOUT_MS as f, PushedAddonKind as g, PushResult as h, DEFAULT_BRIDGE_PORT as i, ReactDevtoolsFrame as k, EvalRequest as l, PushRequest as m, BridgeMessage as n, DeviceHello as o, PUSH_TIMEOUT_MS as p, CONTROLLER_ENDPOINT_MARKER as r, DeviceInfo as s, BRIDGE_REPLY_GRACE_MS as t, EvalResult as u, _default as v, ViewNode as w, serializeMessage as x, parseMessage as y };

package/dist/index.d.mts

@@ -1,2 +1,2 @@
-import { _ as serializeMessage, a as DeviceHello, c as EvalRequest, d as MAX_EVAL_TIMEOUT_MS, f as PluginPushRequest, g as parseMessage, h as _default, i as DEFAULT_EVAL_TIMEOUT_MS, l as EvalResult, m as PushedAddonKind, n as CONTROLLER_ENDPOINT_MARKER, o as DeviceInfo, p as PluginPushResult, r as DEFAULT_BRIDGE_PORT, s as DeviceStatus, t as BridgeMessage, u as LogMessage } from "./index-DdSiZNoR.mjs";
-export { BridgeMessage, CONTROLLER_ENDPOINT_MARKER, DEFAULT_BRIDGE_PORT, DEFAULT_EVAL_TIMEOUT_MS, DeviceHello, DeviceInfo, DeviceStatus, EvalRequest, EvalResult, LogMessage, MAX_EVAL_TIMEOUT_MS, PluginPushRequest, PluginPushResult, PushedAddonKind, _default as default, parseMessage, serializeMessage };
+import { A as ReactDevtoolsStatus, C as ViewHighlight, D as REACT_DEVTOOLS_SHUTDOWN_EVENT, E as ViewsResult, O as REACT_DEVTOOLS_STATUS_EVENT, S as ViewFrame, T as ViewsRequest, _ as RequestFailureCode, a as DEFAULT_EVAL_TIMEOUT_MS, b as resolveEvalTimeout, c as DeviceStatus, d as LogMessage, f as MAX_EVAL_TIMEOUT_MS, g as PushedAddonKind, h as PushResult, i as DEFAULT_BRIDGE_PORT, k as ReactDevtoolsFrame, l as EvalRequest, m as PushRequest, n as BridgeMessage, o as DeviceHello, p as PUSH_TIMEOUT_MS, r as CONTROLLER_ENDPOINT_MARKER, s as DeviceInfo, t as BRIDGE_REPLY_GRACE_MS, u as EvalResult, v as _default, w as ViewNode, x as serializeMessage, y as parseMessage } from "./index-DwVwBIbm.mjs";
+export { BRIDGE_REPLY_GRACE_MS, BridgeMessage, CONTROLLER_ENDPOINT_MARKER, DEFAULT_BRIDGE_PORT, DEFAULT_EVAL_TIMEOUT_MS, DeviceHello, DeviceInfo, DeviceStatus, EvalRequest, EvalResult, LogMessage, MAX_EVAL_TIMEOUT_MS, PUSH_TIMEOUT_MS, PushRequest, PushResult, PushedAddonKind, REACT_DEVTOOLS_SHUTDOWN_EVENT, REACT_DEVTOOLS_STATUS_EVENT, type ReactDevtoolsFrame, type ReactDevtoolsStatus, RequestFailureCode, type ViewFrame, type ViewHighlight, type ViewNode, type ViewsRequest, type ViewsResult, _default as default, parseMessage, resolveEvalTimeout, serializeMessage };

package/dist/index.mjs

@@ -1,73 +1 @@
-// src/index.ts
-/** The default port the bridge listens on and controllers dial. */
-const DEFAULT_BRIDGE_PORT = 9090;
-const DEFAULT_EVAL_TIMEOUT_MS = 1e4;
-const MAX_EVAL_TIMEOUT_MS = 864e5;
-/** The query marker a controller appends to its URL so the bridge routes it as a controller, not a device. */
-const CONTROLLER_ENDPOINT_MARKER = "mcp";
-const MESSAGE_TYPES = /* @__PURE__ */ new Set([
-	"eval",
-	"eval-result",
-	"plugin-push",
-	"plugin-push-result",
-	"log",
-	"hello",
-	"device-status"
-]);
-/**
-* @description Safely parses a raw wire frame into a {@link BridgeMessage}, guarding against invalid
-* JSON and unknown shapes so both ends can trust what they route.
-* @param raw The JSON string received off the socket.
-* @returns The parsed message, or `undefined` if it isn't a recognised frame.
-*/
-function parseMessage(raw) {
-	let value;
-	try {
-		value = JSON.parse(raw);
-	} catch {
-		return;
-	}
-	return isBridgeMessage(value) ? value : void 0;
-}
-function hasRequiredFields(frame) {
-	if (typeof frame !== "object" || frame === null || !("type" in frame)) return false;
-	switch (frame.type) {
-		case "log": return "message" in frame && typeof frame.message === "string" && "level" in frame && (frame.level === 1 || frame.level === 2 || frame.level === 3);
-		case "eval": return "id" in frame && typeof frame.id === "string" && "code" in frame && typeof frame.code === "string";
-		case "eval-result": return "id" in frame && typeof frame.id === "string" && "ok" in frame && (frame.ok === true ? "value" in frame && typeof frame.value === "string" : frame.ok === false && hasError(frame));
-		case "plugin-push-result": return "id" in frame && typeof frame.id === "string" && "ok" in frame && (frame.ok === true || frame.ok === false && hasError(frame));
-		case "plugin-push": return "id" in frame && typeof frame.id === "string" && "addonId" in frame && typeof frame.addonId === "string" && (!("kind" in frame) || frame.kind === void 0 || frame.kind === "plugin" || frame.kind === "theme") && "bundle" in frame && typeof frame.bundle === "string" && "manifest" in frame && typeof frame.manifest === "object" && frame.manifest !== null && (!("bytecode" in frame) || frame.bytecode === void 0 || isStringRecord(frame.bytecode)) && (!("files" in frame) || frame.files === void 0 || isStringRecord(frame.files));
-		case "hello": return "device" in frame && isDeviceInfo(frame.device);
-		case "device-status": return "connected" in frame && (frame.connected === false || frame.connected === true && (!("device" in frame) || frame.device === void 0 || isDeviceInfo(frame.device)));
-		default: return false;
-	}
-}
-function hasError(frame) {
-	return typeof frame === "object" && frame !== null && "error" in frame && typeof frame.error === "string";
-}
-function isDeviceInfo(value) {
-	return typeof value === "object" && value !== null && "platform" in value && typeof value.platform === "string" && "discordVersion" in value && typeof value.discordVersion === "string" && "loaderVersion" in value && typeof value.loaderVersion === "string" && "clientVersion" in value && typeof value.clientVersion === "string";
-}
-function isStringRecord(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value) && Object.values(value).every((entry) => typeof entry === "string");
-}
-function isBridgeMessage(value) {
-	return typeof value === "object" && value !== null && "type" in value && typeof value.type === "string" && MESSAGE_TYPES.has(value.type) && hasRequiredFields(value);
-}
-/**
-* @description Serialises a {@link BridgeMessage} into its wire form. Inverse of {@link parseMessage}.
-* @param message The message to frame.
-* @returns The JSON string to send over the socket.
-*/
-function serializeMessage(message) {
-	return JSON.stringify(message);
-}
-var src_default = {
-	DEFAULT_BRIDGE_PORT,
-	DEFAULT_EVAL_TIMEOUT_MS,
-	MAX_EVAL_TIMEOUT_MS,
-	CONTROLLER_ENDPOINT_MARKER: "mcp",
-	parseMessage,
-	serializeMessage
-};
-export { CONTROLLER_ENDPOINT_MARKER, DEFAULT_BRIDGE_PORT, DEFAULT_EVAL_TIMEOUT_MS, MAX_EVAL_TIMEOUT_MS, src_default as default, parseMessage, serializeMessage };
+export { t as BRIDGE_REPLY_GRACE_MS, n as CONTROLLER_ENDPOINT_MARKER, r as DEFAULT_BRIDGE_PORT, i as DEFAULT_EVAL_TIMEOUT_MS, a as MAX_EVAL_TIMEOUT_MS, o as PUSH_TIMEOUT_MS, d as REACT_DEVTOOLS_SHUTDOWN_EVENT, f as REACT_DEVTOOLS_STATUS_EVENT, u as default, s as parseMessage, c as resolveEvalTimeout, l as serializeMessage } from "./src-D0Oi4NXs.mjs";

package/dist/pending-requests.d.mts

@@ -0,0 +1,42 @@
+/**
+ * Id-correlated requests awaiting a reply. Each settles exactly once: by its reply, its timeout, or
+ * a fail-all when its peer goes away. Used by both the bridge and the controller.
+ */
+type PendingRequest<R, M> = {
+  /** Receives the reply, the timeout result or the fail-all result. */
+  settle: (result: R) => void;
+  timeoutMs: number;
+  /** Builds the result delivered when the reply doesn't arrive in time. */
+  onTimeout: () => R;
+  /** Caller data kept with the request, such as the socket that issued it. */
+  meta: M;
+};
+export declare class PendingRequests<R, M = undefined> {
+  private readonly entries;
+  /**
+   * @description Tracks a request until its reply arrives or `timeoutMs` elapses.
+   * @param id The correlation id its reply will carry.
+   * @param request How to settle it, when to give up and what to keep with it.
+   */
+  add(id: string, { settle, timeoutMs, onTimeout, meta }: PendingRequest<R, M>): void;
+  /**
+   * @description Settles the request with this id, if one is still pending.
+   * @param id The reply's correlation id.
+   * @param result The result to deliver.
+   * @returns Whether a pending request took the result.
+   */
+  resolve(id: string, result: R): boolean;
+  /**
+   * @description Settles every pending request with a failure, so no caller waits forever.
+   * @param fail Builds each request's failure result from its id.
+   */
+  failAll(fail: (id: string) => R): void;
+  /**
+   * @description Drops matching requests without settling them, for when nobody is left to answer.
+   * @param matches Picks the requests to drop by their meta.
+   */
+  discard(matches: (meta: M) => boolean): void;
+  /** @description The meta of every pending request, in the order they were added. */
+  metas(): M[];
+}
+export {};

package/dist/pending-requests.mjs

@@ -0,0 +1,54 @@
+// src/pending-requests.ts
+var PendingRequests = class {
+	entries = /* @__PURE__ */ new Map();
+	/**
+	* @description Tracks a request until its reply arrives or `timeoutMs` elapses.
+	* @param id The correlation id its reply will carry.
+	* @param request How to settle it, when to give up and what to keep with it.
+	*/
+	add(id, { settle, timeoutMs, onTimeout, meta }) {
+		const timer = setTimeout(() => this.resolve(id, onTimeout()), timeoutMs);
+		this.entries.set(id, {
+			settle,
+			timer,
+			meta
+		});
+	}
+	/**
+	* @description Settles the request with this id, if one is still pending.
+	* @param id The reply's correlation id.
+	* @param result The result to deliver.
+	* @returns Whether a pending request took the result.
+	*/
+	resolve(id, result) {
+		const entry = this.entries.get(id);
+		if (!entry) return false;
+		clearTimeout(entry.timer);
+		this.entries.delete(id);
+		entry.settle(result);
+		return true;
+	}
+	/**
+	* @description Settles every pending request with a failure, so no caller waits forever.
+	* @param fail Builds each request's failure result from its id.
+	*/
+	failAll(fail) {
+		for (const id of this.entries.keys()) this.resolve(id, fail(id));
+	}
+	/**
+	* @description Drops matching requests without settling them, for when nobody is left to answer.
+	* @param matches Picks the requests to drop by their meta.
+	*/
+	discard(matches) {
+		for (const [id, entry] of this.entries) {
+			if (!matches(entry.meta)) continue;
+			clearTimeout(entry.timer);
+			this.entries.delete(id);
+		}
+	}
+	/** @description The meta of every pending request, in the order they were added. */
+	metas() {
+		return [...this.entries.values()].map((entry) => entry.meta);
+	}
+};
+export { PendingRequests };

package/dist/src-D0Oi4NXs.mjs

@@ -0,0 +1,139 @@
+// src/react-devtools.ts
+/**
+* The event the device sends the frontend, with a {@link ReactDevtoolsStatus}, when its backend
+* starts a session, cannot start one, or ends one.
+*/
+const REACT_DEVTOOLS_STATUS_EVENT = "unbound:backend-status";
+/** React DevTools' own event that ends a backend session; the bridge sends it when the frontend leaves. */
+const REACT_DEVTOOLS_SHUTDOWN_EVENT = "shutdown";
+/**
+* @description Checks the fields of a React DevTools frame whose `type` is already known.
+* @param frame The parsed frame.
+* @returns Whether the frame names an event.
+*/
+function isReactDevtoolsFrame(frame) {
+	return typeof frame === "object" && frame !== null && "event" in frame && typeof frame.event === "string";
+}
+// src/views.ts
+const VISIBILITIES = /* @__PURE__ */ new Set([
+	"visible",
+	"invisible",
+	"gone"
+]);
+function isObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNullableString(value) {
+	return value === null || typeof value === "string";
+}
+function isViewFrame(value) {
+	return isObject(value) && "x" in value && typeof value.x === "number" && "y" in value && typeof value.y === "number" && "width" in value && typeof value.width === "number" && "height" in value && typeof value.height === "number";
+}
+/**
+* @description Checks that a value has every field a {@link ViewNode} needs.
+* @param value The parsed value.
+* @returns Whether it is a view node.
+*/
+function isViewNode(value) {
+	return isObject(value) && "id" in value && typeof value.id === "string" && "className" in value && typeof value.className === "string" && "resourceName" in value && isNullableString(value.resourceName) && "frame" in value && isViewFrame(value.frame) && "visibility" in value && VISIBILITIES.has(value.visibility) && "alpha" in value && (value.alpha === null || typeof value.alpha === "number") && "text" in value && isNullableString(value.text) && "childCount" in value && typeof value.childCount === "number";
+}
+/**
+* @description Checks the fields of a view finder frame whose `type` is already known.
+* @param frame The parsed frame.
+* @returns Whether the frame is a valid view request, result or highlight.
+*/
+function isViewFrameMessage(frame) {
+	if (!isObject(frame) || !("type" in frame)) return false;
+	switch (frame.type) {
+		case "views-request": return "id" in frame && typeof frame.id === "string" && (!("parent" in frame) || frame.parent === void 0 || typeof frame.parent === "string");
+		case "views-result": return "id" in frame && typeof frame.id === "string" && "ok" in frame && (frame.ok === true ? "nodes" in frame && Array.isArray(frame.nodes) && frame.nodes.every(isViewNode) : frame.ok === false && "error" in frame && typeof frame.error === "string");
+		case "view-highlight": return "node" in frame && isNullableString(frame.node);
+		default: return false;
+	}
+}
+// src/index.ts
+/** The default port the bridge listens on and controllers dial. */
+const DEFAULT_BRIDGE_PORT = 9090;
+const DEFAULT_EVAL_TIMEOUT_MS = 1e4;
+const MAX_EVAL_TIMEOUT_MS = 864e5;
+/** How long the bridge waits for the device to reload a pushed addon. */
+const PUSH_TIMEOUT_MS = 6e4;
+/**
+* How much longer a controller waits than the bridge, so the bridge's own timeout reply always
+* arrives before the controller gives up on its own.
+*/
+const BRIDGE_REPLY_GRACE_MS = 5e3;
+/**
+* @description Picks how long an eval may run: the requested timeout when it is a positive number of
+* milliseconds, capped at {@link MAX_EVAL_TIMEOUT_MS}, otherwise {@link DEFAULT_EVAL_TIMEOUT_MS}.
+* @param requested The timeout the controller asked for, if any.
+* @returns The timeout to apply, in milliseconds.
+*/
+function resolveEvalTimeout(requested) {
+	return typeof requested === "number" && requested > 0 ? Math.min(requested, MAX_EVAL_TIMEOUT_MS) : DEFAULT_EVAL_TIMEOUT_MS;
+}
+/** The query marker a controller appends to its URL so the bridge routes it as a controller, not a device. */
+const CONTROLLER_ENDPOINT_MARKER = "mcp";
+/**
+* @description Safely parses a raw wire frame into a {@link BridgeMessage}, guarding against invalid
+* JSON and unknown shapes so both ends can trust what they route.
+* @param raw The JSON string received off the socket.
+* @returns The parsed message, or `undefined` if it isn't a recognised frame.
+*/
+function parseMessage(raw) {
+	let value;
+	try {
+		value = JSON.parse(raw);
+	} catch {
+		return;
+	}
+	return hasRequiredFields(value) ? value : void 0;
+}
+function hasRequiredFields(frame) {
+	if (typeof frame !== "object" || frame === null || !("type" in frame)) return false;
+	switch (frame.type) {
+		case "log": return "message" in frame && typeof frame.message === "string" && "level" in frame && (frame.level === 1 || frame.level === 2 || frame.level === 3);
+		case "eval": return "id" in frame && typeof frame.id === "string" && "code" in frame && typeof frame.code === "string";
+		case "eval-result": return "id" in frame && typeof frame.id === "string" && "ok" in frame && (frame.ok === true ? "value" in frame && typeof frame.value === "string" : frame.ok === false && hasError(frame));
+		case "plugin-push-result": return "id" in frame && typeof frame.id === "string" && "ok" in frame && (frame.ok === true || frame.ok === false && hasError(frame));
+		case "plugin-push": return "id" in frame && typeof frame.id === "string" && "addonId" in frame && typeof frame.addonId === "string" && (!("kind" in frame) || frame.kind === void 0 || frame.kind === "plugin" || frame.kind === "theme") && "bundle" in frame && typeof frame.bundle === "string" && "manifest" in frame && typeof frame.manifest === "object" && frame.manifest !== null && (!("bytecode" in frame) || frame.bytecode === void 0 || isStringRecord(frame.bytecode)) && (!("files" in frame) || frame.files === void 0 || isStringRecord(frame.files));
+		case "hello": return "device" in frame && isDeviceInfo(frame.device);
+		case "device-status": return "connected" in frame && (frame.connected === false || frame.connected === true && (!("device" in frame) || frame.device === void 0 || isDeviceInfo(frame.device)));
+		case "views-request":
+		case "views-result":
+		case "view-highlight": return isViewFrameMessage(frame);
+		case "react-devtools": return isReactDevtoolsFrame(frame);
+		default: return false;
+	}
+}
+function hasError(frame) {
+	return typeof frame === "object" && frame !== null && "error" in frame && typeof frame.error === "string";
+}
+function isDeviceInfo(value) {
+	return typeof value === "object" && value !== null && "platform" in value && typeof value.platform === "string" && "discordVersion" in value && typeof value.discordVersion === "string" && "loaderVersion" in value && typeof value.loaderVersion === "string" && "clientVersion" in value && typeof value.clientVersion === "string";
+}
+function isStringRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value) && Object.values(value).every((entry) => typeof entry === "string");
+}
+/**
+* @description Serialises a {@link BridgeMessage} into its wire form. Inverse of {@link parseMessage}.
+* @param message The message to frame.
+* @returns The JSON string to send over the socket.
+*/
+function serializeMessage(message) {
+	return JSON.stringify(message);
+}
+var src_default = {
+	DEFAULT_BRIDGE_PORT,
+	DEFAULT_EVAL_TIMEOUT_MS,
+	MAX_EVAL_TIMEOUT_MS,
+	PUSH_TIMEOUT_MS,
+	BRIDGE_REPLY_GRACE_MS,
+	CONTROLLER_ENDPOINT_MARKER: "mcp",
+	REACT_DEVTOOLS_SHUTDOWN_EVENT,
+	REACT_DEVTOOLS_STATUS_EVENT,
+	resolveEvalTimeout,
+	parseMessage,
+	serializeMessage
+};
+export { MAX_EVAL_TIMEOUT_MS as a, resolveEvalTimeout as c, REACT_DEVTOOLS_SHUTDOWN_EVENT as d, REACT_DEVTOOLS_STATUS_EVENT as f, DEFAULT_EVAL_TIMEOUT_MS as i, serializeMessage as l, CONTROLLER_ENDPOINT_MARKER as n, PUSH_TIMEOUT_MS as o, DEFAULT_BRIDGE_PORT as r, parseMessage as s, BRIDGE_REPLY_GRACE_MS as t, src_default as u };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@unbound-app/debugger-protocol",
-	"version": "1.0.2",
+	"version": "2.0.1",
 	"description": "The wire protocol and controller client shared by the debugger bridge, the on-device client, and the CLI.",
 	"author": {
 		"name": "Mario P.",
@@ -26,6 +26,10 @@
 			"types": "./dist/controller.d.mts",
 			"import": "./dist/controller.mjs"
 		},
+		"./pending-requests": {
+			"types": "./dist/pending-requests.d.mts",
+			"import": "./dist/pending-requests.mjs"
+		},
 		"./registry": {
 			"types": "./dist/registry.d.mts",
 			"import": "./dist/registry.mjs"

package/dist/index-DdSiZNoR.d.mts

@@ -1,124 +0,0 @@
-import { PushedManifest } from "@unbound-app/types";
-/**
- * The wire protocol shared by the bridge, the device and controllers: every frame is a JSON-encoded
- * {@link BridgeMessage}. Dependency-free at runtime so the React Native client can bundle it.
- */
-/** A request to evaluate code on the device, sent controller → bridge → device. */
-type EvalRequest = {
-  type: 'eval';
-  /** Correlation id echoed back on the matching {@link EvalResult}. */
-  id: string;
-  code: string;
-  timeout?: number;
-};
-/** The outcome of an {@link EvalRequest}, sent device → bridge → the one waiting controller. */
-type EvalResult = {
-  type: 'eval-result';
-  /** The `id` of the {@link EvalRequest} this answers. */
-  id: string;
-  /**
-   * Console output captured during this eval, so callers see its side effects too. Populated by
-   * the controller that owns the request, not sent by the device.
-   */
-  logs?: LogMessage[];
-} & ({
-  ok: true;
-  /** The inspected return value. */
-  value: string;
-} | {
-  ok: false;
-  /** The inspected error. */
-  error: string;
-});
-/** The addon managers a push can reload into. */
-type PushedAddonKind = 'plugin' | 'theme';
-/**
- * A request to hot-reload a plugin or theme on the device, sent controller → bridge → device. Carries
- * the freshly built bundle and manifest so the device swaps them in without a re-fetch.
- */
-type PluginPushRequest = {
-  type: 'plugin-push';
-  /** Correlation id echoed back on the matching {@link PluginPushResult}. */
-  id: string;
-  addonId: string;
-  /** Which manager reloads the addon; a plugin when omitted, as pushes from older CLIs are. */
-  kind?: PushedAddonKind;
-  bundle: string;
-  /** The manifest as authored; the device validates it before swapping anything in. */
-  manifest: PushedManifest;
-  /** The bundle compiled to Hermes bytecode, base64-encoded, by bytecode version; its digests are in `manifest.bytecode`. */
-  bytecode?: Record<string, string>;
-  /** Each extra file the manifest lists beside the bundle, such as an image, base64-encoded, by path. */
-  files?: Record<string, string>;
-};
-/** The outcome of a {@link PluginPushRequest}, sent device → bridge → the one waiting controller. */
-type PluginPushResult = {
-  type: 'plugin-push-result';
-  /** The `id` of the {@link PluginPushRequest} this answers. */
-  id: string;
-} & ({
-  ok: true;
-} | {
-  ok: false;
-  /** The reload failure, inspected. */
-  error: string;
-});
-/** A `console.*` / `nativeLoggingHook` line, streamed device → bridge → all controllers. */
-type LogMessage = {
-  type: 'log';
-  /** 1 = log/gray, 2 = warn/yellow, 3 = error/red. */
-  level: 1 | 2 | 3;
-  message: string;
-};
-/** What a device reports about itself when it connects. */
-type DeviceInfo = {
-  platform: string;
-  discordVersion: string;
-  loaderVersion: string;
-  clientVersion: string;
-};
-/** Device → bridge, once its socket opens, so the bridge can say which device is attached. */
-type DeviceHello = {
-  type: 'hello';
-  device: DeviceInfo;
-};
-/** Bridge → controller, once on attach and whenever the device connects, drops or says hello. */
-type DeviceStatus = {
-  type: 'device-status';
-} & ({
-  connected: false;
-} | {
-  connected: true;
-  /** Present once the connected device has said hello. */
-  device?: DeviceInfo;
-});
-/** Every framed message on the wire. */
-type BridgeMessage = EvalRequest | EvalResult | PluginPushRequest | PluginPushResult | LogMessage | DeviceHello | DeviceStatus;
-/** The default port the bridge listens on and controllers dial. */
-declare const DEFAULT_BRIDGE_PORT = 9090;
-declare const DEFAULT_EVAL_TIMEOUT_MS = 10000;
-declare const MAX_EVAL_TIMEOUT_MS = 86400000;
-/** The query marker a controller appends to its URL so the bridge routes it as a controller, not a device. */
-declare const CONTROLLER_ENDPOINT_MARKER = "mcp";
-/**
- * @description Safely parses a raw wire frame into a {@link BridgeMessage}, guarding against invalid
- * JSON and unknown shapes so both ends can trust what they route.
- * @param raw The JSON string received off the socket.
- * @returns The parsed message, or `undefined` if it isn't a recognised frame.
- */
-declare function parseMessage(raw: string): BridgeMessage | undefined;
-/**
- * @description Serialises a {@link BridgeMessage} into its wire form. Inverse of {@link parseMessage}.
- * @param message The message to frame.
- * @returns The JSON string to send over the socket.
- */
-declare function serializeMessage(message: BridgeMessage): string;
-declare const _default: {
-  DEFAULT_BRIDGE_PORT: number;
-  DEFAULT_EVAL_TIMEOUT_MS: number;
-  MAX_EVAL_TIMEOUT_MS: number;
-  CONTROLLER_ENDPOINT_MARKER: string;
-  parseMessage: typeof parseMessage;
-  serializeMessage: typeof serializeMessage;
-};
-export { serializeMessage as _, DeviceHello as a, EvalRequest as c, MAX_EVAL_TIMEOUT_MS as d, PluginPushRequest as f, parseMessage as g, _default as h, DEFAULT_EVAL_TIMEOUT_MS as i, EvalResult as l, PushedAddonKind as m, CONTROLLER_ENDPOINT_MARKER as n, DeviceInfo as o, PluginPushResult as p, DEFAULT_BRIDGE_PORT as r, DeviceStatus as s, BridgeMessage as t, LogMessage as u };