@atolljs/devtools 0.1.7

package/dist/chunk-4N3NBFL3.js

@@ -0,0 +1,474 @@
+// ../../src/devtools.ts
+var THREAD = typeof WorkerGlobalScope !== "undefined" && self instanceof WorkerGlobalScope ? "worker" : "main";
+var sink = null;
+var setDevtoolsSink = (custom) => {
+  sink = custom;
+};
+var emitDevtools = (event) => {
+  if (sink) sink({ ...event, at: performance.now(), thread: THREAD });
+};
+var PROBED = /* @__PURE__ */ Symbol.for("atoll.devtools.fetch");
+var BODY_PREVIEW = 8 * 1024;
+var TEXTISH = /text|json|javascript|xml|html|css|svg|csv|urlencoded|graphql/;
+var headerList = (h) => h ? [...h.entries()].slice(0, 64) : void 0;
+var bodyPreview = (body) => {
+  if (body === null || body === void 0) return void 0;
+  if (typeof body === "string") return body.slice(0, BODY_PREVIEW);
+  if (body instanceof URLSearchParams) return String(body).slice(0, BODY_PREVIEW);
+  if (body instanceof Blob) return `[${body.type || "blob"} ${body.size}B]`;
+  if (body instanceof ArrayBuffer) return `[ArrayBuffer ${body.byteLength}B]`;
+  if (ArrayBuffer.isView(body)) return `[${body.constructor.name} ${body.byteLength}B]`;
+  if (typeof FormData !== "undefined" && body instanceof FormData) return "[FormData]";
+  return "[stream]";
+};
+var readPreview = async (res, cap) => {
+  const reader = res.body?.getReader();
+  if (!reader) return void 0;
+  const chunks = [];
+  let n = 0;
+  try {
+    while (n < cap) {
+      const { done, value } = await reader.read();
+      if (done || !value) break;
+      chunks.push(value);
+      n += value.byteLength;
+    }
+  } catch {
+  }
+  if (!n) return void 0;
+  const all = new Uint8Array(n);
+  let off = 0;
+  for (const c of chunks) {
+    all.set(c, off);
+    off += c.byteLength;
+  }
+  return new TextDecoder().decode(all) + (n >= cap ? "\u2026" : "");
+};
+var findTiming = async (absUrl, t0) => {
+  const perf = globalThis.performance;
+  if (!perf?.getEntriesByType) return void 0;
+  for (let tries = 0; tries < 12; tries++) {
+    let best;
+    for (const e of perf.getEntriesByType("resource")) {
+      if (e.name !== absUrl || e.startTime < t0 - 5) continue;
+      if (!best || e.startTime < best.startTime) best = e;
+    }
+    if (best) {
+      const seg = (a, b) => b > a && a > 0 ? b - a : 0;
+      return {
+        queue: seg(best.fetchStart, best.domainLookupStart),
+        dns: seg(best.domainLookupStart, best.domainLookupEnd),
+        tcp: best.secureConnectionStart > 0 ? seg(best.connectStart, best.secureConnectionStart) : seg(best.connectStart, best.connectEnd),
+        tls: best.secureConnectionStart > 0 ? seg(best.secureConnectionStart, best.connectEnd) : 0,
+        wait: seg(best.requestStart, best.responseStart),
+        download: seg(best.responseStart, best.responseEnd),
+        transferSize: best.transferSize,
+        encodedSize: best.encodedBodySize,
+        decodedSize: best.decodedBodySize
+      };
+    }
+    await new Promise((r) => setTimeout(r, 250));
+  }
+  return void 0;
+};
+var installFetchProbe = (scope) => {
+  const original = scope.fetch;
+  if (!original || original[PROBED]) return;
+  let seq = 0;
+  const wrapped = async (input, init) => {
+    const t0 = performance.now();
+    const id = ++seq;
+    const isReq = typeof Request !== "undefined" && input instanceof Request;
+    const url = isReq ? input.url : String(input);
+    const abs = (() => {
+      try {
+        return new URL(url, self.location?.href).href;
+      } catch {
+        return url;
+      }
+    })();
+    const method = (init?.method ?? (isReq ? input.method : "GET")).toUpperCase();
+    const reqClone = isReq && !init?.body ? input.clone() : null;
+    const reqHeaders = headerList(
+      init?.headers ? new Headers(init.headers) : isReq ? input.headers : void 0
+    );
+    let reqBody = bodyPreview(init?.body);
+    try {
+      const res = await original.call(scope, input, init);
+      const len = res.headers.get("content-length");
+      emitDevtools({
+        type: "net:fetch",
+        id,
+        url: url.slice(0, 300),
+        method,
+        status: res.status,
+        ms: performance.now() - t0,
+        bytes: len === null ? void 0 : Number(len),
+        reqHeaders,
+        reqBody
+      });
+      const resClone = res.clone();
+      void (async () => {
+        reqBody ??= reqClone ? await reqClone.text().then((t2) => t2.slice(0, BODY_PREVIEW)).catch(() => void 0) : void 0;
+        const ct = res.headers.get("content-type") ?? "";
+        const resBody = TEXTISH.test(ct) ? await readPreview(resClone, BODY_PREVIEW).catch(() => void 0) : void 0;
+        const t = await findTiming(abs, t0);
+        emitDevtools({
+          type: "net:fetch-detail",
+          id,
+          reqBody,
+          resHeaders: headerList(res.headers),
+          resBody,
+          timing: t,
+          transferSize: t?.transferSize,
+          encodedSize: t?.encodedSize,
+          decodedSize: t?.decodedSize
+        });
+      })();
+      return res;
+    } catch (err) {
+      emitDevtools({
+        type: "net:fetch",
+        id,
+        url: url.slice(0, 300),
+        method,
+        ms: performance.now() - t0,
+        error: err instanceof Error ? err.message : String(err),
+        reqHeaders,
+        reqBody
+      });
+      throw err;
+    }
+  };
+  wrapped[PROBED] = true;
+  scope.fetch = wrapped;
+};
+var memProbed = /* @__PURE__ */ new WeakSet();
+var installMemoryProbe = (scope, intervalMs = 2500) => {
+  if (memProbed.has(scope)) return;
+  const perf = scope.performance;
+  if (!perf) return;
+  const mem = perf.memory;
+  const inWorker = typeof WorkerGlobalScope !== "undefined" && globalThis.self instanceof WorkerGlobalScope;
+  const measure = perf.measureUserAgentSpecificMemory?.bind(perf);
+  const procMem = globalThis.process?.memoryUsage;
+  if (!mem && (!measure || inWorker) && !procMem) return;
+  memProbed.add(scope);
+  if (measure && !inWorker) {
+    const timer2 = setInterval(() => {
+      measure().then((res) => {
+        const contexts = (res.breakdown ?? []).map((b) => ({
+          bytes: b.bytes,
+          scope: b.attribution?.[0]?.scope,
+          url: b.attribution?.[0]?.url
+        })).sort((a, b) => b.bytes - a.bytes).slice(0, 24);
+        emitDevtools({
+          type: "runtime:memory",
+          heapBytes: res.bytes,
+          heapLimitBytes: mem?.jsHeapSizeLimit,
+          contexts
+        });
+      }).catch(() => {
+        if (mem) {
+          emitDevtools({
+            type: "runtime:memory",
+            heapBytes: mem.usedJSHeapSize,
+            heapLimitBytes: mem.jsHeapSizeLimit
+          });
+        }
+      });
+    }, Math.max(intervalMs, 4e3));
+    timer2.unref?.();
+    return;
+  }
+  const timer = setInterval(() => {
+    if (mem) {
+      emitDevtools({
+        type: "runtime:memory",
+        heapBytes: mem.usedJSHeapSize,
+        heapLimitBytes: mem.jsHeapSizeLimit
+      });
+    } else if (procMem) {
+      const u = procMem();
+      emitDevtools({ type: "runtime:memory", heapBytes: u.heapUsed, rssBytes: u.rss });
+    }
+  }, intervalMs);
+  timer.unref?.();
+};
+
+// src/protocol.ts
+var DEVTOOLS_CHANNEL = "atoll-devtools";
+
+// src/broadcast.ts
+function connectBroadcast(opts, session) {
+  const bc = new BroadcastChannel(DEVTOOLS_CHANNEL);
+  const cap = opts.bufferCap ?? 5e4;
+  const tailCap = opts.replayBatches ?? 500;
+  const pending = [];
+  const tail = [];
+  let closed = false;
+  const post = (msg) => {
+    try {
+      bc.postMessage(msg);
+    } catch {
+    }
+  };
+  const hello = () => post({ type: "hello", session });
+  const flush = () => {
+    if (closed || pending.length === 0) return;
+    const events = pending.splice(0, pending.length);
+    tail.push(events);
+    if (tail.length > tailCap) tail.shift();
+    post({ type: "batch", session, events });
+  };
+  bc.onmessage = (m) => {
+    if (m.data?.type === "view") {
+      hello();
+      for (const events of tail) post({ type: "batch", session, events });
+    }
+  };
+  const timer = setInterval(flush, opts.flushMs ?? 100);
+  timer.unref?.();
+  const bye = () => {
+    flush();
+    post({ type: "bye", sessionId: session.id });
+  };
+  const onHide = () => bye();
+  if (typeof addEventListener === "function") addEventListener("pagehide", onHide);
+  if (opts.network !== false) installFetchProbe(globalThis);
+  if (opts.memory !== false) installMemoryProbe(globalThis);
+  setDevtoolsSink((event) => {
+    if (closed) return;
+    pending.push(event);
+    if (pending.length > cap) pending.shift();
+    if (pending.length >= 1e3) flush();
+  });
+  hello();
+  return {
+    session,
+    get open() {
+      return !closed;
+    },
+    close() {
+      if (closed) return;
+      closed = true;
+      bye();
+      setDevtoolsSink(null);
+      clearInterval(timer);
+      if (typeof removeEventListener === "function") removeEventListener("pagehide", onHide);
+      bc.close();
+    }
+  };
+}
+
+// src/client.ts
+var sessionSeq = 0;
+var makeSession = (opts) => {
+  const runtime = typeof window !== "undefined" && typeof window.document !== "undefined" ? "browser" : "node";
+  const hint = opts.session?.hint ?? (runtime === "browser" ? globalThis.location?.href : globalThis.process?.title);
+  return {
+    id: `s-${Date.now().toString(36)}-${++sessionSeq}`,
+    name: opts.session?.name,
+    runtime,
+    hint
+  };
+};
+var autoBroadcast = () => typeof BroadcastChannel !== "undefined" && typeof window !== "undefined" && typeof window.document !== "undefined";
+function connectDevtools(opts = {}) {
+  const session = makeSession(opts);
+  const t = opts.url !== void 0 ? "websocket" : opts.transport ?? "auto";
+  const useBc = t === "broadcast" ? typeof BroadcastChannel !== "undefined" : t === "auto" && autoBroadcast();
+  return useBc ? connectBroadcast(opts, session) : connectWebSocket(opts, session);
+}
+function connectWebSocket(opts, session) {
+  const url = opts.url ?? "ws://127.0.0.1:4780/events";
+  const cap = opts.bufferCap ?? 5e4;
+  const pending = [];
+  let closed = false;
+  let sock = null;
+  const send = (msg) => {
+    if (sock?.open) sock.send(JSON.stringify(msg));
+  };
+  const flush = () => {
+    if (!sock?.open || pending.length === 0) return;
+    const events = pending.splice(0, pending.length);
+    send({ type: "batch", events });
+  };
+  const onOpen = () => {
+    send({ type: "hello", session });
+    flush();
+  };
+  const isNode = typeof window === "undefined" || typeof window.document === "undefined";
+  if (typeof WebSocket !== "undefined") {
+    const ws = new WebSocket(url);
+    sock = {
+      get open() {
+        return ws.readyState === ws.OPEN;
+      },
+      send: (t) => ws.send(t),
+      close: () => ws.close()
+    };
+    ws.onopen = onOpen;
+    ws.onclose = () => clearInterval(timer);
+    ws.onerror = () => ws.close();
+  } else if (isNode) {
+    const mod = "./nodeWs.ts";
+    void import(
+      /* @vite-ignore */
+      mod
+    ).then((m) => {
+      if (closed) return;
+      const ws = m.connectNodeWebSocket(url);
+      sock = ws;
+      ws.onOpen = onOpen;
+      ws.onClose = () => clearInterval(timer);
+    }).catch(() => {
+    });
+  }
+  const timer = setInterval(flush, opts.flushMs ?? 100);
+  timer.unref?.();
+  if (opts.network !== false) installFetchProbe(globalThis);
+  if (opts.memory !== false) installMemoryProbe(globalThis);
+  setDevtoolsSink((event) => {
+    if (closed) return;
+    pending.push(event);
+    if (pending.length > cap) pending.shift();
+    if (pending.length >= 1e3) flush();
+  });
+  return {
+    session,
+    get open() {
+      return sock?.open ?? false;
+    },
+    close() {
+      closed = true;
+      setDevtoolsSink(null);
+      flush();
+      sock?.close();
+      clearInterval(timer);
+    }
+  };
+}
+
+// src/overlay.ts
+var BTN_STYLE = "position:fixed;z-index:2147483646;font:11px ui-monospace,monospace;color:#c9d1d9;background:#161b22;border:1px solid #30363d;border-radius:6px;padding:5px 9px;cursor:pointer";
+var PANEL_STYLE = "position:fixed;z-index:2147483646;display:flex;flex-direction:column;background:#0d1117;border:1px solid #30363d;border-radius:8px;box-shadow:0 12px 40px #000c;overflow:hidden;min-width:340px;min-height:220px";
+var ANCHOR = {
+  topleft: (m) => `left:${m}px;top:${m}px`,
+  topcenter: (m) => `left:50%;top:${m}px;transform:translateX(-50%)`,
+  topright: (m) => `right:${m}px;top:${m}px`,
+  bottomleft: (m) => `left:${m}px;bottom:${m}px`,
+  bottomcenter: (m) => `left:50%;bottom:${m}px;transform:translateX(-50%)`,
+  bottomright: (m) => `right:${m}px;bottom:${m}px`
+};
+function mountDevtoolsOverlay(opts = {}) {
+  const src = opts.src ?? "/__atoll/?mini=1";
+  const W = opts.width ?? 760;
+  const H = opts.height ?? 580;
+  const anchor = ANCHOR[opts.position ?? "bottomright"];
+  let open = false;
+  const btn = document.createElement("button");
+  btn.textContent = "atoll devtools";
+  btn.style.cssText = `${BTN_STYLE};${anchor(12)}`;
+  const panel = document.createElement("div");
+  panel.style.cssText = `${PANEL_STYLE};width:${W}px;height:${H}px;display:none;${anchor(16)}`;
+  const head = document.createElement("div");
+  head.style.cssText = "display:flex;align-items:center;gap:8px;padding:5px 10px;flex:none;border-bottom:1px solid #21262d;font:11px ui-monospace,monospace;color:#8b949e;background:#161b22;cursor:move;user-select:none";
+  head.textContent = "atoll devtools";
+  const pop = document.createElement("a");
+  pop.href = "/__atoll/";
+  pop.target = "_blank";
+  pop.rel = "noopener";
+  pop.textContent = "full page \u2197";
+  pop.style.cssText = "color:#58a6ff;text-decoration:none;margin-left:auto";
+  const x = document.createElement("button");
+  x.textContent = "\u2014";
+  x.title = "collapse";
+  x.style.cssText = "color:#8b949e;background:none;border:none;cursor:pointer;font:inherit;padding:0 2px";
+  head.append(pop, x);
+  const frame = document.createElement("iframe");
+  frame.src = src;
+  frame.style.cssText = "flex:1;border:0;background:#0d1117;min-height:0";
+  const grip = document.createElement("div");
+  grip.style.cssText = "position:absolute;right:0;bottom:0;width:16px;height:16px;cursor:nwse-resize;background:linear-gradient(135deg,transparent 50%,#30363d 50%);border-radius:0 0 7px";
+  panel.append(head, frame, grip);
+  document.body.append(panel, btn);
+  const drag = (e, move) => {
+    e.preventDefault();
+    let lx = e.clientX, ly = e.clientY;
+    const mm = (ev) => {
+      move(ev.clientX - lx, ev.clientY - ly);
+      lx = ev.clientX;
+      ly = ev.clientY;
+    };
+    const up = () => {
+      removeEventListener("pointermove", mm);
+      removeEventListener("pointerup", up);
+    };
+    addEventListener("pointermove", mm);
+    addEventListener("pointerup", up);
+  };
+  head.onpointerdown = (e) => {
+    if (e.target.closest("a,button")) return;
+    drag(e, (dx, dy) => {
+      const r = panel.getBoundingClientRect();
+      const left = Math.min(Math.max(0, r.left + dx), innerWidth - 60);
+      const top = Math.min(Math.max(0, r.top + dy), innerHeight - 40);
+      panel.style.left = `${left}px`;
+      panel.style.top = `${top}px`;
+      panel.style.right = "auto";
+      panel.style.bottom = "auto";
+      panel.style.transform = "none";
+    });
+  };
+  grip.onpointerdown = (e) => {
+    e.stopPropagation();
+    drag(e, (dx, dy) => {
+      const r = panel.getBoundingClientRect();
+      panel.style.width = `${Math.max(340, r.width + dx)}px`;
+      panel.style.height = `${Math.max(220, r.height + dy)}px`;
+    });
+  };
+  const set = (v) => {
+    open = v;
+    panel.style.display = v ? "flex" : "none";
+    btn.style.display = v ? "none" : "block";
+  };
+  btn.onclick = () => set(true);
+  x.onclick = () => set(false);
+  set(opts.startOpen === true);
+  return {
+    open: () => set(true),
+    close: () => set(false),
+    toggle: () => set(!open),
+    unmount: () => {
+      panel.remove();
+      btn.remove();
+    }
+  };
+}
+
+// src/init.ts
+var DEVTOOLS_PARAM = "__atoll_devtools";
+var devtoolsEnabled2 = (enabled) => {
+  if (enabled !== void 0) return enabled;
+  if (typeof location !== "undefined" && typeof location.search === "string") {
+    return new URLSearchParams(location.search).has(DEVTOOLS_PARAM);
+  }
+  return !!globalThis.process?.env?.ATOLL_DEVTOOLS;
+};
+function initDevtools(opts = {}) {
+  if (!devtoolsEnabled2(opts.enabled)) return null;
+  const conn = connectDevtools(opts);
+  const inWindow = typeof window !== "undefined" && typeof window.document !== "undefined";
+  const overlay = inWindow && opts.overlay !== false ? mountDevtoolsOverlay(typeof opts.overlay === "object" ? opts.overlay : {}) : null;
+  return { conn, overlay };
+}
+
+export {
+  connectDevtools,
+  mountDevtoolsOverlay,
+  DEVTOOLS_PARAM,
+  devtoolsEnabled2 as devtoolsEnabled,
+  initDevtools
+};

