@shadow-js/devtools 0.0.0-stage → 1.0.1

package/dist/dev/overlay.js

@@ -0,0 +1,176 @@
+import "./protocol.js";
+import { nodeLabel } from "./inspector.js";
+//#region src/overlay.ts
+const STYLE = `
+:host { all: initial; }
+.layer { position: fixed; left: 0; top: 0; width: 0; height: 0; z-index: 2147483646; pointer-events: none; }
+.box { position: fixed; box-sizing: border-box; pointer-events: none; }
+.highlight { background: rgba(86, 156, 214, 0.25); outline: 1px solid rgba(86, 156, 214, 0.9); }
+.label { position: absolute; left: 0; top: -18px; padding: 1px 6px; font: 11px/16px ui-monospace, monospace; color: #fff; background: rgba(40, 90, 150, 0.95); border-radius: 3px; white-space: nowrap; }
+.flash { outline: 2px solid rgba(255, 193, 7, 0.95); background: rgba(255, 193, 7, 0.18); animation: shadowjs-flash 600ms ease-out forwards; }
+@keyframes shadowjs-flash { from { opacity: 1; } to { opacity: 0; } }
+@media (prefers-reduced-motion: reduce) { .flash { animation-duration: 1ms; } }
+`;
+/**
+* The union of the boxes of `nodes`: the smallest rectangle that contains all of them. Elements are
+* measured with their bounding box, text nodes with a range. Nodes with no layout (zero width and
+* height, or neither an element nor a text node) are skipped.
+*
+* @param nodes The DOM nodes to measure.
+* @param doc The document, used to create ranges for text nodes.
+* @returns The box in viewport coordinates, or `null` when none is laid out.
+* @example
+* import { boxOf } from "@shadow-js/devtools";
+*
+* const box = boxOf([document.body], document);
+* @since 1.0.0
+*/
+function boxOf(nodes, doc) {
+	let left = Number.POSITIVE_INFINITY;
+	let top = Number.POSITIVE_INFINITY;
+	let right = Number.NEGATIVE_INFINITY;
+	let bottom = Number.NEGATIVE_INFINITY;
+	for (const node of nodes) {
+		let rect = null;
+		if (node instanceof Element) rect = node.getBoundingClientRect();
+		else if (node.nodeType === 3 && typeof doc.createRange === "function") {
+			const range = doc.createRange();
+			range.selectNodeContents(node);
+			rect = range.getBoundingClientRect();
+		}
+		if (rect === null || rect.width === 0 && rect.height === 0) continue;
+		left = Math.min(left, rect.left);
+		top = Math.min(top, rect.top);
+		right = Math.max(right, rect.right);
+		bottom = Math.max(bottom, rect.bottom);
+	}
+	if (!Number.isFinite(left) || !Number.isFinite(top)) return null;
+	return {
+		left,
+		top,
+		width: right - left,
+		height: bottom - top
+	};
+}
+function place(element, box) {
+	element.style.left = `${box.left}px`;
+	element.style.top = `${box.top}px`;
+	element.style.width = `${box.width}px`;
+	element.style.height = `${box.height}px`;
+}
+/**
+* Creates the in-page overlay: a shadow-root layer above the page that never takes pointer events.
+* It draws the hover highlight and, when enabled, flashes a component's box each time one of its
+* effects or memos re-runs after its first run. It reads positions from the DOM nodes the agent
+* holds weakly. Dev only: `mountDevtools` creates it, and that call does nothing outside `__DEV__`
+* builds, so this layer never ships.
+*
+* @param agent The agent that knows which DOM nodes a component rendered.
+* @param options Document, flash switch and flash limit.
+* @returns The overlay. Call `dispose` on it when it is no longer needed.
+* @example
+* import { componentStats, createAgent, createOverlay } from "@shadow-js/devtools";
+*
+* const agent = createAgent();
+* const overlay = createOverlay(agent);
+* const top = componentStats(agent.model)[0];
+* if (top !== undefined) overlay.highlight(top.id);
+* @see boxOf
+* @since 1.0.0
+*/
+function createOverlay(agent, options = {}) {
+	const doc = options.document ?? globalThis.document;
+	const limit = options.maxFlashes ?? 40;
+	let flashEnabled = options.flash !== false;
+	const host = doc.createElement("div");
+	host.setAttribute("data-shadowjs-devtools-overlay", "");
+	const root = host.attachShadow({ mode: "open" });
+	const style = doc.createElement("style");
+	style.textContent = STYLE;
+	const layer = doc.createElement("div");
+	layer.className = "layer";
+	root.append(style, layer);
+	doc.body.appendChild(host);
+	let hover = null;
+	const flashBoxes = [];
+	const removeFlash = (element) => {
+		const index = flashBoxes.indexOf(element);
+		if (index !== -1) flashBoxes.splice(index, 1);
+		element.remove();
+	};
+	const boxFor = (id) => {
+		const nodes = agent.nodesOf(id);
+		return nodes.length === 0 ? null : boxOf(nodes, doc);
+	};
+	const flash = (id) => {
+		if (!flashEnabled) return;
+		const box = boxFor(id);
+		if (box === null) return;
+		const element = doc.createElement("div");
+		element.className = "box flash";
+		place(element, box);
+		element.addEventListener("animationend", () => removeFlash(element), { once: true });
+		layer.appendChild(element);
+		flashBoxes.push(element);
+		while (flashBoxes.length > limit) {
+			const oldest = flashBoxes[0];
+			if (oldest === void 0) break;
+			removeFlash(oldest);
+		}
+	};
+	const stop = agent.subscribe((events) => {
+		if (!flashEnabled) return;
+		const flashed = /* @__PURE__ */ new Set();
+		for (const event of events) {
+			if (event.k !== "run") continue;
+			const record = agent.model.node(event.id);
+			if (record === void 0 || record.runs < 2) continue;
+			const component = agent.model.componentOf(event.id);
+			if (component === 0 || flashed.has(component)) continue;
+			flashed.add(component);
+			flash(component);
+		}
+	});
+	return {
+		host,
+		get flashes() {
+			return flashBoxes.length;
+		},
+		highlight(id) {
+			hover?.remove();
+			hover = null;
+			if (id === null) return;
+			const component = agent.model.node(id)?.isComponent === true ? id : agent.model.componentOf(id);
+			const target = component === 0 ? id : component;
+			const box = boxFor(target);
+			if (box === null) return;
+			const element = doc.createElement("div");
+			element.className = "box highlight";
+			place(element, box);
+			const record = agent.model.node(target);
+			const label = doc.createElement("span");
+			label.className = "label";
+			label.textContent = record === void 0 ? `#${target}` : `<${nodeLabel(record)}>`;
+			element.appendChild(label);
+			layer.appendChild(element);
+			hover = element;
+		},
+		flash,
+		clearFlashes() {
+			for (const element of [...flashBoxes]) removeFlash(element);
+		},
+		setFlash(on) {
+			flashEnabled = on;
+		},
+		dispose() {
+			stop();
+			for (const element of [...flashBoxes]) removeFlash(element);
+			hover = null;
+			host.remove();
+		}
+	};
+}
+//#endregion
+export { boxOf, createOverlay };
+
+//# sourceMappingURL=overlay.js.map

