@atolljs/devtools 0.1.7

package/src/client.ts

@@ -0,0 +1,178 @@
+/**
+ * The instrumented-app side: `connectDevtools()` installs the core event
+ * sink and batches events to dashboards. Two transports:
+ *
+ *   connectDevtools()                    // auto — BroadcastChannel in a
+ *                                        // browser (pure client), else ws
+ *   connectDevtools({ url })             // explicit aggregate server
+ *   connectDevtools({ transport: 'websocket' })   // server, default url
+ *
+ * BroadcastChannel mode needs no backend: the dashboard is served on the
+ * app's own origin (vite plugin mounts it at /__atoll/) and listens on
+ * the same channel — origin scoping is the isolation. WebSocket mode
+ * targets the standalone aggregate server (`atoll devtools`, default
+ * ws://127.0.0.1:4780/events) — opt-in for cross-app views and Node.
+ *
+ * Events emitted while a socket is still connecting are buffered; the
+ * buffer is bounded so an app that runs without a listener doesn't grow
+ * memory unboundedly.
+ */
+import {
+  installFetchProbe,
+  installMemoryProbe,
+  setDevtoolsSink,
+  type EmittedDevtoolsEvent,
+} from '@atolljs/core';
+import { connectBroadcast } from './broadcast';
+import type { ClientMessage, SessionInfo } from './protocol';
+
+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;
+}
+
+let sessionSeq = 0;
+
+const makeSession = (opts: ConnectDevtoolsOptions): SessionInfo => {
+  const runtime: SessionInfo['runtime'] =
+    typeof window !== 'undefined' && typeof window.document !== 'undefined' ? 'browser' : 'node';
+  const hint =
+    opts.session?.hint ??
+    (runtime === 'browser'
+      ? (globalThis as { location?: { href?: string } }).location?.href
+      : (globalThis as { process?: { title?: string } }).process?.title);
+  return {
+    id: `s-${Date.now().toString(36)}-${++sessionSeq}`,
+    name: opts.session?.name,
+    runtime,
+    hint,
+  };
+};
+
+/** 'auto' picks broadcast only in a real browser window — workers and
+ *  Node contexts keep the aggregate-server path. An explicit
+ *  `transport: 'broadcast'` is honored wherever BroadcastChannel exists
+ *  (SharedWorkers have no window but can still be pure-client hubs). */
+const autoBroadcast = () =>
+  typeof BroadcastChannel !== 'undefined' &&
+  typeof window !== 'undefined' &&
+  typeof window.document !== 'undefined';
+
+export function connectDevtools(opts: ConnectDevtoolsOptions = {}): DevtoolsConnection {
+  const session = makeSession(opts);
+  const t = opts.url !== undefined ? '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: ConnectDevtoolsOptions, session: SessionInfo): DevtoolsConnection {
+  const url = opts.url ?? 'ws://127.0.0.1:4780/events';
+  const cap = opts.bufferCap ?? 50_000;
+  const pending: EmittedDevtoolsEvent[] = [];
+  let closed = false;
+
+  /** Uniform socket surface over the global WebSocket and the Node fallback. */
+  let sock: { open: boolean; send(text: string): void; close(): void } | null = null;
+
+  const send = (msg: ClientMessage) => {
+    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) {
+    // No global WebSocket (Node < 22) — dependency-free client, loaded lazily
+    // so node:net/crypto never enter a browser bundle. The specifier is
+    // computed: a literal would pull nodeWs.ts (and its node:* imports)
+    // into browser-app tsconfig programs and vite's static analysis.
+    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(() => {
+      /* no net available — sink stays installed but dead */
+    });
+  }
+
+  const timer = setInterval(flush, opts.flushMs ?? 100);
+  // Node: don't hold the process open for the flush interval.
+  (timer as unknown as { unref?: () => void }).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 >= 1000) flush(); // large bursts flush early
+  });
+
+  return {
+    session,
+    get open() {
+      return sock?.open ?? false;
+    },
+    close() {
+      closed = true;
+      setDevtoolsSink(null);
+      flush();
+      sock?.close();
+      clearInterval(timer);
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+// @atolljs/devtools — instrumented-app client for browsers (broadcast
+// transport, /__atoll/ dashboard, overlay flyout). The aggregate server
+// lives at '@atolljs/devtools/server'; Node apps use '@atolljs/devtools/node'
+// (env gate, WebSocket-only — no overlay, no BroadcastChannel).
+export { connectDevtools } from './client';
+export type { ConnectDevtoolsOptions, DevtoolsConnection } from './client';
+export { mountDevtoolsOverlay } from './overlay';
+export type { DevtoolsOverlay, DevtoolsOverlayOptions } from './overlay';
+export { DEVTOOLS_PARAM, devtoolsEnabled, initDevtools } from './init';
+export type { InitDevtools, InitDevtoolsOptions } from './init';
+export type { SessionInfo } from './protocol';

package/src/init.ts

@@ -0,0 +1,50 @@
+/**
+ * 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 { connectDevtools, type ConnectDevtoolsOptions, type DevtoolsConnection } from './client';
+import { mountDevtoolsOverlay, type DevtoolsOverlay, type DevtoolsOverlayOptions } from './overlay';
+
+export const DEVTOOLS_PARAM = '__atoll_devtools';
+
+/** Whether devtools should activate in this context. */
+export const devtoolsEnabled = (enabled?: boolean): boolean => {
+  if (enabled !== undefined) return enabled;
+  if (typeof location !== 'undefined' && typeof location.search === 'string') {
+    return new URLSearchParams(location.search).has(DEVTOOLS_PARAM);
+  }
+  // Node — no URL to gate on; honor the env var instead.
+  return !!(globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env
+    ?.ATOLL_DEVTOOLS;
+};
+
+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 function initDevtools(opts: InitDevtoolsOptions = {}): InitDevtools | null {
+  if (!devtoolsEnabled(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 };
+}

package/src/node.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';
+export type { ConnectDevtoolsOptions, DevtoolsConnection } from './client';
+export { initDevtools, devtoolsEnabled, DEVTOOLS_PARAM } from './init';
+export type { InitDevtools, InitDevtoolsOptions } from './init';
+export type { SessionInfo } from './protocol';

package/src/nodeWs.ts

@@ -0,0 +1,118 @@
+/**
+ * Minimal RFC6455 *client* for Node — the `ws`-free counterpart to the
+ * server in ws.ts. Used only when the global `WebSocket` doesn't exist
+ * (Node < 22); imported lazily from client.ts so it never enters browser
+ * bundles. Supports ws:// and wss://, text frames, ping/pong, and close.
+ */
+import { randomBytes } from 'node:crypto';
+import { connect as netConnect } from 'node:net';
+import { connect as tlsConnect } from 'node:tls';
+import type { Socket } from 'node:net';
+import {
+  decodeFrames,
+  encodeMaskedControl,
+  encodeMaskedTextFrame,
+  OPCODES,
+} from './ws';
+
+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 function connectNodeWebSocket(url: string): NodeWebSocket {
+  const u = new URL(url);
+  const secure = u.protocol === 'wss:';
+  const port = Number(u.port || (secure ? 443 : 80));
+  const key = randomBytes(16).toString('base64');
+  const path = `${u.pathname || '/'}${u.search}`;
+
+  const socket: Socket = secure
+    ? tlsConnect({ host: u.hostname, port, servername: u.hostname })
+    : netConnect(port, u.hostname);
+
+  let buf: Buffer<ArrayBufferLike> = Buffer.alloc(0);
+  let fragments: Buffer<ArrayBufferLike>[] = [];
+  let upgraded = false;
+  let open = false;
+  let closed = false;
+
+  const conn: NodeWebSocket = {
+    get open() {
+      return open;
+    },
+    send(text) {
+      if (open && !closed) socket.write(encodeMaskedTextFrame(text));
+    },
+    close() {
+      if (closed) return;
+      closed = true;
+      try {
+        if (open) socket.write(encodeMaskedControl(OPCODES.close));
+        socket.end();
+      } catch {
+        /* already gone */
+      }
+      open = false;
+      conn.onClose?.();
+    },
+    onOpen: null,
+    onClose: null,
+  };
+
+  const die = () => {
+    if (!closed) {
+      closed = true;
+      open = false;
+      conn.onClose?.();
+    }
+  };
+
+  socket.on('connect', () => {
+    socket.write(
+      `GET ${path} HTTP/1.1\r\n` +
+        `Host: ${u.host}\r\n` +
+        'Upgrade: websocket\r\n' +
+        'Connection: Upgrade\r\n' +
+        `Sec-WebSocket-Key: ${key}\r\n` +
+        'Sec-WebSocket-Version: 13\r\n' +
+        '\r\n',
+    );
+  });
+
+  socket.on('data', (chunk: Buffer) => {
+    buf = Buffer.concat([buf, chunk]);
+    if (!upgraded) {
+      const end = buf.indexOf('\r\n\r\n');
+      if (end === -1) return;
+      const head = buf.subarray(0, end).toString('latin1');
+      buf = buf.subarray(end + 4);
+      if (!/^HTTP\/1\.1 101\b/.test(head)) return die();
+      upgraded = true;
+      open = true;
+      conn.onOpen?.();
+      if (closed) return; // onOpen may have closed us
+    }
+    const { frames, rest } = decodeFrames(buf);
+    buf = rest;
+    for (const { fin, opcode, payload } of frames) {
+      if (opcode === OPCODES.close) return conn.close();
+      if (opcode === OPCODES.ping) {
+        socket.write(encodeMaskedControl(OPCODES.pong, payload));
+        continue;
+      }
+      if (opcode === OPCODES.pong) continue;
+      if (opcode === OPCODES.text || opcode === OPCODES.continuation) {
+        fragments.push(payload);
+        if (fin) fragments = []; // client.ts never reads frames — drain only
+      }
+    }
+  });
+  socket.on('error', die);
+  socket.on('close', die);
+  return conn;
+}

package/src/overlay.ts

@@ -0,0 +1,165 @@
+/**
+ * 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;
+}
+
+const 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';
+
+const 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';
+
+const ANCHOR: Record<DevtoolsOverlayPosition, (m: number) => string> = {
+  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`,
+};
+
+export function mountDevtoolsOverlay(opts: DevtoolsOverlayOptions = {}): DevtoolsOverlay {
+  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 ↗';
+  pop.style.cssText = 'color:#58a6ff;text-decoration:none;margin-left:auto';
+  const x = document.createElement('button');
+  x.textContent = '—';
+  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';
+
+  // manual resize grip — CSS `resize` doesn't work over an iframe
+  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);
+
+  /** Pointer-drag helper: run `move` on pointermove until pointerup. */
+  const drag = (e: PointerEvent, move: (dx: number, dy: number) => void) => {
+    e.preventDefault();
+    let lx = e.clientX, ly = e.clientY;
+    const mm = (ev: PointerEvent) => {
+      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 as HTMLElement).closest('a,button')) return;
+    drag(e, (dx, dy) => {
+      const r = panel.getBoundingClientRect();
+      // keep at least 40px of the title bar on screen
+      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'; // drop the center anchor's translateX
+    });
+  };
+
+  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: boolean) => {
+    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();
+    },
+  };
+}

