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

package/dist/dashboard/frame-cursor.ts

@@ -0,0 +1,81 @@
+/**
+ * Time-travel frame cursor (#29 Phase A — passive frame-link).
+ *
+ * `null` = live (panels tail as usual). A number parks every panel at
+ * that engine frame: stats read the ring sample at frame ≤ cursor, the
+ * protocol log scrolls to the nearest row and stops tailing, buffers
+ * freeze (historical playback is the Phase C flight recorder).
+ *
+ * Cursors are remembered per provider — switching producers restores
+ * that producer's parked position (or live).
+ */
+
+type Listener = () => void
+
+const cursorByProvider = new Map<string, number>()
+let activeProviderId: string | null = null
+let liveCursor: number | null = null
+const listeners = new Set<Listener>()
+
+function fire(): void {
+  for (const cb of listeners) {
+    try {
+      cb()
+    } catch {
+      /* listener errors shouldn't break the cursor */
+    }
+  }
+}
+
+export function addFrameCursorListener(cb: Listener): () => void {
+  listeners.add(cb)
+  return () => {
+    listeners.delete(cb)
+  }
+}
+
+/** The parked frame, or null when live. */
+export function getFrameCursor(): number | null {
+  return liveCursor
+}
+
+/**
+ * Park at a frame (clamped by callers to their known range). Passing
+ * `null` deletes the active provider's parked cursor entirely, not
+ * just sets it to "live" — the next `setCursorProvider` switch away
+ * and back finds no stored entry and comes up live rather than
+ * re-parking at the old frame.
+ */
+export function setFrameCursor(frame: number | null): void {
+  if (liveCursor === frame) return
+  liveCursor = frame
+  if (activeProviderId !== null) {
+    if (frame === null) cursorByProvider.delete(activeProviderId)
+    else cursorByProvider.set(activeProviderId, frame)
+  }
+  fire()
+}
+
+/**
+ * Return to live. Deletes the active provider's parked cursor (see
+ * `setFrameCursor`) — intentional: a manual go-live is a decision to
+ * stop watching a specific frame, so switching providers and back
+ * should not silently re-park.
+ */
+export function goLive(): void {
+  setFrameCursor(null)
+}
+
+/**
+ * Provider switch: remember the outgoing provider's cursor, restore
+ * the incoming one's (per-provider cursor semantics).
+ */
+export function setCursorProvider(providerId: string | null): void {
+  if (activeProviderId === providerId) return
+  activeProviderId = providerId
+  const restored = providerId !== null ? (cursorByProvider.get(providerId) ?? null) : null
+  if (liveCursor !== restored) {
+    liveCursor = restored
+    fire()
+  }
+}

package/dist/dashboard/hooks.ts

@@ -10,6 +10,7 @@ import { useEffect, useState } from 'preact/hooks'
 import type { DevtoolsState } from '../devtools-client.js'
 import { getClient } from './client.js'
 import { getProtocolStore } from './protocol-store.js'
+import { addFrameCursorListener } from './frame-cursor.js'
 
 type Subscriber = () => void
 
@@ -25,14 +26,20 @@ function scheduleFrame(): void {
   requestAnimationFrame(() => {
     _frameScheduled = false
     for (const cb of _frameListeners) {
-      try { cb() } catch { /* listener errors shouldn't break the bus */ }
+      try {
+        cb()
+      } catch {
+        /* listener errors shouldn't break the bus */
+      }
     }
   })
 }
 
 function subscribeFrame(cb: Subscriber): () => void {
   _frameListeners.add(cb)
-  return () => { _frameListeners.delete(cb) }
+  return () => {
+    _frameListeners.delete(cb)
+  }
 }
 
 // Wire the underlying data sources to the shared rAF once. Any event on
