@three-flatland/devtools 0.1.0-alpha.3

package/dist/stats-graph.cjs

@@ -0,0 +1,297 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var stats_graph_exports = {};
+__export(stats_graph_exports, {
+  addStatsGraph: () => addStatsGraph
+});
+module.exports = __toCommonJS(stats_graph_exports);
+var import_debug_protocol = require("three-flatland/debug-protocol");
+const MODES = ["fps", "ms", "gpu", "mem"];
+const BUFFER_SIZE = 80;
+const MODE_COLORS = {
+  fps: "#47cca9",
+  // retro-cyan
+  ms: "#47cc6a",
+  // green variant
+  gpu: "#ffa347",
+  // retro-amber
+  mem: "#d94c87"
+  // retro-pink
+};
+const MODE_UNITS = {
+  fps: "FPS",
+  ms: "MS",
+  gpu: "MS",
+  mem: "MB"
+};
+function addStatsGraph(parent, client, options = {}) {
+  const { rows = 2, driver = "raf" } = options;
+  let mode = "fps";
+  let modeIndex = 0;
+  const graphMax = {
+    fps: 120,
+    ms: 16.67,
+    gpu: 16.67,
+    mem: 256
+  };
+  const sessionMin = { fps: Infinity, ms: Infinity, gpu: Infinity, mem: Infinity };
+  const sessionMax = { fps: 0, ms: 0, gpu: 0, mem: 0 };
+  const lblv = document.createElement("div");
+  lblv.className = "tp-lblv";
+  lblv.style.cursor = "pointer";
+  const lblvL = document.createElement("div");
+  lblvL.className = "tp-lblv_l";
+  lblvL.textContent = "fps";
+  lblv.appendChild(lblvL);
+  const lblvV = document.createElement("div");
+  lblvV.className = "tp-lblv_v";
+  lblv.appendChild(lblvV);
+  const fpsv = document.createElement("div");
+  fpsv.className = "tp-fpsv";
+  lblvV.appendChild(fpsv);
+  const fpsvG = document.createElement("div");
+  fpsvG.className = "tp-fpsv_g";
+  fpsv.appendChild(fpsvG);
+  const grlv = document.createElement("div");
+  grlv.className = "tp-grlv";
+  fpsvG.appendChild(grlv);
+  const canvas = document.createElement("canvas");
+  canvas.classList.add("tp-grlv_g");
+  canvas.style.cssText = `display:block;width:100%;height:calc(var(--cnt-usz, 20px) * ${rows})`;
+  canvas.width = 1;
+  canvas.height = 1;
+  grlv.appendChild(canvas);
+  const gfx = canvas.getContext("2d");
+  const fpsvL = document.createElement("div");
+  fpsvL.className = "tp-fpsv_l";
+  fpsvL.style.cssText = "background:rgba(0,2,28,0.65);padding:1px 4px;border-radius:2px;";
+  fpsv.appendChild(fpsvL);
+  const valueSpan = document.createElement("span");
+  valueSpan.className = "tp-fpsv_v";
+  valueSpan.textContent = "--";
+  fpsvL.appendChild(valueSpan);
+  const unitSpan = document.createElement("span");
+  unitSpan.className = "tp-fpsv_u";
+  unitSpan.textContent = "FPS";
+  fpsvL.appendChild(unitSpan);
+  const blade = parent.addBlade({ view: "separator" });
+  const bladeEl = blade.element;
+  bladeEl.innerHTML = "";
+  bladeEl.className = "tp-cntv";
+  bladeEl.style.cssText = "";
+  bladeEl.appendChild(lblv);
+  function applyMode() {
+    lblvL.textContent = mode;
+    unitSpan.textContent = MODE_UNITS[mode];
+  }
+  applyMode();
+  lblv.addEventListener("click", () => {
+    const state = client.state;
+    do {
+      modeIndex = (modeIndex + 1) % MODES.length;
+      mode = MODES[modeIndex];
+    } while (mode === "mem" && state.heapUsedMB === void 0 || mode === "gpu" && !state.gpuModeEnabled);
+    applyMode();
+  });
+  let cachedW = 0;
+  let cachedH = 0;
+  const resizeObserver = new ResizeObserver(([entry]) => {
+    if (!entry) return;
+    const r = entry.contentRect;
+    const dpr = window.devicePixelRatio || 1;
+    const w = Math.max(1, Math.round(r.width * dpr));
+    const h = Math.max(1, Math.round(r.height * dpr));
+    if (canvas.width !== w || canvas.height !== h) {
+      canvas.width = w;
+      canvas.height = h;
+    }
+    cachedW = w;
+    cachedH = h;
+  });
+  resizeObserver.observe(canvas);
+  const MODE_LABEL = { fps: "fps", ms: "ms", gpu: "gpu", mem: "mem" };
+  const MODE_VALUE_UNIT = { fps: "FPS", ms: "MS", gpu: "MS", mem: "MB" };
+  const MODE_RANGE_UNIT = { fps: "FPS", ms: "MS", gpu: "GPU", mem: "MB" };
+  const MODE_DECIMALS = { fps: 0, ms: 1, gpu: 1, mem: 0 };
+  const MODE_SCALE = { fps: 1, ms: 10, gpu: 10, mem: 1 };
+  const fmtCache = {
+    fps: { key: NaN, str: "" },
+    ms: { key: NaN, str: "" },
+    gpu: { key: NaN, str: "" },
+    mem: { key: NaN, str: "" }
+  };
+  function fmtCached(m, v) {
+    const key = Math.round(v * MODE_SCALE[m]);
+    const c = fmtCache[m];
+    if (c.key === key) return c.str;
+    c.key = key;
+    c.str = v.toFixed(MODE_DECIMALS[m]);
+    return c.str;
+  }
+  function seriesFor(m) {
+    const s = client.state.series;
+    switch (m) {
+      case "fps":
+        return s.fps;
+      case "ms":
+        return s.cpuMs;
+      case "gpu":
+        return s.gpuMs;
+      case "mem":
+        return s.heapUsedMB;
+    }
+  }
+  const prevLabel = { fps: 0, ms: 0, gpu: 0, mem: 0 };
+  const currLabel = { fps: 0, ms: 0, gpu: 0, mem: 0 };
+  const hasLabel = { fps: false, ms: false, gpu: false, mem: false };
+  let batchCount = 0;
+  let lastBatchAt = performance.now();
+  let prevRingWrite = 0;
+  const snap = (m, v) => {
+    if (v === void 0) return;
+    prevLabel[m] = hasLabel[m] ? currLabel[m] : v;
+    currLabel[m] = v;
+    hasLabel[m] = true;
+  };
+  const unsubscribe = client.addListener((s) => {
+    if (s.heapLimitMB !== void 0) graphMax.mem = s.heapLimitMB;
+    snap("fps", s.fps);
+    snap("ms", s.cpuMs);
+    snap("gpu", s.gpuMs);
+    snap("mem", s.heapUsedMB);
+    const fps = s.series.fps;
+    const size = fps.data.length;
+    const delta = (fps.write - prevRingWrite + size) % size;
+    if (delta > 0) {
+      batchCount = delta;
+      prevRingWrite = fps.write;
+      lastBatchAt = performance.now();
+    }
+  });
+  let rafId = 0;
+  let disposed = false;
+  function setText(node, next, cache) {
+    if (cache.v === next) return;
+    node.textContent = next;
+    cache.v = next;
+  }
+  const labelCache = { v: "" };
+  const valueCache = { v: "" };
+  const unitCache = { v: "" };
+  const titleCache = { v: "" };
+  function update() {
+    if (disposed) return;
+    if (cachedW === 0 || cachedH === 0 || gfx === null) return;
+    const now = performance.now();
+    const t = Math.min(1, Math.max(0, (now - lastBatchAt) / import_debug_protocol.STATS_BATCH_MS));
+    const ring = seriesFor(mode);
+    const size = ring.data.length;
+    const max = graphMax[mode] || 1;
+    const phase = batchCount * (1 - t);
+    const intPhase = Math.floor(phase);
+    const fracPhase = phase - intPhase;
+    const w = cachedW;
+    const h = cachedH;
+    gfx.clearRect(0, 0, w, h);
+    const color = MODE_COLORS[mode];
+    const samplePixelW = w / (BUFFER_SIZE - 1);
+    let mn = Infinity;
+    let mx = 0;
+    const baseRingIdx = ring.write - intPhase - BUFFER_SIZE + size * 2;
+    gfx.beginPath();
+    for (let i = -1; i < BUFFER_SIZE; i++) {
+      const ringIdx = (baseRingIdx + i) % size;
+      const v = ring.data[ringIdx];
+      if (i >= 0) {
+        if (v < mn) mn = v;
+        if (v > mx) mx = v;
+      }
+      const x = (i + fracPhase) * samplePixelW;
+      const yRaw = h - v / max * h * 0.85 - h * 0.05;
+      const y = yRaw < h * 0.05 ? h * 0.05 : yRaw;
+      if (i === -1) gfx.moveTo(x, y);
+      else gfx.lineTo(x, y);
+    }
+    gfx.lineTo(w, h);
+    gfx.lineTo(0, h);
+    gfx.closePath();
+    gfx.fillStyle = color;
+    gfx.globalAlpha = 0.33;
+    gfx.fill();
+    gfx.globalAlpha = 1;
+    gfx.beginPath();
+    for (let i = -1; i < BUFFER_SIZE; i++) {
+      const ringIdx = (baseRingIdx + i) % size;
+      const v = ring.data[ringIdx];
+      const x = (i + fracPhase) * samplePixelW;
+      const yRaw = h - v / max * h * 0.85 - h * 0.05;
+      const y = yRaw < h * 0.05 ? h * 0.05 : yRaw;
+      if (i === -1) gfx.moveTo(x, y);
+      else gfx.lineTo(x, y);
+    }
+    gfx.strokeStyle = color;
+    gfx.lineWidth = Math.max(1, window.devicePixelRatio || 1);
+    gfx.stroke();
+    if (hasLabel[mode]) {
+      sessionMin[mode] = Math.min(sessionMin[mode], mn);
+      sessionMax[mode] = Math.max(sessionMax[mode], mx);
+    }
+    const has = hasLabel[mode];
+    const lerped = prevLabel[mode] + (currLabel[mode] - prevLabel[mode]) * t;
+    const sMn = sessionMin[mode];
+    const sMx = sessionMax[mode];
+    setText(lblvL, MODE_LABEL[mode], labelCache);
+    setText(valueSpan, has ? fmtCached(mode, lerped) : "--", valueCache);
+    setText(unitSpan, MODE_VALUE_UNIT[mode], unitCache);
+    const nextTitle = sMn !== Infinity ? `${MODE_RANGE_UNIT[mode]} range: ${Math.round(sMn)}\u2013${Math.round(sMx)}` : "";
+    if (titleCache.v !== nextTitle) {
+      lblvL.title = nextTitle;
+      titleCache.v = nextTitle;
+    }
+  }
+  if (driver === "raf") {
+    const autoFrame = () => {
+      if (disposed) return;
+      rafId = requestAnimationFrame(autoFrame);
+      update();
+    };
+    rafId = requestAnimationFrame(autoFrame);
+  }
+  return {
+    element: bladeEl,
+    // In `'raf'` mode the internal loop already runs, so public `update()`
+    // is a no-op — we don't want to paint twice per frame when the host
+    // also (redundantly) drives it. In `'manual'` mode this is the only
+    // way the graph gets painted.
+    update: driver === "manual" ? update : () => {
+    },
+    dispose() {
+      disposed = true;
+      if (rafId !== 0) cancelAnimationFrame(rafId);
+      unsubscribe();
+      resizeObserver.disconnect();
+      blade.dispose();
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  addStatsGraph
+});
+//# sourceMappingURL=stats-graph.cjs.map

package/dist/stats-graph.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/stats-graph.ts"],"sourcesContent":["/**\n * Cycling stats graph — click to cycle FPS / MS / MEM (like stats.js).\n *\n * Replicates the exact DOM structure of Tweakpane's built-in fpsgraph blade.\n * Uses SVG polyline like GraphLogView (tp-grlv). Click anywhere to cycle modes.\n * Only the graph line is colorized per mode; text uses default Tweakpane colors.\n */\n\nimport type { FolderApi, Pane } from 'tweakpane'\nimport { STATS_BATCH_MS } from 'three-flatland/debug-protocol'\n\nimport type { DevtoolsClient, DevtoolsSeries } from './devtools-client.js'\n\nexport interface StatsGraphHandle {\n  /** The root element */\n  readonly element: HTMLElement\n  /**\n   * Render a frame. Required when constructed with `driver: 'manual'`;\n   * no-op for the `'raf'` driver (the internal rAF is doing it).\n   */\n  update(): void\n  /** Stop and remove. */\n  dispose(): void\n}\n\nexport interface AddStatsGraphOptions {\n  rows?: number\n  /**\n   * `'raf'` (default) — the graph runs its own `requestAnimationFrame`\n   * loop. `'manual'` — no rAF; caller drives via `handle.update()` from\n   * their own frame tick (e.g. `renderer.setAnimationLoop`, R3F\n   * `useFrame`).\n   */\n  driver?: 'raf' | 'manual'\n}\n\ntype Mode = 'fps' | 'ms' | 'gpu' | 'mem'\n\n// Cycle order: FPS → MS → GPU → MEM (gpu next to ms so you can A/B them).\nconst MODES: Mode[] = ['fps', 'ms', 'gpu', 'mem']\nconst BUFFER_SIZE = 80\n\n// Retro-themed line colors (only applied to the graph line)\nconst MODE_COLORS: Record<Mode, string> = {\n  fps: '#47cca9', // retro-cyan\n  ms: '#47cc6a', // green variant\n  gpu: '#ffa347', // retro-amber\n  mem: '#d94c87', // retro-pink\n}\n\n// Unit labels shown next to the live value overlay (bottom-right of the\n// graph). The left-side mode label distinguishes fps/ms/gpu/mem; this is\n// just the unit of the number itself, so `gpu` (also milliseconds) reads\n// `MS` here.\nconst MODE_UNITS: Record<Mode, string> = {\n  fps: 'FPS',\n  ms: 'MS',\n  gpu: 'MS',\n  mem: 'MB',\n}\n\n/**\n * Add a cycling stats graph to a Tweakpane parent.\n * Matches the visual design of the built-in fpsgraph blade.\n */\nexport function addStatsGraph(\n  parent: Pane | FolderApi,\n  client: DevtoolsClient,\n  options: AddStatsGraphOptions = {},\n): StatsGraphHandle {\n  const { rows = 2, driver = 'raf' } = options\n\n  // State\n  let mode: Mode = 'fps'\n  let modeIndex = 0\n\n  // Graph max scales\n  // FPS: 120 (tops out at 120fps)\n  // MS: 16.67 (one frame at 60fps — hitting the top means blown frame budget)\n  // GPU: 16.67 (same frame budget as MS, just measured on the GPU side)\n  // MEM: heap limit in MB — pulled from `state.heapLimitMB` once it\n  //      arrives; default 256 until then.\n  const graphMax: Record<Mode, number> = {\n    fps: 120,\n    ms: 16.67,\n    gpu: 16.67,\n    mem: 256,\n  }\n\n  // Session min/max tracking (like stats.js displays \"60 FPS (55-62)\")\n  const sessionMin: Record<Mode, number> = { fps: Infinity, ms: Infinity, gpu: Infinity, mem: Infinity }\n  const sessionMax: Record<Mode, number> = { fps: 0, ms: 0, gpu: 0, mem: 0 }\n\n  // ── Build DOM matching Tweakpane's label + graph structure ──\n\n  // tp-lblv: label view (left label + right value)\n  const lblv = document.createElement('div')\n  lblv.className = 'tp-lblv'\n  lblv.style.cursor = 'pointer'\n\n  const lblvL = document.createElement('div')\n  lblvL.className = 'tp-lblv_l'\n  lblvL.textContent = 'fps'\n  lblv.appendChild(lblvL)\n\n  // Value area (right side — full width when no label)\n  const lblvV = document.createElement('div')\n  lblvV.className = 'tp-lblv_v'\n  lblv.appendChild(lblvV)\n\n  // tp-fpsv: FPS view container (positions the overlay label)\n  const fpsv = document.createElement('div')\n  fpsv.className = 'tp-fpsv'\n  lblvV.appendChild(fpsv)\n\n  // tp-fpsv_g: graph area\n  const fpsvG = document.createElement('div')\n  fpsvG.className = 'tp-fpsv_g'\n  fpsv.appendChild(fpsvG)\n\n  // tp-grlv: graph log view. We render into a 2D canvas instead of an\n  // SVG polyline because per-frame `setAttribute('points', ...)` was\n  // (a) allocating long template-literal strings every rAF and (b)\n  // forcing the browser to re-allocate CSS-selector strings to\n  // re-evaluate styles for every ancestor in the `.tp-cntv .tp-v-fst …`\n  // chain — a measurable string-GC cost in profiles. Canvas drawing is\n  // pure path commands, no DOM mutation.\n  const grlv = document.createElement('div')\n  grlv.className = 'tp-grlv'\n  fpsvG.appendChild(grlv)\n\n  const canvas = document.createElement('canvas')\n  canvas.classList.add('tp-grlv_g')\n  canvas.style.cssText = `display:block;width:100%;height:calc(var(--cnt-usz, 20px) * ${rows})`\n  canvas.width = 1\n  canvas.height = 1\n  grlv.appendChild(canvas)\n  const gfx = canvas.getContext('2d')\n\n  // tp-fpsv_l: value label overlay (bottom-right) with bg for readability\n  const fpsvL = document.createElement('div')\n  fpsvL.className = 'tp-fpsv_l'\n  fpsvL.style.cssText = 'background:rgba(0,2,28,0.65);padding:1px 4px;border-radius:2px;'\n  fpsv.appendChild(fpsvL)\n\n  const valueSpan = document.createElement('span')\n  valueSpan.className = 'tp-fpsv_v'\n  valueSpan.textContent = '--'\n  fpsvL.appendChild(valueSpan)\n\n  const unitSpan = document.createElement('span')\n  unitSpan.className = 'tp-fpsv_u'\n  unitSpan.textContent = 'FPS'\n  fpsvL.appendChild(unitSpan)\n\n  // ── Inject into Tweakpane via a real blade slot ──\n  // Use addBlade to get a proper slot in the blade rack (maintains ordering).\n  // Then replace the blade element's inner content with our custom graph.\n\n  const blade = parent.addBlade({ view: 'separator' })\n  const bladeEl = blade.element\n\n  // Replace separator content with our graph layout\n  bladeEl.innerHTML = ''\n  bladeEl.className = 'tp-cntv'\n  bladeEl.style.cssText = ''\n  bladeEl.appendChild(lblv)\n\n  // ── Mode cycling ──\n\n  function applyMode() {\n    lblvL.textContent = mode\n    unitSpan.textContent = MODE_UNITS[mode]\n  }\n  applyMode()\n\n  lblv.addEventListener('click', () => {\n    // Only cycle to modes the producer is actually streaming values for\n    // (gpuMs for gpu, heapUsedMB for mem). Client state is the source of\n    // truth — no separate enabled flags.\n    const state = client.state\n    do {\n      modeIndex = (modeIndex + 1) % MODES.length\n      mode = MODES[modeIndex]!\n    } while (\n      (mode === 'mem' && state.heapUsedMB === undefined) ||\n      (mode === 'gpu' && !state.gpuModeEnabled)\n    )\n    applyMode()\n  })\n\n  // ── Graph rendering ──\n\n  // Sync canvas backing to CSS box × DPR so 1 source pixel = 1 device\n  // pixel; avoids per-frame `getBoundingClientRect` which Safari pays\n  // dearly for, and keeps the polyline crisp on HiDPI.\n  let cachedW = 0\n  let cachedH = 0\n  const resizeObserver = new ResizeObserver(([entry]) => {\n    if (!entry) return\n    const r = entry.contentRect\n    const dpr = window.devicePixelRatio || 1\n    const w = Math.max(1, Math.round(r.width * dpr))\n    const h = Math.max(1, Math.round(r.height * dpr))\n    if (canvas.width !== w || canvas.height !== h) {\n      canvas.width = w\n      canvas.height = h\n    }\n    cachedW = w\n    cachedH = h\n  })\n  resizeObserver.observe(canvas)\n\n  const MODE_LABEL: Record<Mode, string> = { fps: 'fps', ms: 'ms', gpu: 'gpu', mem: 'mem' }\n  const MODE_VALUE_UNIT: Record<Mode, string> = { fps: 'FPS', ms: 'MS', gpu: 'MS', mem: 'MB' }\n  const MODE_RANGE_UNIT: Record<Mode, string> = { fps: 'FPS', ms: 'MS', gpu: 'GPU', mem: 'MB' }\n  const MODE_DECIMALS: Record<Mode, number> = { fps: 0, ms: 1, gpu: 1, mem: 0 }\n  const MODE_SCALE: Record<Mode, number> = { fps: 1, ms: 10, gpu: 10, mem: 1 }\n\n  // Rounded-integer-keyed cache for the `toFixed` result per mode.\n  // `toFixed` allocates a fresh string every call; with this cache,\n  // we only allocate when the rounded display value actually changes\n  // (e.g. fps stays at 60 for many rAF ticks while the lerped value\n  // wiggles in the high 59s — single string reused for the whole run).\n  const fmtCache: Record<Mode, { key: number; str: string }> = {\n    fps: { key: NaN, str: '' },\n    ms: { key: NaN, str: '' },\n    gpu: { key: NaN, str: '' },\n    mem: { key: NaN, str: '' },\n  }\n  function fmtCached(m: Mode, v: number): string {\n    const key = Math.round(v * MODE_SCALE[m])\n    const c = fmtCache[m]\n    if (c.key === key) return c.str\n    c.key = key\n    c.str = v.toFixed(MODE_DECIMALS[m])\n    return c.str\n  }\n\n  function seriesFor(m: Mode): DevtoolsSeries {\n    const s = client.state.series\n    switch (m) {\n      case 'fps': return s.fps\n      case 'ms': return s.cpuMs\n      case 'gpu': return s.gpuMs\n      case 'mem': return s.heapUsedMB\n    }\n  }\n\n  // ── Arrival snapshots (written in the listener, read in RAF) ──────────\n  // The listener only snapshots values and resets the interpolation\n  // clock. RAF does all rendering, so the display stays smooth between\n  // the 4 Hz batches.\n  const prevLabel: Record<Mode, number> = { fps: 0, ms: 0, gpu: 0, mem: 0 }\n  const currLabel: Record<Mode, number> = { fps: 0, ms: 0, gpu: 0, mem: 0 }\n  const hasLabel: Record<Mode, boolean> = { fps: false, ms: false, gpu: false, mem: false }\n  let batchCount = 0\n  let lastBatchAt = performance.now()\n  let prevRingWrite = 0\n\n  const snap = (m: Mode, v: number | undefined): void => {\n    if (v === undefined) return\n    prevLabel[m] = hasLabel[m] ? currLabel[m] : v\n    currLabel[m] = v\n    hasLabel[m] = true\n  }\n\n  const unsubscribe = client.addListener((s) => {\n    if (s.heapLimitMB !== undefined) graphMax.mem = s.heapLimitMB\n    snap('fps', s.fps)\n    snap('ms', s.cpuMs)\n    snap('gpu', s.gpuMs)\n    snap('mem', s.heapUsedMB)\n    // How many new samples came in this batch? All series write in\n    // lockstep, so we can just watch `fps`.\n    const fps = s.series.fps\n    const size = fps.data.length\n    const delta = (fps.write - prevRingWrite + size) % size\n    if (delta > 0) {\n      batchCount = delta\n      prevRingWrite = fps.write\n      lastBatchAt = performance.now()\n    }\n  })\n\n  // ── Render ────────────────────────────────────────────────────────────\n  // Canvas path-based draw — no DOM attribute mutation per frame, no\n  // string allocations beyond the unavoidable `toFixed` for the text\n  // label (and even those are deduped: textContent is only re-assigned\n  // when the rendered string actually changes).\n\n  let rafId = 0\n  let disposed = false\n\n  function setText(node: HTMLElement, next: string, cache: { v: string }): void {\n    if (cache.v === next) return\n    node.textContent = next\n    cache.v = next\n  }\n  // Boxed cache holders keep `setText` allocation-free past creation.\n  const labelCache = { v: '' }\n  const valueCache = { v: '' }\n  const unitCache = { v: '' }\n  const titleCache = { v: '' }\n\n  function update(): void {\n    if (disposed) return\n    if (cachedW === 0 || cachedH === 0 || gfx === null) return\n\n    const now = performance.now()\n    const t = Math.min(1, Math.max(0, (now - lastBatchAt) / STATS_BATCH_MS))\n\n    // Slide the display window through the ring so newest samples fade\n    // in at 60 Hz between the producer's 4 Hz batches.\n    //\n    // **Don't blend sample VALUES across the slide.** Earlier the\n    // sample at each pixel was `a*(1-frac) + b*frac` for a\n    // continuously-changing `frac` — that means a single peak at\n    // ring slot K shows different *heights* at different sub-batch\n    // times (full height only when frac=0; lower whenever it's\n    // blended with a neighbor). Visible as peaks \"changing shape as\n    // they scroll.\" Sample each ring slot at its INTEGER index — the\n    // height never moves — and shift the entire polyline's X by the\n    // fractional sub-sample offset. The line slides smoothly across\n    // the canvas; each sample's height is the same in every frame\n    // that contains it.\n    const ring = seriesFor(mode)\n    const size = ring.data.length\n    const max = graphMax[mode] || 1\n    const phase = batchCount * (1 - t)            // continuous 0..batchCount\n    const intPhase = Math.floor(phase)             // integer slide steps remaining\n    const fracPhase = phase - intPhase             // 0..1 sub-step (sub-pixel scroll)\n\n    const w = cachedW\n    const h = cachedH\n    gfx.clearRect(0, 0, w, h)\n\n    const color = MODE_COLORS[mode]\n    const samplePixelW = w / (BUFFER_SIZE - 1)\n\n    // Draw BUFFER_SIZE + 1 samples — one extra at i=-1 so the leftmost\n    // visible pixel always has a polyline endpoint, no matter where\n    // fracPhase sits between integer steps. Without this extra, the\n    // line would have a visible gap at the canvas's left edge during\n    // sub-pixel slide.\n    //\n    // Two passes (fill polygon, then crisp stroke) over the same\n    // points; computing each point in a tight inner loop keeps allocs\n    // at zero. The values cache `mn`/`mx` are session-min/max trackers,\n    // populated from the ring (not the rendered polyline) — they\n    // bypass the integer-index loop and read raw ring values.\n    let mn = Infinity\n    let mx = 0\n    // Walk the same range we render to compute mn/mx — no separate\n    // pass. Adds an `if` per sample but skips a second loop.\n    const baseRingIdx = ring.write - intPhase - BUFFER_SIZE + size * 2\n\n    gfx.beginPath()\n    for (let i = -1; i < BUFFER_SIZE; i++) {\n      const ringIdx = (baseRingIdx + i) % size\n      const v = ring.data[ringIdx]!\n      if (i >= 0) {\n        if (v < mn) mn = v\n        if (v > mx) mx = v\n      }\n      const x = (i + fracPhase) * samplePixelW\n      // Clamp y to the canvas top so over-budget samples (v > graphMax)\n      // saturate at the top edge instead of drawing above the canvas.\n      const yRaw = h - (v / max) * h * 0.85 - h * 0.05\n      const y = yRaw < h * 0.05 ? h * 0.05 : yRaw\n      if (i === -1) gfx.moveTo(x, y)\n      else gfx.lineTo(x, y)\n    }\n\n    // Translucent fill under the line. Close to bottom-right then\n    // bottom-left of the canvas — the polyline's leftmost x may be\n    // slightly negative during sub-pixel slide, but the canvas crops\n    // off-edge pixels for free, so the polygon closes cleanly.\n    gfx.lineTo(w, h)\n    gfx.lineTo(0, h)\n    gfx.closePath()\n    gfx.fillStyle = color\n    gfx.globalAlpha = 0.33\n    gfx.fill()\n    gfx.globalAlpha = 1\n\n    // Re-stroke the line over the fill so the top edge is sharp.\n    gfx.beginPath()\n    for (let i = -1; i < BUFFER_SIZE; i++) {\n      const ringIdx = (baseRingIdx + i) % size\n      const v = ring.data[ringIdx]!\n      const x = (i + fracPhase) * samplePixelW\n      const yRaw = h - (v / max) * h * 0.85 - h * 0.05\n      const y = yRaw < h * 0.05 ? h * 0.05 : yRaw\n      if (i === -1) gfx.moveTo(x, y)\n      else gfx.lineTo(x, y)\n    }\n    gfx.strokeStyle = color\n    gfx.lineWidth = Math.max(1, (window.devicePixelRatio || 1))\n    gfx.stroke()\n\n    if (hasLabel[mode]) {\n      sessionMin[mode] = Math.min(sessionMin[mode], mn)\n      sessionMax[mode] = Math.max(sessionMax[mode], mx)\n    }\n\n    // Text — lerp the label's number toward the latest batch mean.\n    // `toFixed` allocates a new string each call (~one per rAF) but\n    // we dedupe assignment to avoid setting `textContent` redundantly,\n    // which would trigger DOM mutation work even when the string is\n    // identical.\n    const has = hasLabel[mode]\n    const lerped = prevLabel[mode] + (currLabel[mode] - prevLabel[mode]) * t\n    const sMn = sessionMin[mode]\n    const sMx = sessionMax[mode]\n    setText(lblvL, MODE_LABEL[mode], labelCache)\n    setText(valueSpan, has ? fmtCached(mode, lerped) : '--', valueCache)\n    setText(unitSpan, MODE_VALUE_UNIT[mode], unitCache)\n    const nextTitle = sMn !== Infinity ? `${MODE_RANGE_UNIT[mode]} range: ${Math.round(sMn)}–${Math.round(sMx)}` : ''\n    if (titleCache.v !== nextTitle) {\n      lblvL.title = nextTitle\n      titleCache.v = nextTitle\n    }\n  }\n\n  if (driver === 'raf') {\n    const autoFrame = (): void => {\n      if (disposed) return\n      rafId = requestAnimationFrame(autoFrame)\n      update()\n    }\n    rafId = requestAnimationFrame(autoFrame)\n  }\n\n  return {\n    element: bladeEl,\n    // In `'raf'` mode the internal loop already runs, so public `update()`\n    // is a no-op — we don't want to paint twice per frame when the host\n    // also (redundantly) drives it. In `'manual'` mode this is the only\n    // way the graph gets painted.\n    update: driver === 'manual' ? update : () => {},\n    dispose() {\n      disposed = true\n      if (rafId !== 0) cancelAnimationFrame(rafId)\n      unsubscribe()\n      resizeObserver.disconnect()\n      blade.dispose()\n    },\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/stats-graph.d.cts

@@ -0,0 +1,40 @@
+import { Pane, FolderApi } from 'tweakpane';
+import { DevtoolsClient } from './devtools-client.cjs';
+import 'three-flatland/debug-protocol';
+
+/**
+ * Cycling stats graph — click to cycle FPS / MS / MEM (like stats.js).
+ *
+ * Replicates the exact DOM structure of Tweakpane's built-in fpsgraph blade.
+ * Uses SVG polyline like GraphLogView (tp-grlv). Click anywhere to cycle modes.
+ * Only the graph line is colorized per mode; text uses default Tweakpane colors.
+ */
+
+interface StatsGraphHandle {
+    /** The root element */
+    readonly element: HTMLElement;
+    /**
+     * Render a frame. Required when constructed with `driver: 'manual'`;
+     * no-op for the `'raf'` driver (the internal rAF is doing it).
+     */
+    update(): void;
+    /** Stop and remove. */
+    dispose(): void;
+}
+interface AddStatsGraphOptions {
+    rows?: number;
+    /**
+     * `'raf'` (default) — the graph runs its own `requestAnimationFrame`
+     * loop. `'manual'` — no rAF; caller drives via `handle.update()` from
+     * their own frame tick (e.g. `renderer.setAnimationLoop`, R3F
+     * `useFrame`).
+     */
+    driver?: 'raf' | 'manual';
+}
+/**
+ * Add a cycling stats graph to a Tweakpane parent.
+ * Matches the visual design of the built-in fpsgraph blade.
+ */
+declare function addStatsGraph(parent: Pane | FolderApi, client: DevtoolsClient, options?: AddStatsGraphOptions): StatsGraphHandle;
+
+export { type AddStatsGraphOptions, type StatsGraphHandle, addStatsGraph };

package/dist/stats-graph.d.ts

@@ -0,0 +1,40 @@
+import { Pane, FolderApi } from 'tweakpane';
+import { DevtoolsClient } from './devtools-client.js';
+import 'three-flatland/debug-protocol';
+
+/**
+ * Cycling stats graph — click to cycle FPS / MS / MEM (like stats.js).
+ *
+ * Replicates the exact DOM structure of Tweakpane's built-in fpsgraph blade.
+ * Uses SVG polyline like GraphLogView (tp-grlv). Click anywhere to cycle modes.
+ * Only the graph line is colorized per mode; text uses default Tweakpane colors.
+ */
+
+interface StatsGraphHandle {
+    /** The root element */
+    readonly element: HTMLElement;
+    /**
+     * Render a frame. Required when constructed with `driver: 'manual'`;
+     * no-op for the `'raf'` driver (the internal rAF is doing it).
+     */
+    update(): void;
+    /** Stop and remove. */
+    dispose(): void;
+}
+interface AddStatsGraphOptions {
+    rows?: number;
+    /**
+     * `'raf'` (default) — the graph runs its own `requestAnimationFrame`
+     * loop. `'manual'` — no rAF; caller drives via `handle.update()` from
+     * their own frame tick (e.g. `renderer.setAnimationLoop`, R3F
+     * `useFrame`).
+     */
+    driver?: 'raf' | 'manual';
+}
+/**
+ * Add a cycling stats graph to a Tweakpane parent.
+ * Matches the visual design of the built-in fpsgraph blade.
+ */
+declare function addStatsGraph(parent: Pane | FolderApi, client: DevtoolsClient, options?: AddStatsGraphOptions): StatsGraphHandle;
+
+export { type AddStatsGraphOptions, type StatsGraphHandle, addStatsGraph };