package/dist/client.d.ts

@@ -0,0 +1,34 @@
+import type { SessionInfo } from './protocol.js';
+export interface ConnectDevtoolsOptions {
+    /**
+     * Transport. Default `'auto'`: BroadcastChannel in a browser window
+     * (pure client — dashboards open on the app's own origin via /__atoll/),
+     * WebSocket everywhere else (Node, workers, non-BC browsers).
+     * `'websocket'` or setting `url` opts into the aggregate server.
+     */
+    transport?: 'auto' | 'broadcast' | 'websocket';
+    /** Server ingest endpoint — implies websocket transport. */
+    url?: string;
+    /** Session identity shown in the dashboard. */
+    session?: {
+        name?: string;
+        hint?: string;
+    };
+    /** Batch flush interval ms (default 100). */
+    flushMs?: number;
+    /** Events buffered while disconnected (default 50_000 — oldest dropped). */
+    bufferCap?: number;
+    /** Batches kept for replay to late-joining dashboards (broadcast, default 500). */
+    replayBatches?: number;
+    /** Patch global fetch to log requests (default true). Worker fetch is probed via the pool's devtools INIT flag. */
+    network?: boolean;
+    /** Sample JS heap usage periodically — Chrome/Blink only (default true). */
+    memory?: boolean;
+}
+export interface DevtoolsConnection {
+    readonly open: boolean;
+    readonly session: SessionInfo;
+    /** Uninstall the sink and close the socket. */
+    close(): void;
+}
+export declare function connectDevtools(opts?: ConnectDevtoolsOptions): DevtoolsConnection;

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { connectDevtools } from './client.js';
+export type { ConnectDevtoolsOptions, DevtoolsConnection } from './client.js';
+export { mountDevtoolsOverlay } from './overlay.js';
+export type { DevtoolsOverlay, DevtoolsOverlayOptions } from './overlay.js';
+export { DEVTOOLS_PARAM, devtoolsEnabled, initDevtools } from './init.js';
+export type { InitDevtools, InitDevtoolsOptions } from './init.js';
+export type { SessionInfo } from './protocol.js';

