what-core 0.11.8 → 0.12.0

package/src/a11y.js

@@ -4,6 +4,7 @@
 import { signal, effect } from './reactive.js';
 import { h } from './h.js';
 import { getCurrentComponent } from './dom.js';
+import { getServerContext } from './server-context.js';
 
 // --- Focus Management ---
 
@@ -401,17 +402,48 @@ export function LiveRegion({ children, priority = 'polite', atomic = true }) {
 // --- ID Generator ---
 // Generate unique IDs for ARIA attributes
 
+// The counter is render-scoped on the server and module-global on the client.
+//
+// A bare module-global counter is wrong on the server in two independent ways.
+// Ids drift between the SSR pass and hydration, which breaks exactly the
+// relationships useId exists to create (`for`/`id`, `aria-labelledby`,
+// `aria-describedby`), and concurrent requests interleave into each other's
+// sequence, so two visitors can be served HTML whose ids were allocated in the
+// order the event loop happened to run. Every framework in the cohort ships this
+// primitive as SSR-stable because that is the whole point of shipping it.
+//
+// getServerContext() is the render-scoped store the SSR keystone already
+// maintains (AsyncLocalStorage-backed in Node), so this is wiring rather than
+// new machinery, and it adds no public API.
 let idCounter = 0;
 
+function nextIdSuffix() {
+  const ctx = getServerContext();
+  if (ctx) {
+    ctx.idCounter = (ctx.idCounter || 0) + 1;
+    return ctx.idCounter;
+  }
+  return ++idCounter;
+}
+
+/**
+ * Reset the client-side counter. Called at the start of hydration so the client
+ * reproduces the server's id sequence instead of continuing past it.
+ * @internal
+ */
+export function __resetIdCounter() {
+  idCounter = 0;
+}
+
 export function useId(prefix = 'what') {
-  const id = `${prefix}-${++idCounter}`;
+  const id = `${prefix}-${nextIdSuffix()}`;
   return () => id;
 }
 
 export function useIds(count, prefix = 'what') {
   const ids = [];
   for (let i = 0; i < count; i++) {
-    ids.push(`${prefix}-${++idCounter}`);
+    ids.push(`${prefix}-${nextIdSuffix()}`);
   }
   return ids;
 }

package/src/agent-context.js

@@ -8,7 +8,7 @@ import { getCollectedErrors } from './errors.js';
 // --- Version ---
 // Keep in sync with packages/core/package.json (checked by
 // core/test/guardrails.test.js so it can't silently go stale again).
-const VERSION = '0.11.8';
+const VERSION = '0.12.0';
 
 // --- Component Registry ---
 // Tracks mounted components for agent inspection.

package/src/components.js

@@ -3,6 +3,7 @@
 
 import { h } from './h.js';
 import { signal, effect, untrack, __DEV__ } from './reactive.js';
+import { isServerRender } from './server-context.js';
 
 // Legacy errorBoundaryStack removed — tree-based resolution via _parentCtx._errorBoundary
 // is now the only mechanism. See reportError() below.
@@ -271,94 +272,161 @@ export function Match(props) {
 }
 
 // --- Island ---
-// Deferred hydration component for islands architecture.
-// Usage: h(Island, { component: Counter, mode: 'idle' })
-// 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);
-  const hydrated = signal(false);
-
-  function doHydrate() {
-    if (hydrated()) return;
-    hydrated.set(true);
-    // Render the actual component
-    wrapper.set(h(Component, props));
+// Islands architecture: the content ships as server-rendered HTML and only the
+// *interactivity* is deferred to a client trigger. The babel plugin compiles
+// `<Counter client:idle />` into h(Island, { component: Counter, mode: 'idle' }).
+//
+// This used to render an empty marker div on every path, on the server AND the
+// client, in every mode: the SSR branch never rendered the component, and the
+// client branch read `hydrated()` once in a run-once component so the swap-in
+// never happened. Every `client:*` directive silently deleted its component.
+
+// Late-bound renderers, injected by render.js. components.js cannot import
+// render.js directly (render -> dom -> components is already a cycle), so the
+// same injection precedent as _injectGetCurrentComponent applies here.
+let _islandRuntime = null;
+
+/** @internal */
+export function _injectIslandRuntime(runtime) {
+  _islandRuntime = runtime;
+}
+
+// Island props cross the server/client boundary as JSON, so anything that is not
+// representable is dropped rather than throwing mid-render. Functions in
+// particular are common (event handlers passed down) and are simply not
+// transferable: the island re-creates its own handlers when it hydrates.
+function serializeIslandProps(props) {
+  const out = {};
+  for (const key in props) {
+    const value = props[key];
+    if (typeof value === 'function' || typeof value === 'symbol' || value === undefined) continue;
+    out[key] = value;
+  }
+  try {
+    return JSON.stringify(out);
+  } catch {
+    return '{}';
+  }
+}
+
+export function Island({ component: Component, mode, mediaQuery, name, children, ...props }) {
+  const islandName = name || Component?.name || 'Island';
+  const resolvedMode = mode || 'idle';
+
+  const marker = {
+    'data-island': islandName,
+    'data-island-mode': resolvedMode,
+    'data-hydrate': resolvedMode,
+    // Tells hydrateIslands() to leave this element alone: a compiler-emitted
+    // island holds a direct component reference and hydrates itself, so it
+    // needs no registry entry and must not be claimed twice.
+    'data-island-self': '1',
+  };
+
+  // Server: render the island's HTML inline, inside the marker. An island that
+  // emits nothing costs SEO and LCP to buy lazy hydration, which is a strictly
+  // worse trade than not using the directive at all.
+  // Children arrive as props here but must be handed to the component
+  // positionally: the renderers rebuild `props.children` from the vnode's own
+  // children list, so anything passed through props alone is overwritten.
+  const childList = children == null ? [] : (Array.isArray(children) ? children : [children]);
+
+  if (isServerRender()) {
+    return h(
+      'div',
+      { ...marker, 'data-island-props': serializeIslandProps(props) },
+      h(Component, props, ...childList)
+    );
+  }
+
+  let hydrated = false;
+
+  function hydrateInto(el) {
+    if (hydrated) return;
+    hydrated = true;
+
+    const vnode = h(Component, props, ...childList);
+
+    // Server-rendered children present => hydrate in place, reusing the DOM.
+    // Nothing there => a client-only render, so build it from scratch.
+    if (el.childNodes.length > 0 && _islandRuntime?.hydrate) {
+      _islandRuntime.hydrate(vnode, el);
+    } else if (_islandRuntime?.insert) {
+      _islandRuntime.insert(el, vnode, null);
+    }
+
+    el.removeAttribute('data-hydrate');
+    el.removeAttribute('data-island-self');
+    el.setAttribute('data-island-hydrated', '');
+    // Build the event in the element's own realm. A global CustomEvent belongs
+    // to a different realm inside an iframe or a DOM shim, and dispatchEvent
+    // rejects it as "not of type 'Event'".
+    const view = el.ownerDocument?.defaultView ?? globalThis;
+    if (typeof view.CustomEvent === 'function') {
+      el.dispatchEvent(new view.CustomEvent('island:hydrated', {
+        bubbles: true,
+        detail: { name: islandName, mode: resolvedMode },
+      }));
+    }
   }
 
-  // Schedule hydration based on mode
   function scheduleHydration(el) {
-    switch (mode) {
+    const trigger = () => hydrateInto(el);
+
+    switch (resolvedMode) {
       case 'load':
-        queueMicrotask(doHydrate);
+        queueMicrotask(trigger);
         break;
 
       case 'idle':
-        if (typeof requestIdleCallback !== 'undefined') {
-          requestIdleCallback(doHydrate);
-        } else {
-          setTimeout(doHydrate, 200);
-        }
+        if (typeof requestIdleCallback !== 'undefined') requestIdleCallback(trigger);
+        else setTimeout(trigger, 200);
         break;
 
       case 'visible': {
+        if (typeof IntersectionObserver === 'undefined') { queueMicrotask(trigger); break; }
         const observer = new IntersectionObserver((entries) => {
-          if (entries[0].isIntersecting) {
+          if (entries.some((entry) => entry.isIntersecting)) {
             observer.disconnect();
-            doHydrate();
+            trigger();
           }
-        });
+        }, { rootMargin: '200px' });
         observer.observe(el);
         break;
       }
 
-      case 'interaction': {
-        const hydrate = () => {
-          el.removeEventListener('click', hydrate);
-          el.removeEventListener('focus', hydrate);
-          el.removeEventListener('mouseenter', hydrate);
-          doHydrate();
+      case 'interaction':
+      case 'action': {
+        const events = ['click', 'focus', 'mouseenter', 'touchstart'];
+        const onInteract = () => {
+          for (const type of events) el.removeEventListener(type, onInteract);
+          trigger();
         };
-        el.addEventListener('click', hydrate, { once: true });
-        el.addEventListener('focus', hydrate, { once: true });
-        el.addEventListener('mouseenter', hydrate, { once: true });
+        for (const type of events) el.addEventListener(type, onInteract, { once: true });
         break;
       }
 
       case 'media': {
-        if (!mediaQuery) { doHydrate(); break; }
+        if (!mediaQuery || typeof window === 'undefined' || !window.matchMedia) { trigger(); break; }
         const mq = window.matchMedia(mediaQuery);
-        if (mq.matches) {
-          queueMicrotask(doHydrate);
-        } else {
-          const checkMedia = () => {
-            if (mq.matches) {
-              mq.removeEventListener('change', checkMedia);
-              doHydrate();
-            }
-          };
-          mq.addEventListener('change', checkMedia);
-        }
+        if (mq.matches) { queueMicrotask(trigger); break; }
+        const onChange = () => {
+          if (!mq.matches) return;
+          mq.removeEventListener('change', onChange);
+          trigger();
+        };
+        mq.addEventListener('change', onChange);
         break;
       }
 
+      // 'static' ships no JS at all: the server HTML is the whole island.
+      case 'static':
+        break;
+
       default:
-        // Unknown mode, hydrate immediately
-        queueMicrotask(doHydrate);
+        queueMicrotask(trigger);
     }
   }
 
-  // Use ref callback to get the DOM element and schedule hydration
-  const refCallback = (el) => {
-    if (el) scheduleHydration(el);
-  };
-
-  // Return: show placeholder until hydrated, then show the real component
-  return h('div', { 'data-island': Component.name || 'Island', 'data-hydrate': mode, ref: refCallback },
-    hydrated() ? wrapper() : null
-  );
+  return h('div', { ...marker, ref: (el) => { if (el) scheduleHydration(el); } });
 }

package/src/data.js

@@ -14,6 +14,25 @@ const validatingSignals = new Map(); // key -> signal(boolean)
 const cacheTimestamps = new Map(); // key -> last access time (for LRU)
 const MAX_CACHE_SIZE = 200;
 
+// --- Query key normalization ---
+// Array keys are joined into the same flat string space as useSWR's string keys,
+// so `useQuery({queryKey: ['todos']})` and `useSWR('todos')` share one cache
+// entry by design. Every cache-facing entry point must normalize identically:
+// useQuery used to be the only one that did, so `invalidateQueries(['todos'])`
+// looked up a raw Array object as a Map key, found nothing, and silently did
+// nothing. The documented shape was the broken one.
+//
+// Segments escape ':' so `['user', 'a:b']` cannot collide with
+// `['user', 'a', 'b']`. A collision here serves one query's data to another,
+// which is worse than a miss.
+function normalizeQueryKey(key) {
+  if (!Array.isArray(key)) return key;
+  return key
+    .map((part) => (typeof part === 'string' ? part : JSON.stringify(part) ?? String(part)))
+    .map((part) => part.replace(/([\\:])/g, '\\$1'))
+    .join(':');
+}
+
 function getCacheSignal(key) {
   cacheTimestamps.set(key, Date.now());
   if (!cacheSignals.has(key)) {
@@ -335,7 +354,7 @@ export function useQuery(options) {
     placeholderData,
   } = options;
 
-  const key = Array.isArray(queryKey) ? queryKey.join(':') : queryKey;
+  const key = normalizeQueryKey(queryKey);
 
   const cacheS = getCacheSignal(key);
   const data = computed(() => {
@@ -503,7 +522,7 @@ export function useInfiniteQuery(options) {
   const isFetchingNextPage = signal(false);
   const isFetchingPreviousPage = signal(false);
 
-  const key = Array.isArray(queryKey) ? queryKey.join(':') : queryKey;
+  const key = normalizeQueryKey(queryKey);
   let abortController = null;
 
   let isRefetching = false;
@@ -595,15 +614,36 @@ export function useInfiniteQuery(options) {
 
 // --- Cache Management ---
 
+// Every key the cache knows about. A query that has subscribed but not yet
+// resolved has a revalidation subscriber before it has a cache signal, and
+// invalidating it is exactly how you tell it to fetch, so both maps count.
+function allKnownKeys() {
+  const keys = new Set(cacheSignals.keys());
+  for (const key of revalidationSubscribers.keys()) keys.add(key);
+  return keys;
+}
+
 export function invalidateQueries(keyOrPredicate, options = {}) {
-  const { hard = false } = options;
+  const { hard = false, exact = false } = options;
   const keysToInvalidate = [];
   if (typeof keyOrPredicate === 'function') {
     for (const [key] of cacheSignals) {
       if (keyOrPredicate(key)) keysToInvalidate.push(key);
     }
+  } else if (Array.isArray(keyOrPredicate) && !exact) {
+    // An array key is a PREFIX: invalidateQueries(['todos']) invalidates
+    // ['todos', 1] and ['todos', {done: true}] too, which is what the shape
+    // implies and what every peer library does. Matching is on segment
+    // boundaries, so ['todo'] never matches 'todos'.
+    const prefix = normalizeQueryKey(keyOrPredicate);
+    const scoped = prefix + ':';
+    for (const key of allKnownKeys()) {
+      if (key === prefix || (typeof key === 'string' && key.startsWith(scoped))) {
+        keysToInvalidate.push(key);
+      }
+    }
   } else {
-    keysToInvalidate.push(keyOrPredicate);
+    keysToInvalidate.push(normalizeQueryKey(keyOrPredicate));
   }
 
   for (const key of keysToInvalidate) {
@@ -619,6 +659,7 @@ export function invalidateQueries(keyOrPredicate, options = {}) {
 }
 
 export function prefetchQuery(key, fetcher) {
+  key = normalizeQueryKey(key);
   const cacheS = getCacheSignal(key);
   return fetcher(key).then(result => {
     cacheS.set(result);
@@ -628,6 +669,7 @@ export function prefetchQuery(key, fetcher) {
 }
 
 export function setQueryData(key, updater) {
+  key = normalizeQueryKey(key);
   const cacheS = getCacheSignal(key);
   const current = cacheS.peek();
   cacheS.set(typeof updater === 'function' ? updater(current) : updater);
@@ -635,6 +677,7 @@ export function setQueryData(key, updater) {
 }
 
 export function getQueryData(key) {
+  key = normalizeQueryKey(key);
   return cacheSignals.has(key) ? cacheSignals.get(key).peek() : undefined;
 }
 

package/src/dom.js

@@ -70,6 +70,24 @@ export function _isUnsafeAttr(key, value) {
   return !isSafeUrl(value);
 }
 
+// ARIA attributes and `role` take ENUMERATED string values, never HTML boolean
+// syntax. `aria-checked=""` is not a valid value, and an ABSENT `aria-expanded`
+// means something different from `aria-expanded="false"` (unsupported versus
+// collapsed) to assistive technology.
+//
+// This is shared because the three render paths disagreed. The client
+// (dom.js setProp) hit a generic `typeof value === 'boolean'` branch before it
+// ever reached its aria branch, so it emitted `aria-checked=""` for true and
+// removed the attribute for false. The server special-cased `true` correctly but
+// skipped every falsy value earlier in the loop, so it dropped `false` entirely.
+// So SSR emitted valid ARIA and the first client update silently corrupted it,
+// while `aria-*={false}` was wrong everywhere. Every widget built on the a11y
+// module is affected, since useAriaExpanded/useAriaSelected/useAriaChecked all
+// return booleans.
+export function _isAriaAttr(key) {
+  return key === 'role' || key.startsWith('aria-');
+}
+
 // Track all mounted component contexts for disposal
 const mountedComponents = new Set();
 
@@ -250,7 +268,26 @@ export function createDOM(vnode, parent, isSvg) {
     frag.appendChild(startMarker);
     frag.appendChild(endMarker);
 
+    // Capture the owning component at CREATION time.
+    //
+    // This effect re-runs long after the synchronous render that created it,
+    // when the component stack is empty. Everything it builds on a re-run
+    // therefore got `parentCtx = null`, severing the owner chain, and the two
+    // things that walk that chain both went blind:
+    //   - suspend() found no Suspense boundary, so a lazy() component reached by
+    //     a signal update (any client-side navigation) threw its pending promise
+    //     as an uncaught error and left the region permanently empty.
+    //   - the ErrorBoundary lookup found nothing, so a throw from a component
+    //     rendered after any state change escaped the boundary wrapping it.
+    // Both worked on first paint and only failed once the app was interactive.
+    const owner = componentStack[componentStack.length - 1] || null;
+
     const dispose = effect(() => {
+      // Already on top during the initial synchronous run; only re-push when the
+      // stack has since unwound.
+      const restoreOwner = owner !== null && componentStack[componentStack.length - 1] !== owner;
+      if (restoreOwner) componentStack.push(owner);
+      try {
       const val = vnode();
       const vnodes = (val == null || val === false || val === true)
         ? []
@@ -282,6 +319,9 @@ export function createDOM(vnode, parent, isSvg) {
           }
         }
       }
+      } finally {
+        if (restoreOwner) componentStack.pop();
+      }
     });
 
     startMarker._dispose = dispose;
@@ -970,6 +1010,14 @@ function setProp(el, key, value, isSvg) {
     return;
   }
 
+  // aria-*/role BEFORE the boolean fast-path: these are enumerated string
+  // attributes, so a boolean has to serialize as "true"/"false", never as HTML
+  // boolean syntax. See _isAriaAttr.
+  if (_isAriaAttr(key)) {
+    el.setAttribute(key, typeof value === 'boolean' ? String(value) : value);
+    return;
+  }
+
   // Boolean attributes
   if (typeof value === 'boolean') {
     if (value) el.setAttribute(key, '');
@@ -977,8 +1025,8 @@ function setProp(el, key, value, isSvg) {
     return;
   }
 
-  // data-* and aria-*
-  if (key.startsWith('data-') || key.startsWith('aria-')) {
+  // data-*
+  if (key.startsWith('data-')) {
     el.setAttribute(key, value);
     return;
   }

package/src/index.js

@@ -14,6 +14,9 @@ export { h, Fragment, html } from './h.js';
 
 // DOM mounting & rendering (fine-grained, no VDOM reconciler)
 export { mount } from './dom.js';
+// Internal, underscore-prefixed: shared so the client, compiled-JSX and SSR
+// attribute paths cannot disagree about ARIA serialization again.
+export { _isAriaAttr } from './dom.js';
 
 // Hooks (React-compatible API)
 export {

package/src/render.js

@@ -3,7 +3,9 @@
 // No VDOM diffing — direct DOM manipulation with surgical signal-driven updates.
 
 import { effect, untrack, createRoot, _createItemScope, signal, memo, __DEV__ } from './reactive.js';
+import { __resetIdCounter } from './a11y.js';
 import { createDOM, disposeTree, getCurrentComponent, getComponentStack, addHydrationDisposer, addHydratedComponent, _setSelectValue, _isUnsafeAttr, _isEventProp, _installLazyChildren, _handleNavigationSignal } from './dom.js';
+import { _injectIslandRuntime } from './components.js';
 export { effect, untrack };
 // Re-export memo for compiled output (branch memoization: the compiler emits
 // _$memo(() => cond) so conditional branches only re-create DOM when the
@@ -1596,6 +1598,12 @@ export function isHydrating() {
  */
 export function hydrate(vnode, container) {
   _isHydrating = true;
+  // Restart the useId sequence so the client reproduces the server's ids rather
+  // than continuing past them. The server allocates from a render-scoped counter
+  // starting at 1; without this reset any client-side useId call made before
+  // hydration would shift every id and break the `for`/`aria-labelledby`
+  // relationships the primitive exists to create.
+  __resetIdCounter();
   _hydrationCursor = { parent: container, index: 0 };
 
   try {
@@ -1843,9 +1851,20 @@ function hydrateNode(vnode, parent) {
  */
 function hydrateElementProps(el, props) {
   for (const key in props) {
-    if (key === 'children' || key === 'key' || key === 'ref') continue;
+    if (key === 'children' || key === 'key') continue;
     if (key === 'dangerouslySetInnerHTML' || key === 'innerHTML') continue;
 
+    // Refs must fire on the hydration path too. Skipping them meant every
+    // component that reaches for its own DOM node through a ref got nothing
+    // under SSR while working fine in a client-only render, which is the
+    // hardest class of bug to find: it only reproduces in production.
+    if (key === 'ref') {
+      const ref = props.ref;
+      if (typeof ref === 'function') ref(el);
+      else if (ref && typeof ref === 'object') ref.current = el;
+      continue;
+    }
+
     const value = props[key];
 
     // Event handlers — always attach (they don't exist in SSR HTML)
@@ -1880,3 +1899,9 @@ function hydrateElementProps(el, props) {
     if (key === 'data-hk') continue;
   }
 }
+
+// Islands hydrate themselves against their own DOM element, which needs both the
+// hydration walker and the insert path. components.js is upstream of this module
+// (render -> dom -> components), so the renderers are handed down rather than
+// imported back up, matching _injectGetCurrentComponent.
+_injectIslandRuntime({ hydrate, insert });

package/src/server-context.js

@@ -33,6 +33,18 @@ export function getServerContext() {
   return _asyncContextStorage?.getStore() ?? _current;
 }
 
+/**
+ * True while a server render is in progress.
+ *
+ * Prefer this over a bare `typeof document === 'undefined'` check. That test asks
+ * "is there a DOM?" when the question is "am I rendering to a string?", and the
+ * two answers diverge under every DOM shim (jsdom, happy-dom, a Workers
+ * polyfill) and in any test that renders both ways in one process.
+ */
+export function isServerRender() {
+  return typeof document === 'undefined' || getServerContext() != null;
+}
+
 /**
  * Set the active context. Returns the PREVIOUS context so callers can restore it
  * manually (runWithServerContext does this for you).

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;
@@ -101,3 +101,38 @@ export interface Screen {
 }
 
 export const screen: Screen;
+
+// --- renderTest ---
+// Render a component and expose the signals it created by debug name, so a test
+// can drive state directly instead of going through the DOM.
+
+export interface RenderTestResult {
+  container: HTMLElement;
+  /** Signals created during the component's single run, keyed by debug name. */
+  signals: Record<string, Signal<any>>;
+  /** Flush pending effects synchronously. */
+  update(): void;
+  unmount(): void;
+}
+
+export function renderTest<P = {}>(Component: (props: P) => any, props?: P): RenderTestResult;
+
+/** Run every pending effect synchronously, so assertions see settled DOM. */
+export function flushEffects(): void;
+
+/** Record which signals a callback reads and writes, by debug name. */
+export function trackSignals(fn: () => void): { accessed: string[]; written: string[] };
+
+// --- mockSignal ---
+// A signal that records every distinct value it has held.
+
+export interface MockSignal<T> extends Signal<T> {
+  /** Every distinct value, oldest first, starting with the initial value. */
+  readonly history: T[];
+  /** How many times the value actually changed (equal writes do not count). */
+  readonly setCount: number;
+  /** Restore the initial value (or `value`) and clear the history. */
+  reset(value?: T): void;
+}
+
+export function mockSignal<T>(name: string, initialValue: T): MockSignal<T>;