@atolljs/devtools 0.1.7 → 0.1.8

package/app/panels/recorder.js

@@ -0,0 +1,344 @@
+// Record / export / import / replay. Every received batch lands in a
+// bounded rolling capture; ● Rec marks an explicit recording. Export writes
+// the recording when there is one, else the rolling buffer. Import pauses
+// the live transport (api.livePaused), resets the dashboard, and re-ingests
+// the file's frames through api.ingest under closed '⏺ ' sessions, so the
+// views rebuild exactly as they did live and no control command can fire.
+// File format and pacing math: recording-format.js.
+
+import {
+  SPEEDS, countEvents, createFrameBuffer, fmtClock, indexAt, nextChunk, playheadAt,
+  recordingDuration, recordingFileName, replaySessions, serializeRecording, validateRecording,
+} from './recording-format.js';
+import { toast } from './toast.js';
+
+const ROLLING_EVENTS = 50_000;
+const RECORDING_EVENTS = 500_000;
+/** Seek ingests synchronously; chunk it only to keep one step from stalling. */
+const PLAY_CHUNK_EVENTS = 2000;
+
+const CSS = `
+#rec-banner { display:flex; flex-wrap:wrap; align-items:center; gap:8px; margin:0 0 10px; padding:6px 10px;
+  border:1px solid #d2992266; border-left:4px solid #d29922; border-radius:6px; background:#1f1a0e; font-size:12px; }
+#rec-banner b { color:#e3b341; }
+#rec-banner .meta { color:#8b949e; }
+#rec-banner input[type=range] { flex:1 1 220px; min-width:160px; accent-color:#d29922; }
+#rec-banner select { background:#0d1117; color:#c9d1d9; border:1px solid #30363d; border-radius:4px; font:inherit; }
+#rec-banner .clock { font-variant-numeric:tabular-nums; color:#c9d1d9; min-width:96px; }
+#rec-drop { position:fixed; inset:0; z-index:9998; display:none; align-items:center; justify-content:center;
+  background:#010409cc; color:#e6edf3; font:600 18px system-ui,sans-serif; border:3px dashed #58a6ff; }
+body.rec-dragging #rec-drop { display:flex; }
+button.act.rec-on { border-color:#f85149; color:#ff7b72; }
+`;
+
+export function setup(api) {
+  const style = document.createElement('style');
+  style.textContent = CSS;
+  document.head.appendChild(style);
+
+  /* ── capture ──────────────────────────────────────────────────────────── */
+
+  const rolling = createFrameBuffer(ROLLING_EVENTS);
+  /** Explicit recording: { frames, events, active, capped } or null. */
+  let rec = null;
+  /** True while this panel itself is feeding api.ingest (replay/seek). */
+  let feeding = false;
+
+  api.onBatch((session, events) => {
+    if (feeding || api.livePaused || !events.length) return;
+    const frame = { t: performance.now(), session, events };
+    rolling.push(frame);
+    if (rec?.active) {
+      if (rec.events + events.length > RECORDING_EVENTS) {
+        if (!rec.capped) toast(`Recording hit ${RECORDING_EVENTS.toLocaleString()} events: stopped`, 'info');
+        rec.capped = true;
+        stopRec();
+        return;
+      }
+      rec.frames.push(frame);
+      rec.events += events.length;
+    }
+  });
+
+  /* ── toolbar ──────────────────────────────────────────────────────────── */
+
+  const recBtn = api.addToolbarButton({
+    id: 'rec-toggle', label: '● Rec', order: 20,
+    title: 'Start an explicit recording (Export then saves just the recording)',
+    onClick: () => (rec?.active ? stopRec() : startRec()),
+  });
+  const exportBtn = api.addToolbarButton({
+    id: 'rec-export', label: 'Export', order: 21,
+    title: 'Download the recording, or the rolling capture of recent frames',
+    onClick: () => exportFrames(),
+  });
+  api.addToolbarButton({
+    id: 'rec-import', label: 'Import', order: 22,
+    title: 'Open a recording (.json) for replay; you can also drop the file on the window',
+    onClick: () => picker.click(),
+  });
+
+  const syncButtons = () => {
+    recBtn.innerHTML = rec?.active ? '■ Stop' : '● Rec';
+    recBtn.classList.toggle('rec-on', !!rec?.active);
+    recBtn.title = rec?.active
+      ? `Recording: ${rec.events.toLocaleString()} events so far (click to stop)`
+      : 'Start an explicit recording (Export then saves just the recording)';
+    exportBtn.innerHTML = rec?.frames.length ? 'Export rec' : 'Export';
+  };
+
+  function startRec() {
+    if (api.livePaused) return toast('Go back to live before recording', 'info');
+    rec = { frames: [], events: 0, active: true, capped: false };
+    syncButtons();
+    toast('Recording started', 'info');
+  }
+
+  function stopRec() {
+    if (!rec) return;
+    rec.active = false;
+    syncButtons();
+    toast(`Recording stopped: ${rec.events.toLocaleString()} events`);
+  }
+
+  api.onTick(() => { if (rec?.active) syncButtons(); });
+
+  function download(name, data) {
+    const blob = new Blob([JSON.stringify(data)], { type: 'application/json' });
+    const a = document.createElement('a');
+    a.href = URL.createObjectURL(blob);
+    a.download = name;
+    document.body.appendChild(a);
+    a.click();
+    a.remove();
+    setTimeout(() => URL.revokeObjectURL(a.href), 1000);
+  }
+
+  function exportFrames({ useRolling = false } = {}) {
+    const fromRec = !useRolling && rec?.frames.length;
+    const source = fromRec ? rec.frames : rolling.frames();
+    const sid = api.state.sel && api.state.sessions.has(api.state.sel) ? api.state.sel : null;
+    const data = serializeRecording(source, { sessionId: sid });
+    if (!data.frames.length) return toast('Nothing captured yet', 'info');
+    const name = sid ? (api.state.sessions.get(sid)?.name ?? sid) : null;
+    download(recordingFileName(name), data);
+    toast(`Exported ${countEvents(data.frames).toLocaleString()} events${fromRec ? ' (recording)' : ''}`);
+  }
+
+  /* ── import ───────────────────────────────────────────────────────────── */
+
+  const picker = document.createElement('input');
+  picker.type = 'file';
+  picker.accept = '.json,application/json';
+  picker.style.display = 'none';
+  picker.onchange = () => {
+    const f = picker.files?.[0];
+    picker.value = '';
+    if (f) importFile(f);
+  };
+  document.body.appendChild(picker);
+
+  const drop = document.createElement('div');
+  drop.id = 'rec-drop';
+  drop.textContent = 'Drop an atoll devtools recording to replay it';
+  document.body.appendChild(drop);
+  const hasFiles = (e) => [...(e.dataTransfer?.types ?? [])].includes('Files');
+  let dragDepth = 0;
+  window.addEventListener('dragenter', (e) => {
+    if (!hasFiles(e)) return;
+    dragDepth++;
+    document.body.classList.add('rec-dragging');
+  });
+  window.addEventListener('dragleave', () => {
+    if (dragDepth && --dragDepth === 0) document.body.classList.remove('rec-dragging');
+  });
+  window.addEventListener('dragover', (e) => { if (hasFiles(e)) e.preventDefault(); });
+  window.addEventListener('drop', (e) => {
+    if (!hasFiles(e)) return;
+    e.preventDefault();
+    dragDepth = 0;
+    document.body.classList.remove('rec-dragging');
+    const f = [...e.dataTransfer.files].find((x) => /\.json$/i.test(x.name) || x.type === 'application/json');
+    if (f) importFile(f);
+    else toast('Drop a .json recording', 'error');
+  });
+
+  async function importFile(file) {
+    let recording;
+    try {
+      recording = validateRecording(JSON.parse(await file.text()));
+    } catch (err) {
+      return toast(`Import failed: ${err.message}`, 'error');
+    }
+    if (rec?.active) stopRec();
+    startReplay(recording, file.name);
+  }
+
+  /* ── replay ───────────────────────────────────────────────────────────── */
+
+  /** { frames, sessions, name, duration, events, cursor, playhead, playing, speed, wallStart, fromMs, timer, els } */
+  let rp = null;
+
+  function startReplay(recording, name) {
+    stopPlayback();
+    api.livePaused = true;
+    const frames = recording.frames;
+    rp = {
+      frames,
+      sessions: replaySessions(recording),
+      name,
+      duration: recordingDuration(frames),
+      events: countEvents(frames),
+      cursor: 0,
+      playhead: 0,
+      playing: false,
+      speed: 1,
+      timer: 0,
+      els: null,
+    };
+    buildBanner();
+    seek(rp.duration); // the full picture first; Play restarts from 0
+    toast(`Loaded ${name}: ${rp.events.toLocaleString()} events`);
+  }
+
+  /** Feed frames [rp.cursor, to) into the dashboard. */
+  function feed(to) {
+    feeding = true;
+    try {
+      for (let i = rp.cursor; i < to; i++) {
+        const f = rp.frames[i];
+        api.ingest(rp.sessions.get(f.sessionId), f.events);
+      }
+    } finally {
+      feeding = false;
+    }
+    rp.cursor = to;
+  }
+
+  /** Jump to recording time `at`: reset, then re-ingest everything up to it. */
+  function seek(at) {
+    rp.seeking = true;
+    try {
+      api.reset();
+    } finally {
+      rp.seeking = false;
+    }
+    rp.cursor = 0;
+    rp.playhead = Math.max(0, Math.min(at, rp.duration));
+    feed(indexAt(rp.frames, rp.playhead));
+    syncBanner();
+  }
+
+  function play() {
+    if (!rp) return;
+    if (rp.cursor >= rp.frames.length) seek(0);
+    rp.playing = true;
+    rp.fromMs = rp.playhead;
+    rp.wallStart = performance.now();
+    step();
+    syncBanner();
+  }
+
+  function stopPlayback() {
+    if (!rp) return;
+    rp.playing = false;
+    clearTimeout(rp.timer);
+    syncBanner();
+  }
+
+  function step() {
+    if (!rp?.playing) return;
+    const target = playheadAt(rp.fromMs, performance.now() - rp.wallStart, rp.speed, rp.duration);
+    const chunk = nextChunk(rp.frames, rp.cursor, target, PLAY_CHUNK_EVENTS);
+    feed(chunk.to);
+    // A capped chunk lags the wall clock: the playhead is what was ingested.
+    rp.playhead = chunk.to < indexAt(rp.frames, target) ? rp.frames[chunk.to - 1]?.t ?? target : target;
+    if (chunk.done && rp.playhead >= rp.duration) {
+      rp.playhead = rp.duration;
+      rp.playing = false;
+      syncBanner();
+      return;
+    }
+    syncBanner();
+    rp.timer = setTimeout(step, rp.speed === Infinity ? 0 : 33);
+  }
+
+  function setSpeed(speed) {
+    if (!rp) return;
+    if (rp.playing) {
+      rp.fromMs = rp.playhead;
+      rp.wallStart = performance.now();
+    }
+    rp.speed = speed;
+  }
+
+  function backToLive() {
+    stopPlayback();
+    rp?.els?.banner.remove();
+    rp = null;
+    api.reset();
+    api.livePaused = false;
+    api.reannounce();
+    toast('Back to live', 'info');
+  }
+
+  function buildBanner() {
+    document.getElementById('rec-banner')?.remove();
+    const banner = document.createElement('div');
+    banner.id = 'rec-banner';
+    banner.innerHTML = `
+      <span>⏺ Replay <b></b></span>
+      <span class="meta"></span>
+      <button class="act" data-r="play">▶ Play</button>
+      <select data-r="speed" title="Playback speed">${SPEEDS.map((s) => `<option value="${s}">${s === Infinity ? 'max' : `${s}x`}</option>`).join('')}</select>
+      <input type="range" data-r="scrub" min="0" step="1" title="Seek: rebuilds the dashboard up to this point">
+      <span class="clock"></span>
+      <button class="act" data-r="live" title="Discard the replay and reconnect to live apps">Back to live</button>`;
+    const q = (r) => banner.querySelector(`[data-r="${r}"]`);
+    const els = { banner, name: banner.querySelector('b'), meta: banner.querySelector('.meta'), play: q('play'), speed: q('speed'), scrub: q('scrub'), clock: banner.querySelector('.clock'), live: q('live') };
+    els.name.textContent = rp.name;
+    els.meta.textContent = `${fmtClock(rp.duration)} · ${rp.events.toLocaleString()} events · ${rp.sessions.size} session(s)`;
+    els.scrub.max = String(Math.max(1, Math.ceil(rp.duration)));
+    els.play.onclick = () => (rp.playing ? stopPlayback() : play());
+    els.speed.onchange = () => setSpeed(Number(els.speed.value));
+    els.scrub.oninput = () => { els.clock.textContent = `${fmtClock(Number(els.scrub.value))} / ${fmtClock(rp.duration)}`; };
+    els.scrub.onchange = () => {
+      const wasPlaying = rp.playing;
+      stopPlayback();
+      seek(Number(els.scrub.value));
+      if (wasPlaying) play();
+    };
+    els.live.onclick = backToLive;
+    rp.els = els;
+    const panels = document.querySelector('.panels');
+    if (panels) panels.prepend(banner);
+    else document.body.prepend(banner);
+  }
+
+  function syncBanner() {
+    const els = rp?.els;
+    if (!els) return;
+    els.play.textContent = rp.playing ? '❚❚ Pause' : '▶ Play';
+    if (document.activeElement !== els.scrub) els.scrub.value = String(Math.round(rp.playhead));
+    els.clock.textContent = `${fmtClock(rp.playhead)} / ${fmtClock(rp.duration)}`;
+  }
+
+  // An outside reset (not our seek) while replaying keeps the replay but
+  // rewinds its cursor so the next Play/seek re-ingests from a clean slate.
+  api.onReset(() => {
+    if (rp && !rp.seeking) {
+      rp.cursor = 0;
+      rp.playhead = 0;
+      stopPlayback();
+    }
+  });
+
+  /* ── palette ──────────────────────────────────────────────────────────── */
+
+  api.addPaletteItem({ id: 'recorder.toggle', title: 'Recording: start / stop', group: 'Recorder', run: () => (rec?.active ? stopRec() : startRec()) });
+  api.addPaletteItem({ id: 'recorder.export', title: 'Export recording', group: 'Recorder', hint: 'The explicit recording when there is one, else the rolling capture', run: () => exportFrames() });
+  api.addPaletteItem({ id: 'recorder.export-rolling', title: 'Export rolling capture', group: 'Recorder', hint: `The last ~${ROLLING_EVENTS.toLocaleString()} received events`, run: () => exportFrames({ useRolling: true }) });
+  api.addPaletteItem({ id: 'recorder.discard', title: 'Discard recording', group: 'Recorder', run: () => { rec = null; syncButtons(); toast('Recording discarded', 'info'); } });
+  api.addPaletteItem({ id: 'recorder.import', title: 'Import recording…', group: 'Recorder', run: () => picker.click() });
+  api.addPaletteItem({ id: 'recorder.live', title: 'Replay: back to live', group: 'Recorder', run: () => { if (rp) backToLive(); else toast('Not replaying', 'info'); } });
+}

