@atolljs/devtools 0.1.7 → 0.1.8

package/src/probes.ts

@@ -0,0 +1,155 @@
+/**
+ * Main-thread responsiveness probes, installed by the transports next to
+ * `installMemoryProbe`:
+ *
+ * - `runtime:longframe`: Long Animation Frame entries (blocking time plus
+ *   the longest scripts) where the engine supports them, `longtask`
+ *   entries otherwise. While the page is hidden, only frames with at least
+ *   `HIDDEN_SCRIPT_MS` of script are reported, flagged `hidden: true`.
+ * - `runtime:frames`: a rAF sampler, one event per second with fps and the
+ *   frames that took over ~2x the display interval.
+ *
+ * Browser main thread only: a no-op in Node and in workers. Idempotent and
+ * reference-counted, so two connections share one observer + one rAF loop
+ * and the loop stops when the last one closes.
+ */
+import { emitDevtools } from '@atolljs/core';
+
+const MAX_SCRIPTS = 5;
+/** Long tasks past this block input; LoAF reports `blockingDuration` directly. */
+const BUDGET_MS = 50;
+/** While hidden, a frame is reported only with at least this much script time. */
+export const HIDDEN_SCRIPT_MS = 100;
+/** A gap this long means the tab was hidden/throttled, not a dropped frame. */
+const STALL_MS = 1000;
+
+interface LoafScript {
+  duration: number;
+  sourceURL?: string;
+  sourceFunctionName?: string;
+  invoker?: string;
+}
+interface LoafEntry extends PerformanceEntry {
+  blockingDuration?: number;
+  scripts?: LoafScript[];
+}
+
+let refs = 0;
+let teardown: (() => void) | null = null;
+
+const isBrowserMain = (): boolean =>
+  typeof window !== 'undefined' &&
+  typeof window.document !== 'undefined' &&
+  typeof requestAnimationFrame === 'function' &&
+  !(typeof WorkerGlobalScope !== 'undefined' && self instanceof WorkerGlobalScope);
+
+const observeLongFrames = (): (() => void) => {
+  if (typeof PerformanceObserver === 'undefined') return () => {};
+  const supported = PerformanceObserver.supportedEntryTypes ?? [];
+  const type = supported.includes('long-animation-frame')
+    ? 'long-animation-frame'
+    : supported.includes('longtask')
+      ? 'longtask'
+      : null;
+  if (!type) return () => {};
+  const obs = new PerformanceObserver((list) => {
+    const hidden = document.visibilityState === 'hidden';
+    for (const e of list.getEntries() as LoafEntry[]) {
+      const ms = Math.round(e.duration);
+      const blockingMs = Math.round(e.blockingDuration ?? Math.max(0, e.duration - BUDGET_MS));
+      // Throttled renders (background or occluded view) stretch frames with
+      // no work in them, so judge by script time, not frame duration.
+      const scriptMs = e.scripts ? e.scripts.reduce((n, s) => n + s.duration, 0) : undefined;
+      if (hidden) {
+        // longtask entries have no script attribution: their duration is the task itself.
+        if ((scriptMs ?? e.duration) < HIDDEN_SCRIPT_MS) continue;
+      } else if (e.blockingDuration === 0 && (scriptMs ?? 0) < BUDGET_MS) continue;
+      const scripts = e.scripts?.length
+        ? [...e.scripts]
+            .sort((a, b) => b.duration - a.duration)
+            .slice(0, MAX_SCRIPTS)
+            .map((s) => ({
+              src: s.sourceURL ? s.sourceURL.slice(0, 300) : undefined,
+              fn: s.sourceFunctionName || s.invoker || undefined,
+              ms: Math.round(s.duration),
+            }))
+        : undefined;
+      emitDevtools({
+        type: 'runtime:longframe', ms, blockingMs,
+        ...(scripts ? { scripts } : {}),
+        ...(hidden ? { hidden: true } : {}),
+      });
+    }
+  });
+  try {
+    obs.observe({ type, buffered: true });
+  } catch {
+    return () => {};
+  }
+  return () => obs.disconnect();
+};
+
+const sampleFrames = (): (() => void) => {
+  let raf = 0;
+  let last = 0;
+  let windowStart = 0;
+  let frames = 0;
+  let dropped = 0;
+  /** Display interval estimate: the shortest frame seen (≥4ms), 60Hz until known. */
+  let interval = 1000 / 60;
+  let shortest = Infinity;
+  const tick = (now: number) => {
+    raf = requestAnimationFrame(tick);
+    if (!last) {
+      last = windowStart = now;
+      return;
+    }
+    const dt = now - last;
+    last = now;
+    if (dt > STALL_MS) {
+      // hidden tab / debugger pause: restart the window, report nothing
+      windowStart = now;
+      frames = dropped = 0;
+      return;
+    }
+    frames++;
+    if (dt >= 4 && dt < shortest) shortest = dt;
+    if (dt > interval * 2) dropped++;
+    const elapsed = now - windowStart;
+    if (elapsed >= 1000) {
+      emitDevtools({ type: 'runtime:frames', fps: Math.round((frames * 1000) / elapsed), dropped });
+      if (shortest !== Infinity) interval = shortest;
+      shortest = Infinity;
+      windowStart = now;
+      frames = dropped = 0;
+    }
+  };
+  raf = requestAnimationFrame(tick);
+  return () => cancelAnimationFrame(raf);
+};
+
+/**
+ * Start the long-frame observer and the frame sampler; returns a release
+ * function (the probes stop when every installer has released).
+ */
+export function installJankProbe(): () => void {
+  if (!isBrowserMain()) return () => {};
+  refs++;
+  if (!teardown) {
+    const stopObs = observeLongFrames();
+    const stopRaf = sampleFrames();
+    teardown = () => {
+      stopObs();
+      stopRaf();
+    };
+  }
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    if (--refs === 0 && teardown) {
+      teardown();
+      teardown = null;
+    }
+  };
+}