package/dist/index.js

@@ -0,0 +1,14 @@
+import {
+  DEVTOOLS_PARAM,
+  connectDevtools,
+  devtoolsEnabled,
+  initDevtools,
+  mountDevtoolsOverlay
+} from "./chunk-4N3NBFL3.js";
+export {
+  DEVTOOLS_PARAM,
+  connectDevtools,
+  devtoolsEnabled,
+  initDevtools,
+  mountDevtoolsOverlay
+};

package/dist/init.d.ts

@@ -0,0 +1,28 @@
+/**
+ * URL-gated devtools: `initDevtools()` is a no-op unless the app was
+ * opened with `?__atoll_devtools` in the URL (Node: `ATOLL_DEVTOOLS`
+ * env). When enabled it connects the broadcast transport and mounts the
+ * overlay flyout — one line in the app, nothing when uninvited:
+ *
+ *   import { initDevtools } from '@atolljs/devtools';
+ *   initDevtools({ session: { name: 'my-app' } });
+ *
+ *   my-app/?__atoll_devtools        → devtools on
+ *   my-app/                         → zero cost, no sink installed
+ */
+import { type ConnectDevtoolsOptions, type DevtoolsConnection } from './client.js';
+import { type DevtoolsOverlay, type DevtoolsOverlayOptions } from './overlay.js';
+export declare const DEVTOOLS_PARAM = "__atoll_devtools";
+/** Whether devtools should activate in this context. */
+export declare const devtoolsEnabled: (enabled?: boolean) => boolean;
+export interface InitDevtoolsOptions extends ConnectDevtoolsOptions {
+    /** Force on/off — defaults to the ?__atoll_devtools URL param. */
+    enabled?: boolean;
+    /** Overlay flyout — default true in a browser window; pass options or false. */
+    overlay?: boolean | DevtoolsOverlayOptions;
+}
+export interface InitDevtools {
+    conn: DevtoolsConnection;
+    overlay: DevtoolsOverlay | null;
+}
+export declare function initDevtools(opts?: InitDevtoolsOptions): InitDevtools | null;

