@unbound-app/debugger-protocol 2.0.1 → 2.1.0

package/dist/index.d.mts

@@ -1,2 +1,2 @@
-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 };
+import { $ as MetroFilesResult, A as ReactDevtoolsStatus, At as ExplorerImage, B as ViewSection, Bt as ExplorerTarget, C as _default, Ct as EXPLORER_RESULT_TYPES, D as REACT_DEVTOOLS_SHUTDOWN_EVENT, Dt as ExplorerClassesResult, E as serializeMessage, Et as ExplorerClassesRequest, F as ViewFrame, Ft as ExplorerObject, G as METRO_RESULT_TYPES, Gt as failExplorerRequest, H as ViewsResult, Ht as ExplorerValueKind, I as ViewHighlight, It as ExplorerObjectRequest, J as MetroChildrenResult, K as METRO_SEARCH_PAGE_SIZE, Kt as isExplorerRequest, L as ViewNode, Lt as ExplorerObjectResult, M as ViewDetails, Mt as ExplorerMemberKind, N as ViewDetailsRequest, Nt as ExplorerMembersRequest, O as REACT_DEVTOOLS_STATUS_EVENT, Ot as ExplorerError, P as ViewDetailsResult, Pt as ExplorerMembersResult, Q as MetroFilesRequest, R as ViewProperty, Rt as ExplorerRequest, S as SERVE_BRIDGE_COMMAND, St as EXPLORER_MEMBERS_PAGE_SIZE, T as resolveEvalTimeout, Tt as ExplorerClass, U as METRO_CHILDREN_PAGE_SIZE, Ut as ExplorerValuesRequest, V as ViewsRequest, Vt as ExplorerValue, W as METRO_MODULES_PAGE_SIZE, Wt as ExplorerValuesResult, X as MetroErrorCode, Y as MetroError, Z as MetroFile, _ as PUSH_TIMEOUT_MS, _t as MetroValueKind, a as BridgeInfo, at as MetroModule, b as PushedAddonKind, bt as isMetroResult, c as DEFAULT_BRIDGE_PORT, ct as MetroModulesResult, d as DeviceInfo, dt as MetroRequest, et as MetroLoadAllRequest, f as DeviceStatus, ft as MetroResult, g as MAX_EVAL_TIMEOUT_MS, gt as MetroValue, h as LogMessage, ht as MetroTarget, i as BridgeAdvertisement, it as MetroMatch, j as VIEWS_PAGE_SIZE, jt as ExplorerMember, k as ReactDevtoolsFrame, kt as ExplorerErrorCode, l as DEFAULT_EVAL_TIMEOUT_MS, lt as MetroReadRequest, m as EvalResult, mt as MetroSearchResult, n as BRIDGE_SERVICE_PROTOCOL, nt as MetroLoadRequest, o as BridgeMessage, ot as MetroModuleStatus, p as EvalRequest, pt as MetroSearchRequest, q as MetroChildrenRequest, qt as isExplorerResult, r as BRIDGE_SERVICE_TYPE, rt as MetroLoadResult, s as CONTROLLER_ENDPOINT_MARKER, st as MetroModulesRequest, t as BRIDGE_REPLY_GRACE_MS, tt as MetroLoadAllResult, u as DeviceHello, ut as MetroReadResult, v as PushRequest, vt as failMetroRequest, w as parseMessage, wt as EXPLORER_VALUES_LIMIT, x as RequestFailureCode, xt as EXPLORER_CLASSES_PAGE_SIZE, y as PushResult, yt as isMetroRequest, z as ViewPropertyValue, zt as ExplorerResult } from "./index-CxErH5OQ.mjs";
+export { BRIDGE_REPLY_GRACE_MS, BRIDGE_SERVICE_PROTOCOL, BRIDGE_SERVICE_TYPE, BridgeAdvertisement, BridgeInfo, BridgeMessage, CONTROLLER_ENDPOINT_MARKER, DEFAULT_BRIDGE_PORT, DEFAULT_EVAL_TIMEOUT_MS, DeviceHello, DeviceInfo, DeviceStatus, EXPLORER_CLASSES_PAGE_SIZE, EXPLORER_MEMBERS_PAGE_SIZE, EXPLORER_RESULT_TYPES, EXPLORER_VALUES_LIMIT, EvalRequest, EvalResult, type ExplorerClass, type ExplorerClassesRequest, type ExplorerClassesResult, type ExplorerError, type ExplorerErrorCode, type ExplorerImage, type ExplorerMember, type ExplorerMemberKind, type ExplorerMembersRequest, type ExplorerMembersResult, type ExplorerObject, type ExplorerObjectRequest, type ExplorerObjectResult, type ExplorerRequest, type ExplorerResult, type ExplorerTarget, type ExplorerValue, type ExplorerValueKind, type ExplorerValuesRequest, type ExplorerValuesResult, LogMessage, MAX_EVAL_TIMEOUT_MS, METRO_CHILDREN_PAGE_SIZE, METRO_MODULES_PAGE_SIZE, METRO_RESULT_TYPES, METRO_SEARCH_PAGE_SIZE, type MetroChildrenRequest, type MetroChildrenResult, type MetroError, type MetroErrorCode, type MetroFile, type MetroFilesRequest, type MetroFilesResult, type MetroLoadAllRequest, type MetroLoadAllResult, type MetroLoadRequest, type MetroLoadResult, type MetroMatch, type MetroModule, type MetroModuleStatus, type MetroModulesRequest, type MetroModulesResult, type MetroReadRequest, type MetroReadResult, type MetroRequest, type MetroResult, type MetroSearchRequest, type MetroSearchResult, type MetroTarget, type MetroValue, type MetroValueKind, PUSH_TIMEOUT_MS, PushRequest, PushResult, PushedAddonKind, REACT_DEVTOOLS_SHUTDOWN_EVENT, REACT_DEVTOOLS_STATUS_EVENT, type ReactDevtoolsFrame, type ReactDevtoolsStatus, RequestFailureCode, SERVE_BRIDGE_COMMAND, VIEWS_PAGE_SIZE, type ViewDetails, type ViewDetailsRequest, type ViewDetailsResult, type ViewFrame, type ViewHighlight, type ViewNode, type ViewProperty, type ViewPropertyValue, type ViewSection, type ViewsRequest, type ViewsResult, _default as default, failExplorerRequest, failMetroRequest, isExplorerRequest, isExplorerResult, isMetroRequest, isMetroResult, parseMessage, resolveEvalTimeout, serializeMessage };

