@shadow-js/devtools 0.0.0-stage → 1.0.0

package/dist/dev/mount.d.ts

@@ -0,0 +1,207 @@
+import { DevtoolsHook } from "./protocol.js";
+import { Agent } from "./agent.js";
+import { Backend } from "./backend.js";
+import { Transport } from "./transport.js";
+import { TabId } from "./ui/state.js";
+//#region src/mount.d.ts
+/**
+ * Options of {@link mountDevtools}. Every field is optional.
+ *
+ * @since 1.0.0
+ */
+export interface MountOptions {
+  /**
+   * The hook to listen to. When unset, the package uses the hook {@link installHook} returns.
+   *
+   * @default installHook()
+   */
+  hook?: DevtoolsHook;
+  /**
+   * Use this agent instead of creating one. It must already be attached to the hook, or be attached by
+   * you: the package attaches only the agent it creates.
+   *
+   * @default createAgent({ writeSignal })
+   */
+  agent?: Agent;
+  /**
+   * Where the overlay host element is appended.
+   *
+   * @default document.body
+   */
+  container?: Element;
+  /**
+   * The document to use.
+   *
+   * @default globalThis.document
+   */
+  document?: Document;
+  /**
+   * Start with the panel open. When false, only the launcher button shows.
+   *
+   * @default false
+   */
+  open?: boolean;
+  /**
+   * Keyboard shortcut that toggles the panel, such as `"Alt+Shift+D"`. Pass `false` to turn the shortcut
+   * off.
+   *
+   * @default "Alt+Shift+D"
+   */
+  toggleKey?: string | false;
+  /**
+   * Panel position in pixels from the top-left corner of the window.
+   *
+   * @default { x: 16, y: 16 }
+   */
+  position?: {
+    x: number;
+    y: number;
+  };
+  /**
+   * Flash components when they update. The panel's Flash button changes this at runtime.
+   *
+   * @default true
+   */
+  flash?: boolean;
+  /**
+   * The tab shown first.
+   *
+   * @default "tree"
+   */
+  tab?: TabId;
+  /**
+   * Also serve the agent over this transport, for a remote panel in an extension or another tab. See
+   * {@link serveAgent}.
+   */
+  serve?: Transport;
+  /**
+   * Show the launcher button that opens the panel.
+   *
+   * @default true
+   */
+  launcher?: boolean;
+}
+/**
+ * The handle `mountDevtools()` returns. Every member is a no-op in production builds, where `host`,
+ * `root`, `agent` and `backend` are `null`.
+ *
+ * @since 1.0.0
+ */
+export interface DevtoolsHandle {
+  /**
+   * The shadow host element the panel is appended to, or `null` when the tools are off.
+   */
+  readonly host: HTMLElement | null;
+  /**
+   * The shadow root holding the panel, or `null` when the tools are off.
+   */
+  readonly root: ShadowRoot | null;
+  /**
+   * The agent the panel reads from, or `null` when the tools are off.
+   */
+  readonly agent: Agent | null;
+  /**
+   * The backend the panel reads from, or `null` when the tools are off.
+   */
+  readonly backend: Backend | null;
+  /**
+   * Whether the panel is open. Each read returns the current value.
+   */
+  readonly isOpen: boolean;
+  /**
+   * Opens the panel and applies the change now.
+   */
+  open(): void;
+  /**
+   * Closes the panel and applies the change now.
+   */
+  close(): void;
+  /**
+   * Opens the panel when it is closed, and closes it when it is open. Applies the change now.
+   */
+  toggle(): void;
+  /**
+   * Moves the panel to `x` and `y` pixels from the top-left corner. The position is clamped to the
+   * window.
+   */
+  moveTo(x: number, y: number): void;
+  /**
+   * Shows a tab and applies the change now.
+   */
+  setTab(tab: TabId): void;
+  /**
+   * Selects a node in the tree.
+   */
+  select(id: number): void;
+  /**
+   * Applies pending model changes to the panel now. The panel normally refreshes once per frame.
+   */
+  flush(): void;
+  /**
+   * Removes the panel, the overlay and every listener, and stops serving the agent. When
+   * `mountDevtools()` created the agent, it is disposed too. Calling this again does nothing.
+   */
+  dispose(): void;
+}
+/** A parsed keyboard shortcut. */
+interface Shortcut {
+  alt: boolean;
+  ctrl: boolean;
+  shift: boolean;
+  meta: boolean;
+  key: string;
+}
+/**
+ * Parses `"Alt+Shift+D"` style shortcuts. Modifier names are case-insensitive: `alt` or `option`,
+ * `ctrl` or `control`, `shift`, and `meta`, `cmd` or `command`. The last part is the key, compared
+ * case-insensitively with `event.key`.
+ *
+ * @param spec The shortcut text.
+ * @returns The parsed shortcut, or `null` when it has no key.
+ * @example
+ * import { parseShortcut } from "@shadow-js/devtools";
+ * const shortcut = parseShortcut("Ctrl+Shift+K"); // { ctrl: true, shift: true, alt: false, meta: false, key: "k" }
+ * @since 1.0.0
+ */
+export declare function parseShortcut(spec: string): Shortcut | null;
+/**
+ * True when a keyboard event is the shortcut. The modifiers must match exactly. The key matches
+ * `event.key`, or, for a single letter, `event.code` (such as `KeyD`), because Alt and Shift change the
+ * character on some keyboard layouts.
+ *
+ * @param event The event.
+ * @param shortcut From {@link parseShortcut}.
+ * @returns True when the event is the shortcut.
+ * @example
+ * import { matchesShortcut, parseShortcut } from "@shadow-js/devtools";
+ * const toggle = parseShortcut("Alt+Shift+D");
+ * document.addEventListener("keydown", (event) => {
+ *   if (toggle !== null && matchesShortcut(event, toggle)) console.log("toggle the panel");
+ * });
+ * @since 1.0.0
+ */
+export declare function matchesShortcut(event: Pick<KeyboardEvent, "key" | "code" | "altKey" | "ctrlKey" | "shiftKey" | "metaKey">, shortcut: Shortcut): boolean;
+/**
+ * Shows the devtools: a floating, draggable panel in a shadow root (so page styles cannot touch it)
+ * with the component tree, a flame timeline of flushes, a state viewer with live editing, and an
+ * issues list. Hovering a row highlights the component on the page; components flash when they
+ * update. Toggle with `Alt+Shift+D`, or with the `toggleKey` option.
+ *
+ * This is a development tool: the panel is for development builds and never ships. In production
+ * builds (`__DEV__` false), on the server, or when another protocol version owns the hook, this does
+ * nothing and returns a handle of no-ops. Call it before your application renders so no event is
+ * missed.
+ *
+ * @param options See {@link MountOptions}.
+ * @returns A handle to control or remove the panel.
+ * @example
+ * import { mountDevtools } from "@shadow-js/devtools";
+ * // Development builds only: production builds ignore this call.
+ * const devtools = mountDevtools({ open: true });
+ * devtools.toggle();
+ * @since 1.0.0
+ */
+export declare function mountDevtools(options?: MountOptions): DevtoolsHandle;
+//#endregion
+export {};
+//# sourceMappingURL=mount.d.ts.map

