@shadow-js/devtools 0.0.0-stage → 1.0.0

package/dist/dev/inspection.d.ts

@@ -0,0 +1,226 @@
+//#region src/inspection.d.ts
+/**
+ * One line of an inspection view. Every field is text, so a row is plain data and can cross a
+ * message channel unchanged.
+ *
+ * @since 1.0.0
+ */
+export interface InspectionRow {
+  /** Stable within the source (a query hash, a route match index, or a fixed name). */
+  readonly id: string;
+  /** What the row is about: a query key, a route pattern, or a fixed label such as `location`. */
+  readonly label: string;
+  /** The details, as one line of text. */
+  readonly detail: string;
+  /** A short state word for the row, such as `success`, `fetching` or `idle`. */
+  readonly state: string;
+}
+/**
+ * Something that can describe itself to a devtools panel: a router, a query cache, or any other part of
+ * the app. `rows()` is called when the panel asks, so it reports the current state, not a copy taken
+ * earlier. It may throw; the agent reports the error to the panel instead of failing the request.
+ *
+ * @example
+ * import { type InspectionSource, registerInspection } from "@shadow-js/devtools";
+ *
+ * const source: InspectionSource = {
+ *   title: "Feature flags",
+ *   rows: () => [{ id: "beta", label: "beta", detail: "on", state: "on" }],
+ * };
+ * registerInspection("flags", source);
+ * @since 1.0.0
+ */
+export interface InspectionSource {
+  /** The heading of the view, for example `Router`. */
+  readonly title: string;
+  /** The rows now. At most {@link MAX_INSPECTION_ROWS} are sent. */
+  rows(): readonly InspectionRow[];
+  /**
+   * Optional. Calls `notify` whenever the rows may have changed, and returns the function that stops the
+   * calls. The extension's page side listens to it, so the panel refreshes at the moment of the change
+   * instead of on a timer. A source without it is read when the panel asks.
+   */
+  subscribe?(notify: () => void): () => void;
+}
+/**
+ * A registered source with its name (the key the app registered it under).
+ *
+ * @since 1.0.0
+ */
+export interface InspectionEntry {
+  /** The name the source was registered under. Unique per hook. */
+  readonly name: string;
+  /** The source. */
+  readonly source: InspectionSource;
+}
+/**
+ * What the agent answers to an `inspect` request: every registered source, read now. A source that
+ * threw has no rows and an `error` message instead.
+ *
+ * @since 1.0.0
+ */
+export interface InspectionSnapshot {
+  /** The registration name. */
+  readonly name: string;
+  /** The heading of the view. */
+  readonly title: string;
+  /** The rows (at most {@link MAX_INSPECTION_ROWS}). */
+  readonly rows: readonly InspectionRow[];
+  /** Why the rows could not be read, or `undefined` when they were. */
+  readonly error?: string;
+}
+/**
+ * The part of a router the router inspection reads. A `Router` from `@shadow-js/router` fits this
+ * shape; it is structural, so devtools does not depend on the router package.
+ *
+ * @since 1.0.0
+ */
+export interface RouterLike {
+  /** The router's live state (accessors). */
+  readonly state: {
+    location(): {
+      readonly pathname: string;
+      readonly search: string;
+      readonly hash: string;
+    } | undefined;
+    status(): string;
+    pending(): boolean;
+    error(): unknown;
+    matches(): readonly {
+      readonly id: string;
+      readonly pattern: string;
+      readonly params: Readonly<Record<string, string>>;
+    }[];
+  };
+}
+/**
+ * One query as the query cache reports it (a `QueryInfo` snapshot of `@shadow-js/query`).
+ *
+ * @since 1.0.0
+ */
+export interface QueryInfoLike {
+  /** The key of the query (plain data). */
+  readonly queryKey: unknown;
+  /** The hash of the key, which identifies the cache entry. */
+  readonly queryHash: string;
+  /** `pending`, `success` or `error`. */
+  readonly status: string;
+  /** `idle`, `fetching` or `paused`. */
+  readonly fetchStatus: string;
+  /** Time (ms since epoch) of the last successful fetch or write; `0` when there was none. */
+  readonly dataUpdatedAt: number;
+  /** True after an invalidation, until the next successful fetch or write. */
+  readonly isInvalidated: boolean;
+  /** Mounted observers of the query. */
+  readonly observers: number;
+}
+/**
+ * The part of a query client the query inspection reads: its cache, as snapshots. A `QueryClient` from
+ * `@shadow-js/query` fits this shape.
+ *
+ * @since 1.0.0
+ */
+export interface QueryLike {
+  /** The query cache, read through its snapshots, and told about its changes. */
+  readonly queryCache: {
+    /** Every query, as snapshots. Untracked. */
+    find(): readonly QueryInfoLike[];
+    /** Calls `listener` for every change of the cache; returns the function that stops it. */
+    subscribe(listener: () => void): () => void;
+  };
+}
+/**
+ * Turns a source's rows into plain rows, cut to the row limit. Each field is coerced to text and cut,
+ * so a source cannot send an object, a function or an unbounded string to the panel.
+ *
+ * @param rows The rows a source returned.
+ * @returns At most {@link MAX_INSPECTION_ROWS} plain rows, and a last row that says how many were cut.
+ * @example
+ * import { type InspectionRow, sanitizeRows } from "@shadow-js/devtools";
+ *
+ * const rows: InspectionRow[] = [{ id: "a", label: "a", detail: "b", state: "c" }];
+ * sanitizeRows(rows); // one plain row
+ * @since 1.0.0
+ */
+export declare function sanitizeRows(rows: readonly InspectionRow[]): InspectionRow[];
+/**
+ * Describes a router: its location, whether a navigation is pending, the error it last reported, and
+ * the chain of matched routes. The source reads the router when the panel asks.
+ *
+ * @param router The router (`createRouter` from `@shadow-js/router`).
+ * @param title The heading of the view. Default `Router`.
+ * @returns An {@link InspectionSource}.
+ * @example
+ * import { type RouterLike, registerInspection, routerInspection } from "@shadow-js/devtools";
+ *
+ * declare const router: RouterLike; // the router from your app's createRouter()
+ * registerInspection("router", routerInspection(router));
+ * @since 1.0.0
+ */
+export declare function routerInspection(router: RouterLike, title?: string): InspectionSource;
+/**
+ * Describes a query cache: one row per query, with its key, fetch state, observers and age. The
+ * source reads the cache when the panel asks, and it subscribes to the cache so that a change is
+ * pushed to a connected panel as soon as it happens. A client without the `inspection` feature of
+ * `@shadow-js/query` cannot notify, so the panel then reads the cache only when it asks.
+ *
+ * @param client The query client (`createQueryClient` from `@shadow-js/query`, created with
+ *   `features: [inspection]` for live updates), or anything with the same `queryCache.find()`.
+ * @param title The heading of the view. Default `Queries`.
+ * @returns An {@link InspectionSource}.
+ * @example
+ * import { type QueryLike, queryInspection, registerInspection } from "@shadow-js/devtools";
+ *
+ * declare const client: QueryLike; // the query client of your app
+ * registerInspection("query", queryInspection(client));
+ * @since 1.0.0
+ */
+export declare function queryInspection(client: QueryLike, title?: string): InspectionSource;
+/**
+ * Registers an inspection source on the installed devtools hook, under `name`, so a panel can show it
+ * (see the `inspect` request of {@link createAgent}). Re-registering a name replaces its source. Returns
+ * `false` when nothing was registered: no hook is installed (no development build, or the hook of
+ * another protocol version), the name is empty, or {@link MAX_INSPECTIONS} sources are already
+ * registered under other names. A development tool; production builds register nothing.
+ *
+ * @param name The name to show the source under. Not empty.
+ * @param source The source.
+ * @returns True when the source is registered.
+ * @example
+ * import { type RouterLike, registerInspection, routerInspection } from "@shadow-js/devtools";
+ *
+ * declare const router: RouterLike; // the router from your app's createRouter()
+ * registerInspection("router", routerInspection(router));
+ * @since 1.0.0
+ */
+export declare function registerInspection(name: string, source: InspectionSource): boolean;
+/**
+ * Reads every registered source, now, as plain snapshots. A source that throws is reported with its
+ * `error` and no rows. Used by the agent for the `inspect` request.
+ *
+ * @param entries The registered entries (the hook's `inspections()`).
+ * @returns One snapshot per entry, in registration order.
+ * @example
+ * import { readInspections } from "@shadow-js/devtools";
+ *
+ * const snapshots = readInspections([]); // []
+ * @since 1.0.0
+ */
+export declare function readInspections(entries: readonly InspectionEntry[]): InspectionSnapshot[];
+/**
+ * Reads the answer of an `inspect` request. The panel gets it from the page, so it checks the shape
+ * and the bounds before it trusts anything: every field is text, there are at most
+ * {@link MAX_INSPECTIONS} sources and at most {@link MAX_INSPECTION_ROWS} + 1 rows each.
+ *
+ * @param value The `result` of an ok `inspect` response.
+ * @returns The snapshots, or `null` when the value is not an answer to `inspect`.
+ * @example
+ * import { parseInspectResult } from "@shadow-js/devtools";
+ *
+ * parseInspectResult({ sources: [] }); // []
+ * parseInspectResult({ nope: true }); // null
+ * @since 1.0.0
+ */
+export declare function parseInspectResult(value: unknown): InspectionSnapshot[] | null;
+//#endregion
+//# sourceMappingURL=inspection.d.ts.map