package/dist/dev/overlay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay.js","names":[],"sources":["../../src/overlay.ts"],"sourcesContent":["import type { Agent } from \"./agent\";\nimport { nodeLabel } from \"./inspector\";\nimport { NO_ID } from \"./protocol\";\n\n/**\n * A rectangle in viewport coordinates, from {@link boxOf}.\n *\n * @since 1.0.0\n */\nexport interface Box {\n  /** Distance from the left edge of the viewport, in pixels. */\n  left: number;\n  /** Distance from the top edge of the viewport, in pixels. */\n  top: number;\n  /** Width in pixels. */\n  width: number;\n  /** Height in pixels. */\n  height: number;\n}\n\n/**\n * Options of {@link createOverlay}.\n *\n * @since 1.0.0\n */\nexport interface OverlayOptions {\n  /** The document to draw in. @default globalThis.document */\n  document?: Document;\n  /** Flash a component's box each time one of its effects or memos re-runs after its first run. @default true */\n  flash?: boolean;\n  /** Most flash boxes alive at once; older ones are removed first. @default 40 */\n  maxFlashes?: number;\n}\n\n/**\n * The in-page layer: the hover highlight and the update flashes. Created by {@link createOverlay}.\n *\n * @since 1.0.0\n */\nexport interface Overlay {\n  /** The shadow host element that holds the layer. It is appended to `document.body`. */\n  readonly host: HTMLElement;\n  /**\n   * Draws a labeled box around the component of this node (the node itself when it is a component),\n   * replacing the previous highlight. `null` removes the highlight; a node with nothing laid out draws\n   * nothing.\n   */\n  highlight(id: number | null): void;\n  /**\n   * Flashes the rendered DOM of the component with this id once. Does nothing while flashing is off or\n   * when none of its DOM is laid out.\n   */\n  flash(id: number): void;\n  /** Number of flash boxes currently in the page. */\n  readonly flashes: number;\n  /** Removes all flash boxes now (they also remove themselves when their animation ends). */\n  clearFlashes(): void;\n  /**\n   * Turns the update flashes on or off. Turning them off does not remove the boxes already shown; use\n   * {@link Overlay.clearFlashes} for that.\n   */\n  setFlash(on: boolean): void;\n  /**\n   * Stops listening to the agent and removes the layer, the flash boxes and the highlight. Do not use\n   * the overlay afterward.\n   */\n  dispose(): void;\n}\n\nconst STYLE = `\n:host { all: initial; }\n.layer { position: fixed; left: 0; top: 0; width: 0; height: 0; z-index: 2147483646; pointer-events: none; }\n.box { position: fixed; box-sizing: border-box; pointer-events: none; }\n.highlight { background: rgba(86, 156, 214, 0.25); outline: 1px solid rgba(86, 156, 214, 0.9); }\n.label { position: absolute; left: 0; top: -18px; padding: 1px 6px; font: 11px/16px ui-monospace, monospace; color: #fff; background: rgba(40, 90, 150, 0.95); border-radius: 3px; white-space: nowrap; }\n.flash { outline: 2px solid rgba(255, 193, 7, 0.95); background: rgba(255, 193, 7, 0.18); animation: shadowjs-flash 600ms ease-out forwards; }\n@keyframes shadowjs-flash { from { opacity: 1; } to { opacity: 0; } }\n@media (prefers-reduced-motion: reduce) { .flash { animation-duration: 1ms; } }\n`;\n\n/**\n * The union of the boxes of `nodes`: the smallest rectangle that contains all of them. Elements are\n * measured with their bounding box, text nodes with a range. Nodes with no layout (zero width and\n * height, or neither an element nor a text node) are skipped.\n *\n * @param nodes The DOM nodes to measure.\n * @param doc The document, used to create ranges for text nodes.\n * @returns The box in viewport coordinates, or `null` when none is laid out.\n * @example\n * import { boxOf } from \"@shadow-js/devtools\";\n *\n * const box = boxOf([document.body], document);\n * @since 1.0.0\n */\nexport function boxOf(nodes: readonly Node[], doc: Document): Box | null {\n  let left = Number.POSITIVE_INFINITY;\n  let top = Number.POSITIVE_INFINITY;\n  let right = Number.NEGATIVE_INFINITY;\n  let bottom = Number.NEGATIVE_INFINITY;\n  for (const node of nodes) {\n    let rect: DOMRect | null = null;\n    if (node instanceof Element) {\n      rect = node.getBoundingClientRect();\n    } else if (node.nodeType === 3 && typeof doc.createRange === \"function\") {\n      const range = doc.createRange();\n      range.selectNodeContents(node);\n      rect = range.getBoundingClientRect();\n    }\n    if (rect === null || (rect.width === 0 && rect.height === 0)) continue;\n    left = Math.min(left, rect.left);\n    top = Math.min(top, rect.top);\n    right = Math.max(right, rect.right);\n    bottom = Math.max(bottom, rect.bottom);\n  }\n  if (!Number.isFinite(left) || !Number.isFinite(top)) return null;\n  return { left, top, width: right - left, height: bottom - top };\n}\n\nfunction place(element: HTMLElement, box: Box): void {\n  element.style.left = `${box.left}px`;\n  element.style.top = `${box.top}px`;\n  element.style.width = `${box.width}px`;\n  element.style.height = `${box.height}px`;\n}\n\n/**\n * Creates the in-page overlay: a shadow-root layer above the page that never takes pointer events.\n * It draws the hover highlight and, when enabled, flashes a component's box each time one of its\n * effects or memos re-runs after its first run. It reads positions from the DOM nodes the agent\n * holds weakly. Dev only: `mountDevtools` creates it, and that call does nothing outside `__DEV__`\n * builds, so this layer never ships.\n *\n * @param agent The agent that knows which DOM nodes a component rendered.\n * @param options Document, flash switch and flash limit.\n * @returns The overlay. Call `dispose` on it when it is no longer needed.\n * @example\n * import { componentStats, createAgent, createOverlay } from \"@shadow-js/devtools\";\n *\n * const agent = createAgent();\n * const overlay = createOverlay(agent);\n * const top = componentStats(agent.model)[0];\n * if (top !== undefined) overlay.highlight(top.id);\n * @see boxOf\n * @since 1.0.0\n */\nexport function createOverlay(agent: Agent, options: OverlayOptions = {}): Overlay {\n  const doc = options.document ?? globalThis.document;\n  const limit = options.maxFlashes ?? 40;\n  let flashEnabled = options.flash !== false;\n  const host = doc.createElement(\"div\");\n  host.setAttribute(\"data-shadowjs-devtools-overlay\", \"\");\n  const root = host.attachShadow({ mode: \"open\" });\n  const style = doc.createElement(\"style\");\n  style.textContent = STYLE;\n  const layer = doc.createElement(\"div\");\n  layer.className = \"layer\";\n  root.append(style, layer);\n  doc.body.appendChild(host);\n\n  let hover: HTMLElement | null = null;\n  const flashBoxes: HTMLElement[] = [];\n\n  const removeFlash = (element: HTMLElement): void => {\n    const index = flashBoxes.indexOf(element);\n    if (index !== -1) flashBoxes.splice(index, 1);\n    element.remove();\n  };\n\n  const boxFor = (id: number): Box | null => {\n    const nodes = agent.nodesOf(id);\n    return nodes.length === 0 ? null : boxOf(nodes, doc);\n  };\n\n  const flash = (id: number): void => {\n    if (!flashEnabled) return;\n    const box = boxFor(id);\n    if (box === null) return;\n    const element = doc.createElement(\"div\");\n    element.className = \"box flash\";\n    place(element, box);\n    element.addEventListener(\"animationend\", () => removeFlash(element), { once: true });\n    layer.appendChild(element);\n    flashBoxes.push(element);\n    while (flashBoxes.length > limit) {\n      const oldest = flashBoxes[0];\n      if (oldest === undefined) break;\n      removeFlash(oldest);\n    }\n  };\n\n  // Flash the component of every effect or memo that re-runs (its second and later runs).\n  const stop = agent.subscribe((events) => {\n    if (!flashEnabled) return;\n    const flashed = new Set<number>();\n    for (const event of events) {\n      if (event.k !== \"run\") continue;\n      const record = agent.model.node(event.id);\n      if (record === undefined || record.runs < 2) continue;\n      const component = agent.model.componentOf(event.id);\n      if (component === NO_ID || flashed.has(component)) continue;\n      flashed.add(component);\n      flash(component);\n    }\n  });\n\n  return {\n    host,\n    get flashes(): number {\n      return flashBoxes.length;\n    },\n    highlight(id): void {\n      hover?.remove();\n      hover = null;\n      if (id === null) return;\n      const component =\n        agent.model.node(id)?.isComponent === true ? id : agent.model.componentOf(id);\n      const target = component === NO_ID ? id : component;\n      const box = boxFor(target);\n      if (box === null) return;\n      const element = doc.createElement(\"div\");\n      element.className = \"box highlight\";\n      place(element, box);\n      const record = agent.model.node(target);\n      const label = doc.createElement(\"span\");\n      label.className = \"label\";\n      label.textContent = record === undefined ? `#${target}` : `<${nodeLabel(record)}>`;\n      element.appendChild(label);\n      layer.appendChild(element);\n      hover = element;\n    },\n    flash,\n    clearFlashes(): void {\n      for (const element of [...flashBoxes]) removeFlash(element);\n    },\n    setFlash(on): void {\n      flashEnabled = on;\n    },\n    dispose(): void {\n      stop();\n      for (const element of [...flashBoxes]) removeFlash(element);\n      hover = null;\n      host.remove();\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/dev/preview.d.ts