package/dist/dev/mount.js

@@ -0,0 +1,256 @@
+import { installHook } from "./hook.js";
+import { createAgent } from "./agent.js";
+import { createLocalBackend } from "./backend.js";
+import { createOverlay } from "./overlay.js";
+import { serveAgent } from "./transport.js";
+import { createPanelState } from "./ui/state.js";
+import { Panel } from "./ui/panel.js";
+import { LAUNCHER_CSS, PANEL_CSS } from "./ui/styles.js";
+import { addEventListener, createComponent, effect, render, template } from "@shadow-js/web";
+import { flushSync, useSignal } from "@shadow-js/core";
+import { writeSignal } from "@shadow-js/core/extend";
+//#region src/mount.tsx
+const _tmpl$ = /*#__PURE__*/ template("<button type=\"button\" class=\"launcher\" aria-label=\"Open ShadowJS devtools\">S</button>");
+/**
+* Parses `"Alt+Shift+D"` style shortcuts. Modifier names are case-insensitive: `alt` or `option`,
+* `ctrl` or `control`, `shift`, and `meta`, `cmd` or `command`. The last part is the key, compared
+* case-insensitively with `event.key`.
+*
+* @param spec The shortcut text.
+* @returns The parsed shortcut, or `null` when it has no key.
+* @example
+* import { parseShortcut } from "@shadow-js/devtools";
+* const shortcut = parseShortcut("Ctrl+Shift+K"); // { ctrl: true, shift: true, alt: false, meta: false, key: "k" }
+* @since 1.0.0
+*/
+function parseShortcut(spec) {
+	const parts = spec.split("+").map((part) => part.trim().toLowerCase()).filter((part) => part !== "");
+	const key = parts.pop();
+	if (key === void 0) return null;
+	const has = (...names) => parts.some((part) => names.includes(part));
+	return {
+		alt: has("alt", "option"),
+		ctrl: has("ctrl", "control"),
+		shift: has("shift"),
+		meta: has("meta", "cmd", "command"),
+		key
+	};
+}
+/**
+* True when a keyboard event is the shortcut. The modifiers must match exactly. The key matches
+* `event.key`, or, for a single letter, `event.code` (such as `KeyD`), because Alt and Shift change the
+* character on some keyboard layouts.
+*
+* @param event The event.
+* @param shortcut From {@link parseShortcut}.
+* @returns True when the event is the shortcut.
+* @example
+* import { matchesShortcut, parseShortcut } from "@shadow-js/devtools";
+* const toggle = parseShortcut("Alt+Shift+D");
+* document.addEventListener("keydown", (event) => {
+*   if (toggle !== null && matchesShortcut(event, toggle)) console.log("toggle the panel");
+* });
+* @since 1.0.0
+*/
+function matchesShortcut(event, shortcut) {
+	if (event.altKey !== shortcut.alt || event.ctrlKey !== shortcut.ctrl || event.shiftKey !== shortcut.shift || event.metaKey !== shortcut.meta) return false;
+	if (event.key.toLowerCase() === shortcut.key) return true;
+	return shortcut.key.length === 1 && event.code.toLowerCase() === `key${shortcut.key}`;
+}
+function noop() {}
+const OFF = {
+	host: null,
+	root: null,
+	agent: null,
+	backend: null,
+	isOpen: false,
+	open: noop,
+	close: noop,
+	toggle: noop,
+	moveTo: noop,
+	setTab: noop,
+	select: noop,
+	flush: noop,
+	dispose: noop
+};
+/**
+* Shows the devtools: a floating, draggable panel in a shadow root (so page styles cannot touch it)
+* with the component tree, a flame timeline of flushes, a state viewer with live editing, and an
+* issues list. Hovering a row highlights the component on the page; components flash when they
+* update. Toggle with `Alt+Shift+D`, or with the `toggleKey` option.
+*
+* This is a development tool: the panel is for development builds and never ships. In production
+* builds (`__DEV__` false), on the server, or when another protocol version owns the hook, this does
+* nothing and returns a handle of no-ops. Call it before your application renders so no event is
+* missed.
+*
+* @param options See {@link MountOptions}.
+* @returns A handle to control or remove the panel.
+* @example
+* import { mountDevtools } from "@shadow-js/devtools";
+* // Development builds only: production builds ignore this call.
+* const devtools = mountDevtools({ open: true });
+* devtools.toggle();
+* @since 1.0.0
+*/
+function mountDevtools(options = {}) {
+	const doc = options.document ?? (typeof document === "undefined" ? void 0 : document);
+	if (doc === void 0) return OFF;
+	const hook = options.hook ?? installHook();
+	if (hook === void 0) return OFF;
+	const ownsAgent = options.agent === void 0;
+	const agent = options.agent ?? createAgent({ writeSignal });
+	const detach = ownsAgent ? agent.attach(hook) : noop;
+	const overlay = createOverlay(agent, {
+		document: doc,
+		flash: options.flash !== false
+	});
+	const backend = createLocalBackend(agent, { highlight: (id) => overlay.highlight(id) });
+	const stopServing = options.serve === void 0 ? noop : serveAgent(agent, options.serve, { highlight: (id) => overlay.highlight(id) });
+	const host = doc.createElement("div");
+	host.setAttribute("data-shadowjs-devtools", "");
+	const root = host.attachShadow({ mode: "open" });
+	const style = doc.createElement("style");
+	style.textContent = `${PANEL_CSS}${LAUNCHER_CSS}`;
+	root.appendChild(style);
+	(options.container ?? doc.body).appendChild(host);
+	let state;
+	let setOpen = noop;
+	let setPosition = noop;
+	let isOpen = options.open === true;
+	const start = options.position ?? {
+		x: 16,
+		y: 16
+	};
+	const unmount = agent.quiet(() => render(() => {
+		const [open, setOpenSignal] = useSignal(isOpen);
+		const [position, setPositionSignal] = useSignal({
+			x: start.x,
+			y: start.y
+		});
+		setOpen = (value) => {
+			isOpen = value;
+			setOpenSignal(value);
+		};
+		setPosition = (x, y) => {
+			const maxX = Math.max((doc.defaultView?.innerWidth ?? 1024) - 80, 0);
+			const maxY = Math.max((doc.defaultView?.innerHeight ?? 768) - 40, 0);
+			setPositionSignal({
+				x: Math.min(Math.max(x, 0), maxX),
+				y: Math.min(Math.max(y, 0), maxY)
+			});
+		};
+		state = createPanelState(backend, {
+			...options.tab === void 0 ? {} : { tab: options.tab },
+			flash: options.flash !== false,
+			onFlash: (on) => overlay.setFlash(on),
+			onPause: (paused) => {
+				if (paused) agent.pause();
+				else agent.resume();
+			}
+		});
+		return [createComponent(Panel, {
+			state,
+			get open() {
+				return open();
+			},
+			get x() {
+				return position().x;
+			},
+			get y() {
+				return position().y;
+			},
+			onMove: (x, y) => setPosition(x, y),
+			onClose: () => setOpen(false)
+		}, "Panel"), (() => {
+			const _el$ = _tmpl$();
+			effect(() => {
+				_el$.hidden = open() || options.launcher === false;
+			});
+			addEventListener(_el$, "click", () => setOpen(true));
+			return _el$;
+		})()];
+	}, root));
+	let refreshPending = false;
+	let frame;
+	const refresh = () => {
+		refreshPending = false;
+		frame = void 0;
+		state?.refresh();
+	};
+	const stopSubscription = backend.subscribe(() => {
+		if (refreshPending) return;
+		refreshPending = true;
+		if (typeof doc.defaultView?.requestAnimationFrame === "function") frame = doc.defaultView.requestAnimationFrame(refresh);
+		else queueMicrotask(refresh);
+	});
+	const shortcut = options.toggleKey === false ? null : parseShortcut(options.toggleKey ?? "Alt+Shift+D");
+	const onKey = (event) => {
+		if (shortcut === null || !matchesShortcut(event, shortcut)) return;
+		event.preventDefault();
+		setOpen(!isOpen);
+		flushSync();
+	};
+	doc.addEventListener("keydown", onKey, true);
+	const flush = () => {
+		agent.flush();
+		if (refreshPending) {
+			if (frame !== void 0) doc.defaultView?.cancelAnimationFrame(frame);
+			refresh();
+		}
+		flushSync();
+	};
+	let disposed = false;
+	return {
+		host,
+		root,
+		agent,
+		backend,
+		get isOpen() {
+			return isOpen;
+		},
+		open() {
+			setOpen(true);
+			flushSync();
+		},
+		close() {
+			setOpen(false);
+			flushSync();
+		},
+		toggle() {
+			setOpen(!isOpen);
+			flushSync();
+		},
+		moveTo(x, y) {
+			setPosition(x, y);
+			flushSync();
+		},
+		setTab(tab) {
+			state?.setTab(tab);
+			flushSync();
+		},
+		select(id) {
+			state?.select(id);
+			flushSync();
+		},
+		flush,
+		dispose() {
+			if (disposed) return;
+			disposed = true;
+			doc.removeEventListener("keydown", onKey, true);
+			stopSubscription();
+			if (frame !== void 0) doc.defaultView?.cancelAnimationFrame(frame);
+			stopServing();
+			unmount();
+			overlay.dispose();
+			backend.dispose();
+			host.remove();
+			detach();
+			if (ownsAgent) agent.dispose();
+		}
+	};
+}
+//#endregion
+export { matchesShortcut, mountDevtools, parseShortcut };
+
+//# sourceMappingURL=mount.js.map

