@three-flatland/devtools 0.1.0-alpha.3

package/dist/dashboard/app.tsx

@@ -0,0 +1,42 @@
+/** @jsxImportSource preact */
+/**
+ * Dashboard root layout. Producer switcher lives in the header to
+ * reclaim left-rail real estate — the rail is gone, the content area
+ * fills the full viewport.
+ */
+import { BatchesPanel } from './panels/batches.js'
+import { BuffersPanel } from './panels/buffers.js'
+import { EnvPopover } from './panels/env.js'
+import { HeaderStats } from './panels/header-stats.js'
+import { ProducerSelect } from './panels/producer-select.js'
+import { ProtocolLog } from './panels/protocol-log.js'
+import { RegistryPanel } from './panels/registry.js'
+import { StatsStrip } from './panels/stats.js'
+
+export function App() {
+  return (
+    <div class="dashboard-root">
+      <header class="dashboard-header">
+        <span class="brand">three-flatland devtools</span>
+        <ProducerSelect />
+        <EnvPopover />
+        <HeaderStats />
+      </header>
+      <main class="dashboard-main">
+        <section class="dashboard-content">
+          <StatsStrip />
+          <div class="dashboard-split">
+            <div class="dashboard-split-col">
+              <BuffersPanel />
+              <BatchesPanel />
+              <RegistryPanel />
+            </div>
+            <div class="dashboard-split-col">
+              <ProtocolLog />
+            </div>
+          </div>
+        </section>
+      </main>
+    </div>
+  )
+}

package/dist/dashboard/client.ts

@@ -0,0 +1,21 @@
+/**
+ * Singleton `DevtoolsClient` for the dashboard page.
+ *
+ * The dashboard runs on the same origin as the app (via the microfrontend
+ * proxy) so a regular `new DevtoolsClient()` here reaches every producer
+ * the app creates via `BroadcastChannel`. One client covers the whole
+ * page — all panels share it and subscribe to the same state.
+ */
+import { DevtoolsClient } from '../devtools-client.js'
+
+const ALL_FEATURES = ['stats', 'env', 'registry', 'buffers', 'batches'] as const
+
+let instance: DevtoolsClient | null = null
+
+export function getClient(): DevtoolsClient {
+  if (instance === null) {
+    instance = new DevtoolsClient({ features: [...ALL_FEATURES] })
+    instance.start()
+  }
+  return instance
+}

package/dist/dashboard/export.ts

@@ -0,0 +1,84 @@
+/**
+ * Export helpers — drop the session's protocol log to a file the user
+ * can attach to a bug report or inspect offline. Walks the IDB store
+ * directly so even entries evicted from the in-memory cache make it
+ * into the dump.
+ *
+ * Format: one JSON document with header + entries array. ArrayBuffer /
+ * TypedArray payloads are serialised as `{__buf: base64, byteLength}`
+ * so the dump survives a JSON round-trip without losing binary.
+ */
+
+const DB_NAME = 'tf-devtools-protocol'
+const STORE = 'messages'
+
+interface RawEntry {
+  id: number
+  providerId: string
+  at: number
+  direction: 'in' | 'out'
+  type: string
+  tag?: string
+  frame?: number
+  bytes: number
+  msg: unknown
+}
+
+async function readAll(): Promise<RawEntry[]> {
+  const db = await new Promise<IDBDatabase>((resolve, reject) => {
+    const req = indexedDB.open(DB_NAME)
+    req.onsuccess = () => resolve(req.result)
+    req.onerror = () => reject(req.error ?? new Error('IndexedDB open failed'))
+  })
+  const entries = await new Promise<RawEntry[]>((resolve, reject) => {
+    const tx = db.transaction(STORE, 'readonly')
+    const req = tx.objectStore(STORE).getAll()
+    req.onsuccess = () => resolve(req.result as RawEntry[])
+    req.onerror = () => reject(req.error ?? new Error('IndexedDB read failed'))
+  })
+  db.close()
+  return entries
+}
+
+function replacer(_k: string, v: unknown): unknown {
+  if (v instanceof ArrayBuffer) return tagBuffer(new Uint8Array(v), v.byteLength)
+  if (ArrayBuffer.isView(v)) {
+    const u = new Uint8Array(v.buffer, v.byteOffset, v.byteLength)
+    return { ...tagBuffer(u, v.byteLength), ctor: v.constructor.name }
+  }
+  return v
+}
+
+function tagBuffer(u: Uint8Array, byteLength: number): { __buf: string; byteLength: number } {
+  let binary = ''
+  for (let i = 0; i < u.length; i++) binary += String.fromCharCode(u[i]!)
+  return { __buf: btoa(binary), byteLength }
+}
+
+/**
+ * Read the full session log and prompt the user to save a JSON dump.
+ * Optional `providerId` narrows to a single producer.
+ */
+export async function exportSession(providerId: string | null = null): Promise<void> {
+  const entries = await readAll()
+  const filtered = providerId === null ? entries : entries.filter((e) => e.providerId === providerId)
+  const payload = {
+    exportedAt: new Date().toISOString(),
+    providerId,
+    count: filtered.length,
+    entries: filtered,
+  }
+  const json = JSON.stringify(payload, replacer, 2)
+  const blob = new Blob([json], { type: 'application/json' })
+  const url = URL.createObjectURL(blob)
+  const a = document.createElement('a')
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-')
+  a.href = url
+  a.download = providerId !== null
+    ? `tf-devtools-${providerId}-${stamp}.json`
+    : `tf-devtools-session-${stamp}.json`
+  document.body.appendChild(a)
+  a.click()
+  document.body.removeChild(a)
+  URL.revokeObjectURL(url)
+}