package/dist/dev/inspection.js

@@ -0,0 +1,263 @@
+import "./protocol.js";
+import { getHook } from "./hook.js";
+import { errorMessage, preview } from "./preview.js";
+//#region src/inspection.ts
+/** Longest text of one row field, in characters. Longer text is cut with an ellipsis. */
+const FIELD_LENGTH = 200;
+/**
+* The JSON text of plain data (query keys and route params are plain data), cut to the field length.
+* Falls back to {@link preview} when the value does not serialize (a cycle, a bigint).
+*
+* @param value The value.
+* @returns One line of text.
+*/
+function jsonText(value) {
+	try {
+		const text = JSON.stringify(value);
+		return text === void 0 ? preview(value, FIELD_LENGTH) : clip(text);
+	} catch {
+		return preview(value, FIELD_LENGTH);
+	}
+}
+/**
+* Cuts text to the row field length, with an ellipsis when it was longer.
+*
+* @param text The text.
+* @returns The text, at most {@link FIELD_LENGTH} characters.
+*/
+function clip(text) {
+	return text.length > FIELD_LENGTH ? `${text.slice(0, 199)}…` : text;
+}
+/**
+* Turns a source's rows into plain rows, cut to the row limit. Each field is coerced to text and cut,
+* so a source cannot send an object, a function or an unbounded string to the panel.
+*
+* @param rows The rows a source returned.
+* @returns At most {@link MAX_INSPECTION_ROWS} plain rows, and a last row that says how many were cut.
+* @example
+* import { type InspectionRow, sanitizeRows } from "@shadow-js/devtools";
+*
+* const rows: InspectionRow[] = [{ id: "a", label: "a", detail: "b", state: "c" }];
+* sanitizeRows(rows); // one plain row
+* @since 1.0.0
+*/
+function sanitizeRows(rows) {
+	const out = [];
+	const limit = Math.min(rows.length, 500);
+	for (let index = 0; index < limit; index += 1) {
+		const row = rows[index];
+		if (row === void 0) continue;
+		out.push({
+			id: clip(String(row.id)),
+			label: clip(String(row.label)),
+			detail: clip(String(row.detail)),
+			state: clip(String(row.state))
+		});
+	}
+	if (rows.length > 500) out.push({
+		id: "truncated",
+		label: "…",
+		detail: `${rows.length - 500} more rows not shown`,
+		state: "truncated"
+	});
+	return out;
+}
+/**
+* Describes a router: its location, whether a navigation is pending, the error it last reported, and
+* the chain of matched routes. The source reads the router when the panel asks.
+*
+* @param router The router (`createRouter` from `@shadow-js/router`).
+* @param title The heading of the view. Default `Router`.
+* @returns An {@link InspectionSource}.
+* @example
+* import { type RouterLike, registerInspection, routerInspection } from "@shadow-js/devtools";
+*
+* declare const router: RouterLike; // the router from your app's createRouter()
+* registerInspection("router", routerInspection(router));
+* @since 1.0.0
+*/
+function routerInspection(router, title = "Router") {
+	return {
+		title,
+		rows() {
+			const rows = [];
+			const location = router.state.location();
+			const status = router.state.status();
+			rows.push({
+				id: "location",
+				label: "location",
+				detail: location === void 0 ? "none" : `${location.pathname}${location.search}${location.hash}`,
+				state: status
+			});
+			rows.push({
+				id: "pending",
+				label: "pending",
+				detail: String(router.state.pending()),
+				state: router.state.pending() ? "pending" : "settled"
+			});
+			const error = router.state.error();
+			if (error !== void 0) rows.push({
+				id: "error",
+				label: "error",
+				detail: errorMessage(error),
+				state: "errored"
+			});
+			router.state.matches().forEach((match, index) => {
+				rows.push({
+					id: `match:${index}`,
+					label: match.pattern,
+					detail: jsonText(match.params),
+					state: match.id
+				});
+			});
+			return rows;
+		}
+	};
+}
+/**
+* Describes a query cache: one row per query, with its key, fetch state, observers and age. The
+* source reads the cache when the panel asks, and it subscribes to the cache so that a change is
+* pushed to a connected panel as soon as it happens. A client without the `inspection` feature of
+* `@shadow-js/query` cannot notify, so the panel then reads the cache only when it asks.
+*
+* @param client The query client (`createQueryClient` from `@shadow-js/query`, created with
+*   `features: [inspection]` for live updates), or anything with the same `queryCache.find()`.
+* @param title The heading of the view. Default `Queries`.
+* @returns An {@link InspectionSource}.
+* @example
+* import { type QueryLike, queryInspection, registerInspection } from "@shadow-js/devtools";
+*
+* declare const client: QueryLike; // the query client of your app
+* registerInspection("query", queryInspection(client));
+* @since 1.0.0
+*/
+function queryInspection(client, title = "Queries") {
+	return {
+		title,
+		subscribe(notify) {
+			try {
+				return client.queryCache.subscribe(() => notify());
+			} catch (error) {
+				if (error instanceof TypeError) return () => void 0;
+				throw error;
+			}
+		},
+		rows() {
+			return client.queryCache.find().map((query) => {
+				const flags = [query.fetchStatus, `${query.observers} observers`];
+				if (query.isInvalidated) flags.push("invalidated");
+				flags.push(query.dataUpdatedAt > 0 ? `updated ${new Date(query.dataUpdatedAt).toISOString()}` : "never updated");
+				return {
+					id: query.queryHash,
+					label: jsonText(query.queryKey),
+					detail: flags.join(", "),
+					state: query.status
+				};
+			});
+		}
+	};
+}
+/**
+* Registers an inspection source on the installed devtools hook, under `name`, so a panel can show it
+* (see the `inspect` request of {@link createAgent}). Re-registering a name replaces its source. Returns
+* `false` when nothing was registered: no hook is installed (no development build, or the hook of
+* another protocol version), the name is empty, or {@link MAX_INSPECTIONS} sources are already
+* registered under other names. A development tool; production builds register nothing.
+*
+* @param name The name to show the source under. Not empty.
+* @param source The source.
+* @returns True when the source is registered.
+* @example
+* import { type RouterLike, registerInspection, routerInspection } from "@shadow-js/devtools";
+*
+* declare const router: RouterLike; // the router from your app's createRouter()
+* registerInspection("router", routerInspection(router));
+* @since 1.0.0
+*/
+function registerInspection(name, source) {
+	if (name === "") return false;
+	const hook = getHook();
+	if (hook === void 0 || hook.inspect === void 0) return false;
+	return hook.inspect(name, source);
+}
+/**
+* Reads every registered source, now, as plain snapshots. A source that throws is reported with its
+* `error` and no rows. Used by the agent for the `inspect` request.
+*
+* @param entries The registered entries (the hook's `inspections()`).
+* @returns One snapshot per entry, in registration order.
+* @example
+* import { readInspections } from "@shadow-js/devtools";
+*
+* const snapshots = readInspections([]); // []
+* @since 1.0.0
+*/
+function readInspections(entries) {
+	return entries.map((entry) => {
+		try {
+			return {
+				name: entry.name,
+				title: clip(String(entry.source.title)),
+				rows: sanitizeRows(entry.source.rows())
+			};
+		} catch (error) {
+			return {
+				name: entry.name,
+				title: clip(String(entry.source.title)),
+				rows: [],
+				error: errorMessage(error)
+			};
+		}
+	});
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+function isRow(value) {
+	return isRecord(value) && typeof value["id"] === "string" && typeof value["label"] === "string" && typeof value["detail"] === "string" && typeof value["state"] === "string";
+}
+/**
+* Reads the answer of an `inspect` request. The panel gets it from the page, so it checks the shape
+* and the bounds before it trusts anything: every field is text, there are at most
+* {@link MAX_INSPECTIONS} sources and at most {@link MAX_INSPECTION_ROWS} + 1 rows each.
+*
+* @param value The `result` of an ok `inspect` response.
+* @returns The snapshots, or `null` when the value is not an answer to `inspect`.
+* @example
+* import { parseInspectResult } from "@shadow-js/devtools";
+*
+* parseInspectResult({ sources: [] }); // []
+* parseInspectResult({ nope: true }); // null
+* @since 1.0.0
+*/
+function parseInspectResult(value) {
+	if (!isRecord(value) || !Array.isArray(value["sources"])) return null;
+	const sources = value["sources"];
+	if (sources.length > 16) return null;
+	const out = [];
+	for (const entry of sources) {
+		if (!isRecord(entry)) return null;
+		const name = entry["name"];
+		const title = entry["title"];
+		const rows = entry["rows"];
+		const error = entry["error"];
+		if (typeof name !== "string" || typeof title !== "string" || !Array.isArray(rows)) return null;
+		if (rows.length > 501 || !rows.every(isRow)) return null;
+		if (error !== void 0 && typeof error !== "string") return null;
+		out.push(error === void 0 ? {
+			name,
+			title,
+			rows
+		} : {
+			name,
+			title,
+			rows,
+			error
+		});
+	}
+	return out;
+}
+//#endregion
+export { parseInspectResult, queryInspection, readInspections, registerInspection, routerInspection, sanitizeRows };
+
+//# sourceMappingURL=inspection.js.map

package/dist/dev/inspection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspection.js","names":[],"sources":["../../src/inspection.ts"],"sourcesContent":["import { getHook } from \"./hook\";\nimport { errorMessage, preview } from \"./preview\";\nimport { MAX_INSPECTION_ROWS, MAX_INSPECTIONS } from \"./protocol\";\n\n/** Longest text of one row field, in characters. Longer text is cut with an ellipsis. */\nconst FIELD_LENGTH = 200;\n\n/**\n * One line of an inspection view. Every field is text, so a row is plain data and can cross a\n * message channel unchanged.\n *\n * @since 1.0.0\n */\nexport interface InspectionRow {\n  /** Stable within the source (a query hash, a route match index, or a fixed name). */\n  readonly id: string;\n  /** What the row is about: a query key, a route pattern, or a fixed label such as `location`. */\n  readonly label: string;\n  /** The details, as one line of text. */\n  readonly detail: string;\n  /** A short state word for the row, such as `success`, `fetching` or `idle`. */\n  readonly state: string;\n}\n\n/**\n * Something that can describe itself to a devtools panel: a router, a query cache, or any other part of\n * the app. `rows()` is called when the panel asks, so it reports the current state, not a copy taken\n * earlier. It may throw; the agent reports the error to the panel instead of failing the request.\n *\n * @example\n * import { type InspectionSource, registerInspection } from \"@shadow-js/devtools\";\n *\n * const source: InspectionSource = {\n *   title: \"Feature flags\",\n *   rows: () => [{ id: \"beta\", label: \"beta\", detail: \"on\", state: \"on\" }],\n * };\n * registerInspection(\"flags\", source);\n * @since 1.0.0\n */\nexport interface InspectionSource {\n  /** The heading of the view, for example `Router`. */\n  readonly title: string;\n  /** The rows now. At most {@link MAX_INSPECTION_ROWS} are sent. */\n  rows(): readonly InspectionRow[];\n  /**\n   * Optional. Calls `notify` whenever the rows may have changed, and returns the function that stops the\n   * calls. The extension's page side listens to it, so the panel refreshes at the moment of the change\n   * instead of on a timer. A source without it is read when the panel asks.\n   */\n  subscribe?(notify: () => void): () => void;\n}\n\n/**\n * A registered source with its name (the key the app registered it under).\n *\n * @since 1.0.0\n */\nexport interface InspectionEntry {\n  /** The name the source was registered under. Unique per hook. */\n  readonly name: string;\n  /** The source. */\n  readonly source: InspectionSource;\n}\n\n/**\n * What the agent answers to an `inspect` request: every registered source, read now. A source that\n * threw has no rows and an `error` message instead.\n *\n * @since 1.0.0\n */\nexport interface InspectionSnapshot {\n  /** The registration name. */\n  readonly name: string;\n  /** The heading of the view. */\n  readonly title: string;\n  /** The rows (at most {@link MAX_INSPECTION_ROWS}). */\n  readonly rows: readonly InspectionRow[];\n  /** Why the rows could not be read, or `undefined` when they were. */\n  readonly error?: string;\n}\n\n/**\n * The part of a router the router inspection reads. A `Router` from `@shadow-js/router` fits this\n * shape; it is structural, so devtools does not depend on the router package.\n *\n * @since 1.0.0\n */\nexport interface RouterLike {\n  /** The router's live state (accessors). */\n  readonly state: {\n    location():\n      | { readonly pathname: string; readonly search: string; readonly hash: string }\n      | undefined;\n    status(): string;\n    pending(): boolean;\n    error(): unknown;\n    matches(): readonly {\n      readonly id: string;\n      readonly pattern: string;\n      readonly params: Readonly<Record<string, string>>;\n    }[];\n  };\n}\n\n/**\n * One query as the query cache reports it (a `QueryInfo` snapshot of `@shadow-js/query`).\n *\n * @since 1.0.0\n */\nexport interface QueryInfoLike {\n  /** The key of the query (plain data). */\n  readonly queryKey: unknown;\n  /** The hash of the key, which identifies the cache entry. */\n  readonly queryHash: string;\n  /** `pending`, `success` or `error`. */\n  readonly status: string;\n  /** `idle`, `fetching` or `paused`. */\n  readonly fetchStatus: string;\n  /** Time (ms since epoch) of the last successful fetch or write; `0` when there was none. */\n  readonly dataUpdatedAt: number;\n  /** True after an invalidation, until the next successful fetch or write. */\n  readonly isInvalidated: boolean;\n  /** Mounted observers of the query. */\n  readonly observers: number;\n}\n\n/**\n * The part of a query client the query inspection reads: its cache, as snapshots. A `QueryClient` from\n * `@shadow-js/query` fits this shape.\n *\n * @since 1.0.0\n */\nexport interface QueryLike {\n  /** The query cache, read through its snapshots, and told about its changes. */\n  readonly queryCache: {\n    /** Every query, as snapshots. Untracked. */\n    find(): readonly QueryInfoLike[];\n    /** Calls `listener` for every change of the cache; returns the function that stops it. */\n    subscribe(listener: () => void): () => void;\n  };\n}\n\n/**\n * The JSON text of plain data (query keys and route params are plain data), cut to the field length.\n * Falls back to {@link preview} when the value does not serialize (a cycle, a bigint).\n *\n * @param value The value.\n * @returns One line of text.\n */\nfunction jsonText(value: unknown): string {\n  try {\n    const text = JSON.stringify(value);\n    return text === undefined ? preview(value, FIELD_LENGTH) : clip(text);\n  } catch {\n    return preview(value, FIELD_LENGTH);\n  }\n}\n\n/**\n * Cuts text to the row field length, with an ellipsis when it was longer.\n *\n * @param text The text.\n * @returns The text, at most {@link FIELD_LENGTH} characters.\n */\nfunction clip(text: string): string {\n  return text.length > FIELD_LENGTH ? `${text.slice(0, FIELD_LENGTH - 1)}…` : text;\n}\n\n/**\n * Turns a source's rows into plain rows, cut to the row limit. Each field is coerced to text and cut,\n * so a source cannot send an object, a function or an unbounded string to the panel.\n *\n * @param rows The rows a source returned.\n * @returns At most {@link MAX_INSPECTION_ROWS} plain rows, and a last row that says how many were cut.\n * @example\n * import { type InspectionRow, sanitizeRows } from \"@shadow-js/devtools\";\n *\n * const rows: InspectionRow[] = [{ id: \"a\", label: \"a\", detail: \"b\", state: \"c\" }];\n * sanitizeRows(rows); // one plain row\n * @since 1.0.0\n */\nexport function sanitizeRows(rows: readonly InspectionRow[]): InspectionRow[] {\n  const out: InspectionRow[] = [];\n  const limit = Math.min(rows.length, MAX_INSPECTION_ROWS);\n  for (let index = 0; index < limit; index += 1) {\n    const row = rows[index];\n    if (row === undefined) continue;\n    out.push({\n      id: clip(String(row.id)),\n      label: clip(String(row.label)),\n      detail: clip(String(row.detail)),\n      state: clip(String(row.state)),\n    });\n  }\n  if (rows.length > MAX_INSPECTION_ROWS) {\n    out.push({\n      id: \"truncated\",\n      label: \"…\",\n      detail: `${rows.length - MAX_INSPECTION_ROWS} more rows not shown`,\n      state: \"truncated\",\n    });\n  }\n  return out;\n}\n\n/**\n * Describes a router: its location, whether a navigation is pending, the error it last reported, and\n * the chain of matched routes. The source reads the router when the panel asks.\n *\n * @param router The router (`createRouter` from `@shadow-js/router`).\n * @param title The heading of the view. Default `Router`.\n * @returns An {@link InspectionSource}.\n * @example\n * import { type RouterLike, registerInspection, routerInspection } from \"@shadow-js/devtools\";\n *\n * declare const router: RouterLike; // the router from your app's createRouter()\n * registerInspection(\"router\", routerInspection(router));\n * @since 1.0.0\n */\nexport function routerInspection(router: RouterLike, title = \"Router\"): InspectionSource {\n  return {\n    title,\n    rows() {\n      const rows: InspectionRow[] = [];\n      const location = router.state.location();\n      const status = router.state.status();\n      rows.push({\n        id: \"location\",\n        label: \"location\",\n        detail:\n          location === undefined\n            ? \"none\"\n            : `${location.pathname}${location.search}${location.hash}`,\n        state: status,\n      });\n      rows.push({\n        id: \"pending\",\n        label: \"pending\",\n        detail: String(router.state.pending()),\n        state: router.state.pending() ? \"pending\" : \"settled\",\n      });\n      const error = router.state.error();\n      if (error !== undefined) {\n        rows.push({ id: \"error\", label: \"error\", detail: errorMessage(error), state: \"errored\" });\n      }\n      router.state.matches().forEach((match, index) => {\n        rows.push({\n          id: `match:${index}`,\n          label: match.pattern,\n          detail: jsonText(match.params),\n          state: match.id,\n        });\n      });\n      return rows;\n    },\n  };\n}\n\n/**\n * Describes a query cache: one row per query, with its key, fetch state, observers and age. The\n * source reads the cache when the panel asks, and it subscribes to the cache so that a change is\n * pushed to a connected panel as soon as it happens. A client without the `inspection` feature of\n * `@shadow-js/query` cannot notify, so the panel then reads the cache only when it asks.\n *\n * @param client The query client (`createQueryClient` from `@shadow-js/query`, created with\n *   `features: [inspection]` for live updates), or anything with the same `queryCache.find()`.\n * @param title The heading of the view. Default `Queries`.\n * @returns An {@link InspectionSource}.\n * @example\n * import { type QueryLike, queryInspection, registerInspection } from \"@shadow-js/devtools\";\n *\n * declare const client: QueryLike; // the query client of your app\n * registerInspection(\"query\", queryInspection(client));\n * @since 1.0.0\n */\nexport function queryInspection(client: QueryLike, title = \"Queries\"): InspectionSource {\n  return {\n    title,\n    subscribe(notify) {\n      try {\n        return client.queryCache.subscribe(() => notify());\n      } catch (error) {\n        // Only the missing `inspection` feature is expected here (a TypeError); anything else is a bug.\n        if (error instanceof TypeError) return () => undefined;\n        throw error;\n      }\n    },\n    rows() {\n      return client.queryCache.find().map((query) => {\n        const flags: string[] = [query.fetchStatus, `${query.observers} observers`];\n        if (query.isInvalidated) flags.push(\"invalidated\");\n        flags.push(\n          query.dataUpdatedAt > 0\n            ? `updated ${new Date(query.dataUpdatedAt).toISOString()}`\n            : \"never updated\",\n        );\n        return {\n          id: query.queryHash,\n          label: jsonText(query.queryKey),\n          detail: flags.join(\", \"),\n          state: query.status,\n        };\n      });\n    },\n  };\n}\n\n/**\n * Registers an inspection source on the installed devtools hook, under `name`, so a panel can show it\n * (see the `inspect` request of {@link createAgent}). Re-registering a name replaces its source. Returns\n * `false` when nothing was registered: no hook is installed (no development build, or the hook of\n * another protocol version), the name is empty, or {@link MAX_INSPECTIONS} sources are already\n * registered under other names. A development tool; production builds register nothing.\n *\n * @param name The name to show the source under. Not empty.\n * @param source The source.\n * @returns True when the source is registered.\n * @example\n * import { type RouterLike, registerInspection, routerInspection } from \"@shadow-js/devtools\";\n *\n * declare const router: RouterLike; // the router from your app's createRouter()\n * registerInspection(\"router\", routerInspection(router));\n * @since 1.0.0\n */\nexport function registerInspection(name: string, source: InspectionSource): boolean {\n  if (!__DEV__) return false;\n  if (name === \"\") return false;\n  const hook = getHook();\n  if (hook === undefined || hook.inspect === undefined) return false;\n  return hook.inspect(name, source);\n}\n\n/**\n * Reads every registered source, now, as plain snapshots. A source that throws is reported with its\n * `error` and no rows. Used by the agent for the `inspect` request.\n *\n * @param entries The registered entries (the hook's `inspections()`).\n * @returns One snapshot per entry, in registration order.\n * @example\n * import { readInspections } from \"@shadow-js/devtools\";\n *\n * const snapshots = readInspections([]); // []\n * @since 1.0.0\n */\nexport function readInspections(entries: readonly InspectionEntry[]): InspectionSnapshot[] {\n  return entries.map((entry) => {\n    try {\n      return {\n        name: entry.name,\n        title: clip(String(entry.source.title)),\n        rows: sanitizeRows(entry.source.rows()),\n      };\n    } catch (error) {\n      return {\n        name: entry.name,\n        title: clip(String(entry.source.title)),\n        rows: [],\n        error: errorMessage(error),\n      };\n    }\n  });\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null;\n}\n\nfunction isRow(value: unknown): value is InspectionRow {\n  return (\n    isRecord(value) &&\n    typeof value[\"id\"] === \"string\" &&\n    typeof value[\"label\"] === \"string\" &&\n    typeof value[\"detail\"] === \"string\" &&\n    typeof value[\"state\"] === \"string\"\n  );\n}\n\n/**\n * Reads the answer of an `inspect` request. The panel gets it from the page, so it checks the shape\n * and the bounds before it trusts anything: every field is text, there are at most\n * {@link MAX_INSPECTIONS} sources and at most {@link MAX_INSPECTION_ROWS} + 1 rows each.\n *\n * @param value The `result` of an ok `inspect` response.\n * @returns The snapshots, or `null` when the value is not an answer to `inspect`.\n * @example\n * import { parseInspectResult } from \"@shadow-js/devtools\";\n *\n * parseInspectResult({ sources: [] }); // []\n * parseInspectResult({ nope: true }); // null\n * @since 1.0.0\n */\nexport function parseInspectResult(value: unknown): InspectionSnapshot[] | null {\n  if (!isRecord(value) || !Array.isArray(value[\"sources\"])) return null;\n  const sources: unknown[] = value[\"sources\"];\n  if (sources.length > MAX_INSPECTIONS) return null;\n  const out: InspectionSnapshot[] = [];\n  for (const entry of sources) {\n    if (!isRecord(entry)) return null;\n    const name = entry[\"name\"];\n    const title = entry[\"title\"];\n    const rows = entry[\"rows\"];\n    const error = entry[\"error\"];\n    if (typeof name !== \"string\" || typeof title !== \"string\" || !Array.isArray(rows)) return null;\n    if (rows.length > MAX_INSPECTION_ROWS + 1 || !rows.every(isRow)) return null;\n    if (error !== undefined && typeof error !== \"string\") return null;\n    out.push(error === undefined ? { name, title, rows } : { name, title, rows, error });\n  }\n  return out;\n}\n"],"mappings":"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"}