package/dist/dev/mount.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mount.js","names":["_$createComponent"],"sources":["../../src/mount.tsx"],"sourcesContent":["import { flushSync, useSignal } from \"@shadow-js/core\";\nimport { writeSignal } from \"@shadow-js/core/extend\";\nimport { render } from \"@shadow-js/web\";\nimport { type Agent, createAgent } from \"./agent\";\nimport { type Backend, createLocalBackend } from \"./backend\";\nimport { installHook } from \"./hook\";\nimport { createOverlay } from \"./overlay\";\nimport type { DevtoolsHook } from \"./protocol\";\nimport { serveAgent, type Transport } from \"./transport\";\nimport { Panel } from \"./ui/panel\";\nimport { createPanelState, type PanelState, type TabId } from \"./ui/state\";\nimport { LAUNCHER_CSS, PANEL_CSS } from \"./ui/styles\";\n\n/**\n * Options of {@link mountDevtools}. Every field is optional.\n *\n * @since 1.0.0\n */\nexport interface MountOptions {\n  /**\n   * The hook to listen to. When unset, the package uses the hook {@link installHook} returns.\n   *\n   * @default installHook()\n   */\n  hook?: DevtoolsHook;\n  /**\n   * Use this agent instead of creating one. It must already be attached to the hook, or be attached by\n   * you: the package attaches only the agent it creates.\n   *\n   * @default createAgent({ writeSignal })\n   */\n  agent?: Agent;\n  /**\n   * Where the overlay host element is appended.\n   *\n   * @default document.body\n   */\n  container?: Element;\n  /**\n   * The document to use.\n   *\n   * @default globalThis.document\n   */\n  document?: Document;\n  /**\n   * Start with the panel open. When false, only the launcher button shows.\n   *\n   * @default false\n   */\n  open?: boolean;\n  /**\n   * Keyboard shortcut that toggles the panel, such as `\"Alt+Shift+D\"`. Pass `false` to turn the shortcut\n   * off.\n   *\n   * @default \"Alt+Shift+D\"\n   */\n  toggleKey?: string | false;\n  /**\n   * Panel position in pixels from the top-left corner of the window.\n   *\n   * @default { x: 16, y: 16 }\n   */\n  position?: { x: number; y: number };\n  /**\n   * Flash components when they update. The panel's Flash button changes this at runtime.\n   *\n   * @default true\n   */\n  flash?: boolean;\n  /**\n   * The tab shown first.\n   *\n   * @default \"tree\"\n   */\n  tab?: TabId;\n  /**\n   * Also serve the agent over this transport, for a remote panel in an extension or another tab. See\n   * {@link serveAgent}.\n   */\n  serve?: Transport;\n  /**\n   * Show the launcher button that opens the panel.\n   *\n   * @default true\n   */\n  launcher?: boolean;\n}\n\n/**\n * The handle `mountDevtools()` returns. Every member is a no-op in production builds, where `host`,\n * `root`, `agent` and `backend` are `null`.\n *\n * @since 1.0.0\n */\nexport interface DevtoolsHandle {\n  /**\n   * The shadow host element the panel is appended to, or `null` when the tools are off.\n   */\n  readonly host: HTMLElement | null;\n  /**\n   * The shadow root holding the panel, or `null` when the tools are off.\n   */\n  readonly root: ShadowRoot | null;\n  /**\n   * The agent the panel reads from, or `null` when the tools are off.\n   */\n  readonly agent: Agent | null;\n  /**\n   * The backend the panel reads from, or `null` when the tools are off.\n   */\n  readonly backend: Backend | null;\n  /**\n   * Whether the panel is open. Each read returns the current value.\n   */\n  readonly isOpen: boolean;\n  /**\n   * Opens the panel and applies the change now.\n   */\n  open(): void;\n  /**\n   * Closes the panel and applies the change now.\n   */\n  close(): void;\n  /**\n   * Opens the panel when it is closed, and closes it when it is open. Applies the change now.\n   */\n  toggle(): void;\n  /**\n   * Moves the panel to `x` and `y` pixels from the top-left corner. The position is clamped to the\n   * window.\n   */\n  moveTo(x: number, y: number): void;\n  /**\n   * Shows a tab and applies the change now.\n   */\n  setTab(tab: TabId): void;\n  /**\n   * Selects a node in the tree.\n   */\n  select(id: number): void;\n  /**\n   * Applies pending model changes to the panel now. The panel normally refreshes once per frame.\n   */\n  flush(): void;\n  /**\n   * Removes the panel, the overlay and every listener, and stops serving the agent. When\n   * `mountDevtools()` created the agent, it is disposed too. Calling this again does nothing.\n   */\n  dispose(): void;\n}\n\n/** A parsed keyboard shortcut. */\ninterface Shortcut {\n  alt: boolean;\n  ctrl: boolean;\n  shift: boolean;\n  meta: boolean;\n  key: string;\n}\n\n/**\n * Parses `\"Alt+Shift+D\"` style shortcuts. Modifier names are case-insensitive: `alt` or `option`,\n * `ctrl` or `control`, `shift`, and `meta`, `cmd` or `command`. The last part is the key, compared\n * case-insensitively with `event.key`.\n *\n * @param spec The shortcut text.\n * @returns The parsed shortcut, or `null` when it has no key.\n * @example\n * import { parseShortcut } from \"@shadow-js/devtools\";\n * const shortcut = parseShortcut(\"Ctrl+Shift+K\"); // { ctrl: true, shift: true, alt: false, meta: false, key: \"k\" }\n * @since 1.0.0\n */\nexport function parseShortcut(spec: string): Shortcut | null {\n  const parts = spec\n    .split(\"+\")\n    .map((part) => part.trim().toLowerCase())\n    .filter((part) => part !== \"\");\n  const key = parts.pop();\n  if (key === undefined) return null;\n  const has = (...names: string[]): boolean => parts.some((part) => names.includes(part));\n  return {\n    alt: has(\"alt\", \"option\"),\n    ctrl: has(\"ctrl\", \"control\"),\n    shift: has(\"shift\"),\n    meta: has(\"meta\", \"cmd\", \"command\"),\n    key,\n  };\n}\n\n/**\n * True when a keyboard event is the shortcut. The modifiers must match exactly. The key matches\n * `event.key`, or, for a single letter, `event.code` (such as `KeyD`), because Alt and Shift change the\n * character on some keyboard layouts.\n *\n * @param event The event.\n * @param shortcut From {@link parseShortcut}.\n * @returns True when the event is the shortcut.\n * @example\n * import { matchesShortcut, parseShortcut } from \"@shadow-js/devtools\";\n * const toggle = parseShortcut(\"Alt+Shift+D\");\n * document.addEventListener(\"keydown\", (event) => {\n *   if (toggle !== null && matchesShortcut(event, toggle)) console.log(\"toggle the panel\");\n * });\n * @since 1.0.0\n */\nexport function matchesShortcut(\n  event: Pick<KeyboardEvent, \"key\" | \"code\" | \"altKey\" | \"ctrlKey\" | \"shiftKey\" | \"metaKey\">,\n  shortcut: Shortcut,\n): boolean {\n  if (\n    event.altKey !== shortcut.alt ||\n    event.ctrlKey !== shortcut.ctrl ||\n    event.shiftKey !== shortcut.shift ||\n    event.metaKey !== shortcut.meta\n  ) {\n    return false;\n  }\n  const key = event.key.toLowerCase();\n  if (key === shortcut.key) return true;\n  return shortcut.key.length === 1 && event.code.toLowerCase() === `key${shortcut.key}`;\n}\n\nfunction noop(): void {\n  // Production and server builds: the tools do nothing.\n}\n\nconst OFF: DevtoolsHandle = {\n  host: null,\n  root: null,\n  agent: null,\n  backend: null,\n  isOpen: false,\n  open: noop,\n  close: noop,\n  toggle: noop,\n  moveTo: noop,\n  setTab: noop,\n  select: noop,\n  flush: noop,\n  dispose: noop,\n};\n\n/**\n * Shows the devtools: a floating, draggable panel in a shadow root (so page styles cannot touch it)\n * with the component tree, a flame timeline of flushes, a state viewer with live editing, and an\n * issues list. Hovering a row highlights the component on the page; components flash when they\n * update. Toggle with `Alt+Shift+D`, or with the `toggleKey` option.\n *\n * This is a development tool: the panel is for development builds and never ships. In production\n * builds (`__DEV__` false), on the server, or when another protocol version owns the hook, this does\n * nothing and returns a handle of no-ops. Call it before your application renders so no event is\n * missed.\n *\n * @param options See {@link MountOptions}.\n * @returns A handle to control or remove the panel.\n * @example\n * import { mountDevtools } from \"@shadow-js/devtools\";\n * // Development builds only: production builds ignore this call.\n * const devtools = mountDevtools({ open: true });\n * devtools.toggle();\n * @since 1.0.0\n */\nexport function mountDevtools(options: MountOptions = {}): DevtoolsHandle {\n  if (!__DEV__) return OFF;\n  const doc = options.document ?? (typeof document === \"undefined\" ? undefined : document);\n  if (doc === undefined) return OFF;\n  const hook = options.hook ?? installHook();\n  if (hook === undefined) return OFF;\n\n  const ownsAgent = options.agent === undefined;\n  const agent = options.agent ?? createAgent({ writeSignal });\n  const detach = ownsAgent ? agent.attach(hook) : noop;\n  const overlay = createOverlay(agent, { document: doc, flash: options.flash !== false });\n  const backend = createLocalBackend(agent, { highlight: (id) => overlay.highlight(id) });\n  const stopServing =\n    options.serve === undefined\n      ? noop\n      : serveAgent(agent, options.serve, { highlight: (id) => overlay.highlight(id) });\n\n  const host = doc.createElement(\"div\");\n  host.setAttribute(\"data-shadowjs-devtools\", \"\");\n  const root = host.attachShadow({ mode: \"open\" });\n  const style = doc.createElement(\"style\");\n  style.textContent = `${PANEL_CSS}${LAUNCHER_CSS}`;\n  root.appendChild(style);\n  (options.container ?? doc.body).appendChild(host);\n\n  let state: PanelState | undefined;\n  let setOpen: (value: boolean) => void = noop;\n  let setPosition: (x: number, y: number) => void = noop;\n  let isOpen = options.open === true;\n  const start = options.position ?? { x: 16, y: 16 };\n\n  // Everything the panel creates is invisible to the agent: it must not inspect itself.\n  const unmount = agent.quiet(() =>\n    render(() => {\n      const [open, setOpenSignal] = useSignal(isOpen);\n      const [position, setPositionSignal] = useSignal({ x: start.x, y: start.y });\n      setOpen = (value) => {\n        isOpen = value;\n        setOpenSignal(value);\n      };\n      setPosition = (x, y) => {\n        const maxX = Math.max((doc.defaultView?.innerWidth ?? 1024) - 80, 0);\n        const maxY = Math.max((doc.defaultView?.innerHeight ?? 768) - 40, 0);\n        setPositionSignal({ x: Math.min(Math.max(x, 0), maxX), y: Math.min(Math.max(y, 0), maxY) });\n      };\n      state = createPanelState(backend, {\n        ...(options.tab === undefined ? {} : { tab: options.tab }),\n        flash: options.flash !== false,\n        onFlash: (on) => overlay.setFlash(on),\n        onPause: (paused) => {\n          if (paused) agent.pause();\n          else agent.resume();\n        },\n      });\n      return (\n        <>\n          <Panel\n            state={state}\n            open={open()}\n            x={position().x}\n            y={position().y}\n            onMove={(x, y) => setPosition(x, y)}\n            onClose={() => setOpen(false)}\n          />\n          <button\n            type=\"button\"\n            class=\"launcher\"\n            aria-label=\"Open ShadowJS devtools\"\n            hidden={open() || options.launcher === false}\n            on:click={() => setOpen(true)}\n          >\n            S\n          </button>\n        </>\n      );\n    }, root),\n  );\n\n  // The model changes far more often than anyone can read it: refresh the views once per frame.\n  let refreshPending = false;\n  let frame: number | undefined;\n  const refresh = (): void => {\n    refreshPending = false;\n    frame = undefined;\n    state?.refresh();\n  };\n  const stopSubscription = backend.subscribe(() => {\n    if (refreshPending) return;\n    refreshPending = true;\n    if (typeof doc.defaultView?.requestAnimationFrame === \"function\") {\n      frame = doc.defaultView.requestAnimationFrame(refresh);\n    } else {\n      queueMicrotask(refresh);\n    }\n  });\n\n  const shortcut =\n    options.toggleKey === false ? null : parseShortcut(options.toggleKey ?? \"Alt+Shift+D\");\n  const onKey = (event: KeyboardEvent): void => {\n    if (shortcut === null || !matchesShortcut(event, shortcut)) return;\n    event.preventDefault();\n    setOpen(!isOpen);\n    flushSync();\n  };\n  doc.addEventListener(\"keydown\", onKey, true);\n\n  const flush = (): void => {\n    // Deliver the agent's pending events first: they are what schedules the refresh.\n    agent.flush();\n    if (refreshPending) {\n      if (frame !== undefined) doc.defaultView?.cancelAnimationFrame(frame);\n      refresh();\n    }\n    flushSync();\n  };\n\n  let disposed = false;\n  return {\n    host,\n    root,\n    agent,\n    backend,\n    get isOpen(): boolean {\n      return isOpen;\n    },\n    open(): void {\n      setOpen(true);\n      flushSync();\n    },\n    close(): void {\n      setOpen(false);\n      flushSync();\n    },\n    toggle(): void {\n      setOpen(!isOpen);\n      flushSync();\n    },\n    moveTo(x, y): void {\n      setPosition(x, y);\n      flushSync();\n    },\n    setTab(tab): void {\n      state?.setTab(tab);\n      flushSync();\n    },\n    select(id): void {\n      state?.select(id);\n      flushSync();\n    },\n    flush,\n    dispose(): void {\n      if (disposed) return;\n      disposed = true;\n      doc.removeEventListener(\"keydown\", onKey, true);\n      stopSubscription();\n      if (frame !== undefined) doc.defaultView?.cancelAnimationFrame(frame);\n      stopServing();\n      unmount();\n      overlay.dispose();\n      backend.dispose();\n      host.remove();\n      detach();\n      if (ownsAgent) agent.dispose();\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/dev/overlay.d.ts

