what-devtools 0.5.3 → 0.5.5

package/README.md

@@ -0,0 +1,90 @@
+# what-devtools
+
+Development tools for [What Framework](https://whatfw.com). Provides runtime instrumentation to inspect signals, effects, and components. Exposes a `window.__WHAT_DEVTOOLS__` global for console-based debugging and a subscribable event system for custom tooling.
+
+## Install
+
+```bash
+npm install what-devtools --save-dev
+```
+
+## Quick Start
+
+Call `installDevTools()` once at app startup:
+
+```js
+import { installDevTools } from 'what-devtools';
+
+installDevTools();
+```
+
+Then inspect your app in the browser console:
+
+```js
+__WHAT_DEVTOOLS__.signals      // All live signals with names and values
+__WHAT_DEVTOOLS__.effects      // All active effects
+__WHAT_DEVTOOLS__.components   // All mounted components
+__WHAT_DEVTOOLS__.getSnapshot() // Full state snapshot
+```
+
+## Event Subscription
+
+Subscribe to real-time devtools events for custom tooling or a UI panel:
+
+```js
+import { subscribe } from 'what-devtools';
+
+const unsub = subscribe((event, data) => {
+  console.log(event, data);
+  // Events:
+  //   'signal:created'    { id, name, ref, createdAt }
+  //   'signal:updated'    { id, name, value }
+  //   'signal:disposed'   { id }
+  //   'effect:created'    { id, name, createdAt }
+  //   'effect:disposed'   { id }
+  //   'component:mounted'   { id, name, element, mountedAt }
+  //   'component:unmounted' { id }
+});
+```
+
+## DevPanel Component
+
+A built-in panel component for visual debugging (import separately):
+
+```js
+import DevPanel from 'what-devtools/panel';
+```
+
+## API
+
+| Export | Description |
+|---|---|
+| `installDevTools(core?)` | Initialize devtools and wire into what-core's hooks |
+| `subscribe(fn)` | Subscribe to devtools events. Returns unsubscribe function |
+| `getSnapshot()` | Get a snapshot of all signals, effects, and components |
+| `registerSignal(sig, name?)` | Manually register a signal |
+| `notifySignalUpdate(sig)` | Notify devtools of a signal value change |
+| `unregisterSignal(sig)` | Unregister a signal |
+| `registerEffect(e, name?)` | Manually register an effect |
+| `unregisterEffect(e)` | Unregister an effect |
+| `registerComponent(name, element)` | Register a component mount |
+| `unregisterComponent(id)` | Unregister a component |
+| `signals` | Map of all tracked signals |
+| `effects` | Map of all tracked effects |
+| `components` | Map of all tracked components |
+
+## Sub-path Exports
+
+| Path | Contents |
+|---|---|
+| `what-devtools` | Instrumentation API |
+| `what-devtools/panel` | DevPanel UI component |
+
+## Links
+
+- [Documentation](https://whatfw.com)
+- [GitHub](https://github.com/CelsianJs/whatfw)
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "what-devtools",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "description": "Dev tools for What Framework — signal inspector, component tree, effect graph",
   "type": "module",
   "main": "src/index.js",
@@ -22,14 +22,14 @@
   "peerDependencies": {
     "what-core": "^0.5.3"
   },
-  "author": "",
+  "author": "ZVN DEV (https://zvndev.com)",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/zvndev/what-fw"
+    "url": "https://github.com/CelsianJs/whatfw"
   },
   "bugs": {
-    "url": "https://github.com/zvndev/what-fw/issues"
+    "url": "https://github.com/CelsianJs/whatfw/issues"
   },
-  "homepage": "https://whatframework.dev"
+  "homepage": "https://whatfw.com"
 }

package/src/DevPanel.jsx

@@ -39,9 +39,7 @@ export function DevPanel() {
     clearInterval(interval);
   });
 