package/app/panels/recording-format.js

@@ -0,0 +1,166 @@
+// Pure helpers for devtools recordings: the file format, validation, the
+// bounded rolling capture, and replay pacing. No DOM, no api: recorder.js
+// owns the UI; vitest imports this module directly.
+//
+// File shape (version 1):
+//   { format: 'atoll-devtools-recording', version: 1, exportedAt,
+//     sessions: SessionInfo[], frames: [{ t, sessionId, events }] }
+// `t` is the dashboard's performance.now() at receipt; replay only uses
+// differences, so recordings from any clock origin play back the same.
+
+export const FORMAT = 'atoll-devtools-recording';
+export const VERSION = 1;
+/** Prefix marking replayed sessions in the dashboard. */
+export const REPLAY_PREFIX = '⏺ ';
+/** Playback speeds offered by the replay banner; Infinity = as fast as possible. */
+export const SPEEDS = [1, 4, 16, Infinity];
+
+/**
+ * Bounded capture of received frames, evicting oldest whole frames once
+ * the total event count passes `maxEvents`.
+ */
+export function createFrameBuffer(maxEvents = 50_000) {
+  let frames = [];
+  let head = 0;
+  let events = 0;
+  return {
+    push(frame) {
+      frames.push(frame);
+      events += frame.events.length;
+      while (events > maxEvents && head < frames.length - 1) {
+        events -= frames[head].events.length;
+        frames[head++] = undefined;
+      }
+      if (head > 1024 && head > frames.length / 2) {
+        frames = frames.slice(head);
+        head = 0;
+      }
+    },
+    frames: () => frames.slice(head),
+    get eventCount() { return events; },
+    get frameCount() { return frames.length - head; },
+    clear() { frames = []; head = 0; events = 0; },
+  };
+}
+
+const pad = (n) => String(n).padStart(2, '0');
+
+/** `atoll-devtools-<session-or-all>-<yyyymmdd-hhmmss>.json` (local time). */
+export function recordingFileName(sessionName, date = new Date()) {
+  const slug = (sessionName ?? 'all').toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'session';
+  const stamp = `${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}-${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`;
+  return `atoll-devtools-${slug}-${stamp}.json`;
+}
+
+/**
+ * Build the export object from captured frames ({ t, session, events } as
+ * the recorder holds them). `sessionId` narrows to one session.
+ */
+export function serializeRecording(captured, { sessionId = null, exportedAt = new Date().toISOString() } = {}) {
+  const sessions = new Map();
+  const frames = [];
+  for (const f of captured) {
+    if (sessionId && f.session.id !== sessionId) continue;
+    sessions.set(f.session.id, f.session);
+    frames.push({ t: f.t, sessionId: f.session.id, events: f.events });
+  }
+  return { format: FORMAT, version: VERSION, exportedAt, sessions: [...sessions.values()], frames };
+}
+
+/**
+ * Validate a parsed file; returns the recording with frames sorted by `t`
+ * and times rebased to start at 0. Throws an Error naming the first problem.
+ */
+export function validateRecording(data) {
+  if (!data || typeof data !== 'object') throw new Error('not a JSON object');
+  if (data.format !== FORMAT) throw new Error(`not an atoll devtools recording (format: ${JSON.stringify(data.format)})`);
+  if (data.version !== VERSION) throw new Error(`unsupported recording version ${JSON.stringify(data.version)} (expected ${VERSION})`);
+  if (!Array.isArray(data.sessions)) throw new Error('sessions must be an array');
+  if (!Array.isArray(data.frames)) throw new Error('frames must be an array');
+  for (const [i, s] of data.sessions.entries()) {
+    if (!s || typeof s.id !== 'string') throw new Error(`sessions[${i}] has no string id`);
+  }
+  for (const [i, f] of data.frames.entries()) {
+    if (!f || typeof f.t !== 'number' || !Number.isFinite(f.t)) throw new Error(`frames[${i}].t must be a finite number`);
+    if (typeof f.sessionId !== 'string') throw new Error(`frames[${i}].sessionId must be a string`);
+    if (!Array.isArray(f.events)) throw new Error(`frames[${i}].events must be an array`);
+  }
+  const sorted = data.frames.slice().sort((a, b) => a.t - b.t);
+  const t0 = sorted.length ? sorted[0].t : 0;
+  return {
+    ...data,
+    frames: sorted.map((f) => ({ t: f.t - t0, sessionId: f.sessionId, events: f.events })),
+  };
+}
+
+/**
+ * Sessions for replay, keyed by id: renamed with the replay prefix and
+ * closed (the dashboard sends no control commands to closed sessions).
+ * Frames naming an unlisted session get a stub entry.
+ */
+export function replaySessions(recording) {
+  const out = new Map();
+  for (const s of recording.sessions) {
+    out.set(s.id, { ...s, name: `${REPLAY_PREFIX}${s.name ?? s.id}`, closed: true });
+  }
+  for (const f of recording.frames) {
+    if (!out.has(f.sessionId)) {
+      out.set(f.sessionId, { id: f.sessionId, name: `${REPLAY_PREFIX}${f.sessionId}`, runtime: 'browser', closed: true });
+    }
+  }
+  return out;
+}
+
+/** Recording length in ms (frames rebased by validateRecording). */
+export const recordingDuration = (frames) => (frames.length ? frames[frames.length - 1].t : 0);
+
+export const countEvents = (frames) => frames.reduce((n, f) => n + f.events.length, 0);
+
+/** Number of frames with `t <= at` — the replay cursor for a playhead (binary search). */
+export function indexAt(frames, at) {
+  let lo = 0;
+  let hi = frames.length;
+  while (lo < hi) {
+    const mid = (lo + hi) >> 1;
+    if (frames[mid].t <= at) lo = mid + 1;
+    else hi = mid;
+  }
+  return lo;
+}
+
+/** Frames up to and including playhead `at`. */
+export const framesUpTo = (frames, at) => frames.slice(0, indexAt(frames, at));
+
+/**
+ * Playhead for timed playback: recording ms reached after `wallMs` of
+ * wall time at `speed`, starting from `fromMs`, clamped to `duration`.
+ * Infinity speed jumps to the end (callers chunk the ingest instead).
+ */
+export function playheadAt(fromMs, wallMs, speed, duration) {
+  if (speed === Infinity) return duration;
+  return Math.min(duration, fromMs + Math.max(0, wallMs) * speed);
+}
+
+/**
+ * The next slice to ingest during playback: frames [from, to) are due at
+ * `playhead`, capped at `maxEvents` per step (at least one frame) so a dense
+ * stretch or max speed never blocks the dashboard for long.
+ */
+export function nextChunk(frames, from, playhead, maxEvents = 2000) {
+  const due = indexAt(frames, playhead);
+  let to = from;
+  let n = 0;
+  while (to < due && (to === from || n + frames[to].events.length <= maxEvents)) {
+    n += frames[to].events.length;
+    to++;
+  }
+  return { from, to, events: n, done: to >= frames.length };
+}
+
+/** `1:05.3` style clock for the banner. */
+export function fmtClock(ms) {
+  const s = Math.max(0, ms) / 1000;
+  const m = Math.floor(s / 60);
+  const rest = s - m * 60;
+  return `${m}:${rest < 10 ? '0' : ''}${rest.toFixed(1)}`;
+}