@@ -0,0 +1,102 @@
+import { Agent } from "./agent.js";
+//#region src/overlay.d.ts
+/**
+ * A rectangle in viewport coordinates, from {@link boxOf}.
+ *
+ * @since 1.0.0
+ */
+export interface Box {
+  /** Distance from the left edge of the viewport, in pixels. */
+  left: number;
+  /** Distance from the top edge of the viewport, in pixels. */
+  top: number;
+  /** Width in pixels. */
+  width: number;
+  /** Height in pixels. */
+  height: number;
+}
+/**
+ * Options of {@link createOverlay}.
+ *
+ * @since 1.0.0
+ */
+export interface OverlayOptions {
+  /** The document to draw in. @default globalThis.document */
+  document?: Document;
+  /** Flash a component's box each time one of its effects or memos re-runs after its first run. @default true */
+  flash?: boolean;
+  /** Most flash boxes alive at once; older ones are removed first. @default 40 */
+  maxFlashes?: number;
+}
+/**
+ * The in-page layer: the hover highlight and the update flashes. Created by {@link createOverlay}.
+ *
+ * @since 1.0.0
+ */
+export interface Overlay {
+  /** The shadow host element that holds the layer. It is appended to `document.body`. */
+  readonly host: HTMLElement;
+  /**
+   * Draws a labeled box around the component of this node (the node itself when it is a component),
+   * replacing the previous highlight. `null` removes the highlight; a node with nothing laid out draws
+   * nothing.
+   */
+  highlight(id: number | null): void;
+  /**
+   * Flashes the rendered DOM of the component with this id once. Does nothing while flashing is off or
+   * when none of its DOM is laid out.
+   */
+  flash(id: number): void;
+  /** Number of flash boxes currently in the page. */
+  readonly flashes: number;
+  /** Removes all flash boxes now (they also remove themselves when their animation ends). */
+  clearFlashes(): void;
+  /**
+   * Turns the update flashes on or off. Turning them off does not remove the boxes already shown; use
+   * {@link Overlay.clearFlashes} for that.
+   */
+  setFlash(on: boolean): void;
+  /**
+   * Stops listening to the agent and removes the layer, the flash boxes and the highlight. Do not use
+   * the overlay afterward.
+   */
+  dispose(): void;
+}
+/**
+ * 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
+ */
+export declare function boxOf(nodes: readonly Node[], doc: Document): Box | null;
+/**
+ * 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
+ */
+export declare function createOverlay(agent: Agent, options?: OverlayOptions): Overlay;
+//#endregion
+//# sourceMappingURL=overlay.d.ts.map