@@ -43,6 +50,7 @@ function ensureSourcesWired(): void {
   _sourcesWired = true
   getClient().addListener(scheduleFrame)
   getProtocolStore().addListener(scheduleFrame)
+  addFrameCursorListener(scheduleFrame)
 }
 
 /**

package/dist/dashboard/index.html

@@ -1140,6 +1140,67 @@
       .registry-panel { flex: initial; height: 300px; }
       .protocol-panel { flex: initial; height: 420px; }
     }
+
+    /* ── Time-travel scrubber (#29 Phase A) ─────────────────────────── */
+    .frame-scrubber {
+      display: flex;
+      align-items: center;
+      gap: 8px;
+      padding: 4px 10px;
+      border-bottom: 1px solid var(--border, #22262e);
+      font-size: 11px;
+      color: var(--fg-muted, #8b93a3);
+    }
+    .frame-scrubber.parked {
+      background: color-mix(in srgb, #d94c87 8%, transparent);
+    }
+    .frame-scrubber .scrub-slider {
+      flex: 1;
+      min-width: 80px;
+      accent-color: #d94c87;
+    }
+    .frame-scrubber .scrub-step,
+    .frame-scrubber .scrub-live {
+      background: none;
+      border: 1px solid var(--border, #22262e);
+      border-radius: 3px;
+      color: inherit;
+      cursor: pointer;
+      font: inherit;
+      padding: 1px 6px;
+    }
+    .frame-scrubber .scrub-live.active {
+      color: #47cca9;
+      border-color: #47cca9;
+    }
+    .frame-scrubber.parked .scrub-live {
+      color: #d94c87;
+      border-color: #d94c87;
+    }
+    .frame-scrubber .scrub-frame {
+      font-variant-numeric: tabular-nums;
+      min-width: 9ch;
+      text-align: right;
+    }
+    .stat-value.stat-parked {
+      color: #d94c87;
+    }
+    .buffers-parked-note,
+    .registry-parked-note {
+      position: absolute;
+      inset-inline: 0;
+      bottom: 0;
+      padding: 4px 8px;
+      font-size: 11px;
+      color: #d94c87;
+      background: color-mix(in srgb, #0d1016 82%, transparent);
+      pointer-events: none;
+      z-index: 2;
+    }
+    .registry-parked-note {
+      position: static;
+      pointer-events: auto;
+    }
   </style>
 </head>
 <body>

package/dist/dashboard/panels/batches.tsx

@@ -95,9 +95,7 @@ export function BatchesPanel() {
       run.batches.push({ batchIdx: b.batchIdx, spriteCount: b.spriteCount, label: b.label })
     }
     const arr = Array.from(m.values())
-    arr.sort((a, b) =>
-      a.kind.localeCompare(b.kind) || a.layer - b.layer || a.materialId - b.materialId,
-    )
+    arr.sort((a, b) => a.kind.localeCompare(b.kind) || a.layer - b.layer || a.materialId - b.materialId)
     return arr
   }, [batches.frame])
 
@@ -131,7 +129,8 @@ export function BatchesPanel() {
       <header class="panel-header batches-header">
         <span>Batches</span>
         <span class="batches-header-meta">
-          frame {batches.frame} · {passTotals.calls} draws · {runs.length} runs · {batches.batches.length} batches · {totalSprites} sprites
+          frame {batches.frame} · {passTotals.calls} draws · {runs.length} runs · {batches.batches.length} batches ·{' '}
+          {totalSprites} sprites
         </span>
       </header>
 
@@ -196,12 +195,7 @@ export function BatchesPanel() {
               <li class="batches-empty">no passes captured</li>
             ) : (
               passRoots.map((root) => (
-                <PassRow
-                  key={root.index}
-                  node={root}
-                  collapsed={collapsedPasses}
-                  onToggle={toggleCollapsed}
-                />
+                <PassRow key={root.index} node={root} collapsed={collapsedPasses} onToggle={toggleCollapsed} />
               ))
             )}
           </ul>
@@ -263,14 +257,7 @@ function PassRow({
         <span class="batches-col-num">{pass.cpuMs.toFixed(2)}</span>
       </li>
       {hasChildren && !isCollapsed
-        ? children.map((c) => (
-            <PassRow
-              key={c.index}
-              node={c}
-              collapsed={collapsed}
-              onToggle={onToggle}
-            />
-          ))
+        ? children.map((c) => <PassRow key={c.index} node={c} collapsed={collapsed} onToggle={onToggle} />)
         : null}
     </>
   )

package/dist/dashboard/panels/buffers.tsx

@@ -18,6 +18,7 @@
 import { useEffect, useMemo, useRef, useState } from 'preact/hooks'
 import type { BufferChunkPayload } from '../../devtools-client.js'
 import { getClient } from '../client.js'
+import { getFrameCursor } from '../frame-cursor.js'
 import { useDevtoolsState } from '../hooks.js'
 
 const VP9_CODEC = 'vp09.00.10.08'
@@ -63,18 +64,19 @@ export function BuffersPanel() {
   }, [state.buffers, state.buffers.size])
 
   const needle = filter.trim().toLowerCase()
-  const visible = needle.length > 0
-    ? entries.filter((e) => e.name.toLowerCase().includes(needle) || (e.label?.toLowerCase().includes(needle) ?? false))
-    : entries
+  const visible =
+    needle.length > 0
+      ? entries.filter(
+          (e) => e.name.toLowerCase().includes(needle) || (e.label?.toLowerCase().includes(needle) ?? false)
+        )
+      : entries
 
   // Only clear the selection if the currently-selected name has
   // vanished from the registry. Never auto-pick — selection must be
   // explicit so we don't silently subscribe a producer in stream mode
   // the moment a buffer shows up. Unselected = nothing streaming, no
   // GPU readback or VP9 encode on the producer side.
-  const effectiveSelected = selectedName !== null && visible.some((e) => e.name === selectedName)
-    ? selectedName
-    : null
+  const effectiveSelected = selectedName !== null && visible.some((e) => e.name === selectedName) ? selectedName : null
 
   // Subscribe/unsubscribe to stream mode based on selection. The dashboard
   // is a fresh DevtoolsClient consumer so this subscription is additive
@@ -86,7 +88,9 @@ export function BuffersPanel() {
       return
     }
     client.setBuffers({ [effectiveSelected]: { mode: 'stream' } })
-    return () => { client.setBuffers({}) }
+    return () => {
+      client.setBuffers({})
+    }
   }, [client, effectiveSelected])
 
   // WebCodecs decoder lifecycle — one instance per active selection.
@@ -122,7 +126,11 @@ export function BuffersPanel() {
   const stopDecoder = (): void => {
     const d = decoderRef.current
     if (d !== null && d.state !== 'closed') {
-      try { d.close() } catch { /* may already be errored */ }
+      try {
+        d.close()
+      } catch {
+        /* may already be errored */
+      }
     }
     decoderRef.current = null
     decoderDimsRef.current = { w: 0, h: 0 }
@@ -139,6 +147,12 @@ export function BuffersPanel() {
     waitingForKeyFrameRef.current = true
     const decoder = new globalThis.VideoDecoder({
       output: (frame) => {
+        // Parked cursor freezes the canvas (decode continues so the
+        // delta chain stays valid; we just don't paint).
+        if (getFrameCursor() !== null) {
+          frame.close()
+          return
+        }
         if (canvas.width !== frame.codedWidth || canvas.height !== frame.codedHeight) {
           canvas.width = frame.codedWidth
           canvas.height = frame.codedHeight
@@ -201,6 +215,9 @@ export function BuffersPanel() {
   // Paint those when the stream path isn't decoding.
   useEffect(() => {
     if (CODEC_AVAILABLE) return
+    // Parked cursor freezes the canvas — the last-drawn pixels stay put
+    // until the user returns to live (historical playback is Phase C).
+    if (getFrameCursor() !== null) return
     if (effectiveSelected === null) return
     const snap = state.buffers.get(effectiveSelected)
     if (snap === undefined || snap.pixels === null) return
@@ -304,7 +321,10 @@ export function BuffersPanel() {
     const rect = canvas.getBoundingClientRect()
     const u = (e.clientX - rect.left) / rect.width
     const v = (e.clientY - rect.top) / rect.height
-    if (u < 0 || u > 1 || v < 0 || v > 1) { setProbe(null); return }
+    if (u < 0 || u > 1 || v < 0 || v > 1) {
+      setProbe(null)
+      return
+    }
     const px = Math.min(canvas.width - 1, Math.max(0, Math.floor(u * canvas.width)))
     const py = Math.min(canvas.height - 1, Math.max(0, Math.floor(v * canvas.height)))
     try {
@@ -323,7 +343,7 @@ export function BuffersPanel() {
     setPan({ x: 0, y: 0 })
   }
 
-  const selectedSnap = effectiveSelected !== null ? state.buffers.get(effectiveSelected) ?? null : null
+  const selectedSnap = effectiveSelected !== null ? (state.buffers.get(effectiveSelected) ?? null) : null
 
   return (
     <section class="panel buffers-panel">
@@ -347,17 +367,13 @@ export function BuffersPanel() {
               <li key={e.name}>
                 <button
                   type="button"
-                  class={
-                    'buffers-row' +
-                    (e.name === effectiveSelected ? ' buffers-row-selected' : '')
-                  }
+                  class={'buffers-row' + (e.name === effectiveSelected ? ' buffers-row-selected' : '')}
                   onClick={() => setSelectedName((prev) => (prev === e.name ? null : e.name))}
                   title={e.name === effectiveSelected ? 'Click again to stop streaming' : 'Stream this buffer'}
                 >
                   <span class="buffers-name">{e.name}</span>
                   <span class="buffers-meta">
-                    {(e.srcWidth > 0 ? e.srcWidth : e.width)}×
-                    {(e.srcHeight > 0 ? e.srcHeight : e.height)} · {e.pixelType}
+                    {e.srcWidth > 0 ? e.srcWidth : e.width}×{e.srcHeight > 0 ? e.srcHeight : e.height} · {e.pixelType}
                   </span>
                 </button>
               </li>
@@ -383,6 +399,11 @@ export function BuffersPanel() {
                 onMouseMove={onCanvasMove}
                 onMouseLeave={onCanvasLeave}
               />
+              {getFrameCursor() !== null ? (
+                <div class="buffers-parked-note">
+                  parked at frame {getFrameCursor()} — no playback yet (flight recorder lands in Phase C); canvas frozen
+                </div>
+              ) : null}
               <div class="buffers-info">
                 <span>{selectedSnap.name}</span>
                 <span>
@@ -392,22 +413,25 @@ export function BuffersPanel() {
                 <span>{selectedSnap.pixelType}</span>
                 <span>{selectedSnap.display}</span>
                 {!CODEC_AVAILABLE && <span class="buffers-warn">no WebCodecs — thumbnail fallback</span>}
-                <span class="buffers-zoom">{zoom === 1 ? '1.0×' : `${zoom < 10 ? zoom.toFixed(1) : Math.round(zoom)}×`}</span>
+                <span class="buffers-zoom">
+                  {zoom === 1 ? '1.0×' : `${zoom < 10 ? zoom.toFixed(1) : Math.round(zoom)}×`}
+                </span>
               </div>
               {probe !== null && (
                 <div class="buffers-probe">
-                  <span>({probe.x}, {probe.y})</span>
+                  <span>
+                    ({probe.x}, {probe.y})
+                  </span>
                   <span class="probe-chip" style={{ background: `rgb(${probe.r}, ${probe.g}, ${probe.b})` }} />
-                  <span>{probe.r} {probe.g} {probe.b} {probe.a}</span>
+                  <span>
+                    {probe.r} {probe.g} {probe.b} {probe.a}
+                  </span>
                 </div>
               )}
               {(zoom !== 1 || pan.x !== 0 || pan.y !== 0) && (
-                <button
-                  type="button"
-                  class="buffers-reset"
-                  onClick={resetView}
-                  title="Reset zoom & pan"
-                >⟲</button>
+                <button type="button" class="buffers-reset" onClick={resetView} title="Reset zoom & pan">
+                  ⟲
+                </button>
               )}
               <button
                 type="button"
@@ -415,7 +439,9 @@ export function BuffersPanel() {
                 onClick={() => setSelectedName(null)}
                 title="Stop streaming"
                 aria-label="Stop streaming"
-              >×</button>
+              >
+                ×
+              </button>
             </>
           )}
         </div>

package/dist/dashboard/panels/env.tsx

@@ -39,13 +39,12 @@ export function EnvPopover() {
     }
   }, [open])
 
-  const canvas = s.canvasWidth !== undefined && s.canvasHeight !== undefined
-    ? `${s.canvasWidth}×${s.canvasHeight}${s.canvasPixelRatio !== undefined ? ` @${s.canvasPixelRatio}x` : ''}`
-    : '—'
+  const canvas =
+    s.canvasWidth !== undefined && s.canvasHeight !== undefined
+      ? `${s.canvasWidth}×${s.canvasHeight}${s.canvasPixelRatio !== undefined ? ` @${s.canvasPixelRatio}x` : ''}`
+      : '—'
 
-  const summary = s.backendName !== undefined
-    ? s.backendName
-    : 'Env'
+  const summary = s.backendName !== undefined ? s.backendName : 'Env'
 
   return (
     <div class="env-popover" ref={rootRef}>