@@ -0,0 +1,74 @@
+//#region src/preview.d.ts
+/**
+ * Short, side-effect-free text for a value. It never walks an object (a store view or a proxy could
+ * run user code or be huge): objects show their kind and size only.
+ *
+ * @param value Any value.
+ * @param limit Maximum length of the result (default 80).
+ * @returns Text such as `42`, `"hello"`, `Array(3)`, `Map(2)`, `{…}` or `<div>`. Longer text is cut to
+ * `limit` characters and ends with `…`.
+ * @example
+ * import { preview } from "@shadow-js/devtools";
+ *
+ * preview([1, 2, 3]); // "Array(3)"
+ * @since 1.0.0
+ */
+export declare function preview(value: unknown, limit?: number): string;
+/**
+ * A readable, bounded message for anything thrown: `name: message` for an `Error`, otherwise the
+ * {@link preview} of the value. Use it to show a caught value to a person.
+ *
+ * @param error The thrown value.
+ * @param limit Maximum length of the result; a longer message is cut and ends with `…` (default 300).
+ * @returns The message, cut to `limit` characters when it is longer.
+ * @example
+ * import { errorMessage } from "@shadow-js/devtools";
+ *
+ * errorMessage(new TypeError("bad")); // "TypeError: bad"
+ * errorMessage("plain"); // "\"plain\""
+ * @see preview
+ * @since 1.0.0
+ */
+export declare function errorMessage(error: unknown, limit?: number): string;
+/**
+ * Pretty JSON for the value editor. Values JSON cannot hold (cycles, BigInt) are shown as text
+ * instead of throwing.
+ *
+ * @param value Any value.
+ * @returns Indented JSON. `undefined` is spelled `undefined`. A value JSON has no text for (a function
+ * or a symbol) gives its {@link preview}. A value that makes `JSON.stringify` throw gives its preview
+ * followed by the reason in parentheses, such as `{…} (not JSON: ...)`.
+ * @example
+ * import { toEditableText } from "@shadow-js/devtools";
+ *
+ * toEditableText([1, 2]); // "[\n  1,\n  2\n]"
+ * @see parseEditableText
+ * @since 1.0.0
+ */
+export declare function toEditableText(value: unknown): string;
+/** The result of {@link parseEditableText}. @since 1.0.0 */
+export type ParsedValue = {
+  ok: true;
+  value: unknown;
+} | {
+  ok: false;
+  error: string;
+};
+/**
+ * Parses what a user typed in the value editor: JSON, or the literal `undefined`. Surrounding
+ * whitespace is ignored. It never throws: bad input comes back as `{ ok: false }` with a message.
+ *
+ * @param text The editor text.
+ * @returns `{ ok: true, value }` for valid input, or `{ ok: false, error }` where `error` is a message
+ * cut to 120 characters.
+ * @example
+ * import { parseEditableText } from "@shadow-js/devtools";
+ *
+ * parseEditableText('{"count": 2}'); // { ok: true, value: { count: 2 } }
+ * parseEditableText("{oops").ok; // false
+ * @see toEditableText
+ * @since 1.0.0
+ */
+export declare function parseEditableText(text: string): ParsedValue;
+//#endregion
+//# sourceMappingURL=preview.d.ts.map