package/dist/dashboard/hooks.ts

@@ -0,0 +1,75 @@
+/**
+ * Preact hooks over the dashboard's singleton `DevtoolsClient`.
+ *
+ * State updates fan out through a shared rAF coalescer so a single
+ * `provider → client.addListener` event notifies every subscribed hook
+ * on the same frame. Without this each `use*` hook would schedule its
+ * own rAF, multiplying the update cost by the number of panels.
+ */
+import { useEffect, useState } from 'preact/hooks'
+import type { DevtoolsState } from '../devtools-client.js'
+import { getClient } from './client.js'
+import { getProtocolStore } from './protocol-store.js'
+
+type Subscriber = () => void
+
+// One shared rAF per update, ticked by any underlying source that
+// subscribes. Listeners register with `subscribeFrame`; all fire
+// together when the rAF lands.
+const _frameListeners = new Set<Subscriber>()
+let _frameScheduled = false
+
+function scheduleFrame(): void {
+  if (_frameScheduled) return
+  _frameScheduled = true
+  requestAnimationFrame(() => {
+    _frameScheduled = false
+    for (const cb of _frameListeners) {
+      try { cb() } catch { /* listener errors shouldn't break the bus */ }
+    }
+  })
+}
+
+function subscribeFrame(cb: Subscriber): () => void {
+  _frameListeners.add(cb)
+  return () => { _frameListeners.delete(cb) }
+}
+
+// Wire the underlying data sources to the shared rAF once. Any event on
+// the client or store ticks the shared loop.
+let _sourcesWired = false
+function ensureSourcesWired(): void {
+  if (_sourcesWired) return
+  _sourcesWired = true
+  getClient().addListener(scheduleFrame)
+  getProtocolStore().addListener(scheduleFrame)
+}
+
+/**
+ * Subscribe to the client's state. Returns the live state object; the
+ * client mutates it in place, so we bump a tick to force a re-render.
+ * All subscribers share one rAF per frame.
+ */
+export function useDevtoolsState(): DevtoolsState {
+  ensureSourcesWired()
+  const client = getClient()
+  const [, setTick] = useState(0)
+  useEffect(() => {
+    return subscribeFrame(() => setTick((n) => (n + 1) & 0xffff))
+  }, [])
+  return client.state
+}
+
+/**
+ * Subscribe to the shared frame tick without reading any specific
+ * source. Use this for components (protocol log, header stats, stats
+ * strip) that derive their render from a source other than the client
+ * state but still want to coalesce onto the same rAF.
+ */
+export function useFrameTick(): void {
+  ensureSourcesWired()
+  const [, setTick] = useState(0)
+  useEffect(() => {
+    return subscribeFrame(() => setTick((n) => (n + 1) & 0xffff))
+  }, [])
+}