package/src/protocol.ts

@@ -13,6 +13,11 @@ export interface SessionInfo {
   id: string;
   /** Human label — config `name`, app title, process argv, etc. */
   name?: string;
+  /**
+   * The shell's own framework ('react', 'vue', 'svelte', 'solid', 'angular',
+   * 'vanilla', …): drawn as the main-thread hub's mark on the app map.
+   */
+  framework?: string;
   runtime: 'browser' | 'node';
   /** Browser location.href / process title — whatever helps identify it. */
   hint?: string;
@@ -26,6 +31,18 @@ export interface SessionInfo {
   closedAt?: number;
   /** Viewer-pinned closed sessions are exempt from the retention sweep. */
   pinned?: boolean;
+  /** Runtime facts captured at connect, for the dashboard's audits. */
+  env?: SessionEnv;
+}
+
+export interface SessionEnv {
+  /** `crossOriginIsolated` — false means no SharedArrayBuffer doorbell (islands poll). */
+  crossOriginIsolated?: boolean;
+  sharedArrayBuffer?: boolean;
+  hardwareConcurrency?: number;
+  userAgent?: string;
+  /** Node `process.version` on the Node path. */
+  node?: string;
 }
 
 export interface HelloMessage {
@@ -38,20 +55,48 @@ export interface BatchMessage {
   events: EmittedDevtoolsEvent[];
 }
 
+/**
+ * Dashboard → app command (`runDevtoolsCommand` on the app side). `id` is
+ * viewer-generated and echoed on the result.
+ */
+export interface ControlRequest {
+  type: 'control';
+  sessionId: string;
+  id: string;
+  cmd: string;
+  args?: Record<string, unknown>;
+}
+
+/** App → dashboard reply to a ControlRequest. */
+export interface ControlResult {
+  type: 'control-result';
+  sessionId: string;
+  id: string;
+  ok: boolean;
+  result?: unknown;
+  error?: string;
+}
+
 /** What an instrumented app sends on /events. */
-export type ClientMessage = HelloMessage | BatchMessage;
+export type ClientMessage = HelloMessage | BatchMessage | ControlResult;
+
+/** What the server sends an instrumented app on /events. */
+export type AppMessage = ControlRequest;
 
 /** What a dashboard viewer receives on /view. */
 export type ViewerMessage =
   | { type: 'sessions'; sessions: SessionInfo[] }
-  | { type: 'batch'; session: SessionInfo; events: EmittedDevtoolsEvent[] };
+  | { type: 'batch'; session: SessionInfo; events: EmittedDevtoolsEvent[] }
+  | ControlResult;
 
 /** 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 };
+  | { type: 'pin'; sessionId: string; pinned: boolean }
+  /** Relay a command to the live app with this session id. */
+  | ControlRequest;
 
 /**
  * Pure-client transport: frames on a same-origin BroadcastChannel named
@@ -66,4 +111,7 @@ export type BroadcastMessage =
   /** 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' };
+  | { type: 'view' }
+  /** Dashboard → app command; only the app whose session id matches answers. */
+  | ControlRequest
+  | ControlResult;

package/src/server.ts

@@ -11,6 +11,28 @@ import { join, normalize, extname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import type { ClientMessage, SessionInfo, ViewerMessage, ViewerRequest } from './protocol';
 import { acceptWebSocket, type WsConnection } from './ws';
+import { OtelMapper, type OtelSignals } from './otelMap';
+import {
+  createOtelPipeline,
+  createOtlpSender,
+  sessionResource,
+  type OtelPipeline,
+  type OtlpSenderOptions,
+  type ResourceAttributes,
+} from './otelTransport';
+
+/** Forward every ingested session's events to an OTLP/HTTP endpoint. */
+export interface DevtoolsServerOtlpOptions extends OtlpSenderOptions {
+  /** Fixed `service.name` for every session (default: each session's name). */
+  serviceName?: string;
+  /** Extra resource attributes on every session. */
+  resource?: ResourceAttributes;
+  signals?: OtelSignals;
+  /** Default 5000ms. */
+  flushIntervalMs?: number;
+  /** Default 512. */
+  maxBatch?: number;
+}
 
 export interface DevtoolsServerOptions {
   /** Default 4780. 0 picks an ephemeral port (tests). */
@@ -25,6 +47,11 @@ export interface DevtoolsServerOptions {
   closedTtlMs?: number;
   /** How often the retention sweep runs (default 60s — tests lower it). */
   sweepMs?: number;
+  /**
+   * Also export everything ingested to OpenTelemetry (one OTLP resource per
+   * app session). Off by default.
+   */
+  otlp?: DevtoolsServerOtlpOptions;
   onListen?: (url: string) => void;
 }
 
@@ -77,6 +104,26 @@ export function createDevtoolsServer(opts: DevtoolsServerOptions = {}): Promise<
   const closedTtlMs = opts.closedTtlMs ?? 30 * 60 * 1000;
   /** Batches kept for replay — sessions updates aren't replayed (stale). */
   const tail: ViewerMessage[] = [];
+  /** In-flight control requests: request id → the viewer awaiting the result. */
+  const pendingControl = new Map<string, WsConnection>();
+
+  /** OTLP forwarding: one mapper (resource) per session id. */
+  let otlp: OtelPipeline | null = null;
+  const otlpSessions = new Map<string, SessionInfo>();
+  if (opts.otlp) {
+    const o = opts.otlp;
+    otlp = createOtelPipeline({
+      sender: createOtlpSender(o),
+      signals: o.signals,
+      flushIntervalMs: o.flushIntervalMs,
+      maxBatch: o.maxBatch,
+      newMapper: (id) =>
+        new OtelMapper({
+          resource: sessionResource(otlpSessions.get(id) ?? { id, runtime: 'browser' }, o.serviceName, o.resource),
+          signals: o.signals,
+        }),
+    });
+  }
 
   const sessionList = (): SessionInfo[] => [...sessions.values(), ...closedSessions];
 
@@ -121,7 +168,10 @@ export function createDevtoolsServer(opts: DevtoolsServerOptions = {}): Promise<
 
     if (url.pathname === '/view') {
       viewers.add(conn);
-      conn.onClose = () => viewers.delete(conn);
+      conn.onClose = () => {
+        viewers.delete(conn);
+        for (const [id, v] of pendingControl) if (v === conn) pendingControl.delete(id);
+      };
       conn.onMessage = (text) => {
         let msg: ViewerRequest;
         try {
@@ -139,6 +189,17 @@ export function createDevtoolsServer(opts: DevtoolsServerOptions = {}): Promise<
           if (!s || s.pinned === msg.pinned) return;
           s.pinned = msg.pinned;
           broadcast({ type: 'sessions', sessions: sessionList() });
+        } else if (msg.type === 'control') {
+          const app = [...sessions].find(([, s]) => s.id === msg.sessionId)?.[0];
+          if (!app) {
+            conn.send(JSON.stringify({
+              type: 'control-result', sessionId: msg.sessionId, id: msg.id, ok: false,
+              error: 'session is not live',
+            } satisfies ViewerMessage));
+            return;
+          }
+          pendingControl.set(msg.id, conn);
+          app.send(JSON.stringify(msg));
         }
       };
       conn.send(JSON.stringify({ type: 'sessions', sessions: sessionList() }));
@@ -162,11 +223,27 @@ export function createDevtoolsServer(opts: DevtoolsServerOptions = {}): Promise<
         return;
       }
       if (msg.type === 'batch' && greeted) {
-        broadcast({ type: 'batch', session: sessions.get(conn)!, events: msg.events });
+        const session = sessions.get(conn)!;
+        broadcast({ type: 'batch', session, events: msg.events });
+        if (otlp && Array.isArray(msg.events)) {
+          otlpSessions.set(session.id, session);
+          // Remote clocks are unknown: the mapper rebases on receive time.
+          const recv = Date.now();
+          for (const ev of msg.events) otlp.ingest(ev, recv, session.id);
+        }
+      }
+      if (msg.type === 'control-result') {
+        const viewer = pendingControl.get(msg.id);
+        pendingControl.delete(msg.id);
+        if (viewer && viewers.has(viewer)) viewer.send(JSON.stringify(msg));
       }
     };
     conn.onClose = () => {
       const info = sessions.get(conn);
+      if (info && otlp) {
+        otlp.release(info.id);
+        otlpSessions.delete(info.id);
+      }
       if (sessions.delete(conn) && info) {
         info.closed = true;
         info.closedAt = Date.now();
@@ -210,7 +287,10 @@ export function createDevtoolsServer(opts: DevtoolsServerOptions = {}): Promise<
             clearInterval(sweep);
             for (const v of viewers) v.close();
             for (const c of sessions.keys()) c.close();
-            server.close(() => done());
+            server.close(() => {
+              if (otlp) void otlp.close().then(() => done());
+              else done();
+            });
           }),
       });
     });