@three-flatland/devtools 0.1.0-alpha.3 → 1.0.0-alpha.6

package/dist/dashboard/panels/scrubber.tsx

@@ -0,0 +1,100 @@
+/** @jsxImportSource preact */
+/**
+ * Time-travel scrubber (#29 Phase A) — sits under the stats strip:
+ *
+ *   [◀] ──●── [▶]  [N/M]  [● LIVE]
+ *
+ * Entry points: drag the slider, step ◀/▶, or click a protocol-log
+ * row. Return to live: the LIVE button, double-click the slider, or
+ * Esc. The scrubbable range is the frames covered by the stats series
+ * ring (~17s at 60 fps); deeper history is the Phase C flight recorder.
+ */
+import { useEffect, useLayoutEffect } from 'preact/hooks'
+import { useDevtoolsState, useFrameTick } from '../hooks.js'
+import { addFrameCursorListener, getFrameCursor, goLive, setCursorProvider, setFrameCursor } from '../frame-cursor.js'
+import { useState } from 'preact/hooks'
+
+/** Oldest/newest engine frame currently held by the stats ring. */
+function frameRange(state: ReturnType<typeof useDevtoolsState>): {
+  min: number
+  max: number
+} | null {
+  const ring = state.series.frames
+  if (ring.length === 0) return null
+  const size = ring.data.length
+  const newest = ring.data[(ring.write - 1 + size) % size]!
+  const oldest = ring.data[(ring.write - ring.length + size) % size]!
+  return { min: oldest, max: newest }
+}
+
+export function Scrubber() {
+  const state = useDevtoolsState()
+  useFrameTick()
+  const [, setTick] = useState(0)
+
+  useEffect(() => {
+    return addFrameCursorListener(() => setTick((n) => (n + 1) & 0xffff))
+  }, [])
+
+  // Per-provider cursor memory follows the producer switcher. Layout
+  // effect, not plain effect: the sync must land before paint so panels
+  // reading getFrameCursor() during render never show one frame with the
+  // previous provider's cursor. Still post-render, so the listener →
+  // setState it triggers isn't mid-render.
+  useLayoutEffect(() => {
+    setCursorProvider(state.selectedProviderId)
+  }, [state.selectedProviderId])
+
+  // Esc returns to live (no modal handling needed here — modals stop
+  // propagation of their own keys).
+  useEffect(() => {
+    const onKey = (ev: KeyboardEvent): void => {
+      // A handler that consumed Esc (detail pane close, modal) wins.
+      if (ev.defaultPrevented) return
+      if (ev.key === 'Escape' && getFrameCursor() !== null) goLive()
+    }
+    window.addEventListener('keydown', onKey)
+    return () => window.removeEventListener('keydown', onKey)
+  }, [])
+
+  const cursor = getFrameCursor()
+  const range = frameRange(state)
+  if (range === null) return null
+
+  const parked = cursor !== null
+  const shown = parked ? Math.min(Math.max(cursor, range.min), range.max) : range.max
+
+  const step = (delta: number): void => {
+    const base = parked ? shown : range.max
+    const next = Math.min(range.max, Math.max(range.min, base + delta))
+    setFrameCursor(next)
+  }
+
+  return (
+    <div class={`frame-scrubber${parked ? ' parked' : ''}`}>
+      <button class="scrub-step" title="Back one frame" onClick={() => step(-1)}>
+        ◀
+      </button>
+      <input
+        class="scrub-slider"
+        type="range"
+        min={range.min}
+        max={range.max}
+        value={shown}
+        onInput={(ev) => setFrameCursor(Number((ev.target as HTMLInputElement).value))}
+        onDblClick={() => goLive()}
+      />
+      <button class="scrub-step" title="Forward one frame" onClick={() => step(1)}>
+        ▶
+      </button>
+      <span class="scrub-frame">{parked ? `${shown}/${range.max}` : `${range.max}`}</span>
+      <button
+        class={`scrub-live${parked ? '' : ' active'}`}
+        title={parked ? 'Return to live' : 'Live'}
+        onClick={() => goLive()}
+      >
+        ● LIVE
+      </button>
+    </div>
+  )
+}