package/dist/dev/preview.js

@@ -0,0 +1,122 @@
+//#region src/preview.ts
+/**
+* Short, side-effect-free text for a value. It never walks an object (a store view or a proxy could
+* run user code or be huge): objects show their kind and size only.
+*
+* @param value Any value.
+* @param limit Maximum length of the result (default 80).
+* @returns Text such as `42`, `"hello"`, `Array(3)`, `Map(2)`, `{…}` or `<div>`. Longer text is cut to
+* `limit` characters and ends with `…`.
+* @example
+* import { preview } from "@shadow-js/devtools";
+*
+* preview([1, 2, 3]); // "Array(3)"
+* @since 1.0.0
+*/
+function preview(value, limit = 80) {
+	const text = describe(value);
+	return text.length > limit ? `${text.slice(0, Math.max(limit - 1, 1))}…` : text;
+}
+function describe(value) {
+	switch (typeof value) {
+		case "string": return JSON.stringify(value);
+		case "number":
+		case "boolean":
+		case "undefined": return String(value);
+		case "bigint": return `${value}n`;
+		case "symbol": return value.toString();
+		case "function": return "ƒ()";
+	}
+	if (value === null) return "null";
+	if (Array.isArray(value)) return `Array(${value.length})`;
+	if (value instanceof Map) return `Map(${value.size})`;
+	if (value instanceof Set) return `Set(${value.size})`;
+	if (value instanceof Date) return Number.isNaN(value.getTime()) ? "Invalid Date" : value.toISOString();
+	if (value instanceof Error) return `${value.name}: ${value.message}`;
+	if (typeof Node !== "undefined" && value instanceof Node) return value instanceof Element ? `<${value.localName}>` : `#${value.nodeName}`;
+	const prototype = Object.getPrototypeOf(value);
+	if (prototype === null || prototype === Object.prototype) return "{…}";
+	const ctor = typeof prototype === "object" && prototype !== null ? Reflect.get(prototype, "constructor") : void 0;
+	const name = typeof ctor === "function" ? ctor.name : "";
+	return name === "" ? "{…}" : `${name} {…}`;
+}
+/**
+* A readable, bounded message for anything thrown: `name: message` for an `Error`, otherwise the
+* {@link preview} of the value. Use it to show a caught value to a person.
+*
+* @param error The thrown value.
+* @param limit Maximum length of the result; a longer message is cut and ends with `…` (default 300).
+* @returns The message, cut to `limit` characters when it is longer.
+* @example
+* import { errorMessage } from "@shadow-js/devtools";
+*
+* errorMessage(new TypeError("bad")); // "TypeError: bad"
+* errorMessage("plain"); // "\"plain\""
+* @see preview
+* @since 1.0.0
+*/
+function errorMessage(error, limit = 300) {
+	const text = error instanceof Error ? `${error.name}: ${error.message}` : preview(error, limit);
+	return text.length > limit ? `${text.slice(0, limit - 1)}…` : text;
+}
+/**
+* Pretty JSON for the value editor. Values JSON cannot hold (cycles, BigInt) are shown as text
+* instead of throwing.
+*
+* @param value Any value.
+* @returns Indented JSON. `undefined` is spelled `undefined`. A value JSON has no text for (a function
+* or a symbol) gives its {@link preview}. A value that makes `JSON.stringify` throw gives its preview
+* followed by the reason in parentheses, such as `{…} (not JSON: ...)`.
+* @example
+* import { toEditableText } from "@shadow-js/devtools";
+*
+* toEditableText([1, 2]); // "[\n  1,\n  2\n]"
+* @see parseEditableText
+* @since 1.0.0
+*/
+function toEditableText(value) {
+	if (value === void 0) return "undefined";
+	try {
+		const json = JSON.stringify(value, null, 2);
+		return json === void 0 ? preview(value, 500) : json;
+	} catch (error) {
+		return `${preview(value, 200)} (not JSON: ${errorMessage(error, 80)})`;
+	}
+}
+/**
+* Parses what a user typed in the value editor: JSON, or the literal `undefined`. Surrounding
+* whitespace is ignored. It never throws: bad input comes back as `{ ok: false }` with a message.
+*
+* @param text The editor text.
+* @returns `{ ok: true, value }` for valid input, or `{ ok: false, error }` where `error` is a message
+* cut to 120 characters.
+* @example
+* import { parseEditableText } from "@shadow-js/devtools";
+*
+* parseEditableText('{"count": 2}'); // { ok: true, value: { count: 2 } }
+* parseEditableText("{oops").ok; // false
+* @see toEditableText
+* @since 1.0.0
+*/
+function parseEditableText(text) {
+	const trimmed = text.trim();
+	if (trimmed === "undefined") return {
+		ok: true,
+		value: void 0
+	};
+	try {
+		return {
+			ok: true,
+			value: JSON.parse(trimmed)
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			error: errorMessage(error, 120)
+		};
+	}
+}
+//#endregion
+export { errorMessage, parseEditableText, preview, toEditableText };
+
+//# sourceMappingURL=preview.js.map