package/dist/node.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `@atolljs/devtools/node` — the Node-facing entry.
+ *
+ * Same API as the browser entry, minus the browser-only pieces: there is no
+ * BroadcastChannel transport (WebSocket is the only path — the global
+ * WebSocket on Node ≥ 22, the bundled dependency-free client below it) and
+ * no overlay flyout (there's no page to mount it in). `initDevtools` gates
+ * on the ATOLL_DEVTOOLS env var instead of the ?__atoll_devtools URL param;
+ * the dashboard is the standalone aggregate server (`atoll devtools`).
+ *
+ *   import { initDevtools } from '@atolljs/devtools/node';
+ *   initDevtools({ session: { name: 'my-api' } });
+ */
+export { connectDevtools } from './client.js';
+export type { ConnectDevtoolsOptions, DevtoolsConnection } from './client.js';
+export { initDevtools, devtoolsEnabled, DEVTOOLS_PARAM } from './init.js';
+export type { InitDevtools, InitDevtoolsOptions } from './init.js';
+export type { SessionInfo } from './protocol.js';

package/dist/node.js

@@ -0,0 +1,12 @@
+import {
+  DEVTOOLS_PARAM,
+  connectDevtools,
+  devtoolsEnabled,
+  initDevtools
+} from "./chunk-4N3NBFL3.js";
+export {
+  DEVTOOLS_PARAM,
+  connectDevtools,
+  devtoolsEnabled,
+  initDevtools
+};

package/dist/nodeWs.d.ts

@@ -0,0 +1,9 @@
+export interface NodeWebSocket {
+    readonly open: boolean;
+    send(text: string): void;
+    close(): void;
+    onOpen: (() => void) | null;
+    onClose: (() => void) | null;
+}
+/** Connect a WebSocket to `url` — handshake, then framed text IO. */
+export declare function connectNodeWebSocket(url: string): NodeWebSocket;

package/dist/overlay.d.ts

@@ -0,0 +1,31 @@
+/**
+ * In-app devtools overlay: a floating flyout hosting the mini dashboard
+ * in a same-origin iframe (default /__atoll/?mini=1, served by the vite
+ * plugin). Same-origin means the iframe shares the app's BroadcastChannel
+ * — the pure-client transport needs no other wiring.
+ *
+ *   import { connectDevtools, mountDevtoolsOverlay } from '@atolljs/devtools';
+ *   if (import.meta.env.DEV) {
+ *     connectDevtools();
+ *     mountDevtoolsOverlay();
+ *   }
+ */
+export type DevtoolsOverlayPosition = 'topleft' | 'topcenter' | 'topright' | 'bottomleft' | 'bottomcenter' | 'bottomright';
+export interface DevtoolsOverlayOptions {
+    /** Dashboard URL — default '/__atoll/?mini=1' (vite-plugin mount, mini layout). */
+    src?: string;
+    /** Start expanded (default false — a small corner toggle shows first). */
+    startOpen?: boolean;
+    /** Initial size (default 760×580). */
+    width?: number;
+    height?: number;
+    /** Where the flyout (and its collapsed toggle) anchors — default 'bottomright'. */
+    position?: DevtoolsOverlayPosition;
+}
+export interface DevtoolsOverlay {
+    open(): void;
+    close(): void;
+    toggle(): void;
+    unmount(): void;
+}
+export declare function mountDevtoolsOverlay(opts?: DevtoolsOverlayOptions): DevtoolsOverlay;