package/app/panels/route.d.ts

@@ -0,0 +1,44 @@
+// Types for route.js (plain JS, served without a build step).
+
+export interface Route {
+  view: string;
+  sub: string | null;
+  params: Record<string, string>;
+}
+export interface RouteInput {
+  view: string;
+  sub?: string | null;
+  params?: Record<string, string | null | undefined>;
+}
+export interface PaletteLike {
+  title: string;
+  group?: string;
+  hint?: string;
+  keywords?: string;
+}
+export interface Ranked<T> {
+  item: T;
+  score: number;
+  idx: number[];
+}
+
+export const ROUTE_PARAMS: string[];
+export function parseRoute(hash: string): Route | null;
+export function formatRoute(route: RouteInput): string;
+export function keyTail(k: string): string;
+export function resolveKey(
+  keys: Iterable<string>,
+  want: string | null | undefined,
+  isLive?: (k: string) => boolean,
+): string | null;
+export function fuzzyMatch(query: string, text: string): { score: number; idx: number[] } | null;
+export function rankItems<T extends PaletteLike>(query: string, items: T[]): Ranked<T>[];
+export function groupResults<T extends PaletteLike>(
+  ranked: Ranked<T>[],
+  opts?: { order?: string[]; perGroup?: number; byScore?: boolean },
+): { group: string; items: Ranked<T>[] }[];
+export const G_VIEWS: Record<string, string>;
+export function viewForLetter(letter: string, views: { id: string; label?: string }[]): string | null;
+export function letterForView(id: string, views: { id: string; label?: string }[]): string | null;
+export function isTypingTarget(el: unknown): boolean;
+export function layoutNav(widths: number[], avail: number, active: number, moreW: number): number[];