@atolljs/devtools 0.1.7 → 0.1.9

package/dist/node.js

@@ -3,7 +3,8 @@ import {
   connectDevtools,
   devtoolsEnabled,
   initDevtools
-} from "./chunk-4N3NBFL3.js";
+} from "./chunk-6E54FXKS.js";
+import "./chunk-57NGHQUL.js";
 export {
   DEVTOOLS_PARAM,
   connectDevtools,

package/dist/nodeWs.d.ts

@@ -4,6 +4,7 @@ export interface NodeWebSocket {
     close(): void;
     onOpen: (() => void) | null;
     onClose: (() => void) | null;
+    onMessage: ((text: string) => void) | null;
 }
 /** Connect a WebSocket to `url` — handshake, then framed text IO. */
 export declare function connectNodeWebSocket(url: string): NodeWebSocket;

package/dist/otel.d.ts

@@ -0,0 +1,35 @@
+import { type OtelSignals } from './otelMap.js';
+import { type OtlpSenderOptions, type ResourceAttributes } from './otelTransport.js';
+export interface ExportOtelOptions extends OtlpSenderOptions {
+    /** Resource `service.name` (default 'unknown_service'). */
+    serviceName?: string;
+    /** Extra resource attributes, merged over the detected ones. */
+    resource?: ResourceAttributes;
+    /** Signals to export: all on by default. */
+    signals?: OtelSignals;
+    /** Periodic flush interval (default 5000ms). */
+    flushIntervalMs?: number;
+    /** Spans / log records per request (default 512). */
+    maxBatch?: number;
+    /** Queued spans and log records each before the oldest drop (default 2048). */
+    maxQueue?: number;
+    /** Series per metric before new attribute sets drop (default 2000). */
+    maxSeries?: number;
+    /** Patch global fetch for `net:fetch` spans (default true). */
+    network?: boolean;
+    /** Sample JS heap for `atoll.runtime.heap` (default true). */
+    memory?: boolean;
+    /** Browser main thread: long-frame / fps probe (default true). */
+    jank?: boolean;
+}
+export interface OtelExporter {
+    /** Ship everything queued now (plus a metrics snapshot). Never rejects. */
+    flush(): Promise<void>;
+    /** Uninstall the listener and lifecycle hooks, then flush. Never rejects. */
+    close(): Promise<void>;
+}
+export declare function exportOtel(opts?: ExportOtelOptions): OtelExporter;
+export { OtelMapper, SEVERITY, newSpanId, newTraceId, toUnixNano } from './otelMap.js';
+export type { KeyValue, OtelMapperOptions, OtelSignals, OtlpLogRecord, OtlpMetric, OtlpSpan } from './otelMap.js';
+export { createOtelPipeline, createOtlpSender, localResource, sessionResource } from './otelTransport.js';
+export type { OtelPipeline, OtelPipelineOptions, OtlpSender, OtlpSenderOptions, OtlpSignal, ResourceAttributes, } from './otelTransport.js';

package/dist/otel.js

@@ -0,0 +1,87 @@
+import {
+  addDevtoolsSink,
+  installFetchProbe,
+  installJankProbe,
+  installMemoryProbe
+} from "./chunk-57NGHQUL.js";
+import {
+  OtelMapper,
+  SEVERITY,
+  createOtelPipeline,
+  createOtlpSender,
+  localResource,
+  newSpanId,
+  newTraceId,
+  sessionResource,
+  toUnixNano
+} from "./chunk-WIL2P7HG.js";
+
+// src/otel.ts
+function exportOtel(opts = {}) {
+  const sender = createOtlpSender(opts);
+  const endpoint = sender.endpoint;
+  const perf = globalThis.performance;
+  const originMs = perf.timeOrigin ?? Date.now() - perf.now();
+  const mapperOpts = {
+    resource: localResource(opts.serviceName, opts.resource),
+    originMs,
+    signals: opts.signals,
+    maxQueue: opts.maxQueue,
+    maxSeries: opts.maxSeries,
+    // An earlier probe (connectDevtools) may already wrap the captured fetch.
+    ignoreUrl: (url) => url.startsWith(endpoint)
+  };
+  const pipeline = createOtelPipeline({
+    sender,
+    newMapper: () => new OtelMapper(mapperOpts),
+    flushIntervalMs: opts.flushIntervalMs,
+    maxBatch: opts.maxBatch,
+    signals: opts.signals
+  });
+  const remove = addDevtoolsSink((ev) => pipeline.ingest(ev, originMs + perf.now()));
+  if (opts.network !== false) installFetchProbe(globalThis);
+  if (opts.memory !== false) installMemoryProbe(globalThis);
+  const releaseJank = opts.jank !== false ? installJankProbe() : () => {
+  };
+  const g = globalThis;
+  const onHide = () => {
+    if (g.document?.visibilityState === "hidden") void pipeline.flush({ keepalive: true });
+  };
+  const onPageHide = () => void pipeline.flush({ keepalive: true });
+  const inBrowser = typeof g.document !== "undefined" && typeof g.addEventListener === "function";
+  if (inBrowser) {
+    g.addEventListener("pagehide", onPageHide);
+    g.document.addEventListener?.("visibilitychange", onHide);
+  }
+  const onBeforeExit = () => void pipeline.flush();
+  const inNode = !inBrowser && typeof g.process?.once === "function" && g.process.versions?.node !== void 0;
+  if (inNode) g.process.once("beforeExit", onBeforeExit);
+  let closed = false;
+  return {
+    flush: () => pipeline.flush(),
+    async close() {
+      if (closed) return;
+      closed = true;
+      remove();
+      releaseJank();
+      if (inBrowser) {
+        g.removeEventListener?.("pagehide", onPageHide);
+        g.document?.removeEventListener?.("visibilitychange", onHide);
+      }
+      if (inNode) g.process.off?.("beforeExit", onBeforeExit);
+      await pipeline.close();
+    }
+  };
+}
+export {
+  OtelMapper,
+  SEVERITY,
+  createOtelPipeline,
+  createOtlpSender,
+  exportOtel,
+  localResource,
+  newSpanId,
+  newTraceId,
+  sessionResource,
+  toUnixNano
+};

package/dist/otelMap.d.ts

@@ -0,0 +1,232 @@
+/**
+ * Pure devtools-event → OTLP/HTTP JSON mapping (no transport, no globals
+ * beyond crypto for ids). `otel.ts` drives it from a devtools sink; the
+ * aggregate server drives one mapper per app session.
+ *
+ * Encoding follows the OTLP JSON Protobuf mapping: lowerCamelCase keys,
+ * traceId/spanId as hex strings, enums as integers, 64-bit integers
+ * (timestamps, intValue, counts) as decimal strings.
+ */
+import type { EmittedDevtoolsEvent } from '@atolljs/core';
+export type AnyValue = {
+    stringValue: string;
+} | {
+    intValue: string;
+} | {
+    doubleValue: number;
+} | {
+    boolValue: boolean;
+};
+export interface KeyValue {
+    key: string;
+    value: AnyValue;
+}
+export interface OtlpSpanEvent {
+    timeUnixNano: string;
+    name: string;
+    attributes?: KeyValue[];
+}
+export interface OtlpSpan {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    kind: number;
+    startTimeUnixNano: string;
+    endTimeUnixNano: string;
+    attributes: KeyValue[];
+    events?: OtlpSpanEvent[];
+    status?: {
+        code: number;
+        message?: string;
+    };
+}
+export interface OtlpLogRecord {
+    timeUnixNano: string;
+    observedTimeUnixNano: string;
+    severityNumber: number;
+    severityText: string;
+    body: AnyValue;
+    attributes: KeyValue[];
+}
+export interface OtlpNumberPoint {
+    attributes: KeyValue[];
+    startTimeUnixNano?: string;
+    timeUnixNano: string;
+    asInt?: string;
+    asDouble?: number;
+}
+export interface OtlpHistogramPoint {
+    attributes: KeyValue[];
+    startTimeUnixNano: string;
+    timeUnixNano: string;
+    count: string;
+    sum: number;
+    min: number;
+    max: number;
+    bucketCounts: string[];
+    explicitBounds: number[];
+}
+export interface OtlpMetric {
+    name: string;
+    unit: string;
+    description: string;
+    sum?: {
+        aggregationTemporality: number;
+        isMonotonic: boolean;
+        dataPoints: OtlpNumberPoint[];
+    };
+    gauge?: {
+        dataPoints: OtlpNumberPoint[];
+    };
+    histogram?: {
+        aggregationTemporality: number;
+        dataPoints: OtlpHistogramPoint[];
+    };
+}
+/** Span.SpanKind */
+export declare const SPAN_KIND_CLIENT = 3;
+/** Status.StatusCode */
+export declare const STATUS_ERROR = 2;
+/** AggregationTemporality */
+export declare const TEMPORALITY_CUMULATIVE = 2;
+/** SeverityNumber base value per level. */
+export declare const SEVERITY: Record<'trace' | 'debug' | 'info' | 'warn' | 'error', number>;
+export declare const OTEL_SCOPE: {
+    name: string;
+};
+export declare const attr: {
+    str: (key: string, v: string) => KeyValue;
+    int: (key: string, v: number) => KeyValue;
+    dbl: (key: string, v: number) => KeyValue;
+    bool: (key: string, v: boolean) => KeyValue;
+};
+/** Untyped attribute bag → KeyValues: integers as intValue, other numbers as doubleValue. */
+export declare const toAttributes: (bag: Record<string, string | number | boolean | undefined>) => KeyValue[];
+/** Epoch milliseconds (fractional) → nanoseconds as a decimal string, without float overflow. */
+export declare const toUnixNano: (epochMs: number) => string;
+/** 16 random bytes → 32 hex chars. */
+export declare const newTraceId: () => string;
+/** 8 random bytes → 16 hex chars. */
+export declare const newSpanId: () => string;
+/**
+ * Converts an event's `at` (performance.now() on the emitting thread) to
+ * epoch ms. Main-thread events with a known `originMs`
+ * (performance.timeOrigin of that thread) convert exactly. Everything else
+ * (worker-forwarded events carry the worker's own clock; remote sessions
+ * have an unknown origin) is rebased per clock: offset = min over samples
+ * of (receive time − at), i.e. the least-latency delivery seen so far.
+ * Durations and intra-thread order survive; absolute times are late by at
+ * most that minimum delivery latency. A jump of more than `resetMs` above
+ * the current estimate is treated as a new clock (a respawned worker in a
+ * reused slot) and re-seeds the offset.
+ */
+export declare class ClockRebaser {
+    private readonly originMs?;
+    private readonly resetMs;
+    private offsets;
+    constructor(originMs?: number | undefined, resetMs?: number);
+    epochMs(ev: Pick<EmittedDevtoolsEvent, 'at' | 'thread' | 'worker'>, recvEpochMs: number): number;
+}
+/** Default ms histogram bounds: sub-ms through 10s. */
+export declare const MS_BOUNDS: number[];
+export interface OtelSignals {
+    traces?: boolean;
+    metrics?: boolean;
+    logs?: boolean;
+}
+export interface OtelMapperOptions {
+    /** Resource attributes (service.name, telemetry.sdk.*, …). */
+    resource: KeyValue[];
+    /** performance.timeOrigin of the main thread, when events come from this process. */
+    originMs?: number;
+    signals?: OtelSignals;
+    /** net:fetch URLs to skip: the exporter's own OTLP posts. */
+    ignoreUrl?: (url: string) => boolean;
+    /** Queued spans / log records each, oldest dropped past this (default 2048). */
+    maxQueue?: number;
+    /** Open task calls tracked for correlation (default 10_000, oldest dropped). */
+    maxPending?: number;
+    /** Series per metric before new attribute sets are dropped (default 2000). */
+    maxSeries?: number;
+}
+export declare class OtelMapper {
+    readonly resource: KeyValue[];
+    readonly spans: OtlpSpan[];
+    readonly logs: OtlpLogRecord[];
+    /** Items dropped by the queue bound since creation. */
+    dropped: number;
+    private readonly clock;
+    private readonly traces;
+    private readonly metricsOn;
+    private readonly logsOn;
+    private readonly maxQueue;
+    private readonly maxPending;
+    private readonly ignoreUrl?;
+    private readonly pending;
+    private readonly pools;
+    private readonly instruments;
+    private readonly m;
+    constructor(opts: OtelMapperOptions);
+    private pushSpan;
+    private pushLog;
+    private log;
+    /** Thread attribution shared by logs and runtime metrics. */
+    private threadAttrs;
+    /** Feed one event; `recvEpochMs` is when the sink saw it (rebases foreign clocks). */
+    ingest(ev: EmittedDevtoolsEvent, recvEpochMs: number): void;
+    /** Remove up to `max` queued spans. */
+    takeSpans(max: number): OtlpSpan[];
+    /** Remove up to `max` queued log records. */
+    takeLogs(max: number): OtlpLogRecord[];
+    /** Cumulative snapshot of every metric with data; empty when metrics are off. */
+    collectMetrics(nowEpochMs: number): OtlpMetric[];
+}
+export declare const encodeTraces: (groups: {
+    resource: KeyValue[];
+    spans: OtlpSpan[];
+}[]) => {
+    resourceSpans: {
+        resource: {
+            attributes: KeyValue[];
+        };
+        scopeSpans: {
+            scope: {
+                name: string;
+            };
+            spans: OtlpSpan[];
+        }[];
+    }[];
+};
+export declare const encodeMetrics: (groups: {
+    resource: KeyValue[];
+    metrics: OtlpMetric[];
+}[]) => {
+    resourceMetrics: {
+        resource: {
+            attributes: KeyValue[];
+        };
+        scopeMetrics: {
+            scope: {
+                name: string;
+            };
+            metrics: OtlpMetric[];
+        }[];
+    }[];
+};
+export declare const encodeLogs: (groups: {
+    resource: KeyValue[];
+    logs: OtlpLogRecord[];
+}[]) => {
+    resourceLogs: {
+        resource: {
+            attributes: KeyValue[];
+        };
+        scopeLogs: {
+            scope: {
+                name: string;
+            };
+            logRecords: OtlpLogRecord[];
+        }[];
+    }[];
+};

package/dist/otelTransport.d.ts

@@ -0,0 +1,69 @@
+/**
+ * OTLP/HTTP JSON transport: a retrying `fetch` sender and the batching
+ * pipeline that drains `OtelMapper`s into it. No @atolljs/core runtime
+ * imports, so the aggregate server can forward without bundling the SDK.
+ */
+import type { EmittedDevtoolsEvent } from '@atolljs/core';
+import { type KeyValue, type OtelMapper, type OtelSignals } from './otelMap.js';
+import type { SessionInfo } from './protocol.js';
+export type OtlpSignal = 'traces' | 'metrics' | 'logs';
+export interface OtlpSenderOptions {
+    /** OTLP/HTTP base URL; `/v1/<signal>` is appended (default http://localhost:4318). */
+    endpoint?: string;
+    /** Extra request headers (auth: `x-honeycomb-team`, `authorization`, …). */
+    headers?: Record<string, string>;
+    /** fetch implementation (default: the global fetch captured at creation). */
+    fetch?: typeof fetch;
+    /** Retries per request on 429/502/503/504 or network failure (default 3). */
+    maxRetries?: number;
+    /** Exponential backoff base when no Retry-After is sent (default 500ms). */
+    retryBaseMs?: number;
+    /** Cap on any single retry delay (default 30s). */
+    retryMaxMs?: number;
+    /**
+     * Export failures (non-retryable status, retries exhausted). Never thrown
+     * into app code. Don't route this through atoll's `log()`: that tees back
+     * into the devtools stream and becomes the next export.
+     */
+    onError?: (error: Error, signal: OtlpSignal) => void;
+}
+export interface OtlpSender {
+    readonly endpoint: string;
+    /** POST one request body; resolves true when accepted. Never rejects. */
+    send(signal: OtlpSignal, body: unknown, opts?: {
+        keepalive?: boolean;
+    }): Promise<boolean>;
+}
+export declare const normalizeEndpoint: (endpoint?: string) => string;
+export declare function createOtlpSender(opts?: OtlpSenderOptions): OtlpSender;
+export interface OtelPipelineOptions {
+    sender: OtlpSender;
+    /** Builds the mapper for a key on first use ('' for a single-app exporter). */
+    newMapper: (key: string) => OtelMapper;
+    /** Periodic flush interval (default 5000ms). 0 disables the timer. */
+    flushIntervalMs?: number;
+    /** Spans / log records per request; reaching it triggers an early flush (default 512). */
+    maxBatch?: number;
+    signals?: OtelSignals;
+    /** Epoch-ms clock for metric collection (default Date.now). */
+    now?: () => number;
+}
+export interface OtelPipeline {
+    ingest(ev: EmittedDevtoolsEvent, recvEpochMs: number, key?: string): void;
+    /** Stop tracking a key after its queued data ships on the next flush. */
+    release(key: string): void;
+    /** Serialized: concurrent calls queue behind the in-flight flush. Never rejects. */
+    flush(opts?: {
+        keepalive?: boolean;
+    }): Promise<void>;
+    close(): Promise<void>;
+}
+export declare function createOtelPipeline(opts: OtelPipelineOptions): OtelPipeline;
+export type ResourceAttributes = Record<string, string | number | boolean | undefined>;
+/** Resource attributes for this process: service.name, telemetry.sdk.*, runtime hints. */
+export declare function localResource(serviceName?: string, extra?: ResourceAttributes): KeyValue[];
+/**
+ * Resource attributes for a remote app session (aggregate-server
+ * forwarding): the session name is the service unless a fixed one is given.
+ */
+export declare function sessionResource(session: SessionInfo, serviceName?: string, extra?: ResourceAttributes): KeyValue[];

package/dist/overlay.d.ts

@@ -9,18 +9,30 @@
  *     connectDevtools();
  *     mountDevtoolsOverlay();
  *   }