package/dist/index.mjs

@@ -1 +1 @@
-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";
+export { t as BRIDGE_REPLY_GRACE_MS, n as BRIDGE_SERVICE_PROTOCOL, r as BRIDGE_SERVICE_TYPE, i as CONTROLLER_ENDPOINT_MARKER, a as DEFAULT_BRIDGE_PORT, o as DEFAULT_EVAL_TIMEOUT_MS, w as EXPLORER_CLASSES_PAGE_SIZE, T as EXPLORER_MEMBERS_PAGE_SIZE, E as EXPLORER_RESULT_TYPES, D as EXPLORER_VALUES_LIMIT, s as MAX_EVAL_TIMEOUT_MS, _ as METRO_CHILDREN_PAGE_SIZE, v as METRO_MODULES_PAGE_SIZE, y as METRO_RESULT_TYPES, b as METRO_SEARCH_PAGE_SIZE, c as PUSH_TIMEOUT_MS, m as REACT_DEVTOOLS_SHUTDOWN_EVENT, h as REACT_DEVTOOLS_STATUS_EVENT, l as SERVE_BRIDGE_COMMAND, g as VIEWS_PAGE_SIZE, p as default, O as failExplorerRequest, x as failMetroRequest, k as isExplorerRequest, A as isExplorerResult, S as isMetroRequest, C as isMetroResult, u as parseMessage, d as resolveEvalTimeout, f as serializeMessage } from "./src-D7-HmLkb.mjs";

package/dist/pending-requests.d.mts