package/dist/dev/preview.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview.js","names":[],"sources":["../../src/preview.ts"],"sourcesContent":["/**\n * Short, side-effect-free text for a value. It never walks an object (a store view or a proxy could\n * run user code or be huge): objects show their kind and size only.\n *\n * @param value Any value.\n * @param limit Maximum length of the result (default 80).\n * @returns Text such as `42`, `\"hello\"`, `Array(3)`, `Map(2)`, `{…}` or `<div>`. Longer text is cut to\n * `limit` characters and ends with `…`.\n * @example\n * import { preview } from \"@shadow-js/devtools\";\n *\n * preview([1, 2, 3]); // \"Array(3)\"\n * @since 1.0.0\n */\nexport function preview(value: unknown, limit = 80): string {\n  const text = describe(value);\n  return text.length > limit ? `${text.slice(0, Math.max(limit - 1, 1))}…` : text;\n}\n\nfunction describe(value: unknown): string {\n  switch (typeof value) {\n    case \"string\":\n      return JSON.stringify(value);\n    case \"number\":\n    case \"boolean\":\n    case \"undefined\":\n      return String(value);\n    case \"bigint\":\n      return `${value}n`;\n    case \"symbol\":\n      return value.toString();\n    case \"function\":\n      return \"ƒ()\";\n    default:\n      break;\n  }\n  if (value === null) return \"null\";\n  if (Array.isArray(value)) return `Array(${value.length})`;\n  if (value instanceof Map) return `Map(${value.size})`;\n  if (value instanceof Set) return `Set(${value.size})`;\n  if (value instanceof Date)\n    return Number.isNaN(value.getTime()) ? \"Invalid Date\" : value.toISOString();\n  if (value instanceof Error) return `${value.name}: ${value.message}`;\n  if (typeof Node !== \"undefined\" && value instanceof Node) {\n    return value instanceof Element ? `<${value.localName}>` : `#${value.nodeName}`;\n  }\n  const prototype: unknown = Object.getPrototypeOf(value);\n  if (prototype === null || prototype === Object.prototype) return \"{…}\";\n  const ctor: unknown =\n    typeof prototype === \"object\" && prototype !== null\n      ? Reflect.get(prototype, \"constructor\")\n      : undefined;\n  const name = typeof ctor === \"function\" ? ctor.name : \"\";\n  return name === \"\" ? \"{…}\" : `${name} {…}`;\n}\n\n/**\n * A readable, bounded message for anything thrown: `name: message` for an `Error`, otherwise the\n * {@link preview} of the value. Use it to show a caught value to a person.\n *\n * @param error The thrown value.\n * @param limit Maximum length of the result; a longer message is cut and ends with `…` (default 300).\n * @returns The message, cut to `limit` characters when it is longer.\n * @example\n * import { errorMessage } from \"@shadow-js/devtools\";\n *\n * errorMessage(new TypeError(\"bad\")); // \"TypeError: bad\"\n * errorMessage(\"plain\"); // \"\\\"plain\\\"\"\n * @see preview\n * @since 1.0.0\n */\nexport function errorMessage(error: unknown, limit = 300): string {\n  const text = error instanceof Error ? `${error.name}: ${error.message}` : preview(error, limit);\n  return text.length > limit ? `${text.slice(0, limit - 1)}…` : text;\n}\n\n/**\n * Pretty JSON for the value editor. Values JSON cannot hold (cycles, BigInt) are shown as text\n * instead of throwing.\n *\n * @param value Any value.\n * @returns Indented JSON. `undefined` is spelled `undefined`. A value JSON has no text for (a function\n * or a symbol) gives its {@link preview}. A value that makes `JSON.stringify` throw gives its preview\n * followed by the reason in parentheses, such as `{…} (not JSON: ...)`.\n * @example\n * import { toEditableText } from \"@shadow-js/devtools\";\n *\n * toEditableText([1, 2]); // \"[\\n  1,\\n  2\\n]\"\n * @see parseEditableText\n * @since 1.0.0\n */\nexport function toEditableText(value: unknown): string {\n  if (value === undefined) return \"undefined\";\n  try {\n    const json = JSON.stringify(value, null, 2);\n    return json === undefined ? preview(value, 500) : json;\n  } catch (error) {\n    // Circular structures and BigInt values cannot be JSON: show what they are instead.\n    return `${preview(value, 200)} (not JSON: ${errorMessage(error, 80)})`;\n  }\n}\n\n/** The result of {@link parseEditableText}. @since 1.0.0 */\nexport type ParsedValue = { ok: true; value: unknown } | { ok: false; error: string };\n\n/**\n * Parses what a user typed in the value editor: JSON, or the literal `undefined`. Surrounding\n * whitespace is ignored. It never throws: bad input comes back as `{ ok: false }` with a message.\n *\n * @param text The editor text.\n * @returns `{ ok: true, value }` for valid input, or `{ ok: false, error }` where `error` is a message\n * cut to 120 characters.\n * @example\n * import { parseEditableText } from \"@shadow-js/devtools\";\n *\n * parseEditableText('{\"count\": 2}'); // { ok: true, value: { count: 2 } }\n * parseEditableText(\"{oops\").ok; // false\n * @see toEditableText\n * @since 1.0.0\n */\nexport function parseEditableText(text: string): ParsedValue {\n  const trimmed = text.trim();\n  if (trimmed === \"undefined\") return { ok: true, value: undefined };\n  try {\n    return { ok: true, value: JSON.parse(trimmed) as unknown };\n  } catch (error) {\n    return { ok: false, error: errorMessage(error, 120) };\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;AAcA,SAAgB,QAAQ,OAAgB,QAAQ,IAAY;CAC1D,MAAM,OAAO,SAAS,KAAK;CAC3B,OAAO,KAAK,SAAS,QAAQ,GAAG,KAAK,MAAM,GAAG,KAAK,IAAI,QAAQ,GAAG,CAAC,CAAC,EAAE,KAAK;AAC7E;AAEA,SAAS,SAAS,OAAwB;CACxC,QAAQ,OAAO,OAAf;EACE,KAAK,UACH,OAAO,KAAK,UAAU,KAAK;EAC7B,KAAK;EACL,KAAK;EACL,KAAK,aACH,OAAO,OAAO,KAAK;EACrB,KAAK,UACH,OAAO,GAAG,MAAM;EAClB,KAAK,UACH,OAAO,MAAM,SAAS;EACxB,KAAK,YACH,OAAO;CAGX;CACA,IAAI,UAAU,MAAM,OAAO;CAC3B,IAAI,MAAM,QAAQ,KAAK,GAAG,OAAO,SAAS,MAAM,OAAO;CACvD,IAAI,iBAAiB,KAAK,OAAO,OAAO,MAAM,KAAK;CACnD,IAAI,iBAAiB,KAAK,OAAO,OAAO,MAAM,KAAK;CACnD,IAAI,iBAAiB,MACnB,OAAO,OAAO,MAAM,MAAM,QAAQ,CAAC,IAAI,iBAAiB,MAAM,YAAY;CAC5E,IAAI,iBAAiB,OAAO,OAAO,GAAG,MAAM,KAAK,IAAI,MAAM;CAC3D,IAAI,OAAO,SAAS,eAAe,iBAAiB,MAClD,OAAO,iBAAiB,UAAU,IAAI,MAAM,UAAU,KAAK,IAAI,MAAM;CAEvE,MAAM,YAAqB,OAAO,eAAe,KAAK;CACtD,IAAI,cAAc,QAAQ,cAAc,OAAO,WAAW,OAAO;CACjE,MAAM,OACJ,OAAO,cAAc,YAAY,cAAc,OAC3C,QAAQ,IAAI,WAAW,aAAa,IACpC,KAAA;CACN,MAAM,OAAO,OAAO,SAAS,aAAa,KAAK,OAAO;CACtD,OAAO,SAAS,KAAK,QAAQ,GAAG,KAAK;AACvC;;;;;;;;;;;;;;;;AAiBA,SAAgB,aAAa,OAAgB,QAAQ,KAAa;CAChE,MAAM,OAAO,iBAAiB,QAAQ,GAAG,MAAM,KAAK,IAAI,MAAM,YAAY,QAAQ,OAAO,KAAK;CAC9F,OAAO,KAAK,SAAS,QAAQ,GAAG,KAAK,MAAM,GAAG,QAAQ,CAAC,EAAE,KAAK;AAChE;;;;;;;;;;;;;;;;AAiBA,SAAgB,eAAe,OAAwB;CACrD,IAAI,UAAU,KAAA,GAAW,OAAO;CAChC,IAAI;EACF,MAAM,OAAO,KAAK,UAAU,OAAO,MAAM,CAAC;EAC1C,OAAO,SAAS,KAAA,IAAY,QAAQ,OAAO,GAAG,IAAI;CACpD,SAAS,OAAO;EAEd,OAAO,GAAG,QAAQ,OAAO,GAAG,EAAE,cAAc,aAAa,OAAO,EAAE,EAAE;CACtE;AACF;;;;;;;;;;;;;;;;AAoBA,SAAgB,kBAAkB,MAA2B;CAC3D,MAAM,UAAU,KAAK,KAAK;CAC1B,IAAI,YAAY,aAAa,OAAO;EAAE,IAAI;EAAM,OAAO,KAAA;CAAU;CACjE,IAAI;EACF,OAAO;GAAE,IAAI;GAAM,OAAO,KAAK,MAAM,OAAO;EAAa;CAC3D,SAAS,OAAO;EACd,OAAO;GAAE,IAAI;GAAO,OAAO,aAAa,OAAO,GAAG;EAAE;CACtD;AACF"}