@kfiross44/valtio-inspector 0.9.0

package/.changeset/README.md

@@ -0,0 +1,8 @@
+# Changesets
+
+Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
+with multi-package repos, or single-package repos to help you version and publish your code. You can
+find the full documentation for it [in our repository](https://github.com/changesets/changesets).
+
+We have a quick list of common questions to get you started engaging with this project in
+[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md).

package/.changeset/config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.3/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "restricted",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

package/README.md

@@ -0,0 +1,99 @@
+# Valtio Inspector
+
+A dev-only state inspector for [Valtio](https://github.com/pmndrs/valtio) with live WebSocket updates, multiple store support, history, and time travel.
+
+## Features
+
+- 🔴 **Live WebSocket updates** — no polling
+- 🗂 **Multiple stores** — sidebar navigation
+- 🌳 **Collapsible JSON tree** — expand/collapse nodes
+- 📜 **History log** — every change tracked with timestamps
+- ⏪ **Time travel** — click any history entry to inspect that snapshot
+- 🔍 **Diff view** — see exactly what changed between snapshots
+- ⚡ **Auto-reconnect** — if the server restarts
+
+---
+
+## Setup
+
+### 1. Install & run the inspector server
+
+```bash
+cd valtio-inspector
+npm install
+npm run dev
+# → http://localhost:7777
+```
+
+### 2. Instrument your stores
+
+Copy `instrument/attachInspector.ts` into your app (requires `valtio` installed).
+
+```ts
+import { proxy } from 'valtio'
+import { attachInspector } from './attachInspector'
+
+export const authStore = proxy({
+  user: { id: 1, name: 'kfir' },
+  isLoggedIn: false
+})
+
+export const uiStore = proxy({
+  darkMode: true,
+  sidebarOpen: false
+})
+
+// Only in dev!
+if (process.env.NODE_ENV !== 'production') {
+  attachInspector(authStore, { name: 'auth' })
+  attachInspector(uiStore, { name: 'ui' })
+}
+```
+
+`attachInspector` returns a cleanup function (for React `useEffect`, etc.):
+```ts
+const cleanup = attachInspector(store, { name: 'myStore' })
+// later:
+cleanup()
+```
+
+### Options
+
+```ts
+attachInspector(store, {
+  name: 'myStore',       // required — display name
+  debounce: 100,         // optional — ms debounce (default: 100)
+  inspectorUrl: 'http://localhost:7777'  // optional — if running elsewhere
+})
+```
+
+---
+
+## API
+
+The server exposes these endpoints (used internally by the UI):
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/state` | Push a store update |
+| `GET`  | `/state` | Get the current full state tree |
+| `DELETE` | `/state` | Clear all state + history |
+| `GET`  | `/history` | Get full history log |
+| `GET`  | `/history/:id` | Get a specific history snapshot |
+
+---
+
+## Building for production (server)
+
+```bash
+npm run build
+npm start
+```
+
+---
+
+## ⚠️ Security
+
+- **Never expose port 7777 publicly.** This is a dev-only tool.
+- Always gate `attachInspector` behind `process.env.NODE_ENV !== 'production'`.
+- Do not run the inspector server in production builds.

package/client/app.js

@@ -0,0 +1,329 @@
+/* ── State ── */
+let stateTree = {}
+let historyLog = []
+let selectedStore = null
+let selectedHistoryId = null
+let activeTab = 'tree'
+let collapsedPaths = new Set()
+let lastDiff = {}
+
+/* ── WebSocket ── */
+const wsUrl = `ws://${location.host}`
+let ws
+
+function connect() {
+  ws = new WebSocket(wsUrl)
+
+  ws.onopen = () => {
+    setStatus(true)
+  }
+
+  ws.onclose = () => {
+    setStatus(false)
+    setTimeout(connect, 2000)
+  }
+
+  ws.onerror = () => {
+    setStatus(false)
+  }
+
+  ws.onmessage = (event) => {
+    const msg = JSON.parse(event.data)
+
+    if (msg.type === 'INIT') {
+      stateTree = msg.state || {}
+      historyLog = msg.history || []
+      renderAll()
+    }
+
+    if (msg.type === 'STATE_UPDATE') {
+      stateTree = msg.state
+      if (msg.entry) {
+        historyLog.push(msg.entry)
+        if (historyLog.length > 100) historyLog.shift()
+        if (msg.entry.store === selectedStore && msg.entry.diff) {
+          lastDiff[selectedStore] = msg.entry.diff
+        }
+      }
+      flashStore(msg.entry?.store)
+      renderAll()
+    }
+
+    if (msg.type === 'CLEAR') {
+      stateTree = {}
+      historyLog = []
+      selectedStore = null
+      selectedHistoryId = null
+      lastDiff = {}
+      renderAll()
+    }
+  }
+}
+
+function setStatus(connected) {
+  const pill = document.getElementById('status-pill')
+  const text = document.getElementById('status-text')
+  pill.className = 'status-pill' + (connected ? ' connected' : '')
+  text.textContent = connected ? 'connected' : 'disconnected'
+}
+
+/* ── Render all ── */
+function renderAll() {
+  renderSidebar()
+  renderMain()
+  renderHistory()
+}
+
+/* ── Sidebar ── */
+const storeColors = ['#7c6af7', '#56e0a0', '#f7a26a', '#f06c8a', '#7ec8e3', '#c8e37e']
+function storeColor(name) {
+  let hash = 0
+  for (let c of name) hash = (hash * 31 + c.charCodeAt(0)) & 0xffffffff
+  return storeColors[Math.abs(hash) % storeColors.length]
+}
+
+function renderSidebar() {
+  const list = document.getElementById('store-list')
+  const stores = Object.keys(stateTree)
+
+  if (stores.length === 0) {
+    list.innerHTML = ''
+    return
+  }
+
+  list.innerHTML = stores.map(name => {
+    const color = storeColor(name)
+    const initial = name[0].toUpperCase()
+    const active = name === selectedStore ? ' active' : ''
+    return `
+      <div class="store-item${active}" onclick="selectStore('${name}')">
+        <div class="store-icon" style="color:${color};border:1px solid ${color}33">${initial}</div>
+        <span class="store-name">${name}</span>
+        <div class="store-flash" id="flash-${name}"></div>
+      </div>`
+  }).join('')
+}
+
+function flashStore(name) {
+  if (!name) return
+  setTimeout(() => {
+    const el = document.getElementById(`flash-${name}`)
+    if (el) {
+      el.parentElement.classList.remove('flash')
+      void el.parentElement.offsetWidth
+      el.parentElement.classList.add('flash')
+    }
+  }, 0)
+}
+
+function selectStore(name) {
+  selectedStore = name
+  selectedHistoryId = null
+  renderAll()
+}
+
+/* ── Main panel ── */
+function renderMain() {
+  const title = document.getElementById('main-title')
+  const tag = document.getElementById('main-tag')
+  const emptyState = document.getElementById('empty-state')
+  const treeView = document.getElementById('tree-view')
+  const rawView = document.getElementById('raw-view')
+  const diffView = document.getElementById('diff-view')
+
+  const hasStores = Object.keys(stateTree).length > 0
+
+  if (!selectedStore || !stateTree[selectedStore]) {
+    emptyState.style.display = hasStores ? '' : ''
+    treeView.style.display = 'none'
+    rawView.style.display = 'none'
+    diffView.style.display = 'none'
+    emptyState.style.display = ''
+    title.textContent = '—'
+    tag.textContent = 'no store selected'
+    return
+  }
+
+  const data = selectedHistoryId != null
+    ? (historyLog.find(h => h.id === selectedHistoryId)?.state?.[selectedStore] ?? stateTree[selectedStore])
+    : stateTree[selectedStore]
+
+  title.textContent = selectedStore
+  tag.textContent = selectedHistoryId != null ? `time travel #${selectedHistoryId}` : 'live'
+  tag.style.color = selectedHistoryId != null ? 'var(--accent3)' : 'var(--text-dim)'
+
+  emptyState.style.display = 'none'
+  treeView.style.display = activeTab === 'tree' ? '' : 'none'
+  rawView.style.display = activeTab === 'raw' ? '' : 'none'
+  diffView.style.display = activeTab === 'diff' ? '' : 'none'
+
+  if (activeTab === 'tree') {
+    treeView.innerHTML = ''
+    treeView.appendChild(renderJsonTree(data, selectedStore))
+  } else if (activeTab === 'raw') {
+    document.getElementById('raw-content').textContent = JSON.stringify(data, null, 2)
+  } else if (activeTab === 'diff') {
+    renderDiffView(diffView, lastDiff[selectedStore] || {})
+  }
+}
+
+/* ── JSON Tree ── */
+function renderJsonTree(value, path) {
+  const wrap = document.createElement('div')
+  wrap.className = 'json-tree'
+  buildNode(wrap, value, null, path, 0)
+  return wrap
+}
+
+function buildNode(parent, value, key, path, depth) {
+  const type = typeof value
+  const row = document.createElement('div')
+  row.className = 'json-row'
+
+  const isObj = value !== null && type === 'object'
+  const isArr = Array.isArray(value)
+  const childCount = isObj ? Object.keys(value).length : 0
+
+  if (isObj && childCount > 0) {
+    const collapsed = collapsedPaths.has(path)
+    const toggle = document.createElement('span')
+    toggle.className = 'json-collapse'
+    toggle.textContent = collapsed ? '▶' : '▼'
+    toggle.onclick = () => {
+      if (collapsedPaths.has(path)) collapsedPaths.delete(path)
+      else collapsedPaths.add(path)
+      renderMain()
+    }
+    row.appendChild(toggle)
+    if (key !== null) {
+      const k = document.createElement('span')
+      k.className = 'json-key'
+      k.textContent = JSON.stringify(key)
+      row.appendChild(k)
+      row.appendChild(makeSpan('json-colon', ': '))
+    }
+    row.appendChild(makeSpan('', isArr ? `[${childCount}]` : `{${childCount}}`))
+    row.style.color = 'var(--text-dim)'
+    parent.appendChild(row)
+
+    if (!collapsed) {
+      const kids = document.createElement('div')
+      kids.className = 'json-children'
+      for (const [k2, v2] of Object.entries(value)) {
+        buildNode(kids, v2, k2, `${path}.${k2}`, depth + 1)
+      }
+      parent.appendChild(kids)
+    }
+  } else {
+    const spacer = document.createElement('span')
+    spacer.style.display = 'inline-block'
+    spacer.style.width = '14px'
+    row.appendChild(spacer)
+
+    if (key !== null) {
+      row.appendChild(makeSpan('json-key', JSON.stringify(key)))
+      row.appendChild(makeSpan('json-colon', ': '))
+    }
+
+    if (value === null) {
+      row.appendChild(makeSpan('json-null', 'null'))
+    } else if (type === 'string') {
+      row.appendChild(makeSpan('json-string', JSON.stringify(value)))
+    } else if (type === 'number') {
+      row.appendChild(makeSpan('json-number', String(value)))
+    } else if (type === 'boolean') {
+      row.appendChild(makeSpan('json-bool', String(value)))
+    } else {
+      row.appendChild(makeSpan('', '{}'))
+    }
+    parent.appendChild(row)
+  }
+}
+
+function makeSpan(cls, text) {
+  const s = document.createElement('span')
+  if (cls) s.className = cls
+  s.textContent = text
+  return s
+}
+
+/* ── Diff view ── */
+function renderDiffView(container, diff) {
+  container.innerHTML = ''
+  if (!diff || Object.keys(diff).length === 0) {
+    const empty = document.createElement('div')
+    empty.className = 'empty-state'
+    empty.innerHTML = '<div class="big">≈</div><div class="hint">No diff recorded yet.<br>Change a store value to see what changed.</div>'
+    container.appendChild(empty)
+    return
+  }
+
+  for (const [key, change] of Object.entries(diff)) {
+    const line = document.createElement('div')
+    line.className = 'diff-line changed'
+    line.innerHTML = `
+      <span class="diff-key">${key}</span>
+      <span class="diff-arrow">:</span>
+      <span class="diff-old">${JSON.stringify(change.from)}</span>
+      <span class="diff-arrow">→</span>
+      <span class="diff-new">${JSON.stringify(change.to)}</span>
+    `
+    container.appendChild(line)
+  }
+}
+
+/* ── History panel ── */
+function renderHistory() {
+  const list = document.getElementById('history-list')
+  const count = document.getElementById('history-count')
+  count.textContent = historyLog.length
+
+  if (historyLog.length === 0) {
+    list.innerHTML = '<div style="padding:12px 14px;color:var(--text-dim);font-size:11px">No history yet</div>'
+    return
+  }
+
+  list.innerHTML = [...historyLog].reverse().map(entry => {
+    const active = entry.id === selectedHistoryId ? ' active' : ''
+    const time = new Date(entry.timestamp).toLocaleTimeString('en-US', { hour12: false, hour: '2-digit', minute: '2-digit', second: '2-digit', fractionalSecondDigits: 2 })
+    const pills = entry.diff ? Object.entries(entry.diff).slice(0, 4).map(([k]) =>
+      `<span class="hist-pill change">${k}</span>`
+    ).join('') : ''
+    return `
+      <div class="hist-item${active}" onclick="selectHistory(${entry.id})">
+        <span class="hist-store">${entry.store}</span>
+        <span class="hist-time">${time}</span>
+        ${pills ? `<div class="hist-diff-pills">${pills}</div>` : ''}
+      </div>`
+  }).join('')
+}
+
+function selectHistory(id) {
+  if (selectedHistoryId === id) {
+    selectedHistoryId = null
+  } else {
+    selectedHistoryId = id
+    const entry = historyLog.find(h => h.id === id)
+    if (entry) selectedStore = entry.store
+  }
+  renderAll()
+}
+
+/* ── Tabs ── */
+document.querySelectorAll('.tab').forEach(tab => {
+  tab.addEventListener('click', () => {
+    document.querySelectorAll('.tab').forEach(t => t.classList.remove('active'))
+    tab.classList.add('active')
+    activeTab = tab.dataset.tab
+    renderMain()
+  })
+})
+
+/* ── Clear ── */
+document.getElementById('btn-clear').addEventListener('click', () => {
+  fetch('/state', { method: 'DELETE' }).catch(() => {})
+})
+
+/* ── Boot ── */
+connect()
+renderAll()

package/client/index.html

@@ -0,0 +1,203 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Valtio Inspector</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500;600&family=Space+Mono:wght@400;700&display=swap" rel="stylesheet">
+  <style>
+    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+
+    :root {
+      --bg:        #0d0f14;
+      --bg2:       #12151c;
+      --bg3:       #191d27;
+      --bg4:       #1f2432;
+      --border:    #262c3d;
+      --border2:   #2e3549;
+      --text:      #c8d0e8;
+      --text-dim:  #5a6480;
+      --text-mid:  #8892b0;
+      --accent:    #7c6af7;
+      --accent2:   #56e0a0;
+      --accent3:   #f7a26a;
+      --accent4:   #f06c8a;
+      --add:       #56e0a0;
+      --remove:    #f06c8a;
+      --change:    #f7a26a;
+      --dot-size:  6px;
+    }
+
+    html, body { height: 100%; background: var(--bg); color: var(--text); font-family: 'JetBrains Mono', monospace; font-size: 13px; overflow: hidden; }
+
+    /* ── Layout ── */
+    #app { display: grid; grid-template-columns: 220px 1fr 260px; grid-template-rows: 48px 1fr; height: 100vh; }
+
+    /* ── Topbar ── */
+    #topbar {
+      grid-column: 1 / -1;
+      display: flex; align-items: center; gap: 16px;
+      padding: 0 20px;
+      background: var(--bg2);
+      border-bottom: 1px solid var(--border);
+      position: relative;
+      z-index: 10;
+    }
+    #topbar .logo { display: flex; align-items: center; gap: 8px; font-family: 'Space Mono', monospace; font-size: 14px; font-weight: 700; letter-spacing: -0.02em; }
+    #topbar .logo .dot { width: 8px; height: 8px; border-radius: 50%; background: var(--accent); box-shadow: 0 0 10px var(--accent); animation: pulse 2s ease-in-out infinite; }
+    @keyframes pulse { 0%,100%{opacity:1;transform:scale(1)} 50%{opacity:.6;transform:scale(.85)} }
+    #topbar .spacer { flex: 1; }
+    .status-pill { display: flex; align-items: center; gap: 6px; font-size: 11px; color: var(--text-dim); padding: 4px 10px; border-radius: 20px; border: 1px solid var(--border); }
+    .status-pill .led { width: 6px; height: 6px; border-radius: 50%; background: var(--text-dim); transition: background .3s, box-shadow .3s; }
+    .status-pill.connected .led { background: var(--accent2); box-shadow: 0 0 8px var(--accent2); }
+    .status-pill.connected { border-color: #2a4040; color: var(--accent2); }
+    #btn-clear { background: none; border: 1px solid var(--border); border-radius: 6px; color: var(--text-dim); cursor: pointer; padding: 4px 12px; font-family: inherit; font-size: 11px; transition: all .2s; }
+    #btn-clear:hover { border-color: var(--accent4); color: var(--accent4); }
+
+    /* ── Sidebar ── */
+    #sidebar {
+      background: var(--bg2);
+      border-right: 1px solid var(--border);
+      overflow-y: auto;
+      display: flex; flex-direction: column;
+    }
+    #sidebar-head { padding: 12px 14px 8px; font-size: 10px; font-weight: 600; text-transform: uppercase; letter-spacing: .12em; color: var(--text-dim); }
+    .store-item {
+      display: flex; align-items: center; gap: 10px;
+      padding: 8px 14px; cursor: pointer;
+      border-left: 2px solid transparent;
+      transition: background .15s, border-color .15s;
+      position: relative;
+    }
+    .store-item:hover { background: var(--bg3); }
+    .store-item.active { background: var(--bg3); border-left-color: var(--accent); }
+    .store-item .store-icon { width: 22px; height: 22px; border-radius: 6px; display: flex; align-items: center; justify-content: center; font-size: 11px; background: var(--bg4); color: var(--accent); flex-shrink: 0; }
+    .store-item .store-name { flex: 1; color: var(--text); font-size: 12px; }
+    .store-item .store-flash { position: absolute; inset: 0; background: var(--accent); opacity: 0; pointer-events: none; border-radius: 0; }
+    .store-item.flash .store-flash { animation: flash-anim .4s ease-out; }
+    @keyframes flash-anim { 0%{opacity:.12} 100%{opacity:0} }
+
+    /* ── Main ── */
+    #main { display: flex; flex-direction: column; overflow: hidden; background: var(--bg); }
+    #main-head { display: flex; align-items: center; gap: 10px; padding: 10px 16px; border-bottom: 1px solid var(--border); background: var(--bg2); flex-shrink: 0; }
+    #main-head .store-label { font-size: 14px; font-weight: 600; color: var(--text); }
+    #main-head .store-tag { font-size: 10px; color: var(--text-dim); background: var(--bg4); border: 1px solid var(--border); padding: 2px 8px; border-radius: 4px; }
+    #tabs { display: flex; gap: 2px; padding: 8px 16px 0; background: var(--bg2); border-bottom: 1px solid var(--border); }
+    .tab { padding: 6px 14px 7px; cursor: pointer; font-size: 11px; color: var(--text-dim); border-bottom: 2px solid transparent; transition: all .2s; border-radius: 4px 4px 0 0; }
+    .tab:hover { color: var(--text); background: var(--bg3); }
+    .tab.active { color: var(--accent); border-bottom-color: var(--accent); background: var(--bg3); }
+    #view { flex: 1; overflow-y: auto; padding: 16px; }
+
+    /* ── JSON tree ── */
+    .json-tree { line-height: 1.7; }
+    .json-node { display: flex; flex-direction: column; }
+    .json-row { display: flex; align-items: baseline; gap: 6px; cursor: default; padding: 1px 4px; border-radius: 3px; }
+    .json-row:hover { background: var(--bg3); }
+    .json-key { color: #7ec8e3; }
+    .json-colon { color: var(--text-dim); }
+    .json-string { color: var(--accent2); }
+    .json-number { color: #f9c46b; }
+    .json-bool   { color: var(--accent3); }
+    .json-null   { color: var(--text-dim); }
+    .json-collapse { color: var(--text-dim); font-size: 10px; cursor: pointer; user-select: none; padding: 0 3px; }
+    .json-collapse:hover { color: var(--text); }
+    .json-children { padding-left: 18px; border-left: 1px solid var(--border); margin-left: 8px; }
+
+    /* ── History panel ── */
+    #history-panel { background: var(--bg2); border-left: 1px solid var(--border); overflow-y: auto; display: flex; flex-direction: column; }
+    #history-head { padding: 12px 14px 8px; font-size: 10px; font-weight: 600; text-transform: uppercase; letter-spacing: .12em; color: var(--text-dim); border-bottom: 1px solid var(--border); flex-shrink: 0; display: flex; align-items: center; justify-content: space-between; }
+    #history-count { font-size: 10px; color: var(--accent); background: #1e1a3a; border: 1px solid #2d2660; padding: 1px 7px; border-radius: 10px; }
+    #history-list { flex: 1; overflow-y: auto; }
+    .hist-item {
+      padding: 8px 14px; cursor: pointer;
+      border-bottom: 1px solid var(--border);
+      transition: background .15s;
+      display: flex; flex-direction: column; gap: 3px;
+    }
+    .hist-item:hover { background: var(--bg3); }
+    .hist-item.active { background: #191630; border-left: 2px solid var(--accent); }
+    .hist-item .hist-store { font-size: 11px; color: var(--accent); font-weight: 500; }
+    .hist-item .hist-time { font-size: 10px; color: var(--text-dim); }
+    .hist-item .hist-diff-pills { display: flex; flex-wrap: wrap; gap: 3px; }
+    .hist-pill { font-size: 9px; padding: 1px 6px; border-radius: 10px; font-weight: 500; }
+    .hist-pill.change { background: #2c200d; color: var(--change); border: 1px solid #3d2c12; }
+    .hist-pill.add    { background: #0d2316; color: var(--add);    border: 1px solid #123020; }
+    .hist-pill.remove { background: #2c0d14; color: var(--remove); border: 1px solid #3d1220; }
+
+    /* ── Empty / no store states ── */
+    .empty-state { display: flex; flex-direction: column; align-items: center; justify-content: center; height: 100%; gap: 10px; color: var(--text-dim); text-align: center; }
+    .empty-state .big { font-size: 32px; opacity: .3; }
+    .empty-state .hint { font-size: 11px; line-height: 1.8; max-width: 280px; }
+    .empty-state code { background: var(--bg3); padding: 2px 6px; border-radius: 4px; font-size: 11px; color: var(--accent); }
+
+    /* ── Diff view ── */
+    .diff-line { display: flex; gap: 8px; padding: 3px 8px; border-radius: 3px; font-size: 12px; align-items: baseline; }
+    .diff-line.changed { background: #1e1505; border-left: 2px solid var(--change); }
+    .diff-line.added   { background: #061510; border-left: 2px solid var(--add); }
+    .diff-line.removed { background: #150509; border-left: 2px solid var(--remove); }
+    .diff-label { font-size: 10px; min-width: 50px; opacity: .7; }
+    .diff-key   { color: #7ec8e3; }
+    .diff-arrow { color: var(--text-dim); }
+    .diff-val   { color: var(--text); }
+    .diff-old   { color: var(--remove); text-decoration: line-through; opacity: .7; }
+    .diff-new   { color: var(--add); }
+
+    /* scrollbar */
+    ::-webkit-scrollbar { width: 5px; height: 5px; }
+    ::-webkit-scrollbar-track { background: transparent; }
+    ::-webkit-scrollbar-thumb { background: var(--border2); border-radius: 3px; }
+    ::-webkit-scrollbar-thumb:hover { background: var(--text-dim); }
+  </style>
+</head>
+<body>
+  <div id="app">
+    <!-- Topbar -->
+    <div id="topbar">
+      <div class="logo"><span class="dot"></span> valtio inspector</div>
+      <div class="spacer"></div>
+      <div class="status-pill" id="status-pill"><span class="led"></span><span id="status-text">disconnected</span></div>
+      <button id="btn-clear">⌫ clear</button>
+    </div>
+
+    <!-- Sidebar: stores -->
+    <div id="sidebar">
+      <div id="sidebar-head">Stores</div>
+      <div id="store-list"></div>
+    </div>
+
+    <!-- Main panel -->
+    <div id="main">
+      <div id="main-head">
+        <span class="store-label" id="main-title">—</span>
+        <span class="store-tag" id="main-tag">no store selected</span>
+      </div>
+      <div id="tabs">
+        <div class="tab active" data-tab="tree">Tree</div>
+        <div class="tab" data-tab="raw">Raw JSON</div>
+        <div class="tab" data-tab="diff">Last Diff</div>
+      </div>
+      <div id="view">
+        <div class="empty-state" id="empty-state">
+          <div class="big">◎</div>
+          <div class="hint">No stores connected yet.<br>In your app, call <code>attachInspector(store, { name: 'myStore' })</code> and make sure the inspector server is running.</div>
+        </div>
+        <div id="tree-view" style="display:none"></div>
+        <div id="raw-view" style="display:none"><pre id="raw-content" style="line-height:1.7;color:var(--text-mid)"></pre></div>
+        <div id="diff-view" style="display:none"></div>
+      </div>
+    </div>
+
+    <!-- History panel -->
+    <div id="history-panel">
+      <div id="history-head">
+        <span>History</span>
+        <span id="history-count">0</span>
+      </div>
+      <div id="history-list"></div>
+    </div>
+  </div>
+
+  <script src="app.js"></script>
+</body>
+</html>

package/dist/attachInspector.d.ts

@@ -0,0 +1,19 @@
+type AttachOptions = {
+    /** Display name for this store in the inspector */
+    name: string;
+    /** Debounce delay in ms (default: 100) */
+    debounce?: number;
+    /** Custom inspector URL (default: http://localhost:7777) */
+    inspectorUrl?: string;
+};
+/**
+ * Attach a Valtio proxy store to the inspector.
+ *
+ * Usage:
+ *   attachInspector(myStore, { name: 'auth' })
+ *
+ * ⚠️  Wrap in process.env.NODE_ENV !== 'production' to exclude from builds.
+ */
+export declare function attachInspector(state: object, options: AttachOptions): () => void;
+export {};
+//# sourceMappingURL=attachInspector.d.ts.map

package/dist/attachInspector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachInspector.d.ts","sourceRoot":"","sources":["../src/attachInspector.ts"],"names":[],"mappings":"AAEA,KAAK,aAAa,GAAG;IACnB,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAA;IACZ,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,4DAA4D;IAC5D,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB,CAAA;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,aAAa,GACrB,MAAM,IAAI,CAmFZ"}

package/dist/attachInspector.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.attachInspector = attachInspector;
+const valtio_1 = require("valtio");
+/**
+ * Attach a Valtio proxy store to the inspector.
+ *
+ * Usage:
+ *   attachInspector(myStore, { name: 'auth' })
+ *
+ * ⚠️  Wrap in process.env.NODE_ENV !== 'production' to exclude from builds.
+ */
+function attachInspector(state, options) {
+    if (typeof window === 'undefined' && typeof process !== 'undefined') {
+        // Node.js / SSR — skip silently
+        return () => { };
+    }
+    const { name, debounce = 100, inspectorUrl = 'http://localhost:7777' } = options;
+    const wsUrl = inspectorUrl.replace('http', 'ws');
+    let timeout = null;
+    let ws = null;
+    let reconnectAttempts = 0;
+    const queue = [];
+    function connect() {
+        ws = new WebSocket(wsUrl);
+        ws.onopen = () => {
+            reconnectAttempts = 0;
+            // flush queue
+            while (queue.length) {
+                ws.send(JSON.stringify(queue.shift()));
+            }
+        };
+        ws.onclose = () => {
+            const delay = Math.min(1000 * 2 ** reconnectAttempts, 10000);
+            reconnectAttempts++;
+            setTimeout(connect, delay);
+        };
+        ws.onerror = () => {
+            ws?.close();
+        };
+    }
+    function send() {
+        const payload = {
+            store: name,
+            data: (0, valtio_1.snapshot)(state)
+        };
+        // try WS first
+        if (ws && ws.readyState === WebSocket.OPEN) {
+            ws.send(JSON.stringify(payload));
+        }
+        else {
+            // queue for later
+            queue.push(payload);
+            // fallback to HTTP (optional)
+            fetch(`${inspectorUrl}/state`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(payload)
+            }).catch(() => {
+                // Inspector not running — fail silently
+            });
+        }
+    }
+    // init connection
+    connect();
+    // Send initial snapshot immediately
+    send();
+    const unsubscribe = (0, valtio_1.subscribe)(state, () => {
+        if (timeout)
+            clearTimeout(timeout);
+        timeout = setTimeout(send, debounce);
+    });
+    return () => {
+        if (timeout)
+            clearTimeout(timeout);
+        unsubscribe();
+        ws?.close();
+    };
+}
+//# sourceMappingURL=attachInspector.js.map

package/dist/attachInspector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachInspector.js","sourceRoot":"","sources":["../src/attachInspector.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const server_1 = require("./server");
+(0, server_1.startServer)();
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";;;AAEA,qCAAuC;AAEvC,IAAA,oBAAW,GAAE,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { attachInspector } from './attachInspector';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA"}

package/dist/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.attachInspector = void 0;
+var attachInspector_1 = require("./attachInspector");
+Object.defineProperty(exports, "attachInspector", { enumerable: true, get: function () { return attachInspector_1.attachInspector; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,qDAAmD;AAA1C,kHAAA,eAAe,OAAA"}

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+export declare function startServer(port?: number): void;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAMA,wBAAgB,WAAW,CAAC,IAAI,GAAE,MAAa,QAwH9C"}

package/dist/server.js

@@ -0,0 +1,107 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startServer = startServer;
+const express_1 = __importDefault(require("express"));
+const ws_1 = require("ws");
+const http_1 = __importDefault(require("http"));
+const path_1 = __importDefault(require("path"));
+const cors_1 = __importDefault(require("cors"));
+function startServer(port = 7777) {
+    const app = (0, express_1.default)();
+    app.use((0, cors_1.default)({
+        origin: 'http://localhost:5173'
+    }));
+    app.use(express_1.default.json());
+    const server = http_1.default.createServer(app);
+    const wss = new ws_1.WebSocketServer({ server });
+    let stateTree = {};
+    let history = [];
+    let historyIdCounter = 0;
+    const MAX_HISTORY = 100;
+    function computeDiff(prev, next) {
+        if (!prev)
+            return null;
+        const diff = {};
+        const allKeys = new Set([...Object.keys(prev || {}), ...Object.keys(next || {})]);
+        for (const key of allKeys) {
+            if (JSON.stringify(prev[key]) !== JSON.stringify(next[key])) {
+                diff[key] = { from: prev[key], to: next[key] };
+            }
+        }
+        return Object.keys(diff).length > 0 ? diff : null;
+    }
+    function broadcast(payload) {
+        const msg = JSON.stringify(payload);
+        wss.clients.forEach(client => {
+            if (client.readyState === ws_1.WebSocket.OPEN) {
+                client.send(msg);
+            }
+        });
+    }
+    app.post('/state', (req, res) => {
+        const { store, data } = req.body;
+        if (!store || data === undefined) {
+            res.sendStatus(400);
+            return;
+        }
+        const prev = stateTree[store];
+        stateTree[store] = data;
+        const diff = computeDiff(prev, data);
+        const entry = {
+            id: ++historyIdCounter,
+            timestamp: Date.now(),
+            store,
+            state: JSON.parse(JSON.stringify(stateTree)),
+            diff: diff ?? undefined
+        };
+        history.push(entry);
+        if (history.length > MAX_HISTORY) {
+            history.shift();
+        }
+        broadcast({
+            type: 'STATE_UPDATE',
+            state: stateTree,
+            entry: { id: entry.id, timestamp: entry.timestamp, store, diff }
+        });
+        res.sendStatus(200);
+    });
+    app.get('/history', (_req, res) => res.json(history));
+    app.get('/history/:id', (req, res) => {
+        const id = parseInt(req.params.id);
+        const entry = history.find(h => h.id === id);
+        if (!entry) {
+            res.sendStatus(404);
+            return;
+        }
+        res.json(entry);
+    });
+    app.get('/state', (_req, res) => res.json(stateTree));
+    app.delete('/state', (_req, res) => {
+        stateTree = {};
+        history = [];
+        broadcast({ type: 'CLEAR' });
+        res.sendStatus(200);
+    });
+    app.use(express_1.default.static(path_1.default.join(__dirname, '../client')));
+    wss.on('connection', (ws) => {
+        ws.send(JSON.stringify({
+            type: 'INIT',
+            state: stateTree,
+            history: history.map(h => ({
+                id: h.id,
+                timestamp: h.timestamp,
+                store: h.store,
+                diff: h.diff
+            }))
+        }));
+    });
+    server.listen(port, () => {
+        console.log('\x1b[36m%s\x1b[0m', `  ▶  Valtio Inspector → http://localhost:${port}`);
+        console.log('\x1b[90m%s\x1b[0m', `     WebSocket ready on ws://localhost:${port}`);
+    });
+}
+// startServer()
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/example.ts

@@ -0,0 +1,53 @@
+/**
+ * Example: how to wire up valtio stores with the inspector
+ * Drop this into your app as a reference.
+ */
+
+import { proxy } from 'valtio'
+import { attachInspector } from './instrument/attachInspector'
+
+// ── Define your stores ──────────────────────────────────────────────────────
+
+export const authStore = proxy({
+  user: { id: 1, name: 'kfir', email: 'kfir@example.com' },
+  isLoggedIn: false,
+  token: null as string | null
+})
+
+export const uiStore = proxy({
+  darkMode: true,
+  sidebarOpen: false,
+  activeModal: null as string | null,
+  notifications: [] as string[]
+})
+
+export const cartStore = proxy({
+  items: [] as Array<{ id: string; name: string; qty: number; price: number }>,
+  coupon: null as string | null
+})
+
+// ── Attach inspector (dev only) ─────────────────────────────────────────────
+
+if (process.env.NODE_ENV !== 'production') {
+  attachInspector(authStore, { name: 'auth' })
+  attachInspector(uiStore,   { name: 'ui' })
+  attachInspector(cartStore, { name: 'cart' })
+}
+
+// ── Test: mutate stores after 1 second ─────────────────────────────────────
+// (remove in real app)
+
+setTimeout(() => {
+  authStore.isLoggedIn = true
+  authStore.token = 'jwt_abc123'
+}, 1000)
+
+setTimeout(() => {
+  uiStore.sidebarOpen = true
+  uiStore.activeModal = 'checkout'
+}, 2000)
+
+setTimeout(() => {
+  cartStore.items.push({ id: 'p1', name: 'Mechanical Keyboard', qty: 1, price: 149.99 })
+  cartStore.items.push({ id: 'p2', name: 'USB-C Hub', qty: 2, price: 34.99 })
+}, 3000)

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@kfiross44/valtio-inspector",
+  "version": "0.9.0",
+  "description": "A dev-only Valtio state inspector with WebSocket live updates",
+  "main": "dist/server/index.js",
+  "bin": {
+    "valtio-inspector": "dist/cli.js"
+  },
+  "scripts": {
+    "dev": "ts-node server/index.ts",
+    "build": "tsc",
+    "release": "bun run build && changeset publish",
+    "start": "node dist/server/index.js"
+  },
+  "dependencies": {
+    "cors": "^2.8.6",
+    "express": "^4.18.2",
+    "ws": "^8.16.0"
+  },
+  "peerDependencies": {
+    "valtio": "^2.0.0"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.30.0",
+    "@types/cors": "^2.8.19",
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.19.39",
+    "@types/ws": "^8.5.10",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.3.3"
+  }
+}

package/script/build.ts

@@ -0,0 +1,14 @@
+import { Glob, $ } from 'bun'
+
+await $`rm -rf dist`
+const files = new Glob('./src/**/*.{ts,tsx}').scan()
+for await (const file of files) {
+  await Bun.build({
+    format: 'esm',
+    outdir: 'dist/esm',
+    external: ['*'],
+    root: 'src',
+    entrypoints: [file],
+  })
+}
+await $`tsc --outDir dist/types --declaration --emitDeclarationOnly --declarationMap`

package/script/changelog.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+
+# Get the package version from package.json
+PACKAGE_VERSION=$(node -p -e "require('./package.json').version || ''")
+
+# Check if PACKAGE_VERSION is empty
+if [ -z "$PACKAGE_VERSION" ]; then
+  echo "Error: Failed to retrieve version from package.json"
+  exit 1
+fi
+
+# Run git-cliff with the correct tag
+bun x git-cliff -o './CHANGELOG.md' --tag "$PACKAGE_VERSION"

package/src/attachInspector.ts

@@ -0,0 +1,106 @@
+import { subscribe, snapshot } from 'valtio'
+
+type AttachOptions = {
+  /** Display name for this store in the inspector */
+  name: string
+  /** Debounce delay in ms (default: 100) */
+  debounce?: number
+  /** Custom inspector URL (default: http://localhost:7777) */
+  inspectorUrl?: string
+}
+
+/**
+ * Attach a Valtio proxy store to the inspector.
+ *
+ * Usage:
+ *   attachInspector(myStore, { name: 'auth' })
+ *
+ * ⚠️  Wrap in process.env.NODE_ENV !== 'production' to exclude from builds.
+ */
+export function attachInspector(
+  state: object,
+  options: AttachOptions
+): () => void {
+  if (typeof window === 'undefined' && typeof process !== 'undefined') {
+    // Node.js / SSR — skip silently
+    return () => {}
+  }
+
+  const {
+    name,
+    debounce = 100,
+    inspectorUrl = 'http://localhost:7777'
+  } = options
+
+  const wsUrl = inspectorUrl.replace('http', 'ws')
+
+  let timeout: ReturnType<typeof setTimeout> | null = null
+  let ws: WebSocket | null = null
+  let reconnectAttempts = 0
+  const queue: any[] = []
+
+  function connect() {
+    ws = new WebSocket(wsUrl)
+
+    ws.onopen = () => {
+      reconnectAttempts = 0
+
+      // flush queue
+      while (queue.length) {
+        ws!.send(JSON.stringify(queue.shift()))
+      }
+    }
+
+    ws.onclose = () => {
+      const delay = Math.min(1000 * 2 ** reconnectAttempts, 10000)
+      reconnectAttempts++
+
+      setTimeout(connect, delay)
+    }
+
+    ws.onerror = () => {
+      ws?.close()
+    }
+  }
+
+  function send() {
+    const payload = {
+      store: name,
+      data: snapshot(state)
+    }
+
+    // try WS first
+    if (ws && ws.readyState === WebSocket.OPEN) {
+      ws.send(JSON.stringify(payload))
+    } else {
+      // queue for later
+      queue.push(payload)
+
+      // fallback to HTTP (optional)
+      fetch(`${inspectorUrl}/state`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(payload)
+      }).catch(() => {
+        // Inspector not running — fail silently
+      })
+    }
+  }
+
+  // init connection
+  connect()
+
+  // Send initial snapshot immediately
+  send()
+
+  const unsubscribe = subscribe(state, () => {
+    if (timeout) clearTimeout(timeout)
+    timeout = setTimeout(send, debounce)
+  })
+
+  return () => {
+    if (timeout) clearTimeout(timeout)
+    unsubscribe()
+    ws?.close()
+  }
+}

package/src/cli.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { startServer } from './server';
+
+startServer();

package/src/index.ts

@@ -0,0 +1 @@
+export { attachInspector } from './attachInspector'

package/src/server.ts

@@ -0,0 +1,129 @@
+import express from 'express'
+import { WebSocketServer, WebSocket } from 'ws'
+import http from 'http'
+import path from 'path'
+import cors from 'cors'
+
+export function startServer(port: number = 7777) {
+  const app = express()
+
+  app.use(cors({
+    origin: 'http://localhost:5173'
+  }))
+
+  app.use(express.json())
+
+  const server = http.createServer(app)
+  const wss = new WebSocketServer({ server })
+
+  interface HistoryEntry {
+    id: number
+    timestamp: number
+    store: string
+    state: Record<string, any>
+    diff?: Record<string, any>
+  }
+
+  let stateTree: Record<string, any> = {}
+  let history: HistoryEntry[] = []
+  let historyIdCounter = 0
+  const MAX_HISTORY = 100
+
+  function computeDiff(prev: any, next: any): Record<string, any> | null {
+    if (!prev) return null
+    const diff: Record<string, any> = {}
+    const allKeys = new Set([...Object.keys(prev || {}), ...Object.keys(next || {})])
+    for (const key of allKeys) {
+      if (JSON.stringify(prev[key]) !== JSON.stringify(next[key])) {
+        diff[key] = { from: prev[key], to: next[key] }
+      }
+    }
+    return Object.keys(diff).length > 0 ? diff : null
+  }
+
+  function broadcast(payload: object) {
+    const msg = JSON.stringify(payload)
+    wss.clients.forEach(client => {
+      if (client.readyState === WebSocket.OPEN) {
+        client.send(msg)
+      }
+    })
+  }
+
+  app.post('/state', (req, res) => {
+    const { store, data } = req.body
+    if (!store || data === undefined) {
+      res.sendStatus(400)
+      return
+    }
+
+    const prev = stateTree[store]
+    stateTree[store] = data
+
+    const diff = computeDiff(prev, data)
+
+    const entry: HistoryEntry = {
+      id: ++historyIdCounter,
+      timestamp: Date.now(),
+      store,
+      state: JSON.parse(JSON.stringify(stateTree)),
+      diff: diff ?? undefined
+    }
+
+    history.push(entry)
+    if (history.length > MAX_HISTORY) {
+      history.shift()
+    }
+
+    broadcast({
+      type: 'STATE_UPDATE',
+      state: stateTree,
+      entry: { id: entry.id, timestamp: entry.timestamp, store, diff }
+    })
+
+    res.sendStatus(200)
+  })
+
+  app.get('/history', (_req, res) => res.json(history))
+
+  app.get('/history/:id', (req, res) => {
+    const id = parseInt(req.params.id)
+    const entry = history.find(h => h.id === id)
+    if (!entry) {
+      res.sendStatus(404)
+      return
+    }
+    res.json(entry)
+  })
+
+  app.get('/state', (_req, res) => res.json(stateTree))
+
+  app.delete('/state', (_req, res) => {
+    stateTree = {}
+    history = []
+    broadcast({ type: 'CLEAR' })
+    res.sendStatus(200)
+  })
+
+  app.use(express.static(path.join(__dirname, '../client')))
+
+  wss.on('connection', (ws) => {
+    ws.send(JSON.stringify({
+      type: 'INIT',
+      state: stateTree,
+      history: history.map(h => ({
+        id: h.id,
+        timestamp: h.timestamp,
+        store: h.store,
+        diff: h.diff
+      }))
+    }))
+  })
+
+  server.listen(port, () => {
+    console.log('\x1b[36m%s\x1b[0m', `  ▶  Valtio Inspector → http://localhost:${port}`)
+    console.log('\x1b[90m%s\x1b[0m', `     WebSocket ready on ws://localhost:${port}`)
+  })
+}
+
+// startServer()

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020", "DOM"],
+    "rootDir": "src",
+    "outDir": "dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist", "client"]
+}