@@ -28,9 +28,9 @@ export declare class PendingRequests<R, M = undefined> {
   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.
+   * @param fail Builds each request's failure result from its id and meta.
    */
-  failAll(fail: (id: string) => R): void;
+  failAll(fail: (id: string, meta: M) => 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.

package/dist/pending-requests.mjs

@@ -30,10 +30,10 @@ var PendingRequests = class {
 	}
 	/**
 	* @description Settles every pending request with a failure, so no caller waits forever.
-	* @param fail Builds each request's failure result from its id.
+	* @param fail Builds each request's failure result from its id and meta.
 	*/
 	failAll(fail) {
-		for (const id of this.entries.keys()) this.resolve(id, fail(id));
+		for (const [id, { meta }] of this.entries) this.resolve(id, fail(id, meta));
 	}
 	/**
 	* @description Drops matching requests without settling them, for when nobody is left to answer.

package/dist/registry.d.mts

@@ -1,5 +1,5 @@
 import { ControllerClient } from "./controller.mjs";
-import { StaticDecode, TObject } from "typebox";
+import { Static, StaticDecode, TObject, Type } from "typebox";
 /**
  * One command definition feeds both surfaces: the CLI builds flags and positionals from its schema,
  * and the MCP server uses the schema as the tool's input schema.
@@ -8,11 +8,30 @@ import { StaticDecode, TObject } from "typebox";
 export type CommandContext = {
   client: ControllerClient;
 };
-/** What a command handler returns: a success flag, human-readable text, and optional structured data. */
+/** Why a command failed, so a front end branches on `code` instead of the text. */
+export declare const CommandErrorCodeSchema: Type.TUnion<[Type.TLiteral<"invalid-input">, Type.TLiteral<"no-device">, Type.TLiteral<"device-disconnected">, Type.TLiteral<"timeout">, Type.TLiteral<"bridge-unreachable">, Type.TLiteral<"shut-down">, Type.TLiteral<"device-error">, Type.TLiteral<"not-found">, Type.TLiteral<"tool-failed">, Type.TLiteral<"unsupported">, Type.TLiteral<"command-failed">]>;
+export type CommandErrorCode = Static<typeof CommandErrorCodeSchema>;
+/** A failed command's reason, as `--json` prints it and the MCP tool result carries it. */
+export declare const CommandErrorSchema: TObject<{
+  code: Type.TUnion<[Type.TLiteral<"invalid-input">, Type.TLiteral<"no-device">, Type.TLiteral<"device-disconnected">, Type.TLiteral<"timeout">, Type.TLiteral<"bridge-unreachable">, Type.TLiteral<"shut-down">, Type.TLiteral<"device-error">, Type.TLiteral<"not-found">, Type.TLiteral<"tool-failed">, Type.TLiteral<"unsupported">, Type.TLiteral<"command-failed">]>;
+  message: Type.TString;
+  /** What to do about it. */
+  hint: Type.TOptional<Type.TString>;
+  /** The schema property the failure is about, for a form to highlight. */
+  field: Type.TOptional<Type.TString>;
+  stack: Type.TOptional<Type.TString>;
+}>;
+export type CommandError = Static<typeof CommandErrorSchema>;
+/** What a command handler returns: a success flag, human-readable text, optional structured data, and why it failed. */
 export type CommandOutput = {
-  ok: boolean;
+  ok: true;
   text: string;
   data?: unknown;
+} | {
+  ok: false;
+  text: string;
+  data?: unknown;
+  error?: CommandError;
 };
 /** A command usable from both the CLI and (when opted in) the MCP server. */
 export type CommandDefinition<S extends TObject = TObject> = {

package/dist/registry.mjs

@@ -1 +1,27 @@
-export {};
+import { Type } from "typebox";
+// src/registry.ts
+/** Why a command failed, so a front end branches on `code` instead of the text. */
+const CommandErrorCodeSchema = Type.Union([
+	Type.Literal("invalid-input"),
+	Type.Literal("no-device"),
+	Type.Literal("device-disconnected"),
+	Type.Literal("timeout"),
+	Type.Literal("bridge-unreachable"),
+	Type.Literal("shut-down"),
+	Type.Literal("device-error"),
+	Type.Literal("not-found"),
+	Type.Literal("tool-failed"),
+	Type.Literal("unsupported"),
+	Type.Literal("command-failed")
+]);
+/** A failed command's reason, as `--json` prints it and the MCP tool result carries it. */
+const CommandErrorSchema = Type.Object({
+	code: CommandErrorCodeSchema,
+	message: Type.String(),
+	/** What to do about it. */
+	hint: Type.Optional(Type.String()),
+	/** The schema property the failure is about, for a form to highlight. */
+	field: Type.Optional(Type.String()),
+	stack: Type.Optional(Type.String())
+});
+export { CommandErrorCodeSchema, CommandErrorSchema };

package/dist/src-D7-HmLkb.mjs

@@ -0,0 +1,492 @@
+// src/explorer.ts
+/**
+* The object explorer's frames: a controller asks the device for a native object's class chain, one page of one kind
+* of a class's members, the values of the members on screen, and (iOS) the loaded images and their classes.
+*/
+/** The most members a device returns for one {@link ExplorerMembersRequest}. */
+const EXPLORER_MEMBERS_PAGE_SIZE = 100;
+/** The most images or class names a device returns for one {@link ExplorerClassesRequest}. */
+const EXPLORER_CLASSES_PAGE_SIZE = 200;
+/** The most member values one {@link ExplorerValuesRequest} may name. */
+const EXPLORER_VALUES_LIMIT = 50;
+/** The result frame type answering each request frame type. */
+const EXPLORER_RESULT_TYPES = {
+	"explorer-object-request": "explorer-object-result",
+	"explorer-members-request": "explorer-members-result",
+	"explorer-values-request": "explorer-values-result",
+	"explorer-classes-request": "explorer-classes-result"
+};
+const MEMBER_KINDS = /* @__PURE__ */ new Set([
+	"properties",
+	"ivars",
+	"methods",
+	"classMethods",
+	"protocols",
+	"fields",
+	"constructors",
+	"interfaces"
+]);
+const VALUE_KINDS$1 = /* @__PURE__ */ new Set([
+	"nil",
+	"number",
+	"bool",
+	"string",
+	"object",
+	"class",
+	"struct",
+	"pointer",
+	"selector",
+	"other",
+	"skipped",
+	"error"
+]);
+const ERROR_CODES$1 = /* @__PURE__ */ new Set([
+	"stale",
+	"disabled",
+	"unavailable",
+	"unsupported",
+	"unknown-class",
+	"failed"
+]);
+const READS = /* @__PURE__ */ new Set([
+	"auto",
+	"manual",
+	"never"
+]);
+/**
+* @description Builds the failed answer to an explorer request.
+* @param request The request, or its type and id.
+* @param error What failed.
+* @param code Why it failed.
+* @returns The result frame.
+*/
+function failExplorerRequest(request, error, code) {
+	return {
+		type: EXPLORER_RESULT_TYPES[request.type],
+		id: request.id,
+		ok: false,
+		error,
+		code
+	};
+}
+/**
+* @description Checks whether a frame is an explorer request, by its type alone.
+* @param frame A parsed frame.
+* @returns Whether it is one.
+*/
+function isExplorerRequest(frame) {
+	return Object.hasOwn(EXPLORER_RESULT_TYPES, frame.type);
+}
+/**
+* @description Checks whether a frame is an explorer result, by its type alone.
+* @param frame A parsed frame.
+* @returns Whether it is one.
+*/
+function isExplorerResult(frame) {
+	return Object.values(EXPLORER_RESULT_TYPES).includes(frame.type);
+}
+function isObject$2(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isCount$1(value) {
+	return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+function isStrings(value) {
+	return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+function isNullableString$1(value) {
+	return value === null || typeof value === "string";
+}
+/** Checks an optional field: absent, `undefined`, or passing `check`. */
+function optional$1(record, key, check) {
+	return record[key] === void 0 || check(record[key]);
+}
+const isString$1 = (value) => typeof value === "string";
+const isNumber = (value) => typeof value === "number" && Number.isFinite(value);
+function isTarget$1(value) {
+	if (!isObject$2(value)) return false;
+	const keys = [
+		"node",
+		"object",
+		"className"
+	].filter((key) => value[key] !== void 0);
+	return keys.length === 1 && typeof value[keys[0] ?? ""] === "string";
+}
+function isExplorerClass(value) {
+	return isObject$2(value) && typeof value.name === "string" && isNullableString$1(value.image) && (value.instanceSize === null || isCount$1(value.instanceSize)) && isObject$2(value.counts) && Object.entries(value.counts).every(([kind, count]) => MEMBER_KINDS.has(kind) && isCount$1(count));
+}
+function isExplorerMember(value) {
+	return isObject$2(value) && typeof value.name === "string" && MEMBER_KINDS.has(value.kind) && isNullableString$1(value.type) && isNullableString$1(value.signature) && READS.has(value.read) && optional$1(value, "returnType", isString$1) && optional$1(value, "parameters", isStrings) && optional$1(value, "attributes", isStrings) && optional$1(value, "static", (flag) => typeof flag === "boolean") && optional$1(value, "offset", isNumber) && optional$1(value, "size", isNumber) && optional$1(value, "image", isNullableString$1);
+}
+function isExplorerValue(value) {
+	return isObject$2(value) && typeof value.name === "string" && VALUE_KINDS$1.has(value.kind) && typeof value.text === "string" && optional$1(value, "object", isString$1) && optional$1(value, "className", isString$1);
+}
+function isExplorerObject(value) {
+	return isObject$2(value) && isNullableString$1(value.ref) && typeof value.className === "string" && isNullableString$1(value.description) && (value.platform === "ios" || value.platform === "android") && Array.isArray(value.chain) && value.chain.every(isExplorerClass);
+}
+function isExplorerImage(value) {
+	return isObject$2(value) && typeof value.path === "string" && typeof value.name === "string" && isCount$1(value.classCount);
+}
+function isPage(frame) {
+	return optional$1(frame, "offset", isCount$1) && optional$1(frame, "limit", isCount$1) && optional$1(frame, "filter", isString$1);
+}
+/** Checks a result's id and outcome; `isOk` checks the payload of a successful one. */
+function isResult$1(frame, isOk) {
+	if (typeof frame.id !== "string") return false;
+	if (frame.ok === true) return isOk();
+	return frame.ok === false && typeof frame.error === "string" && ERROR_CODES$1.has(frame.code);
+}
+/**
+* @description Checks the fields of an explorer frame whose `type` is already known.
+* @param frame The parsed frame.
+* @returns Whether the frame is a valid explorer request or result.
+*/
+function isExplorerFrame(frame) {
+	if (!isObject$2(frame)) return false;
+	switch (frame.type) {
+		case "explorer-object-request": return typeof frame.id === "string" && isTarget$1(frame.target);
+		case "explorer-object-result": return isResult$1(frame, () => isExplorerObject(frame.object));
+		case "explorer-members-request": return typeof frame.id === "string" && typeof frame.className === "string" && MEMBER_KINDS.has(frame.kind) && isPage(frame);
+		case "explorer-members-result": return isResult$1(frame, () => isCount$1(frame.total) && Array.isArray(frame.members) && frame.members.every(isExplorerMember));
+		case "explorer-values-request": return typeof frame.id === "string" && typeof frame.object === "string" && typeof frame.className === "string" && MEMBER_KINDS.has(frame.kind) && isStrings(frame.names) && optional$1(frame, "invokeGetters", (flag) => typeof flag === "boolean");
+		case "explorer-values-result": return isResult$1(frame, () => Array.isArray(frame.values) && frame.values.every(isExplorerValue));
+		case "explorer-classes-request": return typeof frame.id === "string" && optional$1(frame, "image", isString$1) && isPage(frame);
+		case "explorer-classes-result": return isResult$1(frame, () => isCount$1(frame.total) && optional$1(frame, "images", (images) => Array.isArray(images) && images.every(isExplorerImage)) && optional$1(frame, "classes", isStrings));
+		default: return false;
+	}
+}
+// src/metro.ts
+/**
+* The Metro explorer's frames: list, load and search modules, and walk a loaded module's exports as a tree. Long
+* work runs in short device-side batches the controller repeats; getters run only when asked.
+*/
+/** The most modules a device returns for one {@link MetroModulesRequest}. */
+const METRO_MODULES_PAGE_SIZE = 200;
+/** The most properties a device returns for one {@link MetroChildrenRequest}. */
+const METRO_CHILDREN_PAGE_SIZE = 100;
+/** The most matches a device collects for one {@link MetroSearchRequest} before it stops at a module's end. */
+const METRO_SEARCH_PAGE_SIZE = 50;
+/** The result frame type answering each request frame type. */
+const METRO_RESULT_TYPES = {
+	"metro-modules-request": "metro-modules-result",
+	"metro-load-request": "metro-load-result",
+	"metro-load-all-request": "metro-load-all-result",
+	"metro-search-request": "metro-search-result",
+	"metro-files-request": "metro-files-result",
+	"metro-children-request": "metro-children-result",
+	"metro-read-request": "metro-read-result"
+};
+const STATUSES = /* @__PURE__ */ new Set([
+	"loaded",
+	"unloaded",
+	"failed"
+]);
+const VALUE_KINDS = /* @__PURE__ */ new Set([
+	"string",
+	"number",
+	"boolean",
+	"nullish",
+	"symbol",
+	"function",
+	"class",
+	"array",
+	"object",
+	"error",
+	"getter"
+]);
+const ERROR_CODES = /* @__PURE__ */ new Set([
+	"stale",
+	"unknown-module",
+	"unloaded",
+	"failed"
+]);
+/**
+* @description Builds the failed answer to a Metro request.
+* @param request The request, or its type and id.
+* @param error What failed.
+* @param code Why it failed.
+* @returns The result frame.
+*/
+function failMetroRequest(request, error, code) {
+	return {
+		type: METRO_RESULT_TYPES[request.type],
+		id: request.id,
+		ok: false,
+		error,
+		code
+	};
+}
+/**
+* @description Checks whether a frame is a Metro request, by its type alone.
+* @param frame A parsed frame.
+* @returns Whether it is one.
+*/
+function isMetroRequest(frame) {
+	return Object.hasOwn(METRO_RESULT_TYPES, frame.type);
+}
+/**
+* @description Checks whether a frame is a Metro result, by its type alone.
+* @param frame A parsed frame.
+* @returns Whether it is one.
+*/
+function isMetroResult(frame) {
+	return Object.values(METRO_RESULT_TYPES).includes(frame.type);
+}
+function isObject$1(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isCount(value) {
+	return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+/** Checks an optional field: absent, `undefined`, or passing `check`. */
+function optional(record, key, check) {
+	return record[key] === void 0 || check(record[key]);
+}
+const isString = (value) => typeof value === "string";
+function isTarget(value) {
+	if (!isObject$1(value)) return false;
+	const keys = ["module", "ref"].filter((key) => value[key] !== void 0);
+	return keys.length === 1 && (keys[0] === "module" ? isCount(value.module) : isString(value.ref));
+}
+function isMetroModule(value) {
+	return isObject$1(value) && isCount(value.id) && STATUSES.has(value.status) && (value.label === null || typeof value.label === "string");
+}
+function isMetroValue(value) {
+	return isObject$1(value) && typeof value.key === "string" && VALUE_KINDS.has(value.kind) && typeof value.text === "string" && optional(value, "ref", isString) && optional(value, "internal", (flag) => typeof flag === "boolean");
+}
+const isMetroValues = (value) => Array.isArray(value) && value.every(isMetroValue);
+function isMetroFile(value) {
+	return isObject$1(value) && isCount(value.id) && isString(value.path);
+}
+function isMetroMatch(value) {
+	return isObject$1(value) && isMetroModule(value.module) && Array.isArray(value.path) && value.path.every(isString) && isMetroValue(value.value);
+}
+/** Checks a result's id and outcome; `isOk` checks the payload of a successful one. */
+function isResult(frame, isOk) {
+	if (typeof frame.id !== "string") return false;
+	if (frame.ok === true) return isOk();
+	return frame.ok === false && typeof frame.error === "string" && ERROR_CODES.has(frame.code);
+}
+/**
+* @description Checks the fields of a Metro frame whose `type` is already known.
+* @param frame The parsed frame.
+* @returns Whether the frame is a valid Metro request or result.
+*/
+function isMetroFrame(frame) {
+	if (!isObject$1(frame)) return false;
+	switch (frame.type) {
+		case "metro-modules-request": return typeof frame.id === "string" && optional(frame, "filter", isString) && optional(frame, "status", (status) => STATUSES.has(status)) && optional(frame, "offset", isCount) && optional(frame, "limit", isCount);
+		case "metro-modules-result": return isResult(frame, () => isCount(frame.total) && isCount(frame.loaded) && isCount(frame.count) && Array.isArray(frame.modules) && frame.modules.every(isMetroModule));
+		case "metro-load-request": return typeof frame.id === "string" && isCount(frame.module);
+		case "metro-load-result": return isResult(frame, () => isMetroModule(frame.module) && isCount(frame.loaded));
+		case "metro-load-all-request": return typeof frame.id === "string";
+		case "metro-load-all-result": return isResult(frame, () => [
+			frame.attempted,
+			frame.failed,
+			frame.remaining,
+			frame.loaded,
+			frame.count
+		].every(isCount));
+		case "metro-search-request": return typeof frame.id === "string" && isString(frame.query) && optional(frame, "cursor", isCount) && optional(frame, "limit", isCount);
+		case "metro-search-result": return isResult(frame, () => Array.isArray(frame.matches) && frame.matches.every(isMetroMatch) && (frame.cursor === null || isCount(frame.cursor)) && isCount(frame.searched) && isCount(frame.total));
+		case "metro-files-request": return typeof frame.id === "string";
+		case "metro-files-result": return isResult(frame, () => Array.isArray(frame.files) && frame.files.every(isMetroFile) && isCount(frame.unloaded) && isCount(frame.count));
+		case "metro-children-request": return typeof frame.id === "string" && isTarget(frame.target) && optional(frame, "offset", isCount) && optional(frame, "limit", isCount);
+		case "metro-children-result": return isResult(frame, () => isMetroValue(frame.value) && isCount(frame.total) && isMetroValues(frame.children) && isMetroValues(frame.internal));
+		case "metro-read-request": return typeof frame.id === "string" && typeof frame.ref === "string";
+		case "metro-read-result": return isResult(frame, () => isMetroValue(frame.value));
+		default: return false;
+	}
+}
+// src/views.ts
+/**
+* The view finder's frames: a controller asks the device for one page of one level of its native view
+* tree at a time, for one view's properties when it selects it, and names the view to outline on screen.
+*/
+/** The most views a device returns for one {@link ViewsRequest}; a longer level is read in pages. */
+const VIEWS_PAGE_SIZE = 100;
+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";
+}
+function isOptionalCount(value) {
+	return value === void 0 || typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+function isViewProperty(value) {
+	return isObject(value) && "key" in value && typeof value.key === "string" && "value" in value && (isNullableString(value.value) || typeof value.value === "number" || typeof value.value === "boolean") && (!("kind" in value) || value.kind === void 0 || value.kind === "color") && (!("unit" in value) || value.unit === void 0 || typeof value.unit === "string");
+}
+/**
+* @description Checks that a value has every field {@link ViewDetails} needs.
+* @param value The parsed value.
+* @returns Whether it is a view's details.
+*/
+function isViewDetails(value) {
+	return isObject(value) && "classChain" in value && Array.isArray(value.classChain) && value.classChain.every((name) => typeof name === "string") && "sections" in value && Array.isArray(value.sections) && value.sections.every((section) => isObject(section) && "title" in section && typeof section.title === "string" && "properties" in section && Array.isArray(section.properties) && section.properties.every(isViewProperty));
+}
+/**
+* @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, details frame 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") && isOptionalCount("offset" in frame ? frame.offset : void 0) && isOptionalCount("limit" in frame ? frame.limit : void 0);
+		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) && isOptionalCount("total" in frame ? frame.total : void 0) : frame.ok === false && "error" in frame && typeof frame.error === "string");
+		case "view-details-request": return "id" in frame && typeof frame.id === "string" && "node" in frame && typeof frame.node === "string";
+		case "view-details-result": return "id" in frame && typeof frame.id === "string" && "ok" in frame && (frame.ok === true ? "details" in frame && isViewDetails(frame.details) : frame.ok === false && "error" in frame && typeof frame.error === "string");
+		case "view-highlight": return "node" in frame && isNullableString(frame.node);
+		default: return false;
+	}
+}
+// 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/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";
+/** The unlisted `ubd` command that runs the bridge in the foreground; tools that start one run it. */
+const SERVE_BRIDGE_COMMAND = "serve-bridge";
+/** The Bonjour service type a bridge advertises, so a device on the same network can find it. */
+const BRIDGE_SERVICE_TYPE = "_unbound-bridge._tcp";
+/** The `proto` TXT value of an advertised bridge; a device skips bridges that speak another one. */
+const BRIDGE_SERVICE_PROTOCOL = "1";
+/**
+* @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 "bridge-info": return "code" in frame && typeof frame.code === "string" && "advertising" in frame && typeof frame.advertising === "boolean" && (!("address" in frame) || typeof frame.address === "string") && (!("error" in frame) || typeof frame.error === "string");
+		case "views-request":
+		case "views-result":
+		case "view-details-request":
+		case "view-details-result":
+		case "view-highlight": return isViewFrameMessage(frame);
+		case "explorer-object-request":
+		case "explorer-object-result":
+		case "explorer-members-request":
+		case "explorer-members-result":
+		case "explorer-values-request":
+		case "explorer-values-result":
+		case "explorer-classes-request":
+		case "explorer-classes-result": return isExplorerFrame(frame);
+		case "metro-modules-request":
+		case "metro-modules-result":
+		case "metro-load-request":
+		case "metro-load-result":
+		case "metro-load-all-request":
+		case "metro-load-all-result":
+		case "metro-search-request":
+		case "metro-search-result":
+		case "metro-files-request":
+		case "metro-files-result":
+		case "metro-children-request":
+		case "metro-children-result":
+		case "metro-read-request":
+		case "metro-read-result": return isMetroFrame(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 { isExplorerResult as A, isMetroResult as C, EXPLORER_VALUES_LIMIT as D, EXPLORER_RESULT_TYPES as E, failExplorerRequest as O, isMetroRequest as S, EXPLORER_MEMBERS_PAGE_SIZE as T, METRO_CHILDREN_PAGE_SIZE as _, DEFAULT_BRIDGE_PORT as a, METRO_SEARCH_PAGE_SIZE as b, PUSH_TIMEOUT_MS as c, resolveEvalTimeout as d, serializeMessage as f, VIEWS_PAGE_SIZE as g, REACT_DEVTOOLS_STATUS_EVENT as h, CONTROLLER_ENDPOINT_MARKER as i, isExplorerRequest as k, SERVE_BRIDGE_COMMAND as l, REACT_DEVTOOLS_SHUTDOWN_EVENT as m, BRIDGE_SERVICE_PROTOCOL as n, DEFAULT_EVAL_TIMEOUT_MS as o, src_default as p, BRIDGE_SERVICE_TYPE as r, MAX_EVAL_TIMEOUT_MS as s, BRIDGE_REPLY_GRACE_MS as t, parseMessage as u, METRO_MODULES_PAGE_SIZE as v, EXPLORER_CLASSES_PAGE_SIZE as w, failMetroRequest as x, METRO_RESULT_TYPES as y };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@unbound-app/debugger-protocol",
-	"version": "2.0.1",
+	"version": "2.1.0",
 	"description": "The wire protocol and controller client shared by the debugger bridge, the on-device client, and the CLI.",
 	"author": {
 		"name": "Mario P.",