package/dist/dashboard/panels/stats.tsx

@@ -13,8 +13,9 @@
  * jittering zero.
  */
 import { useEffect, useRef, useState } from 'preact/hooks'
-import type { DevtoolsSeries, DevtoolsState } from '../../devtools-client.js'
+import type { DevtoolsSeries, DevtoolsState, DevtoolsFrameSeries } from '../../devtools-client.js'
 import { useDevtoolsState } from '../hooks.js'
+import { getFrameCursor } from '../frame-cursor.js'
 
 interface StatDef {
   label: string
@@ -35,15 +36,15 @@ function fmtMB(v: number | undefined): string {
 }
 
 const STATS: StatDef[] = [
-  { label: 'fps',   pick: (s) => s.fps,        series: (s) => s.series.fps,        format: fmt0,  color: '#47cca9' },
-  { label: 'cpu',   pick: (s) => s.cpuMs,      series: (s) => s.series.cpuMs,      format: fmtMs, color: '#47cc6a' },
-  { label: 'gpu',   pick: (s) => s.gpuMs,      series: (s) => s.series.gpuMs,      format: fmtMs, color: '#ffa347' },
-  { label: 'draws', pick: (s) => s.drawCalls,  series: (s) => s.series.drawCalls,  format: fmt0,  color: '#5eb0ff' },
-  { label: 'tris',  pick: (s) => s.triangles,  series: (s) => s.series.triangles,  format: fmt0,  color: '#c792ea' },
-  { label: 'prims', pick: (s) => s.primitives, series: (s) => s.series.primitives, format: fmt0,  color: '#ff8fa3' },
-  { label: 'geos',  pick: (s) => s.geometries, series: (s) => s.series.geometries, format: fmt0,  color: '#f78c6c' },
-  { label: 'tex',   pick: (s) => s.textures,   series: (s) => s.series.textures,   format: fmt0,  color: '#ffc371' },
-  { label: 'heap',  pick: (s) => s.heapUsedMB, series: (s) => s.series.heapUsedMB, format: fmtMB, color: '#d94c87' },
+  { label: 'fps', pick: (s) => s.fps, series: (s) => s.series.fps, format: fmt0, color: '#47cca9' },
+  { label: 'cpu', pick: (s) => s.cpuMs, series: (s) => s.series.cpuMs, format: fmtMs, color: '#47cc6a' },
+  { label: 'gpu', pick: (s) => s.gpuMs, series: (s) => s.series.gpuMs, format: fmtMs, color: '#ffa347' },
+  { label: 'draws', pick: (s) => s.drawCalls, series: (s) => s.series.drawCalls, format: fmt0, color: '#5eb0ff' },
+  { label: 'tris', pick: (s) => s.triangles, series: (s) => s.series.triangles, format: fmt0, color: '#c792ea' },
+  { label: 'prims', pick: (s) => s.primitives, series: (s) => s.series.primitives, format: fmt0, color: '#ff8fa3' },
+  { label: 'geos', pick: (s) => s.geometries, series: (s) => s.series.geometries, format: fmt0, color: '#f78c6c' },
+  { label: 'tex', pick: (s) => s.textures, series: (s) => s.series.textures, format: fmt0, color: '#ffc371' },
+  { label: 'heap', pick: (s) => s.heapUsedMB, series: (s) => s.series.heapUsedMB, format: fmtMB, color: '#d94c87' },
 ]
 
 export function StatsStrip() {
@@ -75,13 +76,7 @@ export function StatsStrip() {
           />
         ))}
       </div>
