what-core 0.8.4 → 0.11.0

package/src/guardrails.js

@@ -10,7 +10,6 @@ import { createWhatError, collectError } from './errors.js';
 
 const guardrails = {
   signalReadDetection: true,
-  effectCycleDetection: true,
   componentNaming: true,
   importValidation: true,
 };
@@ -25,16 +24,19 @@ export function getGuardrailConfig() {
 
 // --- Guardrail 1: Signal Read Detection ---
 // Detect when a signal function reference is used where its value was intended.
-// This catches the pattern: <span>{count}</span> (should be count())
+// This catches patterns like `Total: ${count}` or `count > 5` (should be count()).
 //
-// At runtime, we can detect this when a signal is coerced to string (via toString/valueOf)
-// and warn that it should be called.
+// At runtime, we detect this when a signal is coerced to a string or number
+// (via toString/valueOf) and warn that it should be called.
+//
+// Wiring: what-devtools calls this for every signal it registers (dev only),
+// so any app with devtools installed gets the guardrail automatically.
+// It can also be called manually: installSignalReadGuardrail(sig, 'name').
 
 export function installSignalReadGuardrail(signalFn, debugName) {
   if (!__DEV__ || !guardrails.signalReadDetection) return signalFn;
 
   // Override toString to catch template literal coercion
-  const originalToString = signalFn.toString;
   signalFn.toString = function () {
     const err = createWhatError('MISSING_SIGNAL_READ', {
       signalName: debugName || '(unnamed)',
@@ -58,47 +60,16 @@ export function installSignalReadGuardrail(signalFn, debugName) {
   return signalFn;
 }
 
-// --- Guardrail 2: Enhanced Effect Cycle Detection ---
-// Track which signals an effect reads AND writes.
-// If an effect writes to a signal it reads, warn about the specific cycle.
-
-const effectWriteTracking = new WeakMap(); // effect -> Set of signal debug names
-
-export function trackEffectSignalWrite(effectRef, signalDebugName) {
-  if (!__DEV__ || !guardrails.effectCycleDetection) return;
-
-  if (!effectWriteTracking.has(effectRef)) {
-    effectWriteTracking.set(effectRef, new Set());
-  }
-  effectWriteTracking.get(effectRef).add(signalDebugName);
-}
-
-export function checkEffectCycle(effectRef, readSignals) {
-  if (!__DEV__ || !guardrails.effectCycleDetection) return null;
-
-  const writes = effectWriteTracking.get(effectRef);
-  if (!writes || writes.size === 0) return null;
-
-  const overlapping = [];
-  for (const sigName of readSignals) {
-    if (writes.has(sigName)) {
-      overlapping.push(sigName);
-    }
-  }
-
-  if (overlapping.length > 0) {
-    const err = createWhatError('INFINITE_EFFECT', {
-      effectName: effectRef.fn?.name || '(anonymous)',
-      signalName: overlapping.join(', '),
-    });
-    collectError(err);
-    return err;
-  }
-
-  return null;
-}
+// NOTE: an "effect cycle detection" guardrail (trackEffectSignalWrite /
+// checkEffectCycle) used to live here, exported but never called by anything
+// — it was removed in v0.11 rather than shipped as a dead API. Reviving it
+// requires hooks inside reactive.js: (1) a call on every signal WRITE while
+// an effect is the active listener (to attribute writes to effects), and
+// (2) a post-run callback with the effect's tracked read-set (to intersect
+// reads with writes). reactive.js already detects runaway cascades at flush
+// time (iteration cap), which covers the practical failure mode.
 
-// --- Guardrail 3: Component Naming ---
+// --- Guardrail 2: Component Naming ---
 // Warn if a component function is not PascalCase.
 
 export function checkComponentName(name) {
@@ -119,7 +90,7 @@ function capitalize(str) {
   return str.charAt(0).toUpperCase() + str.slice(1);
 }
 
-// --- Guardrail 4: Import Validation ---
+// --- Guardrail 3: Import Validation ---
 // Verify that all named imports from 'what-framework' are valid exports.
 
 const VALID_EXPORTS = new Set([

package/src/h.js

@@ -51,7 +51,12 @@ function _flattenSingle(child) {
     _flattenInto(child, out);
     return out;
   }
-  if (typeof child === 'object' && child._vnode) return [child];
+  if (typeof child === 'object') {
+    if (child._vnode) return [child];
+    // Preserve DOM nodes (HTMLElement, Text, DocumentFragment, etc.) — they
+    // can flow through component composition when JSX is pre-realized.
+    if (typeof child.nodeType === 'number') return [child];
+  }
   if (typeof child === 'function') return [child];
   return [String(child)];
 }
@@ -63,8 +68,15 @@ function _flattenInto(child, out) {
     for (let i = 0; i < child.length; i++) {
       _flattenInto(child[i], out);
     }
-  } else if (typeof child === 'object' && child._vnode) {
-    out.push(child);
+  } else if (typeof child === 'object') {
+    if (child._vnode) {
+      out.push(child);
+    } else if (typeof child.nodeType === 'number') {
+      // DOM node: preserve as-is so insert() can attach it directly.
+      out.push(child);
+    } else {
+      out.push(String(child));
+    }
   } else if (typeof child === 'function') {
     out.push(child);
   } else {

package/src/head.js

@@ -1,6 +1,14 @@
 // What Framework - Head Management
 // Declarative <head> updates from any component.
-// Supports title, meta, link, script tags. Auto-deduplicates by key.
+// Supports title, meta, link tags. Auto-deduplicates by key.
+//
+// Isomorphic: on the client it mutates document.head directly (last-one-wins);
+// on the server it writes into the active render context's head sink (see
+// server-context.js), which renderToStringWithHead serializes into <head> HTML.
+// The server and client use IDENTICAL dedup keys so the rendered head matches
+// what the client would produce — no hydration mismatch.
+
+import { getServerContext } from './server-context.js';
 
 const headState = {
   title: null,
@@ -12,7 +20,13 @@ const headState = {
 // Use in any component to set head tags. Last one wins for title/meta.
 
 export function Head({ title, meta, link, children }) {
-  if (typeof document === 'undefined') return null;
+  if (typeof document === 'undefined') {
+    // Server: collect into the active render context's sink (if a render is
+    // collecting head). No active context => no-op (renderToString body-only).
+    const ctx = getServerContext();
+    if (ctx && ctx.head) writeToSink(ctx.head, { title, meta, link });
+    return children ?? null;
+  }
 
   if (title) {
     document.title = title;
@@ -36,6 +50,62 @@ export function Head({ title, meta, link, children }) {
   return children || null;
 }
 
+// --- Server-side head collection ---
+
+function metaKey(attrs) {
+  return attrs.name || attrs.property || attrs.httpEquiv || JSON.stringify(attrs);
+}
+
+function writeToSink(sink, { title, meta, link }) {
+  if (title != null) sink.title = title;
+  if (meta) {
+    for (const attrs of (Array.isArray(meta) ? meta : [meta])) {
+      sink.metas.set(metaKey(attrs), attrs);
+    }
+  }
+  if (link) {
+    for (const attrs of (Array.isArray(link) ? link : [link])) {
+      sink.links.set(attrs.rel + (attrs.href || ''), attrs);
+    }
+  }
+}
+
+/** Create a fresh head sink for one render. */
+export function beginHeadCollection() {
+  return { title: null, metas: new Map(), links: new Map() };
+}
+
+/** Serialize a head sink into escaped <head> HTML (title + meta + link). */
+export function endHeadCollection(sink) {
+  if (!sink) return '';
+  let out = '';
+  if (sink.title != null) out += `<title>${escapeHtml(String(sink.title))}</title>`;
+  for (const attrs of sink.metas.values()) out += renderHeadTag('meta', attrs);
+  for (const attrs of sink.links.values()) out += renderHeadTag('link', attrs);
+  return out;
+}
+
+function renderHeadTag(tag, attrs) {
+  let s = `<${tag}`;
+  for (const [k, v] of Object.entries(attrs)) {
+    if (v == null || v === false) continue;
+    const name = k === 'httpEquiv' ? 'http-equiv' : k;
+    s += ` ${name}="${escapeHtml(String(v))}"`;
+  }
+  return s + '>';
+}
+
+function escapeHtml(str) {
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+// --- Client DOM helpers ---
+
 function setHeadTag(tag, key, attrs) {
   const existing = document.head.querySelector(`[data-what-head="${key}"]`);
   if (existing) {

package/src/hooks.js

@@ -5,6 +5,22 @@
 
 import { signal, computed, effect, batch, untrack, createRoot, __DEV__ } from './reactive.js';
 import { getCurrentComponent } from './dom.js';
+import { getServerContext } from './server-context.js';
+import { getLoaderData as _getLoaderData, getResource as _getResource } from './hydration-data.js';
+
+// --- useLoaderData ---
+// Returns the current page's server loader data. Works during SSR (reads the
+// active render context) and during/after hydration on the client (reads the
+// consolidated #__what_data payload). Intentionally NOT a component-scoped hook
+// (no hook slot) so it is safe to call anywhere — components, effects, helpers.
+export function useLoaderData() {
+  if (typeof document === 'undefined') {
+    const ctx = getServerContext();
+    return ctx ? ctx.loaderData : undefined;
+  }
+  // Client: read from the consolidated hydration payload (cached, single parse).
+  return _getLoaderData();
+}
 
 function getCtx(hookName) {
   const ctx = getCurrentComponent();
@@ -315,8 +331,53 @@ export function onCleanup(fn) {
 // Returns [data, { loading, error, refetch, mutate }]
 
 export function createResource(fetcher, options = {}) {
-  const data = signal(options.initialValue ?? null);
-  const loading = signal(!options.initialValue);
+  // --- Server branch: run the fetcher, cache by key on the render context, and
+  // suspend (throw the promise) so the nearest Suspense shows its fallback until
+  // the data resolves. On re-render the cached value is returned synchronously.
+  if (typeof document === 'undefined') {
+    const ctx = getServerContext();
+    if (ctx) {
+      const key = options.key != null ? options.key : `__r${ctx.resourceCounter++}`;
+      const cached = ctx.resources.get(key);
+      if (cached && cached.status === 'ready') {
+        const accessor = () => cached.value;
+        return [accessor, { loading: () => false, error: () => null, refetch: () => {}, mutate: () => {} }];
+      }
+      if (cached && cached.status === 'error') {
+        const accessor = () => undefined;
+        return [accessor, { loading: () => false, error: () => cached.error, refetch: () => {}, mutate: () => {} }];
+      }
+      if (!cached) {
+        const promise = Promise.resolve()
+          .then(() => fetcher(options.source ?? true, {}))
+          .then((v) => { ctx.resources.set(key, { status: 'ready', value: v }); })
+          .catch((e) => { ctx.resources.set(key, { status: 'error', error: e }); });
+        ctx.resources.set(key, { status: 'pending', promise });
+        throw promise; // caught by the nearest Suspense boundary
+      }
+      // pending (shouldn't normally re-reach here within one pass)
+      throw cached.promise;
+    }
+    // No active render context (bare synchronous renderToString): suspend so the
+    // nearest Suspense boundary shows its fallback. There's no cache to resolve
+    // into here — use renderToStringAsync / renderToStream for resolved data.
+    if (options.initialValue != null) {
+      const accessor = () => options.initialValue;
+      return [accessor, { loading: () => false, error: () => null, refetch: () => {}, mutate: () => {} }];
+    }
+    throw Promise.resolve().then(() => fetcher(options.source ?? true, {}));
+  }
+
+  // --- Client branch: seed from the hydration payload so SSR'd resources don't
+  // refetch on hydrate.
+  let seeded = options.initialValue;
+  if (seeded == null && options.key != null) {
+    const fromPayload = _getResource(options.key);
+    if (fromPayload !== undefined) seeded = fromPayload;
+  }
+
+  const data = signal(seeded ?? null);
+  const loading = signal(seeded == null);
   const error = signal(null);
 
   let controller = null;
@@ -363,8 +424,8 @@ export function createResource(fetcher, options = {}) {
     });
   }
 
-  // Initial fetch if no initial value
-  if (!options.initialValue) {
+  // Initial fetch only if we have no value (initial or hydrated from payload)
+  if (seeded == null) {
     refetch(options.source);
   }
 

package/src/hydration-data.js

@@ -0,0 +1,34 @@
+// Client hydration payload reader. The server emits a single
+// <script id="__what_data" type="application/json">{loaderData,resources,islandStores}</script>
+// (via serializeState — XSS-safe, valid JSON). This module is the single source
+// of truth the client uses for useLoaderData() and createResource() seeding.
+
+let _cache;
+
+export function __readHydrationData() {
+  if (_cache !== undefined) return _cache;
+  if (typeof document === 'undefined') return (_cache = null);
+  const el = document.getElementById('__what_data');
+  if (!el) return (_cache = null);
+  try {
+    _cache = JSON.parse(el.textContent);
+  } catch {
+    _cache = null;
+  }
+  return _cache;
+}
+
+/** Test/HMR hook: drop the cached payload so the next read re-parses. */
+export function __resetHydrationData() {
+  _cache = undefined;
+}
+
+export function getLoaderData() {
+  const data = __readHydrationData();
+  return data ? data.loaderData : undefined;
+}
+
+export function getResource(key) {
+  const data = __readHydrationData();
+  return data && data.resources ? data.resources[key] : undefined;
+}

package/src/index.js

@@ -2,7 +2,7 @@
 // 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, __setDevToolsHooks, __drainPreinstallBuffer } 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';
@@ -30,6 +30,7 @@ export {
   onMount,
   onCleanup,
   createResource,
+  useLoaderData,
 } from './hooks.js';
 
 // Component helpers
@@ -39,7 +40,13 @@ export { memo, lazy, Suspense, ErrorBoundary, Show, For, Switch, Match, Island }
 export { createStore, derived, storeComputed, atom } from './store.js';
 
 // Head management
-export { Head, clearHead } from './head.js';
+export { Head, clearHead, beginHeadCollection, endHeadCollection } from './head.js';
+
+// SSR render-scoped context (keystone for head collection, loaders, resources)
+export { getServerContext, setServerContext, runWithServerContext } from './server-context.js';
+
+// Client hydration payload reader (loader data + resources)
+export { __readHydrationData, __resetHydrationData, getLoaderData, getResource } from './hydration-data.js';
 
 // Utilities
 export {

package/src/reactive.js

@@ -287,6 +287,8 @@ function _updateLevel(e) {
 // Runs a function, auto-tracking signal reads. Re-runs when deps change.
 // Returns a dispose function.
 
+const _noopDispose = () => {};
+
 export function effect(fn, opts) {
   const e = _createEffect(fn);
   e._level = 1;
@@ -303,6 +305,26 @@ export function effect(fn, opts) {
   _updateLevel(e);
   // Mark as stable after first run — subsequent re-runs skip cleanup/re-subscribe
   if (opts?.stable) e._stable = true;
+
+  // Zero-dependency release (SPRINT v0.11 C4): an effect that tracked zero
+  // signals on its first run can never be notified again — re-tracking only
+  // happens during a re-run, and a re-run requires a notification from a
+  // subscribed signal. The compiler conservatively wraps destructured props /
+  // imported accessors in effects; when those turn out to be plain values the
+  // effect is one-shot. If it also registered no cleanup, release it now:
+  // no dispose closure, no owner registration, nothing retained.
+  // - Effects that returned a cleanup keep full registration so the cleanup
+  //   still runs on owner disposal.
+  // - onCleanup() callbacks register with currentRoot directly (not with the
+  //   effect), so they are unaffected by this release.
+  // - untrack()/peek() reads inside the fn produce zero deps by design — the
+  //   effect could never re-fire anyway, so releasing is safe.
+  if (e.deps.length === 0 && e._cleanup === null) {
+    e.disposed = true;
+    if (__DEV__ && __devtools) __devtools.onEffectDispose(e);
+    return _noopDispose;
+  }
+
   const dispose = () => _disposeEffect(e);
   // Register with current root for automatic cleanup
   if (currentRoot) {
@@ -571,7 +593,21 @@ function flush() {
         e._pending = false;
         if (!e.disposed && !e._onNotify) {
           const prevDepsLen = e.deps.length;
-          _runEffect(e);
+          // Isolate per-effect errors: one throwing effect must NOT abort the
+          // rest of the batch (which would drop queued effects and leave the
+          // graph half-updated). NEEDS_UPSTREAM is the iterative-eval sentinel
+          // and must still propagate. (AUDIT-2026-06-06 H8)
+          try {
+            _runEffect(e);
+          } catch (err) {
+            if (err === NEEDS_UPSTREAM) throw err;
+            if (__DEV__ && __devtools?.onError) __devtools.onError(err, { type: 'effect', effect: e });
+            // Surface in production too — an uncaught reactive-update error is a
+            // real bug; staying silent (as the old throw-out-of-flush did once it
+            // escaped) hides it. console.error never aborts the batch.
+            try { console.error('[what] Uncaught error in effect during update:', err); } catch { /* no console */ }
+            continue;
+          }
           // Update level only if deps changed (graph structure change)
           if (!e._computed && e.deps.length !== prevDepsLen) {
             _updateLevel(e);
@@ -843,3 +879,66 @@ export function onCleanup(fn) {
     currentRoot.disposals.push(fn);
   }
 }
+
+// devtools: registry-iterator export for P1-9 —
+// Late-install replay buffer. When installDevTools() runs AFTER signals or
+// effects have already been created (the canonical example: a module-scope
+// `export const todos = signal([], 'todos')` in store.js, imported before
+// the devtools entry point), those signals were invisible to what_signals.
+//
+// We install a placeholder __devtools that ONLY buffers creations into weak
+// refs. When the real devtools install via __setDevToolsHooks, they call
+// __drainPreinstallBuffer() to register every buffered primitive.
+//
+// Cost in production: __DEV__ is false → __devtools stays null, no buffering.
+// Cost in dev: one WeakRef per signal/effect created before install.
+if (__DEV__ && typeof WeakRef !== 'undefined') {
+  // Cap each buffer so an app that never installs devtools doesn't accumulate
+  // refs unbounded. 2k is far more than any realistic component/signal count
+  // needed before the devtools entry point runs; once devtools install, the
+  // buffer is drained and subsequent creations flow through the real hooks.
+  const PREINSTALL_CAP = 2000;
+  const buffer = { signals: new Set(), effects: new Set(), components: [] };
+  __devtools = {
+    __isPreinstallBuffer: true,
+    onSignalCreate(sig) {
+      if (buffer.signals.size < PREINSTALL_CAP) buffer.signals.add(new WeakRef(sig));
+    },
+    onSignalUpdate() {},
+    onEffectCreate(e) {
+      if (buffer.effects.size < PREINSTALL_CAP) buffer.effects.add(new WeakRef(e));
+    },
+    onEffectDispose() {},
+    onEffectRun() {},
+    onError() {},
+    onComponentMount(ctx) {
+      if (buffer.components.length < PREINSTALL_CAP) buffer.components.push(ctx);
+    },
+    onComponentUnmount() {},
+    __buffer: buffer,
+  };
+}
+
+/**
+ * Drain the pre-install buffer. Called by the real devtools hooks after
+ * __setDevToolsHooks replaces the placeholder. Returns arrays of live refs.
+ */
+export function __drainPreinstallBuffer() {
+  if (!__DEV__) return { signals: [], effects: [], components: [] };
+  // If the current __devtools is the real one (no __isPreinstallBuffer), the
+  // caller installed late and there is nothing to drain from this side.
+  const out = { signals: [], effects: [], components: [] };
+  const buf = (typeof __preinstallSnapshot !== 'undefined') ? __preinstallSnapshot : null;
+  if (!buf) return out;
+  for (const ref of buf.signals) { const v = ref.deref?.(); if (v) out.signals.push(v); }
+  for (const ref of buf.effects) { const v = ref.deref?.(); if (v) out.effects.push(v); }
+  for (const ctx of buf.components) out.components.push(ctx);
+  return out;
+}
+
+// Capture the placeholder buffer at module load so __drainPreinstallBuffer
+// can return it AFTER __setDevToolsHooks has replaced __devtools.
+let __preinstallSnapshot = null;
+if (__DEV__ && __devtools?.__isPreinstallBuffer) {
+  __preinstallSnapshot = __devtools.__buffer;
+}