@everystate/perf 1.0.0 → 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ajdin Imsirovic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -13,10 +13,10 @@ npm install @everystate/perf @everystate/core
 ## Quick Start
 
 ```js
-import { createEventState } from '@everystate/core';
+import { createEveryState } from '@everystate/core';
 import { createPerfMonitor, mountOverlay } from '@everystate/perf';
 
-const store = createEventState({ count: 0 });
+const store = createEveryState({ count: 0 });
 
 // Wrap store with performance monitoring
 const monitor = createPerfMonitor(store, {
@@ -59,6 +59,21 @@ store.set = function(path, value) {
 
 Fully reversible via `monitor.destroy()`.
 
+## Ecosystem
+
+| Package | Description | License |
+|---|---|---|
+| [@everystate/aliases](https://www.npmjs.com/package/@everystate/aliases) | Ergonomic single-character and short-name DOM aliases for vanilla JS | MIT |
+| [@everystate/core](https://www.npmjs.com/package/@everystate/core) | Path-based state management with wildcard subscriptions and async support. Core state engine (you are here). | MIT |
+| [@everystate/css](https://www.npmjs.com/package/@everystate/css) | Reactive CSSOM engine: design tokens, typed validation, WCAG enforcement, all via path-based state | MIT |
+| [@everystate/examples](https://www.npmjs.com/package/@everystate/examples) | Example applications and patterns | MIT |
+| [@everystate/perf](https://www.npmjs.com/package/@everystate/perf) | Performance monitoring overlay | MIT |
+| [@everystate/react](https://www.npmjs.com/package/@everystate/react) | React hooks adapter: `usePath`, `useIntent`, `useAsync` hooks and `EveryStateProvider` | MIT |
+| [@everystate/renderer](https://www.npmjs.com/package/@everystate/renderer) | Direct-binding reactive renderer: `bind-*`, `set`, `each` attributes. Zero build step | Proprietary |
+| [@everystate/router](https://www.npmjs.com/package/@everystate/router) | SPA routing as state | MIT |
+| [@everystate/test](https://www.npmjs.com/package/@everystate/test) | Event-sequence testing for EveryState stores. Zero dependency. | Proprietary |
+| [@everystate/view](https://www.npmjs.com/package/@everystate/view) | State-driven view: DOMless resolve + surgical DOM projector. View tree as first-class state | MIT |
+
 ## License
 
 MIT © Ajdin Imsirovic

package/index.js

@@ -1,8 +1,6 @@
 /**
  * @everystate/perf
- *
- * EveryState wrapper for @uistate/perf
- * Re-exports all functionality from the underlying @uistate/perf package
  */
 
-export * from '@uistate/perf';
+export { createPerfMonitor } from './perfMonitor.js';
+export { mountOverlay } from './overlay.js';

package/overlay.js

@@ -0,0 +1,540 @@
+/**
+ * @everystate/perf: overlay.js
+ *
+ * Floating browser overlay that displays live perf stats from a perfMonitor.
+ * Inject into any EveryState-powered page with: perf.mount(document.body)
+ *
+ * Copyright (c) 2026 Ajdin Imsirovic. MIT License.
+ */
+
+const STYLES = `
+  .uiperf-overlay {
+    font-family: monospace; font-size: 10px; color: #c9d1d9;
+    background: #0d1117; border: 1px solid #30363d; border-radius: 8px;
+    box-shadow: 0 4px 24px rgba(0,0,0,0.5); width: 380px;
+    max-height: 80vh; display: flex; flex-direction: column;
+    user-select: none; overflow: hidden;
+  }
+  .uiperf-overlay.collapsed { max-height: 32px; }
+  .uiperf-overlay.collapsed .uiperf-body,
+  .uiperf-overlay.collapsed .uiperf-tabs,
+  .uiperf-overlay.collapsed .uiperf-tree-panel { display: none; }
+
+  .uiperf-header {
+    display: flex; align-items: center; gap: 6px;
+    padding: 6px 10px; background: #161b22; border-bottom: 1px solid #30363d;
+    cursor: grab; flex-shrink: 0;
+  }
+  .uiperf-header:active { cursor: grabbing; }
+  .uiperf-title { color: #58a6ff; font-weight: 700; font-size: 11px; flex: 1; }
+  .uiperf-badge {
+    background: #1f6feb; color: #fff; padding: 1px 6px;
+    border-radius: 9px; font-size: 9px;
+  }
+  .uiperf-btn {
+    background: #21262d; color: #c9d1d9; border: 1px solid #30363d;
+    padding: 2px 6px; border-radius: 3px; cursor: pointer; font-family: monospace;
+    font-size: 9px;
+  }
+  .uiperf-btn:hover { background: #30363d; }
+  .uiperf-btn.download { background: #238636; border-color: #2ea043; }
+  .uiperf-btn.download:hover { background: #2ea043; }
+
+  /* Tabs */
+  .uiperf-tabs {
+    display: flex; gap: 0; border-bottom: 1px solid #21262d;
+    background: #0d1117; flex-shrink: 0;
+  }
+  .uiperf-tab {
+    flex: 1; padding: 5px 0; text-align: center; font-family: monospace;
+    font-size: 10px; font-weight: 600; color: #8b949e; background: transparent;
+    border: none; border-bottom: 2px solid transparent; cursor: pointer;
+    transition: color 0.15s, border-color 0.15s;
+  }
+  .uiperf-tab:hover { color: #c9d1d9; }
+  .uiperf-tab.active { color: #58a6ff; border-bottom-color: #58a6ff; }
+
+  .uiperf-body {
+    overflow-y: auto; flex: 1; padding: 8px 10px;
+  }
+
+  .uiperf-section { margin-top: 8px; padding-top: 6px; border-top: 1px solid #21262d; }
+  .uiperf-section:first-child { margin-top: 0; padding-top: 0; border-top: none; }
+  .uiperf-section-title { color: #d2a8ff; font-weight: 600; margin-bottom: 4px; }
+
+  .uiperf-row { display: flex; justify-content: space-between; line-height: 1.6; }
+  .uiperf-label { color: #8b949e; }
+  .uiperf-val { color: #79c0ff; }
+  .uiperf-val.hot { color: #f0883e; }
+  .uiperf-val.ok { color: #3fb950; }
+
+  .uiperf-table { width: 100%; border-collapse: collapse; margin-top: 4px; }
+  .uiperf-table th {
+    text-align: left; color: #8b949e; border-bottom: 1px solid #21262d;
+    padding: 2px 4px; font-weight: normal;
+  }
+  .uiperf-table td { padding: 2px 4px; }
+  .uiperf-table tr:hover { background: #161b22; }
+  .uiperf-path { color: #a5d6ff; max-width: 160px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .uiperf-num { color: #79c0ff; text-align: right; }
+  .uiperf-ms { color: #3fb950; text-align: right; }
+
+  .uiperf-bar-wrap { height: 3px; background: #21262d; border-radius: 2px; margin-top: 1px; }
+  .uiperf-bar { height: 3px; background: #1f6feb; border-radius: 2px; transition: width 0.3s; }
+
+  /* State Tree panel */
+  .uiperf-tree-panel {
+    display: none; flex-direction: column; flex: 1; overflow: hidden;
+  }
+  .uiperf-tree-panel.visible { display: flex; }
+  .uiperf-tree-toolbar {
+    display: flex; gap: 4px; padding: 6px 10px;
+    border-bottom: 1px solid #21262d; flex-shrink: 0; align-items: center;
+  }
+  .uiperf-tree-toolbar .uiperf-btn { font-size: 9px; }
+  .uiperf-tree-toolbar .sel-label {
+    flex: 1; font-size: 9px; color: #8b949e;
+    overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+  }
+  .uiperf-tree-scroll {
+    overflow-y: auto; flex: 1; padding: 4px 0;
+  }
+  .uiperf-tnode {
+    line-height: 1.7; white-space: nowrap; padding: 0 10px;
+    cursor: default;
+  }
+  .uiperf-tnode:hover { background: #161b22; }
+  .uiperf-tnode.selected { background: #1c2536; }
+  .uiperf-tnode .arrow {
+    display: inline-block; width: 12px; text-align: center;
+    color: #484f58; cursor: pointer; user-select: none;
+  }
+  .uiperf-tnode .arrow:hover { color: #c9d1d9; }
+  .uiperf-tnode .tkey { color: #d2a8ff; }
+  .uiperf-tnode .tcolon { color: #484f58; }
+  .uiperf-tnode .tval { color: #a5d6ff; }
+  .uiperf-tnode .tval.str { color: #a5d6ff; }
+  .uiperf-tnode .tval.num { color: #79c0ff; }
+  .uiperf-tnode .tval.bool { color: #f0883e; }
+  .uiperf-tnode .tval.null { color: #484f58; font-style: italic; }
+  .uiperf-tnode .tval.obj { color: #8b949e; }
+  .uiperf-copy-toast {
+    position: absolute; bottom: 8px; left: 50%; transform: translateX(-50%);
+    background: #238636; color: #fff; padding: 3px 12px; border-radius: 4px;
+    font-size: 9px; pointer-events: none; opacity: 0; transition: opacity 0.2s;
+  }
+  .uiperf-copy-toast.show { opacity: 1; }
+`;
+
+export function mountOverlay(monitor, container) {
+  if (typeof document === 'undefined') return () => {};
+
+  // Shadow DOM host - fully encapsulates styles
+  const host = document.createElement('div');
+  host.style.cssText = 'position:fixed;bottom:12px;right:12px;z-index:99999;';
+  container.appendChild(host);
+  const shadow = host.attachShadow({ mode: 'open' });
+
+  // Styles live inside shadow - no leaking in or out
+  const styleEl = document.createElement('style');
+  styleEl.textContent = STYLES;
+  shadow.appendChild(styleEl);
+
+  // Build DOM inside shadow
+  const overlay = document.createElement('div');
+  overlay.className = 'uiperf-overlay';
+  overlay.style.position = 'relative';
+  overlay.innerHTML = `
+    <div class="uiperf-header">
+      <span class="uiperf-title">@everystate/perf</span>
+      <span class="uiperf-badge" id="uiperf-live">0 events</span>
+      <button class="uiperf-btn" id="uiperf-toggle">_</button>
+      <button class="uiperf-btn" id="uiperf-reset">↺</button>
+      <button class="uiperf-btn download" id="uiperf-dl">↓ JSON</button>
+    </div>
+    <div class="uiperf-tabs">
+      <button class="uiperf-tab active" data-tab="perf">Perf</button>
+      <button class="uiperf-tab" data-tab="tree">State Tree</button>
+    </div>
+    <div class="uiperf-body" id="uiperf-body"></div>
+    <div class="uiperf-tree-panel" id="uiperf-tree-panel">
+      <div class="uiperf-tree-toolbar">
+        <span class="sel-label" id="uiperf-sel-label">none selected</span>
+        <button class="uiperf-btn" id="uiperf-copy-sub">Copy Sub</button>
+        <button class="uiperf-btn" id="uiperf-copy-all">Copy All</button>
+        <button class="uiperf-btn" id="uiperf-tree-refresh">↺</button>
+      </div>
+      <div class="uiperf-tree-scroll" id="uiperf-tree-scroll"></div>
+    </div>
+    <div class="uiperf-copy-toast" id="uiperf-toast">Copied!</div>
+  `;
+  shadow.appendChild(overlay);
+
+  const body = shadow.querySelector('#uiperf-body');
+  const liveEl = shadow.querySelector('#uiperf-live');
+  const toggleBtn = shadow.querySelector('#uiperf-toggle');
+  const resetBtn = shadow.querySelector('#uiperf-reset');
+  const dlBtn = shadow.querySelector('#uiperf-dl');
+  const treePanel = shadow.querySelector('#uiperf-tree-panel');
+  const treeScroll = shadow.querySelector('#uiperf-tree-scroll');
+  const selLabel = shadow.querySelector('#uiperf-sel-label');
+  const copySubBtn = shadow.querySelector('#uiperf-copy-sub');
+  const copyAllBtn = shadow.querySelector('#uiperf-copy-all');
+  const treeRefreshBtn = shadow.querySelector('#uiperf-tree-refresh');
+  const toast = shadow.querySelector('#uiperf-toast');
+  const tabs = shadow.querySelectorAll('.uiperf-tab');
+
+  // Toggle collapse
+  let collapsed = false;
+  toggleBtn.addEventListener('click', () => {
+    collapsed = !collapsed;
+    overlay.classList.toggle('collapsed', collapsed);
+    toggleBtn.textContent = collapsed ? '□' : '_';
+  });
+
+  // Reset
+  resetBtn.addEventListener('click', () => {
+    monitor.reset();
+    render();
+  });
+
+  // Download
+  dlBtn.addEventListener('click', () => {
+    monitor.download();
+  });
+
+  // ==== Tab switching ====
+  let activeTab = 'perf';
+  tabs.forEach(tab => {
+    tab.addEventListener('click', () => {
+      activeTab = tab.dataset.tab;
+      tabs.forEach(t => t.classList.toggle('active', t.dataset.tab === activeTab));
+      body.style.display = activeTab === 'perf' ? '' : 'none';
+      treePanel.classList.toggle('visible', activeTab === 'tree');
+      if (activeTab === 'tree') renderTree();
+    });
+  });
+
+  // ==== State Tree ====
+  const collapsedPaths = new Set();
+  let selectedPath = null;
+
+  function showToast(msg) {
+    toast.textContent = msg || 'Copied!';
+    toast.classList.add('show');
+    setTimeout(() => toast.classList.remove('show'), 1200);
+  }
+
+  function copyToClipboard(text) {
+    if (navigator.clipboard && navigator.clipboard.writeText) {
+      navigator.clipboard.writeText(text).then(() => showToast(), () => fallbackCopy(text));
+    } else {
+      fallbackCopy(text);
+    }
+  }
+
+  function fallbackCopy(text) {
+    const ta = document.createElement('textarea');
+    ta.value = text;
+    ta.style.cssText = 'position:fixed;left:-9999px';
+    document.body.appendChild(ta);
+    ta.select();
+    try { document.execCommand('copy'); showToast(); } catch(e) { showToast('Copy failed'); }
+    document.body.removeChild(ta);
+  }
+
+  function getSubtreeAtPath(obj, dotPath) {
+    if (!dotPath) return obj;
+    const parts = dotPath.split('.');
+    let cur = obj;
+    for (const p of parts) {
+      if (cur == null || typeof cur !== 'object') return undefined;
+      cur = cur[p];
+    }
+    return cur;
+  }
+
+  function valClass(v) {
+    if (v === null || v === undefined) return 'null';
+    if (typeof v === 'string') return 'str';
+    if (typeof v === 'number') return 'num';
+    if (typeof v === 'boolean') return 'bool';
+    return 'obj';
+  }
+
+  function valDisplay(v) {
+    if (v === null) return 'null';
+    if (v === undefined) return 'undefined';
+    if (typeof v === 'string') return v.length > 60 ? '"' + v.slice(0,57) + '..."' : '"' + v + '"';
+    if (typeof v === 'number' || typeof v === 'boolean') return String(v);
+    if (Array.isArray(v)) return `Array(${v.length})`;
+    if (typeof v === 'object') {
+      const keys = Object.keys(v);
+      return `{${keys.length} key${keys.length !== 1 ? 's' : ''}}`;
+    }
+    return String(v);
+  }
+
+  function isExpandable(v) {
+    return v != null && typeof v === 'object' && (Array.isArray(v) ? v.length > 0 : Object.keys(v).length > 0);
+  }
+
+  function renderTree() {
+    const store = monitor.store;
+    if (!store) {
+      treeScroll.innerHTML = '<div style="padding:10px;color:#8b949e">No store reference available</div>';
+      return;
+    }
+    const state = store.get();
+    treeScroll.innerHTML = '';
+    buildTreeNodes(state, '', 0, treeScroll);
+    updateSelLabel();
+  }
+
+  function buildTreeNodes(obj, parentPath, depth, container) {
+    if (obj == null || typeof obj !== 'object') return;
+    const keys = Object.keys(obj);
+    for (const key of keys) {
+      const fullPath = parentPath ? parentPath + '.' + key : key;
+      const value = obj[key];
+      const expandable = isExpandable(value);
+      const isCollapsed = collapsedPaths.has(fullPath);
+
+      const row = document.createElement('div');
+      row.className = 'uiperf-tnode' + (selectedPath === fullPath ? ' selected' : '');
+      row.style.paddingLeft = (10 + depth * 14) + 'px';
+      row.dataset.path = fullPath;
+
+      // Arrow
+      const arrow = document.createElement('span');
+      arrow.className = 'arrow';
+      if (expandable) {
+        arrow.textContent = isCollapsed ? '▶' : '▼';
+        arrow.addEventListener('click', (e) => {
+          e.stopPropagation();
+          if (collapsedPaths.has(fullPath)) collapsedPaths.delete(fullPath);
+          else collapsedPaths.add(fullPath);
+          renderTree();
+        });
+      } else {
+        arrow.textContent = ' ';
+      }
+      row.appendChild(arrow);
+
+      // Key
+      const keySpan = document.createElement('span');
+      keySpan.className = 'tkey';
+      keySpan.textContent = key;
+      row.appendChild(keySpan);
+
+      // Colon
+      const colon = document.createElement('span');
+      colon.className = 'tcolon';
+      colon.textContent = ': ';
+      row.appendChild(colon);
+
+      // Value
+      const valSpan = document.createElement('span');
+      valSpan.className = 'tval ' + valClass(value);
+      if (expandable && !isCollapsed) {
+        valSpan.textContent = Array.isArray(value) ? '[' : '{';
+      } else {
+        valSpan.textContent = valDisplay(value);
+      }
+      row.appendChild(valSpan);
+
+      // Click to select
+      row.addEventListener('click', () => {
+        selectedPath = selectedPath === fullPath ? null : fullPath;
+        treeScroll.querySelectorAll('.uiperf-tnode').forEach(n => {
+          n.classList.toggle('selected', n.dataset.path === selectedPath);
+        });
+        updateSelLabel();
+      });
+
+      container.appendChild(row);
+
+      // Recurse if expanded
+      if (expandable && !isCollapsed) {
+        buildTreeNodes(value, fullPath, depth + 1, container);
+        // Closing bracket
+        const closer = document.createElement('div');
+        closer.className = 'uiperf-tnode';
+        closer.style.paddingLeft = (10 + depth * 14) + 'px';
+        closer.innerHTML = '<span class="arrow"> </span><span class="tval obj">' + (Array.isArray(value) ? ']' : '}') + '</span>';
+        container.appendChild(closer);
+      }
+    }
+  }
+
+  function updateSelLabel() {
+    selLabel.textContent = selectedPath ? selectedPath : 'none selected';
+    selLabel.title = selectedPath || '';
+  }
+
+  // Copy Sub
+  copySubBtn.addEventListener('click', () => {
+    const store = monitor.store;
+    if (!store) return;
+    if (!selectedPath) { showToast('Select a node first'); return; }
+    const sub = getSubtreeAtPath(store.get(), selectedPath);
+    copyToClipboard(JSON.stringify(sub, null, 2));
+  });
+
+  // Copy All
+  copyAllBtn.addEventListener('click', () => {
+    const store = monitor.store;
+    if (!store) return;
+    copyToClipboard(JSON.stringify(store.get(), null, 2));
+  });
+
+  // Tree refresh
+  treeRefreshBtn.addEventListener('click', () => renderTree());
+
+  // Drag support (moves the host element which has position:fixed)
+  let dragX = 0, dragY = 0, isDragging = false;
+  const header = overlay.querySelector('.uiperf-header');
+  header.addEventListener('mousedown', (e) => {
+    if (e.target.tagName === 'BUTTON') return;
+    isDragging = true;
+    dragX = e.clientX - host.offsetLeft;
+    dragY = e.clientY - host.offsetTop;
+  });
+  document.addEventListener('mousemove', (e) => {
+    if (!isDragging) return;
+    host.style.right = 'auto';
+    host.style.bottom = 'auto';
+    host.style.left = (e.clientX - dragX) + 'px';
+    host.style.top = (e.clientY - dragY) + 'px';
+  });
+  document.addEventListener('mouseup', () => { isDragging = false; });
+
+  // Render
+  function render() {
+    const r = monitor.report();
+
+    liveEl.textContent = `${r.totalEvents} events`;
+
+    let html = '';
+
+    // Summary
+    html += `<div class="uiperf-section">`;
+    html += `<div class="uiperf-section-title">Summary</div>`;
+    html += row('Elapsed', fmtMs(r.elapsedMs));
+    html += row('Total sets', r.summary.totalSets);
+    html += row('Total fires', r.summary.totalFires);
+    html += row('Sets/sec', r.summary.setsPerSec, r.summary.setsPerSec > 100 ? 'hot' : 'ok');
+    html += row('Unique paths', r.summary.uniquePaths);
+    html += row('Active subs', r.summary.activeSubscribers);
+    html += row('Subscribes', `${r.summary.totalSubscribes} / unsubs: ${r.summary.totalUnsubscribes}`);
+    html += `</div>`;
+
+    // Batches
+    if (r.batches.count > 0) {
+      html += `<div class="uiperf-section">`;
+      html += `<div class="uiperf-section-title">Batches</div>`;
+      html += row('Batch calls', r.batches.count);
+      html += row('Total paths', r.batches.totalPaths);
+      html += row('Coalesced', r.batches.totalCoalesced, r.batches.totalCoalesced > 0 ? 'ok' : '');
+      html += `</div>`;
+    }
+
+    // Hot paths (top 15)
+    const top = r.hotPaths.slice(0, 15);
+    if (top.length > 0) {
+      const maxSets = top[0].sets || 1;
+      html += `<div class="uiperf-section">`;
+      html += `<div class="uiperf-section-title">Hot Paths (by sets)</div>`;
+      html += `<table class="uiperf-table">`;
+      html += `<tr><th>Path</th><th style="text-align:right">Sets</th><th style="text-align:right">Fires</th><th style="text-align:right">Avg ms</th></tr>`;
+      for (const p of top) {
+        const pct = Math.round((p.sets / maxSets) * 100);
+        html += `<tr>`;
+        html += `<td><span class="uiperf-path" title="${p.path}">${truncPath(p.path)}</span>`;
+        html += `<div class="uiperf-bar-wrap"><div class="uiperf-bar" style="width:${pct}%"></div></div></td>`;
+        html += `<td class="uiperf-num">${p.sets}</td>`;
+        html += `<td class="uiperf-num">${p.fires}</td>`;
+        html += `<td class="uiperf-ms">${p.avgSetMs.toFixed(3)}</td>`;
+        html += `</tr>`;
+      }
+      html += `</table>`;
+      html += `</div>`;
+    }
+
+    // Hot listeners (top 10)
+    const topFires = r.hotListeners.slice(0, 10);
+    if (topFires.length > 0) {
+      html += `<div class="uiperf-section">`;
+      html += `<div class="uiperf-section-title">Hot Listeners (by fires)</div>`;
+      html += `<table class="uiperf-table">`;
+      html += `<tr><th>Path</th><th style="text-align:right">Fires</th><th style="text-align:right">/sec</th></tr>`;
+      for (const p of topFires) {
+        html += `<tr>`;
+        html += `<td class="uiperf-path" title="${p.path}">${truncPath(p.path)}</td>`;
+        html += `<td class="uiperf-num">${p.fires}</td>`;
+        html += `<td class="uiperf-num">${p.firesPerSec}</td>`;
+        html += `</tr>`;
+      }
+      html += `</table>`;
+      html += `</div>`;
+    }
+
+    // Recent events (last 20)
+    const recent = r.timeline.slice(-20).reverse();
+    if (recent.length > 0) {
+      html += `<div class="uiperf-section">`;
+      html += `<div class="uiperf-section-title">Recent Events (${r.totalEvents} total${r.dropped ? `, ${r.dropped} dropped` : ''})</div>`;
+      html += `<table class="uiperf-table">`;
+      html += `<tr><th>Type</th><th>Path</th><th style="text-align:right">ms</th></tr>`;
+      for (const e of recent) {
+        const cls = e.type === 'fire' ? 'hot' : '';
+        html += `<tr>`;
+        html += `<td class="uiperf-val ${cls}">${e.type}</td>`;
+        html += `<td class="uiperf-path" title="${e.path || ''}">${truncPath(e.path || e.paths?.join(', ') || '-')}</td>`;
+        html += `<td class="uiperf-ms">${e.dur !== undefined ? e.dur.toFixed(3) : '-'}</td>`;
+        html += `</tr>`;
+      }
+      html += `</table>`;
+      html += `</div>`;
+    }
+
+    body.innerHTML = html;
+  }
+
+  function row(label, value, cls) {
+    return `<div class="uiperf-row"><span class="uiperf-label">${label}</span><span class="uiperf-val ${cls || ''}">${value}</span></div>`;
+  }
+
+  function fmtMs(ms) {
+    if (ms < 1000) return ms.toFixed(0) + ' ms';
+    return (ms / 1000).toFixed(1) + ' s';
+  }
+
+  function truncPath(p) {
+    if (!p) return '-';
+    return p.length > 28 ? '…' + p.slice(-27) : p;
+  }
+
+  // Auto-refresh at ~2 fps
+  let rafId = null;
+  let lastRender = 0;
+  function tick() {
+    const t = Date.now();
+    if (t - lastRender > 500) {
+      lastRender = t;
+      if (!collapsed) {
+        if (activeTab === 'perf') render();
+        else if (activeTab === 'tree') renderTree();
+      }
+    }
+    rafId = requestAnimationFrame(tick);
+  }
+  rafId = requestAnimationFrame(tick);
+  render();
+
+  // Cleanup
+  return function unmount() {
+    cancelAnimationFrame(rafId);
+    host.remove();
+  };
+}

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@everystate/perf",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "EveryState Performance Monitor: Non-invasive performance monitoring with method wrapping, path heatmaps, timeline recording, browser overlay",
   "type": "module",
   "main": "index.js",
+  "types": "index.d.ts",
   "keywords": [
     "everystate",
     "performance",
@@ -25,7 +26,14 @@
     "type": "git",
     "url": "https://github.com/ImsirovicAjdin/everystate-perf"
   },
-  "dependencies": {
-    "@uistate/perf": "^1.0.0"
-  }
+  "homepage": "https://github.com/ImsirovicAjdin/everystate-perf#readme",
+  "scripts": {
+    "test": "node self-test.js"
+  },
+  "files": [
+    "index.js",
+    "perfMonitor.js",
+    "overlay.js",
+    "README.md"
+  ]
 }

package/perfMonitor.js

@@ -0,0 +1,356 @@
+/**
+ * @everystate/perf: perfMonitor.js
+ *
+ * Non-invasive performance recorder for any EveryState store.
+ * Wraps store methods (prepend pattern) to capture timing, path frequency,
+ * subscriber counts, batch stats, and a full event timeline.
+ *
+ * Usage:
+ *   import { createPerfMonitor } from '@everystate/perf';
+ *   const perf = createPerfMonitor(store);
+ *   perf.mount(document.body);   // optional browser overlay
+ *   perf.download('report.json');
+ *
+ * Copyright (c) 2026 Ajdin Imsirovic. MIT License.
+ */
+
+// == Helpers ================================================================
+
+const now = typeof performance !== 'undefined'
+  ? () => performance.now()
+  : () => Date.now();
+
+function uid() {
+  return Math.random().toString(36).slice(2, 10);
+}
+
+// == createPerfMonitor ======================================================
+
+export function createPerfMonitor(store, options = {}) {
+  const {
+    maxEvents = 10000,
+    trackValues = false,
+    trackGets  = false,
+  } = options;
+
+  // Ring buffer for timeline events
+  const timeline = [];
+  let totalEvents = 0;
+  let dropped = 0;
+
+  function record(event) {
+    if (timeline.length >= maxEvents) {
+      timeline.shift();
+      dropped++;
+    }
+    event._seq = totalEvents++;
+    timeline.push(event);
+  }
+
+  // Per-path stats
+  const pathStats = new Map(); // path -> { sets, gets, fires, totalSetMs, subscriberCount }
+
+  function ensurePath(path) {
+    if (!pathStats.has(path)) {
+      pathStats.set(path, {
+        sets: 0,
+        gets: 0,
+        fires: 0,
+        totalSetMs: 0,
+        peakSetMs: 0,
+        subscriberCount: 0,
+      });
+    }
+    return pathStats.get(path);
+  }
+
+  // Batch tracking
+  let batchDepth = 0;
+  let batchSets = [];
+  const batchStats = { count: 0, totalPaths: 0, totalCoalesced: 0 };
+
+  // Subscribe tracking
+  const activeSubs = new Map(); // subId -> { path, ts }
+  let totalSubscribes = 0;
+  let totalUnsubscribes = 0;
+
+  // Session
+  const sessionId = uid();
+  const sessionStart = now();
+  let destroyed = false;
+
+  // == Wrap store.set =====================================================
+
+  const _origSet = store.set;
+  store.set = function perfSet(path, value) {
+    const t0 = now();
+    const result = _origSet(path, value);
+    const dur = now() - t0;
+
+    const ps = ensurePath(path);
+    ps.sets++;
+    ps.totalSetMs += dur;
+    if (dur > ps.peakSetMs) ps.peakSetMs = dur;
+
+    const evt = { type: 'set', path, dur, ts: t0 };
+    if (trackValues) { evt.value = value; }
+    if (batchDepth > 0) {
+      evt.batched = true;
+      batchSets.push(path);
+    }
+    record(evt);
+
+    return result;
+  };
+
+  // == Wrap store.get =====================================================
+
+  const _origGet = store.get;
+  if (trackGets) {
+    store.get = function perfGet(path) {
+      const t0 = now();
+      const result = _origGet(path);
+      const dur = now() - t0;
+
+      const ps = ensurePath(path);
+      ps.gets++;
+
+      record({ type: 'get', path, dur, ts: t0 });
+      return result;
+    };
+  }
+
+  // == Wrap store.subscribe ===============================================
+
+  const _origSubscribe = store.subscribe;
+  store.subscribe = function perfSubscribe(path, handler) {
+    const subId = uid();
+    const ts = now();
+
+    totalSubscribes++;
+    const ps = ensurePath(path);
+    ps.subscriberCount++;
+
+    // Wrap handler to track fires
+    const wrappedHandler = function perfWrappedHandler(...args) {
+      // Track fire on the subscribed path
+      // For exact subs, the path is the subscribed path
+      // For wildcard subs, we track against the wildcard pattern
+      ps.fires++;
+
+      const t0 = now();
+      const result = handler.apply(this, args);
+      const dur = now() - t0;
+
+      record({ type: 'fire', path, dur, ts: t0, subId });
+      return result;
+    };
+
+    const unsub = _origSubscribe(path, wrappedHandler);
+    activeSubs.set(subId, { path, ts });
+    record({ type: 'subscribe', path, ts, subId });
+
+    return function perfUnsub() {
+      const result = unsub();
+      totalUnsubscribes++;
+      ps.subscriberCount--;
+      activeSubs.delete(subId);
+      record({ type: 'unsubscribe', path, ts: now(), subId });
+      return result;
+    };
+  };
+
+  // == Wrap store.batch ===================================================
+
+  const _origBatch = store.batch;
+  store.batch = function perfBatch(fn) {
+    batchDepth++;
+    const prevSets = batchSets.length;
+    const t0 = now();
+
+    const result = _origBatch(fn);
+
+    const dur = now() - t0;
+    batchDepth--;
+
+    if (batchDepth === 0) {
+      const paths = batchSets.slice(prevSets);
+      const unique = new Set(paths);
+      batchStats.count++;
+      batchStats.totalPaths += paths.length;
+      batchStats.totalCoalesced += paths.length - unique.size;
+
+      record({
+        type: 'batch', dur, ts: t0,
+        pathCount: paths.length,
+        uniquePaths: unique.size,
+        coalesced: paths.length - unique.size,
+        paths: [...unique],
+      });
+
+      batchSets = [];
+    }
+
+    return result;
+  };
+
+  // == Wrap store.setMany =================================================
+
+  const _origSetMany = store.setMany;
+  store.setMany = function perfSetMany(entries) {
+    const t0 = now();
+    let result;
+
+    // Always use the wrapped batch method (which handles the original batch)
+    store.batch(() => {
+      if (entries instanceof Map) {
+        for (const [path, value] of entries) {
+          store.set(path, value);
+        }
+      } else if (Array.isArray(entries)) {
+        for (const [path, value] of entries) {
+          store.set(path, value);
+        }
+      } else if (entries && typeof entries === 'object') {
+        for (const [path, value] of Object.entries(entries)) {
+          store.set(path, value);
+        }
+      }
+    });
+    result = entries;
+    
+    const dur = now() - t0;
+
+    let pathCount = 0;
+    if (entries instanceof Map) pathCount = entries.size;
+    else if (Array.isArray(entries)) pathCount = entries.length;
+    else if (entries && typeof entries === 'object') pathCount = Object.keys(entries).length;
+
+    record({ type: 'setMany', dur, ts: t0, pathCount });
+    return result;
+  };
+
+  // == Report =============================================================
+
+  const RATE_WINDOW_MS = 5000; // 5-second sliding window for /sec rates
+
+  function windowedRate(type, path) {
+    const cutoff = now() - RATE_WINDOW_MS;
+    let count = 0;
+    // Walk backwards from end for efficiency
+    for (let i = timeline.length - 1; i >= 0; i--) {
+      const e = timeline[i];
+      if (e.ts < cutoff) break;
+      if (e.type === type && (!path || e.path === path)) count++;
+    }
+    return +(count / (RATE_WINDOW_MS / 1000)).toFixed(2);
+  }
+
+  function report() {
+    const elapsed = now() - sessionStart;
+
+    // Hot paths: sorted by set count
+    const hotPaths = [...pathStats.entries()]
+      .map(([path, s]) => ({
+        path,
+        sets: s.sets,
+        gets: s.gets,
+        fires: s.fires,
+        avgSetMs: s.sets > 0 ? +(s.totalSetMs / s.sets).toFixed(4) : 0,
+        peakSetMs: +s.peakSetMs.toFixed(4),
+        subscriberCount: s.subscriberCount,
+      }))
+      .sort((a, b) => b.sets - a.sets);
+
+    // Fire frequency: sorted by fire count, using windowed rate
+    const hotListeners = [...pathStats.entries()]
+      .filter(([, s]) => s.fires > 0)
+      .map(([path, s]) => ({
+        path,
+        fires: s.fires,
+        firesPerSec: windowedRate('fire', path),
+      }))
+      .sort((a, b) => b.fires - a.fires);
+
+    return {
+      sessionId,
+      elapsedMs: +elapsed.toFixed(2),
+      totalEvents,
+      dropped,
+      summary: {
+        totalSets: hotPaths.reduce((s, p) => s + p.sets, 0),
+        totalGets: hotPaths.reduce((s, p) => s + p.gets, 0),
+        totalFires: hotPaths.reduce((s, p) => s + p.fires, 0),
+        uniquePaths: pathStats.size,
+        totalSubscribes,
+        totalUnsubscribes,
+        activeSubscribers: activeSubs.size,
+        setsPerSec: windowedRate('set'),
+      },
+      batches: { ...batchStats },
+      hotPaths: hotPaths.slice(0, 50),
+      hotListeners: hotListeners.slice(0, 50),
+      activeSubs: [...activeSubs.entries()].map(([id, s]) => ({ id, ...s })),
+      timeline: timeline.slice(-200), // last 200 events in download
+    };
+  }
+
+  // == Download ===========================================================
+
+  function download(filename) {
+    const data = report();
+    data.timeline = [...timeline]; // include full timeline in download
+    const json = JSON.stringify(data, null, 2);
+
+    if (typeof document !== 'undefined') {
+      const blob = new Blob([json], { type: 'application/json' });
+      const url = URL.createObjectURL(blob);
+      const a = document.createElement('a');
+      a.href = url;
+      a.download = filename || `everystate-perf-${sessionId}.json`;
+      a.click();
+      URL.revokeObjectURL(url);
+    }
+
+    return data;
+  }
+
+  // == Reset ==============================================================
+
+  function reset() {
+    timeline.length = 0;
+    totalEvents = 0;
+    dropped = 0;
+    pathStats.clear();
+    batchSets = [];
+    batchStats.count = 0;
+    batchStats.totalPaths = 0;
+    batchStats.totalCoalesced = 0;
+    activeSubs.clear();
+    totalSubscribes = 0;
+    totalUnsubscribes = 0;
+  }
+
+  // == Destroy (unwrap) ===================================================
+
+  function destroy() {
+    if (destroyed) return;
+    destroyed = true;
+    store.set = _origSet;
+    if (trackGets) store.get = _origGet;
+    store.subscribe = _origSubscribe;
+    store.batch = _origBatch;
+    store.setMany = _origSetMany;
+  }
+
+  return {
+    report,
+    download,
+    reset,
+    destroy,
+    get timeline() { return timeline; },
+    get pathStats() { return pathStats; },
+    get sessionId() { return sessionId; },
+    get store() { return store; },
+  };
+}