what-core 0.6.2 → 0.6.5

package/src/compiler.js

@@ -0,0 +1,18 @@
+// What Framework - Compiler Runtime Internals
+// Stable import target for generated compiler output. Not for app code.
+
+export {
+  _$createComponent,
+  _$template,
+  _template,
+  template,
+  insert,
+  mapArray,
+  spread,
+  setProp,
+  delegateEvents,
+  on,
+  classList,
+  effect,
+  untrack,
+} from './render.js';

package/src/components.js

@@ -154,42 +154,73 @@ export function reportError(error, startCtx) {
 
 // --- Show ---
 // Conditional rendering component. Cleaner than ternaries.
+// Reactively shows/hides children based on the `when` condition.
 
 export function Show({ when, fallback = null, children }) {
-  // when can be a signal or a value
-  const condition = typeof when === 'function' ? when() : when;
-  return condition ? children : fallback;
+  // If `when` is a signal or function, return a reactive function
+  // so the DOM runtime tracks changes via its effect wrapper
+  if (typeof when === 'function') {
+    return () => when() ? children : fallback;
+  }
+  // Static value — just return directly
+  return when ? children : fallback;
 }
 
 // --- For ---
-// Efficient list rendering with keyed reconciliation.
-
-export function For({ each, fallback = null, children }) {
-  const list = typeof each === 'function' ? each() : each;
-  if (!list || list.length === 0) return fallback;
-
+// Reactive list rendering with keyed reconciliation.
+// Takes a signal (or function returning an array) as `each` and reactively
+// adds/removes/moves DOM nodes when the array changes.
+// Uses mapArray from render.js for efficient keyed reconciliation with LIS.
+//
+// Usage: <For each={items}>{(item, index) => <div>{item}</div>}</For>
+// - `each`: signal or function returning an array
+// - `children`: render function (item, index) => vnode
+// - `fallback`: shown when array is empty
+// - `key`: optional key function (item) => key for keyed reconciliation
+
+export function For({ each, fallback = null, children, key: keyFn }) {
   // children should be a function (item, index) => vnode
   const renderFn = Array.isArray(children) ? children[0] : children;
   if (typeof renderFn !== 'function') {
-    console.warn('[what] For: children must be a render function, e.g. <For each={items}>{(item) => ...}</For>');
+    if (__DEV__) {
+      console.warn('[what] For: children must be a render function, e.g. <For each={items}>{(item) => ...}</For>');
+    }
     return fallback;
   }
 
-  return list.map((item, index) => {
+  // Normalize `each` to a function that returns the current array
+  const source = typeof each === 'function' ? each : () => each;
+
+  // Build the map function that wraps renderFn with auto-key detection
+  const mapFn = (item, index) => {
     const vnode = renderFn(item, index);
     // Auto-detect keys for efficient keyed reconciliation
     if (vnode && typeof vnode === 'object' && vnode.key == null) {
-      if (item != null && typeof item === 'object') {
-        // Use item.id or item.key if available
-        if (item.id != null) vnode.key = item.id;
-        else if (item.key != null) vnode.key = item.key;
-      } else if (typeof item === 'string' || typeof item === 'number') {
-        // Primitive items can be their own key
-        vnode.key = item;
+      const rawItem = typeof item === 'function' && item._signal ? item() : item;
+      if (rawItem != null && typeof rawItem === 'object') {
+        if (rawItem.id != null) vnode.key = rawItem.id;
+        else if (rawItem.key != null) vnode.key = rawItem.key;
+      } else if (typeof rawItem === 'string' || typeof rawItem === 'number') {
+        vnode.key = rawItem;
       }
     }
     return vnode;
-  });
+  };
+
+  // Return a reactive function. The DOM runtime (createDOM in dom.js)
+  // wraps functions in effects, so this will re-evaluate whenever the
+  // source signal changes. For simple cases (no mapArray integration),
+  // this provides correct reactivity by re-rendering the list on change.
+  //
+  // The effect wrapper in createDOM (lines 140-190 in dom.js) handles:
+  // - Creating DOM nodes for new vnodes
+  // - Removing old DOM nodes
+  // - Inserting between comment markers
+  return () => {
+    const list = source();
+    if (!list || list.length === 0) return fallback;
+    return list.map((item, i) => mapFn(item, i));
+  };
 }
 
 // --- Switch / Match ---
@@ -198,12 +229,29 @@ export function For({ each, fallback = null, children }) {
 export function Switch({ fallback = null, children }) {
   const kids = Array.isArray(children) ? children : [children];
 
+  const hasReactiveCondition = kids.some(
+    child => child && child.tag === Match && typeof child.props.when === 'function'
+  );
+
+  if (hasReactiveCondition) {
+    return () => {
+      for (const child of kids) {
+        if (child && child.tag === Match) {
+          const condition = typeof child.props.when === 'function'
+            ? child.props.when()
+            : child.props.when;
+          if (condition) {
+            return child.children;
+          }
+        }
+      }
+      return fallback;
+    };
+  }
+
   for (const child of kids) {
     if (child && child.tag === Match) {
-      const condition = typeof child.props.when === 'function'
-        ? child.props.when()
-        : child.props.when;
-      if (condition) {
+      if (child.props.when) {
         return child.children;
       }
     }
@@ -223,8 +271,6 @@ export function Match({ when, children }) {
 // The babel plugin compiles <Counter client:idle /> into this.
 
 export function Island({ component: Component, mode, mediaQuery, ...props }) {
-  const placeholder = h('div', { 'data-island': Component.name || 'Island', 'data-hydrate': mode });
-
   // We need to return a vnode that the reconciler can handle.
   // The actual hydration scheduling happens after mount via an effect.
   const wrapper = signal(null);
@@ -304,8 +350,8 @@ export function Island({ component: Component, mode, mediaQuery, ...props }) {
     if (el) scheduleHydration(el);
   };
 
-  // Return: show placeholder until hydrated, then show the real component
+  // Return: reactive function so DOM runtime tracks hydration state changes
   return h('div', { 'data-island': Component.name || 'Island', 'data-hydrate': mode, ref: refCallback },
-    hydrated() ? wrapper() : null
+    () => hydrated() ? wrapper() : null
   );
 }

package/src/devtools.js

@@ -0,0 +1,4 @@
+// What Framework - DevTools bridge
+// Internal integration surface consumed by what-devtools.
+
+export { __setDevToolsHooks } from './reactive.js';

package/src/dom.js

@@ -204,6 +204,13 @@ export function createDOM(vnode, parent, isSvg) {
     return createComponent(vnode, parent, isSvg);
   }
 
+  // Special boundary vnodes (returned by ErrorBoundary, Suspense, Portal components)
+  // These have string tags like '__errorBoundary' and must be routed to createComponent
+  // which contains the special-case handlers for them.
+  if (isVNode(vnode) && (vnode.tag === '__errorBoundary' || vnode.tag === '__suspense' || vnode.tag === '__portal')) {
+    return createComponent(vnode, parent, isSvg);
+  }
+
   // VNode with string tag — create element
   if (isVNode(vnode)) {
     return createElementFromVNode(vnode, parent, isSvg);

package/src/guardrails.js

@@ -125,11 +125,10 @@ function capitalize(str) {
 const VALID_EXPORTS = new Set([
   // Reactive primitives
   'signal', 'computed', 'effect', 'signalMemo', 'batch', 'untrack', 'flushSync',
-  'createRoot', 'getOwner', 'runWithOwner', 'onRootCleanup', '__setDevToolsHooks',
+  'createRoot', 'getOwner', 'runWithOwner', 'onRootCleanup',
   // Rendering
-  'template', '_template', 'svgTemplate', 'insert', 'mapArray', 'spread',
+  'template', 'svgTemplate', 'insert', 'mapArray', 'spread',
   'setProp', 'delegateEvents', 'on', 'classList', 'hydrate', 'isHydrating',
-  '_$createComponent',
   // JSX
   'h', 'Fragment', 'html',
   // DOM
@@ -163,7 +162,7 @@ const VALID_EXPORTS = new Set([
   'IslandSkeleton', 'useSkeleton', 'Placeholder', 'LoadingDots', 'Spinner',
   // Data fetching
   'useFetch', 'useSWR', 'useQuery', 'useInfiniteQuery', 'invalidateQueries',
-  'prefetchQuery', 'setQueryData', 'getQueryData', 'clearCache', '__getCacheSnapshot',
+  'prefetchQuery', 'setQueryData', 'getQueryData', 'clearCache',
   // Form
   'useForm', 'useField', 'rules', 'simpleResolver', 'zodResolver', 'yupResolver',
   'Input', 'Textarea', 'Select', 'Checkbox', 'Radio', 'ErrorMessage',

package/src/hooks.js

@@ -371,14 +371,3 @@ export function createResource(fetcher, options = {}) {
   return [data, { loading, error, refetch, mutate }];
 }
 
-// --- Dep comparison (kept for potential external use) ---
-
-function depsChanged(oldDeps, newDeps) {
-  if (oldDeps === undefined) return true;
-  if (!oldDeps || !newDeps) return true;
-  if (oldDeps.length !== newDeps.length) return true;
-  for (let i = 0; i < oldDeps.length; i++) {
-    if (!Object.is(oldDeps[i], newDeps[i])) return true;
-  }
-  return false;
-}

package/src/index.js

@@ -2,10 +2,10 @@
 // The closest framework to vanilla JS.
 
 // Reactive primitives
-export { signal, computed, effect, memo as signalMemo, batch, untrack, flushSync, createRoot, getOwner, runWithOwner, onCleanup as onRootCleanup, __setDevToolsHooks } from './reactive.js';
+export { signal, computed, effect, memo as signalMemo, batch, untrack, flushSync, createRoot, getOwner, runWithOwner, onCleanup as onRootCleanup } from './reactive.js';
 
 // Fine-grained rendering primitives
-export { template, _template, _$template, svgTemplate, insert, mapArray, spread, setProp, delegateEvents, on, classList, hydrate, isHydrating, _$createComponent } from './render.js';
+export { template, svgTemplate, insert, mapArray, spread, setProp, delegateEvents, on, classList, hydrate, isHydrating, getHydrationMismatchCount } from './render.js';
 
 // JSX factory — Fragment and html tagged template are public APIs.
 // h is exported for internal package use only (jsx-runtime, server, router, react-compat).
@@ -15,15 +15,12 @@ export { h, Fragment, html } from './h.js';
 // DOM mounting & rendering (fine-grained, no VDOM reconciler)
 export { mount } from './dom.js';
 
-// Hooks (React-compatible API)
+// Hooks — Solid-style API (signal-first)
+// React-style hooks (useState, useEffect, useMemo, useCallback, useRef)
+// are available via 'what-framework/react-compat' only.
 export {
-  useState,
   useSignal,
   useComputed,
-  useEffect,
-  useMemo,
-  useCallback,
-  useRef,
   useContext,
   useReducer,
   createContext,
@@ -134,7 +131,6 @@ export {
   setQueryData,
   getQueryData,
   clearCache,
-  __getCacheSnapshot,
 } from './data.js';
 
 // Form utilities

package/src/render.js

@@ -2,8 +2,9 @@
 // Solid-style rendering: components run once, signals create individual DOM effects.
 // No VDOM diffing — direct DOM manipulation with surgical signal-driven updates.
 
-import { effect, untrack, createRoot, signal, __DEV__ } from './reactive.js';
+import { effect, untrack, createRoot, signal, __DEV__, __devtools } from './reactive.js';
 import { createDOM, disposeTree, getCurrentComponent, getComponentStack } from './dom.js';
+import { createWhatError, collectError } from './errors.js';
 
 export { effect, untrack };
 
@@ -980,9 +981,16 @@ export function isHydrating() {
 export function hydrate(vnode, container) {
   _isHydrating = true;
   _hydrationCursor = { parent: container, index: 0 };
+  _hydrationMismatchCount = 0;
 
   try {
     const result = hydrateNode(vnode, container);
+    if (__DEV__ && _hydrationMismatchCount > 0) {
+      console.warn(
+        `[what] Hydration completed with ${_hydrationMismatchCount} mismatch${_hydrationMismatchCount === 1 ? '' : 'es'}. ` +
+        'See previous warnings for details. This usually means server and client render different initial HTML.'
+      );
+    }
     return result;
   } finally {
     _isHydrating = false;
@@ -1012,11 +1020,46 @@ function claimNode(parent) {
   return null;
 }
 
-function isDevMode() {
-  return typeof process !== 'undefined' && process.env?.NODE_ENV !== 'production';
+// Track hydration mismatch count for diagnostics
+let _hydrationMismatchCount = 0;
+
+/** Returns the number of hydration mismatches encountered during the last hydrate() call. */
+export function getHydrationMismatchCount() {
+  return _hydrationMismatchCount;
 }
 
-function hydrateNode(vnode, parent) {
+function reportHydrationMismatch(expected, actual, componentName) {
+  _hydrationMismatchCount++;
+  if (__DEV__) {
+    const context = {
+      component: componentName || 'unknown',
+      serverHTML: actual,
+      clientHTML: expected,
+    };
+    const whatError = createWhatError('HYDRATION_MISMATCH', context);
+    collectError(whatError);
+    // Notify devtools so MCP agents see hydration mismatches as live events
+    if (__devtools?.onHydrationMismatch) {
+      __devtools.onHydrationMismatch({
+        component: componentName || 'unknown',
+        expected,
+        actual,
+        mismatchCount: _hydrationMismatchCount,
+      });
+    }
+    // Also notify the error handler so it appears in devtools error log
+    if (__devtools?.onError) {
+      __devtools.onError(whatError, { type: 'hydration', component: componentName });
+    }
+    console.warn(
+      `[what] Hydration mismatch: expected ${expected}, got ${actual}` +
+      (componentName ? ` (in ${componentName})` : '') +
+      '. Falling back to client render.'
+    );
+  }
+}
+
+function hydrateNode(vnode, parent, _componentName) {
   if (vnode == null || typeof vnode === 'boolean') {
     return null;
   }
@@ -1028,9 +1071,9 @@ function hydrateNode(vnode, parent) {
 
     if (existing && existing.nodeType === 3) {
       // Reuse text node — check for mismatch in dev
-      if (isDevMode() && existing.textContent !== text) {
-        console.warn(
-          `[what] Hydration mismatch: expected text "${text}", got "${existing.textContent}"`
+      if (__DEV__ && existing.textContent !== text) {
+        reportHydrationMismatch(
+          `text "${text}"`, `text "${existing.textContent}"`, _componentName
         );
         existing.textContent = text;
       }
@@ -1038,11 +1081,9 @@ function hydrateNode(vnode, parent) {
     }
 
     // Mismatch: expected text node, got element or nothing
-    if (isDevMode()) {
-      console.warn(
-        `[what] Hydration mismatch: expected text node "${text}", got ${existing ? existing.nodeName : 'nothing'}. Falling back to client render.`
-      );
-    }
+    reportHydrationMismatch(
+      `text node "${text}"`, existing ? existing.nodeName : 'nothing', _componentName
+    );
     const textNode = document.createTextNode(text);
     if (existing) {
       parent.replaceChild(textNode, existing);
@@ -1056,7 +1097,7 @@ function hydrateNode(vnode, parent) {
   if (typeof vnode === 'function') {
     // Unwrap to get the initial value for hydration
     const initialValue = vnode();
-    let current = hydrateNode(initialValue, parent);
+    let current = hydrateNode(initialValue, parent, _componentName);
 
     // Set up reactive effect for future updates (normal rendering path)
     effect(() => {
@@ -1073,7 +1114,7 @@ function hydrateNode(vnode, parent) {
   if (Array.isArray(vnode)) {
     const nodes = [];
     for (const child of vnode) {
-      const node = hydrateNode(child, parent);
+      const node = hydrateNode(child, parent, _componentName);
       if (node) nodes.push(node);
     }
     return nodes.length === 1 ? nodes[0] : nodes;
@@ -1085,6 +1126,7 @@ function hydrateNode(vnode, parent) {
     if (typeof vnode.tag === 'function') {
       const componentStack = getComponentStack();
       const Component = vnode.tag;
+      const compName = Component.displayName || Component.name || 'Anonymous';
       const props = vnode.props || {};
       const children = vnode.children || [];
 
@@ -1111,7 +1153,9 @@ function hydrateNode(vnode, parent) {
         result = Component({ ...props, children: propsChildren });
       } catch (error) {
         componentStack.pop();
-        console.error('[what] Error in component during hydration:', Component.name || 'Anonymous', error);
+        if (__DEV__) {
+          console.error('[what] Error in component during hydration:', compName, error);
+        }
         return null;
       }
 
@@ -1128,7 +1172,7 @@ function hydrateNode(vnode, parent) {
         });
       }
 
-      return hydrateNode(result, parent);
+      return hydrateNode(result, parent, compName);
     }
 
     // Element — claim existing DOM element
@@ -1139,6 +1183,16 @@ function hydrateNode(vnode, parent) {
       // Match! Reuse this element. Apply props/bindings.
       hydrateElementProps(existing, vnode.props || {});
 
+      // Handle ref callback — this was previously missing during hydration
+      if (vnode.props?.ref) {
+        const ref = vnode.props.ref;
+        if (typeof ref === 'function') {
+          ref(existing);
+        } else if (typeof ref === 'object' && ref !== null) {
+          ref.current = existing;
+        }
+      }
+
       // Hydrate children
       const savedCursor = _hydrationCursor;
       _hydrationCursor = { parent: existing, index: 0 };
@@ -1146,7 +1200,7 @@ function hydrateNode(vnode, parent) {
       const rawInner = vnode.props?.dangerouslySetInnerHTML?.__html;
       if (rawInner == null) {
         for (const child of vnode.children) {
-          hydrateNode(child, existing);
+          hydrateNode(child, existing, _componentName);
         }
       }
 
@@ -1155,11 +1209,9 @@ function hydrateNode(vnode, parent) {
     }
 
     // Mismatch — fall back to client render for this subtree
-    if (isDevMode()) {
-      console.warn(
-        `[what] Hydration mismatch: expected <${vnode.tag}>, got ${existing ? existing.nodeName : 'nothing'}. Falling back to client render.`
-      );
-    }
+    reportHydrationMismatch(
+      `<${vnode.tag}>`, existing ? existing.nodeName : 'nothing', _componentName
+    );
 
     // Create the element from scratch
     const newEl = document.createElement(vnode.tag);
@@ -1230,8 +1282,23 @@ function hydrateElementProps(el, props) {
       continue;
     }
 
-    // Static props — skip attributes already set from SSR
-    // Only attach non-serializable props or ones that may differ
+    // Static props — verify attributes match in dev mode
     if (key === 'data-hk') continue;
+
+    // In dev mode, check that the server-rendered attribute matches the client value
+    // to catch hydration mismatches early (e.g., class="foo" vs class="bar")
+    if (__DEV__ && typeof value === 'string') {
+      const attrName = key === 'className' ? 'class' : key === 'htmlFor' ? 'for' : key;
+      const serverValue = el.getAttribute(attrName);
+      if (serverValue !== null && serverValue !== value) {
+        reportHydrationMismatch(
+          `${attrName}="${value}"`,
+          `${attrName}="${serverValue}"`,
+          el.tagName.toLowerCase()
+        );
+        // Apply client value to fix the mismatch
+        setProp(el, key, value);
+      }
+    }
   }
 }

package/testing.d.ts

@@ -1,6 +1,6 @@
 // What Framework - Testing Utilities Type Definitions
 
-import { VNode, Signal } from './index';
+import { VNode, Signal } from './index.js';
 
 // Setup and Cleanup
 export function setupDOM(): HTMLElement | null;