package/src/protocol.ts

@@ -0,0 +1,69 @@
+/**
+ * The wire protocol between instrumented apps, the devtools server, and
+ * dashboard viewers — all JSON text frames over WebSocket.
+ *
+ *   app      → server  /events   { hello } then { batch } frames
+ *   server   → viewer  /view     { sessions } on connect, then { batch } per app frame
+ */
+import type { EmittedDevtoolsEvent } from '@atolljs/core';
+
+/** Identifies one connected app (one page, one Node process). */
+export interface SessionInfo {
+  /** Client-generated id — stable for the socket's lifetime. */
+  id: string;
+  /** Human label — config `name`, app title, process argv, etc. */
+  name?: string;
+  runtime: 'browser' | 'node';
+  /** Browser location.href / process title — whatever helps identify it. */
+  hint?: string;
+  /**
+   * Set by the server once the app's socket closes. Closed sessions are
+   * retained (bounded) so dashboards can keep post-mortem history instead of
+   * orphaning their pools/tasks/memory state.
+   */
+  closed?: boolean;
+  /** Server clock (ms) when the socket closed — drives the cleanup sweep. */
+  closedAt?: number;
+  /** Viewer-pinned closed sessions are exempt from the retention sweep. */
+  pinned?: boolean;
+}
+
+export interface HelloMessage {
+  type: 'hello';
+  session: SessionInfo;
+}
+
+export interface BatchMessage {
+  type: 'batch';
+  events: EmittedDevtoolsEvent[];
+}
+
+/** What an instrumented app sends on /events. */
+export type ClientMessage = HelloMessage | BatchMessage;
+
+/** What a dashboard viewer receives on /view. */
+export type ViewerMessage =
+  | { type: 'sessions'; sessions: SessionInfo[] }
+  | { type: 'batch'; session: SessionInfo; events: EmittedDevtoolsEvent[] };
+
+/** What a dashboard viewer sends on /view. */
+export type ViewerRequest =
+  /** Drop a closed session and its replayed history. Live sessions are ignored. */
+  | { type: 'dismiss'; sessionId: string }
+  /** Exempt a closed session from the retention sweep (or release it). */
+  | { type: 'pin'; sessionId: string; pinned: boolean };
+
+/**
+ * Pure-client transport: frames on a same-origin BroadcastChannel named
+ * 'atoll-devtools'. Origin scoping replaces the server's session list —
+ * a dashboard on the app's own origin sees exactly the apps on that origin.
+ */
+export const DEVTOOLS_CHANNEL = 'atoll-devtools';
+
+export type BroadcastMessage =
+  | { type: 'hello'; session: SessionInfo }
+  | { type: 'batch'; session: SessionInfo; events: EmittedDevtoolsEvent[] }
+  /** Posted on close/pagehide so dashboards can mark the session ended. */
+  | { type: 'bye'; sessionId: string }
+  /** Dashboard announcing itself — apps re-hello and replay their tail. */
+  | { type: 'view' };