-  const panelStyle = () => isOpen()
-    ? 'position:fixed;bottom:0;right:0;width:360px;max-height:50vh;z-index:99998;font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:12px;background:#1a1a2e;color:#e0e0e0;border:1px solid #2a2a4a;border-radius:12px 0 0 0;box-shadow:0 -4px 24px rgba(0,0,0,0.3);display:flex;flex-direction:column;overflow:hidden;'
-    : 'display:none;';
+  const PANEL_STYLE = 'position:fixed;bottom:0;right:0;width:360px;max-height:50vh;z-index:99998;font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:12px;background:#1a1a2e;color:#e0e0e0;border:1px solid #2a2a4a;border-radius:12px 0 0 0;box-shadow:0 -4px 24px rgba(0,0,0,0.3);display:flex;flex-direction:column;overflow:hidden;';
 
   const tabStyle = (tab) => () => {
     const isActive = activeTab() === tab;
@@ -110,44 +108,46 @@ export function DevPanel() {
         W
       </button>
 
-      {/* Panel */}
-      <div style={panelStyle}>
-        {/* Header */}
-        <div style="display:flex;align-items:center;justify-content:space-between;padding:8px 12px;border-bottom:1px solid #2a2a4a;background:#16163a;">
-          <div style="display:flex;align-items:center;gap:8px;">
-            <span style="font-weight:700;font-size:12px;color:#818cf8;">What DevTools</span>
+      {/* Panel — conditionally rendered */}
+      {() => 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;">
+            <div style="display:flex;align-items:center;gap:8px;">
+              <span style="font-weight:700;font-size:12px;color:#818cf8;">What DevTools</span>
+            </div>
+            <button
+              onclick={() => isOpen(false)}
+              style="background:none;border:none;color:#6a6a8a;cursor:pointer;font-size:14px;"
+            >
+              x
+            </button>
           </div>
-          <button
-            onclick={() => isOpen(false)}
-            style="background:none;border:none;color:#6a6a8a;cursor:pointer;font-size:14px;"
-          >
-            x
-          </button>
-        </div>
 
-        {/* Tabs */}
-        <div style="display:flex;gap:4px;padding:6px 8px;border-bottom:1px solid #2a2a4a;">
-          <button style={tabStyle('signals')} onclick={() => activeTab('signals')}>
-            Signals ({() => snapshot().signals.length})
-          </button>
-          <button style={tabStyle('effects')} onclick={() => activeTab('effects')}>
-            Effects ({() => snapshot().effects.length})
-          </button>
-          <button style={tabStyle('components')} onclick={() => activeTab('components')}>
-            Components ({() => snapshot().components.length})
-          </button>
-        </div>
+          {/* Tabs */}
+          <div style="display:flex;gap:4px;padding:6px 8px;border-bottom:1px solid #2a2a4a;">
+            <button style={tabStyle('signals')} onclick={() => activeTab('signals')}>
+              Signals ({() => snapshot().signals.length})
+            </button>
+            <button style={tabStyle('effects')} onclick={() => activeTab('effects')}>
+              Effects ({() => snapshot().effects.length})
+            </button>
+            <button style={tabStyle('components')} onclick={() => activeTab('components')}>
+              Components ({() => snapshot().components.length})
+            </button>
+          </div>
 
-        {/* Content */}
-        <div style="overflow-y:auto;flex:1;">
-          {() => {
-            const tab = activeTab();
-            if (tab === 'signals') return renderSignals();
-            if (tab === 'effects') return renderEffects();
-            return renderComponents();
-          }}
+          {/* Content */}
+          <div style="overflow-y:auto;flex:1;">
+            {() => {
+              const tab = activeTab();
+              if (tab === 'signals') return renderSignals();
+              if (tab === 'effects') return renderEffects();
+              return renderComponents();
+            }}
+          </div>
         </div>
-      </div>
+      ) : null}
     </>
   );
 }

package/src/index.js

@@ -20,9 +20,16 @@ let effectId = 0;
 let componentId = 0;
 
 // Registries
-const signals = new Map();    // id → { name, value, subs, createdAt }
-const effects = new Map();    // id → { name, deps, createdAt }
-const components = new Map(); // id → { name, mountedAt, signals: [], effects: [] }
+const signals = new Map();    // id → { name, ref, createdAt, internal }
+const effects = new Map();    // id → { name, createdAt, depSignalIds, runCount, lastRunAt }
+const components = new Map(); // id → { name, element, mountedAt, parentId }
+
+// Reverse lookup: subscriber Set → signal ID (O(1) dep resolution)
+const subsToSignalId = new WeakMap();
+
+// Error log (capped at 100)
+const errors = [];
+const MAX_ERRORS = 100;
 
 // Event listeners for the DevPanel
 const listeners = new Set();
@@ -33,6 +40,88 @@ function emit(event, data) {
   }
 }
 
