what-devtools 0.8.4 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "what-devtools",
-  "version": "0.8.4",
+  "version": "0.11.0",
   "description": "Dev tools for What Framework — signal inspector, component tree, effect graph",
   "type": "module",
   "main": "src/index.js",
@@ -20,7 +20,7 @@
     "inspector"
   ],
   "peerDependencies": {
-    "what-core": "^0.8.4"
+    "what-core": "^0.11.0"
   },
   "author": "ZVN DEV (https://zvndev.com)",
   "license": "MIT",

package/src/DevPanel.jsx

@@ -20,12 +20,25 @@
  */
 
 import { signal, effect, onCleanup } from 'what-core';
-import { subscribe, getSnapshot, getErrors, installDevTools } from './index.js';
+import { subscribe, getSnapshot, getErrors, installDevTools, _suppressDevtools } from './index.js';
 
 export function DevPanel() {
   // Auto-install devtools if not already done
   installDevTools();
 
+  // The panel's ENTIRE body runs with devtools registration suppressed —
+  // the panel must not appear in its own signal/effect lists. More
+  // importantly: if panel-internal effects registered, every panel re-render
+  // would emit effect:created events, the subscribe() callback below would
+  // write `snapshot`, that write would re-render the panel, creating more
+  // effects → an unbounded feedback loop that crashes the page.
+  // The two bindings that (re)create DOM subtrees after mount (the isOpen
+  // panel toggle and the tab-content switch) carry their own _suppressDevtools
+  // wrappers, because their re-runs happen outside this bracket.
+  return _suppressDevtools(() => DevPanelBody());
+}
+
+function DevPanelBody() {
   const isOpen = signal(false);
   const activeTab = signal('overview');
   const snapshot = signal(getSnapshot());
@@ -291,7 +304,11 @@ export function DevPanel() {
   };
 
   return (
-    <>
+    // display:contents wrapper instead of a fragment — the babel plugin
+    // currently miscompiles top-level fragments whose element children carry
+    // event handlers (it references _el$N bindings it never emits). The
+    // wrapper is layout-neutral; both children are position:fixed anyway.
+    <div style="display:contents">
       {/* Toggle button with health indicator */}
       <button
         onclick={() => isOpen((v) => !v)}
@@ -312,9 +329,11 @@ export function DevPanel() {
         W
       </button>
 
-      {/* Panel -- conditionally rendered */}
+      {/* Panel -- conditionally rendered. _suppressDevtools: opening the
+          panel instantiates this whole subtree (dozens of bindings) — none
+          of them may register with devtools (see DevPanel docblock). */}
       {() =>
-        isOpen() ? (
+        _suppressDevtools(() => isOpen() ? (
           <div style={PANEL_STYLE}>
             {/* Header */}
             <div style="display:flex;align-items:center;justify-content:space-between;padding:8px 12px;border-bottom:1px solid #2a2a4a;background:#16163a;">
@@ -373,9 +392,10 @@ export function DevPanel() {
               </button>
             </div>
 
-            {/* Content */}
+            {/* Content. _suppressDevtools: tab switches and snapshot
+                updates rebuild this subtree — keep it out of devtools. */}
             <div style="overflow-y:auto;flex:1;">
-              {() => {
+              {() => _suppressDevtools(() => {
                 const tab = activeTab();
                 if (tab === 'overview') return renderOverview();
                 if (tab === 'signals') return renderSignals();
@@ -383,12 +403,12 @@ export function DevPanel() {
                 if (tab === 'components') return renderComponents();
                 if (tab === 'errors') return renderErrors();
                 return renderOverview();
-              }}
+              })}
             </div>
           </div>
-        ) : null
+        ) : null)
       }
-    </>
+    </div>
   );
 }
 

package/src/index.js

@@ -19,6 +19,11 @@ let signalId = 0;
 let effectId = 0;
 let componentId = 0;
 
+// what-core's installSignalReadGuardrail, captured when the core module is
+// wired up in installDevTools(). Dev-only: warns when a signal is coerced
+// to a string/number without being called (e.g. `Total: ${count}`).
+let coreSignalReadGuardrail = null;
+
 // Registries
 const signals = new Map();    // id → { name, ref, createdAt, internal }
 const effects = new Map();    // id → { name, createdAt, depSignalIds, runCount, lastRunAt }
@@ -27,6 +32,86 @@ const components = new Map(); // id → { name, element, mountedAt, parentId }
 // Reverse lookup: subscriber Set → signal ID (O(1) dep resolution)
 const subsToSignalId = new WeakMap();
 
+// Set of known component function names (added on registerComponent, kept
+// forever even after unmount so post-mortem signals still attribute).
+// Used by attributeToComponent() to recognise component frames in stack traces.
+const knownComponentNames = new Set();
+
+// name -> Set<componentId>. When multiple components share a name we cannot
+// disambiguate via stack; the heuristic falls back to the most-recently-mounted.
+const componentsByName = new Map();
+
+/**
+ * Heuristic attribution: parse new Error().stack to find the most recently
+ * called component frame. Returns a componentId or null.
+ *
+ * Why a stack heuristic instead of a hook:
+ *   - We cannot add bracketing hooks to packages/core (compiler agent owns it).
+ *   - `onComponentMount` fires before the component body runs; there's no
+ *     `onComponentRendered` paired event.
+ *   - Signal/effect creation happens DURING the component body, so its
+ *     stack always contains a frame named after the component function.
+ *
+ * Limitations:
+ *   - Anonymous components (no function name) cannot be matched.
+ *   - Arrow components bound to a const get the const name in V8 stacks.
+ *   - In production builds without source maps, function names may be mangled
+ *     — but installDevTools should only run in dev anyway.
+ */
+function attributeToComponent() {
+  if (knownComponentNames.size === 0) return null;
+  let stack;
+  try { throw new Error(); } catch (e) { stack = e.stack; }
+  if (!stack) return null;
+  // Walk stack from innermost to outermost. The FIRST component frame we
+  // hit is the deepest (currently-running) component.
+  const lines = stack.split('\n');
+  for (const rawLine of lines) {
+    const line = rawLine.trim();
+    if (!line.startsWith('at ')) continue;
+    // Extract function name token. Handles `at Foo`, `at Object.Foo`,
+    // `at new Foo`, `at Foo.bar`, `at Foo (file:line:col)`.
+    const m = line.match(/^at\s+(?:new\s+)?([\w$.]+)/);
+    if (!m) continue;
+    const tokens = m[1].split('.');
+    for (const tok of tokens) {
+      if (knownComponentNames.has(tok)) {
+        const ids = componentsByName.get(tok);
+        if (ids && ids.size > 0) {
+          // Most-recently-mounted wins.
+          let max = -1;
+          for (const id of ids) if (id > max) max = id;
+          return max;
+        }
+      }
+    }
+  }
+  return null;
+}
+
+// --- Self-tracking suppression ---
+// Devtools UI rendered INSIDE the inspected app (the DevPanel) must not
+// register its own signals/effects: panel-internal registrations emit
+// devtools events, the panel reacts by updating its snapshot signal, the
+// resulting re-render creates more effects, which emit again — an unbounded
+// feedback loop that wedges and crashes the page. Re-entrant (counter).
+let suppressDepth = 0;
+
+/**
+ * Run fn with devtools registration suppressed (exception-safe).
+ * Signals/effects/components created inside fn are invisible to devtools.
+ * Does NOT affect what-core's reactive dependency tracking.
+ * @internal Used by DevPanel; exported for devtools-adjacent UIs and tests.
+ */
+export function _suppressDevtools(fn) {
+  suppressDepth++;
+  try {
+    return fn();
+  } finally {
+    suppressDepth--;
+  }
+}
+
 // Error log (capped at 100)
 const errors = [];
 const MAX_ERRORS = 100;
@@ -127,7 +212,7 @@ export function safeSerialize(value, depth = 0, seen) {
  * Called from reactive.js __DEV__ hooks.
  */
 export function registerSignal(sig, name) {
-  if (!installed) return;
+  if (!installed || suppressDepth > 0) return;
   const id = ++signalId;
   const entry = {
     id,
@@ -135,11 +220,19 @@ export function registerSignal(sig, name) {
     ref: sig,
     createdAt: Date.now(),
     internal: false,
+    // P1-6: attribute to the component currently executing, so what_explain
+    // can show component-local signals instead of always returning [].
+    componentId: attributeToComponent(),
   };
   signals.set(id, entry);
   sig._devId = id;
   // Reverse lookup for O(1) effect dep resolution
   if (sig._subs) subsToSignalId.set(sig._subs, id);
+  // Dev guardrail: warn when this signal is string/number-coerced without
+  // being called (catches `Total: ${count}` — should be `${count()}`).
+  if (coreSignalReadGuardrail) {
+    try { coreSignalReadGuardrail(sig, entry.name); } catch {}
+  }
   emit('signal:created', entry);
   return id;
 }
@@ -172,7 +265,7 @@ export function unregisterSignal(sig) {
  * Register an effect with the devtools.
  */
 export function registerEffect(e, name) {
-  if (!installed) return;
+  if (!installed || suppressDepth > 0) return;
   const id = ++effectId;
   const entry = {
     id,
@@ -181,6 +274,8 @@ export function registerEffect(e, name) {
     depSignalIds: [],
     runCount: 0,
     lastRunAt: null,
+    // P1-6: attribute to the component currently executing.
+    componentId: attributeToComponent(),
   };
   effects.set(id, entry);
   e._devId = id;
@@ -241,9 +336,26 @@ function captureError(err, context) {
 
 /**
  * Register a component mount.
+ *
+ * TODO(P2-7) — stable component IDs across remounts.
+ * Currently `componentId` is a monotonic counter, so a view switch (or any
+ * conditional render) produces fresh IDs even when the same component
+ * remounts in the same slot. Agents that cache IDs across calls get burned.
+ *
+ * A stable scheme would key by (parent stable id + position + name), but
+ * that requires:
+ *   - Tracking position within parent (currently only parentDevId is known).
+ *   - Resolving collisions when two siblings have the same name.
+ *   - Deciding how recursion (component-renders-itself) is handled.
+ *   - Migrating every code path that assumes monotonic numeric IDs (devtools
+ *     panel, registries, MCP bridge serialization, snapshot diffing).
+ *
+ * Verdict: the registry rewrite is invasive enough to warrant a dedicated
+ * change. For now, the MCP tool descriptions document the ephemerality
+ * (see what_components / what_explain) so agents re-query before using IDs.
  */
 export function registerComponent(name, element, parentDevId) {
-  if (!installed) return;
+  if (!installed || suppressDepth > 0) return;
   const id = ++componentId;
   const entry = {
     id,
@@ -253,6 +365,13 @@ export function registerComponent(name, element, parentDevId) {
     mountedAt: Date.now(),
   };
   components.set(id, entry);
+  // Index by name so attributeToComponent() can match stack frames.
+  if (name) {
+    knownComponentNames.add(name);
+    let set = componentsByName.get(name);
+    if (!set) { set = new Set(); componentsByName.set(name, set); }
+    set.add(id);
+  }
   emit('component:mounted', entry);
   return id;
 }
@@ -262,7 +381,17 @@ export function registerComponent(name, element, parentDevId) {
  */
 export function unregisterComponent(id) {
   if (!installed) return;
+  const entry = components.get(id);
   components.delete(id);
+  if (entry?.name) {
+    const set = componentsByName.get(entry.name);
+    if (set) {
+      set.delete(id);
+      // Keep knownComponentNames populated even after unmount — a re-mount
+      // of the same component should still attribute correctly, and
+      // attribution costs nothing when no live components match.
+    }
+  }
   emit('component:unmounted', { id });
 }
 
@@ -290,6 +419,7 @@ export function getSnapshot(opts = {}) {
       id,
       name: entry.name,
       value: entry.ref.peek(),
+      componentId: entry.componentId || null,
     });
   }
 
@@ -301,6 +431,7 @@ export function getSnapshot(opts = {}) {
       depSignalIds: entry.depSignalIds || [],
       runCount: entry.runCount || 0,
       lastRunAt: entry.lastRunAt || null,
+      componentId: entry.componentId || null,
     });
   }
 
@@ -357,15 +488,65 @@ export function installDevTools(core) {
   };
 
   // Wire into what-core's reactive system
+  function installInto(mod) {
+    if (!mod) return;
+    // Capture the guardrail BEFORE hooks go live so the very first
+    // registrations (and the pre-install drain below) get wrapped too.
+    if (typeof mod.installSignalReadGuardrail === 'function') {
+      coreSignalReadGuardrail = mod.installSignalReadGuardrail;
+    }
+    if (mod.__setDevToolsHooks) mod.__setDevToolsHooks(hooks);
+    if (typeof window !== 'undefined') window.__WHAT_CORE__ = mod;
+
+    // P1-9: drain anything created BEFORE installDevTools was called
+    // (e.g. module-scope signals in store.js imported before app.js).
+    // The placeholder hooks in reactive.js buffered creations; we now
+    // register them with the live devtools so what_signals can see them.
+    if (typeof mod.__drainPreinstallBuffer === 'function') {
+      try {
+        const drained = mod.__drainPreinstallBuffer();
+        for (const sig of drained.signals || []) {
+          // Avoid double-register if the placeholder somehow already passed
+          // through to hooks (defensive — should be impossible given the
+          // ordering in reactive.js).
+          if (sig._devId == null) registerSignal(sig);
+        }
+        for (const e of drained.effects || []) {
+          if (e._devId == null) {
+            registerEffect(e);
+            // The effect already ran once before install; populate its deps
+            // now so what_dependency_graph shows the edges immediately,
+            // instead of waiting for the next run to re-track.
+            const entry = effects.get(e._devId);
+            if (entry && Array.isArray(e.deps)) {
+              const depSignalIds = [];
+              for (const subSet of e.deps) {
+                const sigId = subsToSignalId.get(subSet);
+                if (sigId != null) depSignalIds.push(sigId);
+              }
+              entry.depSignalIds = depSignalIds;
+              entry.runCount = 1;
+              entry.lastRunAt = Date.now();
+            }
+          }
+        }
+        for (const ctx of drained.components || []) {
+          if (ctx._devId == null) hooks.onComponentMount(ctx);
+        }
+      } catch (err) {
+        // Non-fatal — pre-install drain is best-effort.
+        if (typeof console !== 'undefined') {
+          console.warn('[what-devtools] pre-install drain failed:', err);
+        }
+      }
+    }
+  }
+
   if (core && core.__setDevToolsHooks) {
-    core.__setDevToolsHooks(hooks);
-    if (typeof window !== 'undefined') window.__WHAT_CORE__ = core;
+    installInto(core);
   } else {
     try {
-      import('what-core').then(mod => {
-        if (mod.__setDevToolsHooks) mod.__setDevToolsHooks(hooks);
-        if (typeof window !== 'undefined') window.__WHAT_CORE__ = mod;
-      }).catch(() => {});
+      import('what-core').then(installInto).catch(() => {});
     } catch {}
   }