-      {expandedDef !== null && (
-        <StatDetail
-          def={expandedDef}
-          state={s}
-          onClose={() => setExpandedKey(null)}
-        />
-      )}
+      {expandedDef !== null && <StatDetail def={expandedDef} state={s} onClose={() => setExpandedKey(null)} />}
     </section>
   )
 }
@@ -104,8 +99,12 @@ function StatCard({
   // instantly to match new peaks, decays slowly afterward (see
   // `drawSeries`'s RANGE_DECAY).
   const rangeRef = useRef<{ min: number; max: number } | null>(null)
-  const value = def.pick(state)
   const series = def.series(state)
+  // Parked cursor: show the ring sample whose engine frame is the
+  // closest ≤ the cursor instead of the live smoothed value.
+  const cursor = getFrameCursor()
+  const parkedValue = cursor !== null ? seriesValueAtFrame(series, state.series.frames, cursor) : undefined
+  const value = cursor !== null ? parkedValue : def.pick(state)
 
   useEffect(() => {
     const canvas = canvasRef.current
@@ -133,16 +132,33 @@ function StatCard({
     >
       <canvas class="stat-canvas" ref={canvasRef} />
       <span class="stat-label">{def.label}</span>
-      <span class="stat-value">{def.format(value)}</span>
+      <span class={`stat-value${cursor !== null ? ' stat-parked' : ''}`}>{def.format(value)}</span>
     </button>
   )
 }
 
-function StatDetail({ def, state, onClose }: {
-  def: StatDef
-  state: DevtoolsState
-  onClose: () => void
-}) {
+/**
+ * Ring sample for the closest engine frame ≤ `frame` (time-travel
+ * cursor). Rings ingest in lockstep, so an index into the frames ring
+ * is valid for every series ring.
+ */
+function seriesValueAtFrame(series: DevtoolsSeries, frames: DevtoolsFrameSeries, frame: number): number | undefined {
+  const len = Math.min(series.length, frames.length)
+  if (len === 0) return undefined
+  const size = frames.data.length
+  // Walk newest → oldest; rings are small (1024) and this only runs
+  // while parked.
+  for (let i = 0; i < len; i++) {
+    const idx = (frames.write - 1 - i + size) % size
+    if (frames.data[idx]! <= frame) {
+      return series.data[(series.write - 1 - i + size) % size]
+    }
+  }
+  // Cursor is older than everything we hold — show the oldest sample.
+  return series.data[(series.write - len + size) % size]
+}
+
+function StatDetail({ def, state, onClose }: { def: StatDef; state: DevtoolsState; onClose: () => void }) {
   const series = def.series(state)
   const stats = computeStats(series)
   const histoRef = useRef<HTMLCanvasElement | null>(null)
@@ -166,7 +182,9 @@ function StatDetail({ def, state, onClose }: {
       <div class="stat-detail-header">
         <span class="stat-detail-label">{def.label}</span>
         <span class="stat-detail-samples">{stats.count} samples</span>
-        <button type="button" class="stat-detail-close" onClick={onClose} aria-label="Close">×</button>
+        <button type="button" class="stat-detail-close" onClick={onClose} aria-label="Close">
+          ×
+        </button>
       </div>
       <div class="stat-detail-metrics">
         <Metric label="min" value={def.format(stats.min)} />
@@ -202,7 +220,8 @@ interface SeriesStats {
 
 function computeStats(series: DevtoolsSeries): SeriesStats {
   const len = series.length
-  if (len === 0) return { count: 0, min: undefined, max: undefined, mean: undefined, p50: undefined, p95: undefined, p99: undefined }
+  if (len === 0)
+    return { count: 0, min: undefined, max: undefined, mean: undefined, p50: undefined, p95: undefined, p99: undefined }
   const size = series.data.length
   const start = (series.write - len + size) % size
   // Copy into a dense array for sorting — len is typically ~256 so
@@ -236,7 +255,7 @@ function drawHistogram(
   w: number,
   h: number,
   series: DevtoolsSeries,
-  color: string,
+  color: string
 ): void {
   ctx.clearRect(0, 0, w, h)
   const len = series.length
@@ -333,7 +352,7 @@ function drawSeries(
   h: number,
   series: DevtoolsSeries,
   color: string,
-  rangeRef: { current: { min: number; max: number } | null },
+  rangeRef: { current: { min: number; max: number } | null }
 ): void {
   ctx.clearRect(0, 0, w, h)
   const len = series.length
@@ -349,12 +368,21 @@ function drawSeries(
   // compares per sample, no allocation). Top1 is the max; topK is
   // the K-th-largest = our trimmed observedMax. When fewer than K
   // samples exist (window still warming up), fall back to top1.
-  let top1 = -Infinity, top2 = -Infinity, top3 = -Infinity
+  let top1 = -Infinity,
+    top2 = -Infinity,
+    top3 = -Infinity
   for (let i = 0; i < len; i++) {
     const v = series.data[(start + i) % size]!
-    if (v > top1) { top3 = top2; top2 = top1; top1 = v }
-    else if (v > top2) { top3 = top2; top2 = v }
-    else if (v > top3) { top3 = v }
+    if (v > top1) {
+      top3 = top2
+      top2 = top1
+      top1 = v
+    } else if (v > top2) {
+      top3 = top2
+      top2 = v
+    } else if (v > top3) {
+      top3 = v
+    }
   }
   const observedMax = len < AXIS_TRIM_K ? top1 : top3
   if (!Number.isFinite(observedMax) || observedMax < 0) return

package/dist/dashboard/protocol-store.ts

@@ -102,12 +102,18 @@ export class ProtocolStore {
 
   addListener(cb: Listener): () => void {
     this._listeners.add(cb)
-    return () => { this._listeners.delete(cb) }
+    return () => {
+      this._listeners.delete(cb)
+    }
   }
 
   private _fire(): void {
     for (const cb of this._listeners) {
-      try { cb() } catch { /* ignore */ }
+      try {
+        cb()
+      } catch {
+        /* ignore */
+      }
     }
   }
 
@@ -149,7 +155,7 @@ export class ProtocolStore {
     if (this._flushTimer === null) {
       this._flushTimer = (globalThis.setTimeout as unknown as (cb: () => void, ms: number) => number)(
         () => this._flush(),
-        WRITE_FLUSH_MS,
+        WRITE_FLUSH_MS
       )
     }
     this._evictIfNeeded(providerId)
@@ -170,7 +176,9 @@ export class ProtocolStore {
       try {
         const tx = this._db.transaction(STORE, 'readwrite')
         tx.objectStore(STORE).clear()
-      } catch { /* db closing */ }
+      } catch {
+        /* db closing */
+      }
     }
     this._fire()
   }
@@ -189,7 +197,10 @@ export class ProtocolStore {
     // Quick hit check.
     let allHit = true
     for (let id = startId; id <= endId; id++) {
-      if (!this._cache.has(cacheKey(providerId, id))) { allHit = false; break }
+      if (!this._cache.has(cacheKey(providerId, id))) {
+        allHit = false
+        break
+      }
     }
     if (allHit) return
     const promise = this._readRange(providerId, startId, endId)
@@ -214,7 +225,7 @@ export class ProtocolStore {
   async queryFiltered(
     providerId: string,
     predicate: (entry: LogEntry) => boolean,
-    signal?: { aborted: boolean },
+    signal?: { aborted: boolean }
   ): Promise<number[]> {
     const db = await this._dbReady
     const out: number[] = []
@@ -224,9 +235,15 @@ export class ProtocolStore {
       const index = store.index(INDEX)
       const req = index.openCursor(IDBKeyRange.only(providerId))
       req.onsuccess = () => {
-        if (signal?.aborted === true) { resolve(); return }
+        if (signal?.aborted === true) {
+          resolve()
+          return
+        }
         const cursor = req.result
-        if (cursor === null) { resolve(); return }
+        if (cursor === null) {
+          resolve()
+          return
+        }
         const entry = cursor.value as LogEntry
         if (predicate(entry)) {
           out.push(entry.id)

package/dist/dashboard/vendor/hooks.module.d.ts

@@ -0,0 +1,146 @@
+import { ErrorInfo, PreactContext, Ref as PreactRef } from './preact.module';
+
+type Inputs = ReadonlyArray<unknown>;
+
+export type Dispatch<A> = (value: A) => void;
+export type StateUpdater<S> = S | ((prevState: S) => S);
+
+/**
+ * Returns a stateful value, and a function to update it.
+ * @param initialState The initial value (or a function that returns the initial value)
+ */
+export function useState<S>(
+	initialState: S | (() => S)
+): [S, Dispatch<StateUpdater<S>>];
+
+export function useState<S = undefined>(): [
+	S | undefined,
+	Dispatch<StateUpdater<S | undefined>>
+];
+
+export type Reducer<S, A> = (prevState: S, action: A) => S;
+
+/**
+ * An alternative to `useState`.
+ *
+ * `useReducer` is usually preferable to `useState` when you have complex state logic that involves
+ * multiple sub-values. It also lets you optimize performance for components that trigger deep
+ * updates because you can pass `dispatch` down instead of callbacks.
+ * @param reducer Given the current state and an action, returns the new state
+ * @param initialState The initial value to store as state
+ */
+export function useReducer<S, A>(
+	reducer: Reducer<S, A>,
+	initialState: S
+): [S, Dispatch<A>];
+
+/**
+ * An alternative to `useState`.
+ *
+ * `useReducer` is usually preferable to `useState` when you have complex state logic that involves
+ * multiple sub-values. It also lets you optimize performance for components that trigger deep
+ * updates because you can pass `dispatch` down instead of callbacks.
+ * @param reducer Given the current state and an action, returns the new state
+ * @param initialArg The initial argument to pass to the `init` function
+ * @param init A function that, given the `initialArg`, returns the initial value to store as state
+ */
+export function useReducer<S, A, I>(
+	reducer: Reducer<S, A>,
+	initialArg: I,
+	init: (arg: I) => S
+): [S, Dispatch<A>];
+
+/** @deprecated Use the `Ref` type instead. */
+type PropRef<T> = MutableRef<T>;
+interface Ref<T> {
+	readonly current: T | null;
+}
+
+interface MutableRef<T> {
+	current: T;
+}
+
+/**
+ * `useRef` returns a mutable ref object whose `.current` property is initialized to the passed argument
+ * (`initialValue`). The returned object will persist for the full lifetime of the component.
+ *
+ * Note that `useRef()` is useful for more than the `ref` attribute. It’s handy for keeping any mutable
+ * value around similar to how you’d use instance fields in classes.
+ *
+ * @param initialValue the initial value to store in the ref object
+ */
+export function useRef<T>(initialValue: T): MutableRef<T>;
+export function useRef<T>(initialValue: T | null): Ref<T>;
+export function useRef<T = undefined>(): MutableRef<T | undefined>;
+
+type EffectCallback = () => void | (() => void);
+/**
+ * Accepts a function that contains imperative, possibly effectful code.
+ * The effects run after browser paint, without blocking it.
+ *
+ * @param effect Imperative function that can return a cleanup function
+ * @param inputs If present, effect will only activate if the values in the list change (using ===).
+ */
+export function useEffect(effect: EffectCallback, inputs?: Inputs): void;
+
+type CreateHandle = () => object;
+
+/**
+ * @param ref The ref that will be mutated
+ * @param create The function that will be executed to get the value that will be attached to
+ * ref.current
+ * @param inputs If present, effect will only activate if the values in the list change (using ===).
+ */
+export function useImperativeHandle<T, R extends T>(
+	ref: PreactRef<T>,
+	create: () => R,
+	inputs?: Inputs
+): void;
+
+/**
+ * Accepts a function that contains imperative, possibly effectful code.
+ * Use this to read layout from the DOM and synchronously re-render.
+ * Updates scheduled inside `useLayoutEffect` will be flushed synchronously, after all DOM mutations but before the browser has a chance to paint.
+ * Prefer the standard `useEffect` hook when possible to avoid blocking visual updates.
+ *
+ * @param effect Imperative function that can return a cleanup function
+ * @param inputs If present, effect will only activate if the values in the list change (using ===).
+ */
+export function useLayoutEffect(effect: EffectCallback, inputs?: Inputs): void;
+
+/**
+ * Returns a memoized version of the callback that only changes if one of the `inputs`
+ * has changed (using ===).
+ */
+export function useCallback<T extends Function>(callback: T, inputs: Inputs): T;
+
+/**
+ * Pass a factory function and an array of inputs.
+ * useMemo will only recompute the memoized value when one of the inputs has changed.
+ * This optimization helps to avoid expensive calculations on every render.
+ * If no array is provided, a new value will be computed whenever a new function instance is passed as the first argument.
+ */
+// for `inputs`, allow undefined, but don't make it optional as that is very likely a mistake
+export function useMemo<T>(factory: () => T, inputs: Inputs | undefined): T;
+
+/**
+ * Returns the current context value, as given by the nearest context provider for the given context.
+ * When the provider updates, this Hook will trigger a rerender with the latest context value.
+ *
+ * @param context The context you want to use
+ */
+export function useContext<T>(context: PreactContext<T>): T;
+
+/**
+ * Customize the displayed value in the devtools panel.
+ *
+ * @param value Custom hook name or object that is passed to formatter
+ * @param formatter Formatter to modify value before sending it to the devtools
+ */
+export function useDebugValue<T>(value: T, formatter?: (value: T) => any): void;
+
+export function useErrorBoundary(
+	callback?: (error: any, errorInfo: ErrorInfo) => Promise<void> | void
+): [any, () => void];
+
+export function useId(): string;

package/dist/dashboard/vendor/jsx-runtime.d.ts

@@ -0,0 +1,55 @@
+/**
+ * JSX-runtime types for the vendored Preact copy. Mirrors
+ * `preact/jsx-runtime/src/index.d.ts` verbatim (structure-wise) but imports
+ * from the sibling vendored file instead of the npm-published `preact`.
+ */
+import {
+  Attributes,
+  ComponentChild,
+  ComponentChildren,
+  ComponentType,
+  VNode,
+} from './preact.module'
+import { JSXInternal } from './jsx'
+
+export { Fragment } from './preact.module'
+export { JSXInternal as JSX }
+
+export function jsx(
+  type: string,
+  props: JSXInternal.HTMLAttributes &
+    JSXInternal.SVGAttributes &
+    Record<string, unknown> & { children?: ComponentChild },
+  key?: string,
+): VNode<unknown>
+export function jsx<P>(
+  type: ComponentType<P>,
+  props: Attributes & P & { children?: ComponentChild },
+  key?: string,
+): VNode<unknown>
+
+export function jsxs(
+  type: string,
+  props: JSXInternal.HTMLAttributes &
+    JSXInternal.SVGAttributes &
+    Record<string, unknown> & { children?: ComponentChild[] },
+  key?: string,
+): VNode<unknown>
+export function jsxs<P>(
+  type: ComponentType<P>,
+  props: Attributes & P & { children?: ComponentChild[] },
+  key?: string,
+): VNode<unknown>
+
+export function jsxDEV(
+  type: string,
+  props: JSXInternal.HTMLAttributes &
+    JSXInternal.SVGAttributes &
+    Record<string, unknown> & { children?: ComponentChildren },
+  key?: string,
+): VNode<unknown>
+export function jsxDEV<P>(
+  type: ComponentType<P>,
+  props: Attributes & P & { children?: ComponentChildren },
+  key?: string,
+): VNode<unknown>