+/**
+ * Safely serialize a value for transport (WS, JSON).
+ * Handles DOM nodes, functions, circular refs, Maps, Sets, large collections.
+ */
+export function safeSerialize(value, depth = 0, seen) {
+  if (depth > 6) return '[max depth]';
+  if (value === null || value === undefined) return value;
+
+  const type = typeof value;
+  if (type === 'string' || type === 'number' || type === 'boolean') return value;
+  if (type === 'function') return `[Function: ${value.name || 'anonymous'}]`;
+  if (type === 'symbol') return `[Symbol: ${value.description || ''}]`;
+  if (type === 'bigint') return value.toString() + 'n';
+
+  // DOM nodes
+  if (typeof Node !== 'undefined' && value instanceof Node) {
+    const tag = value.nodeName?.toLowerCase() || 'node';
+    const id = value.id ? `#${value.id}` : '';
+    const cls = value.className ? `.${String(value.className).split(' ')[0]}` : '';
+    return `[DOM: <${tag}${id}${cls}>]`;
+  }
+
+  if (!seen) seen = new Set();
+  if (seen.has(value)) return '[Circular]';
+  seen.add(value);
+
+  // Map
+  if (value instanceof Map) {
+    if (value.size > 50) return `[Map: ${value.size} entries]`;
+    const obj = {};
+    for (const [k, v] of value) {
+      obj[String(k)] = safeSerialize(v, depth + 1, seen);
+    }
+    return { __type: 'Map', entries: obj };
+  }
+
+  // Set
+  if (value instanceof Set) {
+    if (value.size > 50) return `[Set: ${value.size} items]`;
+    return { __type: 'Set', values: [...value].map(v => safeSerialize(v, depth + 1, seen)) };
+  }
+
+  // Array
+  if (Array.isArray(value)) {
+    if (value.length > 100) {
+      return [...value.slice(0, 100).map(v => safeSerialize(v, depth + 1, seen)), `... (${value.length} total)`];
+    }
+    return value.map(v => safeSerialize(v, depth + 1, seen));
+  }
+
+  // Error
+  if (value instanceof Error) {
+    return { __type: 'Error', name: value.name, message: value.message, stack: value.stack };
+  }
+
+  // Date
+  if (value instanceof Date) return { __type: 'Date', iso: value.toISOString() };
+
+  // RegExp
+  if (value instanceof RegExp) return value.toString();
+
+  // Plain object
+  if (type === 'object') {
+    const keys = Object.keys(value);
+    if (keys.length > 100) {
+      const obj = {};
+      for (const k of keys.slice(0, 100)) {
+        obj[k] = safeSerialize(value[k], depth + 1, seen);
+      }
+      obj['...'] = `(${keys.length} total keys)`;
+      return obj;
+    }
+    const obj = {};
+    for (const k of keys) {
+      obj[k] = safeSerialize(value[k], depth + 1, seen);
+    }
+    return obj;
+  }
+
+  return String(value);
+}
+
 /**
  * Register a signal with the devtools.
  * Called from reactive.js __DEV__ hooks.
@@ -42,12 +131,15 @@ export function registerSignal(sig, name) {
   const id = ++signalId;
   const entry = {
     id,
-    name: name || `signal_${id}`,
+    name: sig._debugName || name || `signal_${id}`,
     ref: sig,
     createdAt: Date.now(),
+    internal: false,
   };
   signals.set(id, entry);
   sig._devId = id;
+  // Reverse lookup for O(1) effect dep resolution
+  if (sig._subs) subsToSignalId.set(sig._subs, id);
   emit('signal:created', entry);
   return id;
 }
@@ -86,6 +178,9 @@ export function registerEffect(e, name) {
     id,
     name: name || e.fn?.name || `effect_${id}`,
     createdAt: Date.now(),
+    depSignalIds: [],
+    runCount: 0,
+    lastRunAt: null,
   };
   effects.set(id, entry);
   e._devId = id;
@@ -93,6 +188,30 @@ export function registerEffect(e, name) {
   return id;
 }
 
+/**
+ * Track effect dependencies and run count after an effect runs.
+ */
+function trackEffectRun(e) {
+  const id = e._devId;
+  if (id == null) return;
+  const entry = effects.get(id);
+  if (!entry) return;
+
+  // Resolve deps via WeakMap reverse lookup — O(m) where m = number of deps
+  const depSignalIds = [];
+  if (e.deps) {
+    for (const subSet of e.deps) {
+      const sigId = subsToSignalId.get(subSet);
+      if (sigId != null) depSignalIds.push(sigId);
+    }
+  }
+
+  entry.depSignalIds = depSignalIds;
+  entry.runCount = (entry.runCount || 0) + 1;
+  entry.lastRunAt = Date.now();
+  emit('effect:run', { id, depSignalIds: entry.depSignalIds, runCount: entry.runCount });
+}
+
 /**
  * Unregister an effect.
  */
@@ -104,16 +223,33 @@ export function unregisterEffect(e) {
   emit('effect:disposed', { id });
 }
 
+/**
+ * Capture a runtime error.
+ */
+function captureError(err, context) {
+  const entry = {
+    message: err?.message || String(err),
+    stack: err?.stack || null,
+    type: context?.type || 'unknown',
+    effectId: context?.effect?._devId || null,
+    timestamp: Date.now(),
+  };
+  errors.push(entry);
+  if (errors.length > MAX_ERRORS) errors.shift();
+  emit('error:captured', entry);
+}
+
 /**
  * Register a component mount.
  */
