From fd1d05cea02bb17d1a5b48888b112cac1492e90f Mon Sep 17 00:00:00 2001
From: Bendik Aagaard Lynghaug <bendik.lynghaug@gmail.com>
Date: Tue, 8 Sep 2026 18:57:51 +0200
Subject: [PATCH] =?UTF-8?q?feat(devtools):=20add=20@choojs/devtools=20?=
 =?UTF-8?q?=E2=80=94=20window.choo=20console=20tooling?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Carries forward the choo-devtools 3.x essentials: live state handle,
emit-from-console, event log, nanotiming measures via PerformanceObserver,
state copy(), help(). No-op on the server; verbose logging opt-in via
localStorage.CHOO_DEVTOOLS_VERBOSE.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014NgfSjHE11oFpoSnLVKLXd
---
 package.json                            |  2 +-
 packages/devtools/index.js              | 78 +++++++++++++++++++++++++
 packages/devtools/package.json          | 22 +++++++
 packages/devtools/test/devtools.test.js | 51 ++++++++++++++++
 4 files changed, 152 insertions(+), 1 deletion(-)
 create mode 100644 packages/devtools/index.js
 create mode 100644 packages/devtools/package.json
 create mode 100644 packages/devtools/test/devtools.test.js

diff --git a/package.json b/package.json
index f0669d2..dae178d 100644
--- a/package.json
+++ b/package.json
@@ -11,7 +11,7 @@
     "node": ">=24"
   },
   "scripts": {
-    "test": "node --test packages/core/test/ packages/html/test/ packages/component/test/",
+    "test": "node --test packages/core/test/ packages/html/test/ packages/component/test/ packages/devtools/test/ packages/migrate/test/",
     "test:e2e": "node --test test/e2e/",
     "bench": "node bench/render.js",
     "bench:browser": "node bench/real-browser.js"
diff --git a/packages/devtools/index.js b/packages/devtools/index.js
new file mode 100644
index 0000000..3e4abda
--- /dev/null
+++ b/packages/devtools/index.js
@@ -0,0 +1,78 @@
+// Console devtools for choo v8, carrying forward the essentials of
+// choo-devtools 3.x (MIT): a window.choo handle with the live state, an
+// event log, emit-from-the-console, and render timings via the
+// PerformanceObserver watching nanotiming's measures. Usage:
+//
+//   import devtools from '@choojs/devtools'
+//   app.use(devtools())
+//
+// The store is a no-op on the server and (by default) stays quiet in the
+// console; set localStorage.CHOO_DEVTOOLS_VERBOSE = 'true' to log every
+// event as it happens.
+
+const MAX_LOG = 1000
+
+export default function devtools (opts) {
+  opts = opts || {}
+  const max = opts.max || MAX_LOG
+
+  return function devtoolsStore (state, emitter, app) {
+    if (typeof window === 'undefined') return
+
+    const log = []
+    let verbose = false
+    try {
+      verbose = window.localStorage.CHOO_DEVTOOLS_VERBOSE === 'true'
+    } catch (e) {}
+
+    emitter.on('*', function (name, ...data) {
+      const entry = { name: String(name), data, at: Date.now() }
+      log.push(entry)
+      if (log.length > max) log.shift()
+      if (verbose && name !== state.events.RENDER) {
+        console.debug('choo: %s', entry.name, ...data)
+      }
+    })
+
+    const timings = []
+    if (typeof PerformanceObserver === 'function') {
+      try {
+        const observer = new PerformanceObserver(function (list) {
+          for (const entry of list.getEntries()) {
+            if (!/\[\d+\]$/.test(entry.name)) continue // nanotiming measures only
+            timings.push({ name: entry.name.replace(/ \[\d+\]$/, ''), duration: entry.duration })
+            if (timings.length > max) timings.shift()
+          }
+        })
+        observer.observe({ entryTypes: ['measure'] })
+      } catch (e) {}
+    }
+
+    window.choo = {
+      state,
+      emit: emitter.emit.bind(emitter),
+      emitter,
+      app,
+      log,
+      timings,
+      // JSON snapshot of state (cache/functions excluded via toJSON)
+      copy () {
+        const json = JSON.stringify(state, null, 2)
+        if (navigator.clipboard) navigator.clipboard.writeText(json)
+        return json
+      },
+      help () {
+        console.log([
+          'window.choo — choo devtools',
+          '  choo.state       live app state',
+          '  choo.emit(name, …data)  fire an event',
+          '  choo.log         last ' + max + ' events',
+          '  choo.timings     nanotiming render measures',
+          '  choo.copy()      state as JSON (and to clipboard)',
+          "  localStorage.CHOO_DEVTOOLS_VERBOSE = 'true'  log every event"
+        ].join('\n'))
+        return '☰'
+      }
+    }
+  }
+}
diff --git a/packages/devtools/package.json b/packages/devtools/package.json
new file mode 100644
index 0000000..f4ce06a
--- /dev/null
+++ b/packages/devtools/package.json
@@ -0,0 +1,22 @@
+{
+  "name": "@choojs/devtools",
+  "version": "8.0.0-dev",
+  "description": "Console devtools for choo: window.choo, event log, perf timings",
+  "type": "module",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "index.js"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "repository": "choojs/choo",
+  "keywords": [
+    "choo",
+    "devtools",
+    "debug"
+  ],
+  "license": "MIT"
+}
diff --git a/packages/devtools/test/devtools.test.js b/packages/devtools/test/devtools.test.js
new file mode 100644
index 0000000..4af1e6e
--- /dev/null
+++ b/packages/devtools/test/devtools.test.js
@@ -0,0 +1,51 @@
+import { test, before } from 'node:test'
+import assert from 'node:assert'
+import { Window } from 'happy-dom'
+
+let choo, html, devtools
+
+before(async () => {
+  const win = new Window({ url: 'http://localhost/' })
+  globalThis.window = win
+  globalThis.document = win.document
+  globalThis.requestAnimationFrame = win.requestAnimationFrame.bind(win)
+  ;({ default: choo } = await import('@choojs/core'))
+  ;({ default: html } = await import('@choojs/html/browser'))
+  ;({ default: devtools } = await import('../index.js'))
+})
+
+test('devtools exposes window.choo with live state, log and emit', async () => {
+  const app = choo()
+  app.use(devtools())
+  app.use((state, emitter) => {
+    state.count = 0
+    emitter.on('bump', (n) => { state.count += n })
+  })
+  app.route('/', (state) => html`<div>${state.count}</div>`)
+  app.start()
+
+  assert.ok(window.choo, 'window.choo exists')
+  assert.strictEqual(window.choo.state.count, 0, 'live state exposed')
+
+  window.choo.emit('bump', 2)
+  assert.strictEqual(window.choo.state.count, 2, 'emit from the console handle works')
+  assert.ok(window.choo.log.some((e) => e.name === 'bump'), 'events land in the log')
+  assert.strictEqual(typeof window.choo.help, 'function')
+
+  const json = JSON.parse(window.choo.copy())
+  assert.strictEqual(json.count, 2, 'copy() serializes state')
+  assert.strictEqual(json.cache, null, 'state.cache not serialized')
+})
+
+test('devtools is a no-op on the server', async () => {
+  // fresh import in a windowless world is covered by the guard: calling
+  // the store with no window must not throw or touch globals
+  const store = devtools()
+  const hadWindow = globalThis.window
+  delete globalThis.window
+  try {
+    assert.doesNotThrow(() => store({}, { on () {} }, {}))
+  } finally {
+    globalThis.window = hadWindow
+  }
+})