+ *
+ * Alt+Shift+D toggles the flyout from the host page (`hotkey` option). The
+ * dashboard inside the iframe forwards the same chord via postMessage, so
+ * it works wherever focus is. "full page ↗" opens the dashboard on the
+ * view the flyout is showing (its `#/<view>…` hash route).
  */
 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). */
+    /** Start expanded (default: the remembered state, else collapsed to a corner toggle). */
     startOpen?: boolean;
-    /** Initial size (default 760×580). */
+    /** Initial size (default 760×580; a remembered resize wins). */
     width?: number;
     height?: number;
     /** Where the flyout (and its collapsed toggle) anchors — default 'bottomright'. */
     position?: DevtoolsOverlayPosition;
+    /**
+     * Remember position, size and open state in localStorage across reloads —
+     * default true; a string is the storage key (default 'atoll-devtools:overlay').
+     */
+    persist?: boolean | string;
+    /** Host-page shortcut that toggles the flyout — default 'Alt+Shift+D'; false disables. */
+    hotkey?: string | false;
 }
 export interface DevtoolsOverlay {
     open(): void;
@@ -28,4 +40,6 @@ export interface DevtoolsOverlay {
     toggle(): void;
     unmount(): void;
 }
+/** 'Alt+Shift+D' → a keydown predicate. Letters/digits match on `code`, so Alt/Option layouts still hit. */
+export declare function parseHotkey(spec: string): (e: KeyboardEvent) => boolean;
 export declare function mountDevtoolsOverlay(opts?: DevtoolsOverlayOptions): DevtoolsOverlay;

package/dist/probes.d.ts

@@ -0,0 +1,7 @@
+/** While hidden, a frame is reported only with at least this much script time. */
+export declare const HIDDEN_SCRIPT_MS = 100;
+/**
+ * Start the long-frame observer and the frame sampler; returns a release
+ * function (the probes stop when every installer has released).
+ */
+export declare function installJankProbe(): () => void;

package/dist/protocol.d.ts

@@ -12,6 +12,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;
@@ -25,6 +30,17 @@ 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 {
     type: 'hello';
@@ -34,8 +50,30 @@ export interface BatchMessage {
     type: 'batch';
     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';
@@ -44,7 +82,7 @@ export type ViewerMessage = {
     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. */
@@ -57,7 +95,9 @@ export type ViewerRequest =
     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
  * 'atoll-devtools'. Origin scoping replaces the server's session list —
@@ -80,4 +120,6 @@ export type BroadcastMessage = {
 /** Dashboard announcing itself — apps re-hello and replay their tail. */
  | {
     type: 'view';
-};
+}
+/** Dashboard → app command; only the app whose session id matches answers. */
+ | ControlRequest | ControlResult;

package/dist/server.d.ts

@@ -1,4 +1,18 @@
 import type { SessionInfo } from './protocol.js';
+import { type OtelSignals } from './otelMap.js';
+import { type OtlpSenderOptions, type ResourceAttributes } from './otelTransport.js';
+/** 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). */
     port?: number;
@@ -12,6 +26,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;
 }
 export interface DevtoolsServer {