-export function registerComponent(name, element) {
+export function registerComponent(name, element, parentDevId) {
   if (!installed) return;
   const id = ++componentId;
   const entry = {
     id,
     name: name || 'Anonymous',
     element,
+    parentId: parentDevId || null,
     mountedAt: Date.now(),
   };
   components.set(id, entry);
@@ -141,10 +277,15 @@ export function subscribe(fn) {
 
 /**
  * Get a snapshot of all tracked state.
+ * @param {object} [opts] - Options
+ * @param {boolean} [opts.includeInternal=false] - Include framework-internal signals
  */
-export function getSnapshot() {
+export function getSnapshot(opts = {}) {
+  const { includeInternal = false } = opts;
+
   const signalList = [];
   for (const [id, entry] of signals) {
+    if (!includeInternal && entry.internal) continue;
     signalList.push({
       id,
       name: entry.name,
@@ -154,51 +295,93 @@ export function getSnapshot() {
 
   const effectList = [];
   for (const [id, entry] of effects) {
-    effectList.push({ id, name: entry.name });
+    effectList.push({
+      id,
+      name: entry.name,
+      depSignalIds: entry.depSignalIds || [],
+      runCount: entry.runCount || 0,
+      lastRunAt: entry.lastRunAt || null,
+    });
   }
 
   const componentList = [];
   for (const [id, entry] of components) {
-    componentList.push({ id, name: entry.name });
+    componentList.push({ id, name: entry.name, parentId: entry.parentId });
   }
 
-  return { signals: signalList, effects: effectList, components: componentList };
+  return {
+    signals: signalList,
+    effects: effectList,
+    components: componentList,
+    errors: errors.slice(),
+  };
+}
+
+/**
+ * Get captured errors.
+ * @param {object} [opts]
+ * @param {number} [opts.since] - Only errors after this timestamp
+ */
+export function getErrors(opts = {}) {
+  const { since } = opts;
+  if (since) return errors.filter(e => e.timestamp > since);
+  return errors.slice();
 }
 
 /**
  * Install devtools. Call once at app startup.
  * Wires into what-core's __DEV__ hooks and exposes `window.__WHAT_DEVTOOLS__`.
+ *
+ * @param {object} [core] - Optional what-core module. If not provided, attempts dynamic import.
  */
-export function installDevTools() {
+export function installDevTools(core) {
   if (installed) return;
   installed = true;
 
+  const hooks = {
+    onSignalCreate: (sig) => registerSignal(sig),
+    onSignalUpdate: (sig) => notifySignalUpdate(sig),
+    onEffectCreate: (e) => registerEffect(e),
+    onEffectDispose: (e) => unregisterEffect(e),
+    onEffectRun: (e) => trackEffectRun(e),
+    onError: (err, context) => captureError(err, context),
+    onComponentMount: (ctx) => {
+      const name = ctx.Component?.displayName || ctx.Component?.name || 'Anonymous';
+      const parentDevId = ctx._parentCtx?._devId || null;
+      const id = registerComponent(name, ctx._wrapper, parentDevId);
+      ctx._devId = id;
+    },
+    onComponentUnmount: (ctx) => {
+      if (ctx._devId != null) unregisterComponent(ctx._devId);
+    },
+  };
+
   // Wire into what-core's reactive system
-  try {
-    import('what-core').then(core => {
-      if (core.__setDevToolsHooks) {
-        core.__setDevToolsHooks({
-          onSignalCreate: (sig) => registerSignal(sig),
-          onSignalUpdate: (sig) => notifySignalUpdate(sig),
-          onEffectCreate: (e) => registerEffect(e),
-          onEffectDispose: (e) => unregisterEffect(e),
-        });
-      }
-    }).catch(() => {
-      // what-core not available — devtools still work via manual registration
-    });
-  } catch {}
+  if (core && core.__setDevToolsHooks) {
+    core.__setDevToolsHooks(hooks);
+    if (typeof window !== 'undefined') window.__WHAT_CORE__ = core;
+  } else {
+    try {
+      import('what-core').then(mod => {
+        if (mod.__setDevToolsHooks) mod.__setDevToolsHooks(hooks);
+        if (typeof window !== 'undefined') window.__WHAT_CORE__ = mod;
+      }).catch(() => {});
+    } catch {}
+  }
 
   if (typeof window !== 'undefined') {
     window.__WHAT_DEVTOOLS__ = {
       get signals() { return getSnapshot().signals; },
       get effects() { return getSnapshot().effects; },
       get components() { return getSnapshot().components; },
+      get errors() { return getErrors(); },
       getSnapshot,
+      getErrors,
       subscribe,
-      _registries: { signals, effects, components },
+      safeSerialize,
+      _registries: { signals, effects, components, errors },
     };
   }
 }
 
-export { signals, effects, components };
+export { signals, effects, components, errors };