what-core 0.5.6 → 0.6.0

package/src/hooks.js

@@ -1,15 +1,18 @@
 // What Framework - Hooks
-// React-familiar hooks backed by signals. Zero overhead when deps don't change.
+// React-familiar hooks backed by signals for run-once component model.
+// Components run ONCE. Hooks return signal accessors (functions) so the
+// fine-grained runtime handles reactive updates automatically via effects.
 
-import { signal, computed, effect, batch, untrack, __DEV__ } from './reactive.js';
+import { signal, computed, effect, batch, untrack, createRoot, __DEV__ } from './reactive.js';
 import { getCurrentComponent } from './dom.js';
 
-function getCtx() {
+function getCtx(hookName) {
   const ctx = getCurrentComponent();
   if (!ctx) {
     throw new Error(
-      '[what] Hooks must be called inside a component function. ' +
-      'If you need reactive state outside a component, use signal() directly.'
+      `[what] ${hookName || 'Hook'}() can only be called inside a component function. ` +
+      `Did you call it outside of a component or in an async callback? ` +
+      `If you need reactive state outside a component, use signal() directly.`
     );
   }
   return ctx;
@@ -20,13 +23,14 @@ function getHook(ctx) {
   return { index, exists: index < ctx.hooks.length };
 }
 
-let _useMemoNoDepsWarned = false;
-
 // --- useState ---
-// Returns [value, setter]. Setter triggers re-render of this component only.
+// Returns [signalAccessor, setter]. The accessor is a function — call it to read.
+// In JSX, {count} (where count is the signal function) auto-binds reactively
+// via insert()'s effect wrapper. For interpolation, use count() explicitly.
+// This matches Solid's API and works with the run-once component model.
 
 export function useState(initial) {
-  const ctx = getCtx();
+  const ctx = getCtx('useState');
   const { index, exists } = getHook(ctx);
 
   if (!exists) {
@@ -35,7 +39,7 @@ export function useState(initial) {
   }
 
   const s = ctx.hooks[index];
-  return [s(), s.set];
+  return [s, s.set];
 }
 
 // --- useSignal ---
@@ -43,7 +47,7 @@ export function useState(initial) {
 // Avoids array destructuring overhead.
 
 export function useSignal(initial) {
-  const ctx = getCtx();
+  const ctx = getCtx('useSignal');
   const { index, exists } = getHook(ctx);
 
   if (!exists) {
@@ -57,7 +61,7 @@ export function useSignal(initial) {
 // Derived value. Only recomputes when signal deps change.
 
 export function useComputed(fn) {
-  const ctx = getCtx();
+  const ctx = getCtx('useComputed');
   const { index, exists } = getHook(ctx);
 
   if (!exists) {
@@ -68,72 +72,135 @@ export function useComputed(fn) {
 }
 
 // --- useEffect ---
-// Side effect that runs after render. Cleanup function returned by fn is called
-// before re-running and on unmount.
+// Side effect that runs after mount. In the run-once model, deps-based
+// re-running only works if deps are signal accessors. The implementation:
+// - No deps (undefined): wrap in effect() that auto-tracks signals
+// - Empty deps []: run once on mount, cleanup on unmount
+// - Deps [a, b]: create effect() that reads each dep (calling signal functions
+//   to establish tracking), then runs the callback when any dep changes
 
 export function useEffect(fn, deps) {
-  const ctx = getCtx();
+  const ctx = getCtx('useEffect');
   const { index, exists } = getHook(ctx);
 
   if (!exists) {
-    ctx.hooks[index] = { deps: undefined, cleanup: null };
+    ctx.hooks[index] = { cleanup: null, dispose: null };
+  }
+
+  // Dev-mode: warn when deps array contains non-function values that look like signals
+  if (__DEV__ && Array.isArray(deps) && deps.length > 0) {
+    for (let i = 0; i < deps.length; i++) {
+      const dep = deps[i];
+      if (dep != null && typeof dep !== 'function') {
+        console.warn(
+          `[what] useEffect dep at index ${i} is not a function. ` +
+          `Did you mean to pass a signal? Use count instead of count()`
+        );
+      }
+    }
   }
 
   const hook = ctx.hooks[index];
 
-  if (depsChanged(hook.deps, deps)) {
-    // Schedule after current render
+  // Only set up once — component runs once
+  if (hook.dispose) return;
+
+  if (deps === undefined) {
+    // No deps array: wrap in effect() that auto-tracks signal reads inside fn
     queueMicrotask(() => {
       if (ctx.disposed) return;
-      if (hook.cleanup) hook.cleanup();
-      hook.cleanup = fn() || null;
+      hook.dispose = effect(() => {
+        if (hook.cleanup) {
+          try { hook.cleanup(); } catch (e) { /* cleanup error */ }
+          hook.cleanup = null;
+        }
+        const result = fn();
+        if (typeof result === 'function') hook.cleanup = result;
+      });
+      // Register disposal with component lifecycle
+      ctx.effects = ctx.effects || [];
+      ctx.effects.push(hook.dispose);
+    });
+  } else if (deps.length === 0) {
+    // Empty deps []: run once on mount, cleanup on unmount
+    queueMicrotask(() => {
+      if (ctx.disposed) return;
+      const result = fn();
+      if (typeof result === 'function') hook.cleanup = result;
+    });
+    // Mark as set up so we don't re-run
+    hook.dispose = true;
+  } else {
+    // Deps array with values: create a reactive effect that reads each dep.
+    // If a dep is a signal function, calling it establishes tracking.
+    // When any tracked signal changes, the effect re-runs the callback.
+    queueMicrotask(() => {
+      if (ctx.disposed) return;
+      hook.dispose = effect(() => {
+        // Read all deps to establish signal tracking
+        for (let i = 0; i < deps.length; i++) {
+          const dep = deps[i];
+          if (typeof dep === 'function' && dep._signal) {
+            dep(); // Read signal to track it
+          }
+        }
+
+        // Run cleanup from previous execution
+        if (hook.cleanup) {
+          try { hook.cleanup(); } catch (e) { /* cleanup error */ }
+          hook.cleanup = null;
+        }
+
+        // Run the effect callback
+        const result = untrack(() => fn());
+        if (typeof result === 'function') hook.cleanup = result;
+      });
+      // Register disposal with component lifecycle
+      ctx.effects = ctx.effects || [];
+      ctx.effects.push(hook.dispose);
     });
-    hook.deps = deps;
   }
 }
 
 // --- useMemo ---
-// Memoized value. Only recomputes when deps change.
+// Memoized computed value. Uses computed() for automatic signal tracking.
+// The deps array is accepted for API compatibility but ignored internally —
+// computed() auto-tracks signal dependencies.
+// Returns a computed signal function (call it to read the value).
 
 export function useMemo(fn, deps) {
-  const ctx = getCtx();
+  const ctx = getCtx('useMemo');
   const { index, exists } = getHook(ctx);
 
-  if (__DEV__ && deps === undefined && !_useMemoNoDepsWarned) {
-    _useMemoNoDepsWarned = true;
-    console.warn(
-      '[what] useMemo() called without a deps array. ' +
-      'This recomputes every render. Use useComputed() for signal-derived values, ' +
-      'or pass deps to useMemo().'
-    );
-  }
-
   if (!exists) {
-    ctx.hooks[index] = { value: undefined, deps: undefined };
-  }
-
-  const hook = ctx.hooks[index];
-
-  if (depsChanged(hook.deps, deps)) {
-    hook.value = fn();
-    hook.deps = deps;
+    ctx.hooks[index] = { computed: computed(fn) };
   }
 
-  return hook.value;
+  return ctx.hooks[index].computed;
 }
 
 // --- useCallback ---
-// Memoized callback. Identity-stable when deps don't change.
+// Memoized callback. In the run-once model, the component function only
+// executes once, so the callback reference is inherently stable.
+// Simply store and return the function on first call.
 
 export function useCallback(fn, deps) {
-  return useMemo(() => fn, deps);
+  const ctx = getCtx('useCallback');
+  const { index, exists } = getHook(ctx);
+
+  if (!exists) {
+    ctx.hooks[index] = { callback: fn };
+  }
+
+  return ctx.hooks[index].callback;
 }
 
 // --- useRef ---
 // Mutable ref object. Does NOT trigger re-renders.
+// Works correctly in run-once model — the ref persists for the component lifetime.
 
 export function useRef(initial) {
-  const ctx = getCtx();
+  const ctx = getCtx('useRef');
   const { index, exists } = getHook(ctx);
 
   if (!exists) {
@@ -146,7 +213,8 @@ export function useRef(initial) {
 // --- useContext ---
 // Read from the nearest Provider in the component tree, or the default value.
 // Uses _parentCtx chain (persistent tree) instead of componentStack (runtime stack)
-// so context works correctly in re-renders, effects, and event handlers.
+// so context works correctly in effects and event handlers.
+// Returns the signal itself (not its value) so that consumers get reactive updates.
 
 export function useContext(context) {
   // Walk up the _parentCtx chain to find the nearest provider
@@ -178,7 +246,7 @@ export function createContext(defaultValue) {
   const context = {
     _defaultValue: defaultValue,
     Provider: ({ value, children }) => {
-      const ctx = getCtx();
+      const ctx = getCtx('Context.Provider');
       if (!ctx._contextValues) ctx._contextValues = new Map();
       if (!ctx._contextSignals) ctx._contextSignals = new Map();
 
@@ -202,10 +270,11 @@ export function createContext(defaultValue) {
 }
 
 // --- useReducer ---
-// State management with a reducer function (like React).
+// State management with a reducer function.
+// Returns [signalAccessor, dispatch] — accessor is a signal function.
 
 export function useReducer(reducer, initialState, init) {
-  const ctx = getCtx();
+  const ctx = getCtx('useReducer');
   const { index, exists } = getHook(ctx);
 
   if (!exists) {
@@ -218,14 +287,14 @@ export function useReducer(reducer, initialState, init) {
   }
 
   const hook = ctx.hooks[index];
-  return [hook.signal(), hook.dispatch];
+  return [hook.signal, hook.dispatch];
 }
 
 // --- onMount ---
 // Run callback once when component mounts. SolidJS-style lifecycle.
 
 export function onMount(fn) {
-  const ctx = getCtx();
+  const ctx = getCtx('onMount');
   if (!ctx.mounted) {
     ctx._mountCallbacks = ctx._mountCallbacks || [];
     ctx._mountCallbacks.push(fn);
@@ -236,7 +305,7 @@ export function onMount(fn) {
 // Register cleanup function to run when component unmounts.
 
 export function onCleanup(fn) {
-  const ctx = getCtx();
+  const ctx = getCtx('onCleanup');
   ctx._cleanupCallbacks = ctx._cleanupCallbacks || [];
   ctx._cleanupCallbacks.push(fn);
 }
@@ -302,7 +371,7 @@ export function createResource(fetcher, options = {}) {
   return [data, { loading, error, refetch, mutate }];
 }
 
-// --- Dep comparison ---
+// --- Dep comparison (kept for potential external use) ---
 
 function depsChanged(oldDeps, newDeps) {
   if (oldDeps === undefined) return true;

package/src/index.js

@@ -2,15 +2,17 @@
 // The closest framework to vanilla JS.
 
 // Reactive primitives
-export { signal, computed, effect, memo as signalMemo, batch, untrack, flushSync, createRoot, __setDevToolsHooks } from './reactive.js';
+export { signal, computed, effect, memo as signalMemo, batch, untrack, flushSync, createRoot, getOwner, runWithOwner, onCleanup as onRootCleanup, __setDevToolsHooks } from './reactive.js';
 
 // Fine-grained rendering primitives
-export { template, insert, mapArray, spread, setProp, delegateEvents, on, classList } from './render.js';
+export { template, _template, _$template, svgTemplate, insert, mapArray, spread, setProp, delegateEvents, on, classList, hydrate, isHydrating, _$createComponent } from './render.js';
 
-// Virtual DOM
+// JSX factory — Fragment and html tagged template are public APIs.
+// h is exported for internal package use only (jsx-runtime, server, router, react-compat).
+// It is NOT a public API — users should write JSX, which the compiler transforms directly.
 export { h, Fragment, html } from './h.js';
 
-// DOM mounting & rendering
+// DOM mounting & rendering (fine-grained, no VDOM reconciler)
 export { mount } from './dom.js';
 
 // Hooks (React-compatible API)
@@ -150,3 +152,35 @@ export {
   Radio,
   ErrorMessage,
 } from './form.js';
+
+// Structured error system (agent-first)
+export {
+  WhatError,
+  ERROR_CODES,
+  createWhatError,
+  classifyError,
+  collectError,
+  getCollectedErrors,
+  clearCollectedErrors,
+} from './errors.js';
+
+// Agent guardrails (dev-mode runtime checks)
+export {
+  configureGuardrails,
+  getGuardrailConfig,
+  installSignalReadGuardrail,
+  checkComponentName,
+  validateImports,
+} from './guardrails.js';
+
+// Agent context (global inspection API)
+export {
+  installAgentContext,
+  registerComponent,
+  unregisterComponent,
+  getMountedComponents,
+  registerSignal,
+  unregisterSignal,
+  getActiveSignals,
+  getHealth,
+} from './agent-context.js';