what-core 0.12.2 → 0.12.4

package/src/render.js

@@ -5,7 +5,7 @@
 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';
+import { _injectIslandRuntime, reportError } 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
@@ -196,7 +196,20 @@ export function insert(parent, child, marker) {
     let current = null;
     let textNode = null; // non-null while on the text fast path
     let mounted = false;
-    effect(() => {
+    // Capture the owning component at CREATION time. See the identical capture
+    // in createDOM's reactive branch (dom.js): this effect re-runs long after
+    // the synchronous render that created it, when the component stack is
+    // empty, so everything it builds on a re-run got parentCtx = null and the
+    // owner chain was severed. useContext then fell through to the context
+    // DEFAULT, and an ErrorBoundary stopped catching throws from components
+    // created by an inner region. Both work on first paint and only break once
+    // the app is interactive, which is why nothing caught it.
+    //
+    // dom.js was given this fix; this path, the one the COMPILER emits for
+    // every `{() => ...}`, was not. So it was broken for exactly the users on
+    // the recommended build setup.
+    const owner = captureOwner();
+    effect(() => withOwner(owner, () => {
       const val = child();
       const vt = typeof val;
       if (!mounted) {
@@ -223,7 +236,7 @@ export function insert(parent, child, marker) {
       // Type changed (or never was text) — full reconcile
       textNode = null;
       current = reconcileInsert(parent, val, current, m);
-    });
+    }));
     return current;
   }
 
@@ -263,6 +276,32 @@ function isSvgParent(parent) {
     && parent.tagName !== 'foreignObject';
 }
 
+// --- Owner capture for effects that outlive their render ---
+//
+// A reactive region's effect re-runs long after the synchronous render that
+// created it, when the component stack has unwound. Anything it builds then has
+// no owning component, which severs the chain that useContext and the
+// ErrorBoundary / Suspense lookups both walk. Capturing the owner at creation
+// and re-pushing it for the duration of each re-run restores it.
+
+function captureOwner() {
+  const stack = getComponentStack();
+  return stack[stack.length - 1] || null;
+}
+
+function withOwner(owner, fn) {
+  const stack = getComponentStack();
+  // Already on top during the initial synchronous run; only re-push when the
+  // stack has since unwound.
+  const restore = owner !== null && stack[stack.length - 1] !== owner;
+  if (restore) stack.push(owner);
+  try {
+    return fn();
+  } finally {
+    if (restore) stack.pop();
+  }
+}
+
 function asNodeArray(value) {
   if (value == null) return [];
   return Array.isArray(value) ? value : [value];
@@ -504,9 +543,36 @@ export function mapArray(source, mapFn, options) {
     return endMarker;
   };
   inserter._mapArray = true;
+  // The server has no DOM to insert into, so it cannot call the inserter at all.
+  // Without these it fell through to the generic reactive-child branch, which
+  // calls the value with no arguments: `parent` was undefined, the insertBefore
+  // threw, SSR swallowed it, and every compiled keyed list rendered as an EMPTY
+  // container. Exposing the inputs lets the server produce the same rows the
+  // client will, in the same order, without touching a DOM.
+  inserter._mapArraySource = source;
+  inserter._mapArrayFn = mapFn;
+  inserter._mapArrayKeyed = !!keyFn && !raw;
   return inserter;
 }
 
+/**
+ * Render a mapArray inserter's rows without a DOM. Server-side only.
+ *
+ * Mirrors the item protocol reconcileKeyed/reconcileList use, because a row
+ * built here is hydrated by one built there: keyed non-raw mode hands the mapFn
+ * a signal ACCESSOR (so `item()` works), every other mode hands it the raw item.
+ * Getting this wrong produces server HTML that differs from the client's on
+ * every row.
+ */
+export function _mapArrayToArray(inserter) {
+  const items = inserter._mapArraySource() || [];
+  const mapFn = inserter._mapArrayFn;
+  const keyed = inserter._mapArrayKeyed;
+  return items.map((item, index) => (
+    keyed ? mapFn(() => item, index) : mapFn(item, index)
+  ));
+}
+
 function reconcileList(parent, endMarker, oldItems, newItems, mappedNodes, disposeFns, mapFn) {
   const newLen = newItems.length;
   const oldLen = oldItems.length;
@@ -1293,6 +1359,22 @@ export function spread(el, props) {
   for (const key in props) {
     const value = props[key];
 
+    // Ref — the element, not a reactive getter.
+    //
+    // This is the one prop whose FUNCTION form is a callback taking the element
+    // rather than an accessor returning a value, which is exactly why the other
+    // two call sites special-case it before the reactive-prop test (setProp
+    // below, and applyProps in dom.js). Spread did not, so a function ref fell
+    // into the reactive branch and was invoked as `value()` with NO ARGUMENT.
+    // Every `{...register('email')}`-shaped API broke in silence on the
+    // compiled path: the ref saw `undefined`, guarded, and returned, so no
+    // element was ever registered and nothing threw to say so.
+    if (key === 'ref') {
+      if (typeof value === 'function') value(el);
+      else if (value && typeof value === 'object') value.current = el;
+      continue;
+    }
+
     if (_isEventProp(key)) {
       // Event handler — direct assignment. Use $$name for delegated events.
       if (typeof value !== 'function') continue;
@@ -1608,6 +1690,15 @@ export function hydrate(vnode, container) {
 
   try {
     const result = hydrateNode(vnode, container);
+    // Same trim as every nested element, with one exclusion. A dedicated root
+    // element holds nothing but the app, so anything the walk did not claim is
+    // stranded server markup. <body> and <html> are different: they also hold
+    // the script tags, the hydration payload and whatever the host page put
+    // there, none of which the walk claims and none of which may be removed.
+    // An app that hydrates into <body> keeps the old behavior.
+    if (container !== document.body && container !== document.documentElement) {
+      trimUnclaimed(container);
+    }
     return result;
   } finally {
     _isHydrating = false;
@@ -1615,6 +1706,64 @@ export function hydrate(vnode, container) {
   }
 }
 
+/**
+ * Drop server-rendered nodes that the client's walk never claimed.
+ *
+ * Everything from the cursor to the end of `parent` is content the server
+ * produced and the client tree has no child for. Nothing references it, no
+ * effect owns it, and no later update can ever reach it: it is stranded markup
+ * that simply stays on screen.
+ *
+ * The case that makes this necessary is a reactive region that is empty on the
+ * client and was NOT empty on the server. An empty region deliberately claims
+ * nothing (claiming took the following sibling and destroyed it, cascading a
+ * warn-and-recreate through the rest of the parent), so the element the server
+ * rendered in its place has nothing to remove it. A cart badge the server drew
+ * for a signed-in visitor stayed visible to a signed-out one, underneath the
+ * region that was supposed to have replaced it.
+ *
+ * The two halves are what make each other safe: the walk never destroys a node
+ * it is unsure about, and this removes what the finished walk proves is unused.
+ */
+function trimUnclaimed(parent) {
+  if (!_hydrationCursor || _hydrationCursor.parent !== parent) return;
+  while (parent.childNodes.length > _hydrationCursor.index) {
+    const node = parent.lastChild;
+    disposeTree(node);
+    parent.removeChild(node);
+  }
+}
+
+/**
+ * Comment markers that belong to the machinery, not to the page.
+ *
+ * '$' / '/$' and '[]' / '/[]' come from the server's hydratable output. The
+ * rest are planted by the hydration walk itself as it goes: 'fn' / '/fn' bound
+ * a reactive region (the function branch of hydrateNode), 'eb:*' and 'sb:*'
+ * bound an <ErrorBoundary> or a <Suspense> (hydrateBoundary), and 'portal' /
+ * 'portal:empty' are a <Portal>'s placeholder.
+ *
+ * In every case the cursor is advanced past the marker at the moment it goes
+ * in, so a later sibling REACHING one means the cursor has desynced. Skipping
+ * is what keeps that desync from turning destructive. No vnode form in this
+ * framework produces a comment node, so the element and text branches treat a
+ * claimed comment as a mismatch and replaceChild() it away: a sibling that
+ * claimed a region's end marker would delete the marker, leave the region
+ * unterminated, and send its next update walking off the end of the parent.
+ * Losing one node's reuse is a scratch; losing a marker is fatal to the region.
+ */
+const _HYDRATION_MARKERS = new Set([
+  '$', '/$', '[]', '/[]',
+  'fn', '/fn',
+  'eb:start', 'eb:end',
+  'sb:start', 'sb:end',
+  'portal', 'portal:empty',
+]);
+
+function _isHydrationMarker(node) {
+  return node.nodeType === 8 && _HYDRATION_MARKERS.has(node.textContent);
+}
+
 /**
  * Claim the next DOM node from the hydration cursor.
  * Returns the existing DOM node or null if none available.
@@ -1623,13 +1772,9 @@ function claimNode(parent) {
   const children = parent.childNodes;
   while (_hydrationCursor.index < children.length) {
     const node = children[_hydrationCursor.index];
-    // Skip hydration comment markers
-    if (node.nodeType === 8) { // Comment node
-      const text = node.textContent;
-      if (text === '$' || text === '/$' || text === '[]' || text === '/[]') {
-        _hydrationCursor.index++;
-        continue;
-      }
+    if (_isHydrationMarker(node)) {
+      _hydrationCursor.index++;
+      continue;
     }
     _hydrationCursor.index++;
     return node;
@@ -1637,8 +1782,54 @@ function claimNode(parent) {
   return null;
 }
 
+/**
+ * What claimNode would return next, without consuming it.
+ *
+ * Used by the branches that must decide whether the server left something
+ * REUSABLE here before they commit to taking it. Claiming first and putting it
+ * back is not possible: claiming is what advances the walk.
+ */
+function peekNode(parent) {
+  if (!_hydrationCursor || _hydrationCursor.parent !== parent) return null;
+  const children = parent.childNodes;
+  for (let i = _hydrationCursor.index; i < children.length; i++) {
+    const node = children[i];
+    if (_isHydrationMarker(node)) continue;
+    return node;
+  }
+  return null;
+}
+
+/**
+ * Put a client-created node in at the cursor and advance past it.
+ *
+ * The mismatch fallbacks used to appendChild here, which puts the node at the
+ * END of the parent rather than at the position being hydrated, and left the
+ * cursor pointing AT it. Inside a reactive region that was fatal: the region's
+ * end marker is placed at the cursor, so it landed BEFORE the content, the
+ * region owned nothing, and it could never remove or replace what it had just
+ * rendered. A `<Show>` whose server arm produced nothing showed its client arm
+ * once and then ignored the signal forever.
+ */
+function insertAtCursor(parent, node) {
+  if (_hydrationCursor && _hydrationCursor.parent === parent) {
+    parent.insertBefore(node, parent.childNodes[_hydrationCursor.index] || null);
+    _hydrationCursor.index++;
+  } else {
+    parent.appendChild(node);
+  }
+  return node;
+}
+
+// Warnings only. Never gate a DOM CORRECTION on this: see the text branch below.
+//
+// This used to test `process.env.NODE_ENV` directly, which is unreachable in a
+// browser (there is no `process`), so hydration warnings could not fire in the
+// one environment where hydration actually runs. __DEV__ resolves the same
+// question across every environment, including a buildless browser app that
+// opts in with globalThis.__WHAT_DEV__.
 function isDevMode() {
-  return typeof process !== 'undefined' && process.env?.NODE_ENV !== 'production';
+  return __DEV__;
 }
 
 function hydrateNode(vnode, parent) {
@@ -1648,21 +1839,63 @@ function hydrateNode(vnode, parent) {
 
   // Text node
   if (typeof vnode === 'string' || typeof vnode === 'number') {
-    const existing = claimNode(parent);
     const text = String(vnode);
 
+    // An empty string never DESTROYS anything to claim it.
+    //
+    // HTML cannot serialize an empty text node, so a reactive child that was
+    // empty on the server emitted nothing at all. Claiming unconditionally took
+    // the next sibling, saw an element where it wanted text, and replaced that
+    // element with an empty text node: the server's real markup was destroyed,
+    // every following sibling shifted, and a warn-and-recreate cascaded through
+    // the rest of the parent. `{() => error()}` next to anything hit it.
+    //
+    // But refusing to claim ANYTHING was the opposite error. When the server
+    // rendered real text here and the client now evaluates to '', the server's
+    // text is exactly what has to be cleared. Skipping it left the stale value
+    // on screen and then rendered the next value ALONGSIDE it ("9 items3
+    // items"), because the region had adopted an empty node of its own while
+    // the server's text sat outside it.
+    //
+    // So: claim a text node if one is there (the client value wins, same as
+    // below), and claim nothing otherwise. The empty and non-empty cases now
+    // differ only in refusing to consume a NON-text node.
+    if (text === '') {
+      const reusable = peekNode(parent);
+      if (reusable && reusable.nodeType === 3) {
+        claimNode(parent);
+        reusable.textContent = '';
+        return reusable;
+      }
+      return insertAtCursor(parent, document.createTextNode(''));
+    }
+
+    const existing = claimNode(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}"`
-        );
+      // Reuse the text node, but the CLIENT value wins.
+      //
+      // Correcting the DOM used to sit inside the dev-only branch, and dev mode
+      // was decided by `process.env.NODE_ENV`, which no browser has. The result
+      // was that in every real browser a differing value was silently discarded
+      // and the server's text stayed on screen until some later write happened
+      // to touch that node. Any state the server cannot know (a cart restored
+      // from localStorage, a saved theme, a relative timestamp) rendered stale
+      // and looked like a broken store rather than a hydration bug.
+      //
+      // The correction is unconditional now. Only the warning is dev-gated.
+      if (existing.textContent !== text) {
+        if (isDevMode()) {
+          console.warn(
+            `[what] Hydration mismatch: expected text "${text}", got "${existing.textContent}"`
+          );
+        }
         existing.textContent = text;
       }
       return existing;
     }
 
-    // Mismatch: expected text node, got element or nothing
+    // 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.`
@@ -1672,7 +1905,7 @@ function hydrateNode(vnode, parent) {
     if (existing) {
       parent.replaceChild(textNode, existing);
     } else {
-      parent.appendChild(textNode);
+      insertAtCursor(parent, textNode);
     }
     return textNode;
   }
@@ -1682,21 +1915,140 @@ function hydrateNode(vnode, parent) {
     return hydrateNode(vnode(), parent);
   }
 
-  // Reactive function child — attach effect to existing node
+  // Compiled keyed list. `.map()` with a key prop, and `<For>`, lower to a
+  // mapArray INSERTER, which is a function taking (parent, marker) rather than a
+  // thunk returning a value. The generic reactive branch below called it with no
+  // arguments, so it threw on `parent.insertBefore` and the exception escaped
+  // hydrate(): the whole page stopped hydrating and stayed inert. That is the
+  // ordinary shape for a compiled app whose server HTML came from an uncompiled
+  // render, which is exactly what the fullstack template produces.
+  //
+  // The list builds its own rows rather than claiming the server's. That is a
+  // missed reuse, not a correctness problem: the inserter owns its end marker
+  // and its effect from here on, and the server's rows are left unclaimed, so
+  // trimUnclaimed removes them once the walk finishes. Claiming them properly
+  // needs the list's own boundary markers in the server HTML, which is the same
+  // thing reactive regions need and is tracked for 0.13.0.
+  if (typeof vnode === 'function' && vnode._mapArray) {
+    const cursorInParent = !!(_hydrationCursor && _hydrationCursor.parent === parent);
+    const anchor = cursorInParent ? (parent.childNodes[_hydrationCursor.index] || null) : null;
+    const endMarker = vnode(parent, anchor);
+    if (cursorInParent) {
+      const index = Array.prototype.indexOf.call(parent.childNodes, endMarker);
+      if (index >= 0) _hydrationCursor.index = index + 1;
+    }
+    return endMarker;
+  }
+
+  // Reactive function child: attach an effect to the existing nodes
   if (typeof vnode === 'function') {
-    // Unwrap to get the initial value for hydration
-    const initialValue = vnode();
-    let current = hydrateNode(initialValue, parent);
+    // Bound the region with the same comment markers the client render path
+    // uses (see the reactive-function branch of createDOM in dom.js). Hydration
+    // used to create none, and paid for it twice on the first update:
+    //
+    //   - reconcileInsert was handed a null marker, so it had no insertion
+    //     point and appended to the END of the parent. A hydrated <Show> that
+    //     flipped arms jumped to the bottom of its container, because a
+    //     component realizes to a DocumentFragment and fragments deliberately
+    //     skip the replace-in-place fast path.
+    //   - the effect's disposer was attached to the CONTENT node, so removing
+    //     that content disposed the effect. The region then stopped reacting
+    //     entirely: a <Show> broke position on its first flip and went dead on
+    //     its second.
+    //
+    // Markers are stable nodes that outlive every value the region ever holds,
+    // which is exactly why the client path has them. Client-only rendering was
+    // always correct here; only the SSR path was missing them.
+    //
+    // The start marker goes in BEFORE the value is hydrated, at the slot the
+    // cursor is pointing at. Anchoring afterwards to the first content node was
+    // wrong in two ways that both showed up as content in the wrong place:
+    //
+    //   - a value of null/false/undefined claims no node, so there was no anchor
+    //     and both markers were appended to the END of the parent. `<Show>` with
+    //     no fallback, or `{cond && <X/>}`, permanently lost its position: the
+    //     content appeared below every following sibling once it filled in.
+    //   - a NESTED region hydrates while we are still inside this one and
+    //     inserts its own markers around the content first. Anchoring to the
+    //     content then put the outer start marker INSIDE the inner pair, so the
+    //     regions interleaved instead of nesting. Switching the outer arm
+    //     removed the content but neither the inner markers nor the inner
+    //     effect, which kept rendering into a region that was switched off and
+    //     duplicated it when the outer arm came back. `<Show>` wrapping
+    //     `<Show>` or `<For>` is the canonical shape, not an exotic one.
+    //
+    // Opening the region first makes both cases fall out: everything the value
+    // hydrates lands after the start marker, and the end marker closes at
+    // wherever the cursor ends up.
+    const cursorInParent = !!(_hydrationCursor && _hydrationCursor.parent === parent);
+    const startMarker = document.createComment('fn');
+    const endMarker = document.createComment('/fn');
+
+    if (cursorInParent) {
+      parent.insertBefore(startMarker, parent.childNodes[_hydrationCursor.index] || null);
+      _hydrationCursor.index++;
+    } else {
+      parent.appendChild(startMarker);
+    }
 
-    // Set up reactive effect for future updates (normal rendering path)
-    const dispose = effect(() => {
+    // Hydrate the value for its side effects: it claims the server's nodes and,
+    // if it contains a nested region, inserts that region's markers. What it
+    // RETURNS is deliberately ignored, because it is not the region's contents:
+    // a nested region's markers are not in it. The tracked set is read back from
+    // the DOM below, between the markers, which is the actual boundary.
+    hydrateNode(vnode(), parent);
+
+    if (cursorInParent) {
+      parent.insertBefore(endMarker, parent.childNodes[_hydrationCursor.index] || null);
+      _hydrationCursor.index++;
+    } else {
+      parent.appendChild(endMarker);
+    }
+
+    // The region owns EVERYTHING between its markers, not just the nodes its own
+    // value produced. A nested region leaves its markers in here too, and those
+    // markers carry the disposer for the nested effect.
+    //
+    // Tracking only the value's own nodes meant that switching this region off
+    // removed the visible content and left the inner markers and the inner
+    // effect behind. The orphaned effect kept rendering into a region that was
+    // switched off, and its output reappeared, doubled, when this region came
+    // back. Collecting from the DOM is also more honest than reasoning about
+    // what hydrateNode returned: the markers are the boundary, so whatever sits
+    // between them is the content.
+    const owned = [];
+    for (let node = startMarker.nextSibling; node && node !== endMarker; node = node.nextSibling) {
+      owned.push(node);
+    }
+    let current = owned.length === 0 ? null : (owned.length === 1 ? owned[0] : owned);
+
+    // Set up reactive effect for future updates (normal rendering path).
+    // The owner is captured for the same reason as in insert() and createDOM:
+    // every re-run happens with the component stack unwound.
+    const owner = captureOwner();
+    const dispose = effect(() => withOwner(owner, () => {
       const value = vnode();
       // After hydration, this runs as normal insert
       if (!_isHydrating) {
-        current = reconcileInsert(parent, value, current, null);
+        current = reconcileInsert(endMarker.parentNode || parent, value, current, endMarker);
       }
-    });
-    addHydrationDisposer(current && current.nodeType ? current : parent, dispose);
+    }));
+
+    // The disposer is now reachable from three places (either marker via
+    // disposeTree, and the hydration disposer registry), which is deliberate:
+    // whichever one the teardown happens to walk, the effect dies. It must
+    // therefore be idempotent, or a tree disposed through more than one route
+    // decrements the live-effect count once per route.
+    let disposed = false;
+    const disposeOnce = () => {
+      if (disposed) return;
+      disposed = true;
+      dispose();
+    };
+
+    startMarker._dispose = disposeOnce;
+    endMarker._dispose = disposeOnce;
+    addHydrationDisposer(startMarker, disposeOnce);
     return current;
   }
 
@@ -1751,9 +2103,29 @@ function hydrateNode(vnode, parent) {
         if (endChildrenPass) endChildrenPass();
       } catch (error) {
         componentStack.pop();
-        // Same classification as createComponent: a navigation signal carries
-        // its own handler and is not a render failure.
-        if (!_handleNavigationSignal(error)) {
+        // Same classification as createComponent, and it has to be the same or
+        // the two paths disagree about what a throw MEANS:
+        //
+        //   - a navigation signal carries its own handler and is not a failure.
+        //   - a thrown thenable is a SUSPENSION. It is how lazy() says "my
+        //     chunk has not landed yet", and during hydration that is not an
+        //     edge case but the normal one: on a real first load the dynamic
+        //     import is still in flight when hydrate() runs. Logging it and
+        //     returning null left `loading` unflipped, so the <Suspense> region
+        //     came out EMPTY, the server's fallback markup was left unclaimed
+        //     and then trimmed, and the chunk resolving re-rendered nothing.
+        //     The boundary sat permanently blank, which is the one outcome
+        //     Suspense exists to prevent.
+        //   - anything else is a real error and belongs to the nearest
+        //     <ErrorBoundary>, exactly as in a client-only render.
+        //
+        // Unlike createComponent this never RE-THROWS when nothing handles it.
+        // An exception escaping here escapes hydrate() itself and the rest of
+        // the page never hydrates at all; whatever this component was, its
+        // siblings are still recoverable.
+        if (!_handleNavigationSignal(error)
+            && !(error && typeof error.then === 'function' && suspendDuringHydration(error, ctx))
+            && !reportError(error, ctx)) {
           console.error('[what] Error in component during hydration:', Component.name || 'Anonymous', error);
         }
         return null;
@@ -1776,22 +2148,108 @@ function hydrateNode(vnode, parent) {
       // createComponent in dom.js.
       try {
         const node = hydrateNode(result, parent);
-        // No comment markers exist on this path, so anchor the ctx to the node
-        // the component produced (or to the parent when it produced none) —
-        // otherwise disposeTree can never reach it and the ctx leaks.
+        // No comment markers exist for a COMPONENT on this path, so the ctx has
+        // to hang off some node that disposeTree will reach, or it leaks.
+        //
+        // Anchoring it to the first node the component produced is only valid
+        // when that node is stable. If the component's root is a reactive
+        // region, that node is the region's current CONTENT, and the region
+        // replaces it on the very first update: disposeTree then ran over it and
+        // took the whole component context with it. Every effect, cleanup and
+        // onCleanup the component owns died the first time its own root
+        // re-rendered, which is the same create-outside/dispose-inside-an-effect
+        // shape the region markers exist to prevent.
+        //
+        // A region root falls back to the parent element instead. That disposes
+        // later than ideal (when the parent goes, not when the component does),
+        // and disposing late is strictly better than disposing while mounted.
+        //
+        // A boundary root needs no case here: hydrateBoundary returns its start
+        // MARKER rather than its contents, and a marker is stable by
+        // construction.
+        const rootIsRegion = typeof result === 'function'
+          || (Array.isArray(result) && result.some((child) => typeof child === 'function'));
         const first = Array.isArray(node) ? node[0] : node;
-        addHydratedComponent(first && first.nodeType ? first : parent, ctx);
+        const anchor = (!rootIsRegion && first && first.nodeType) ? first : parent;
+        addHydratedComponent(anchor, ctx);
         return node;
       } finally {
         componentStack.pop();
       }
     }
 
+    // Boundary marker tags — NOT elements, and never rendered as themselves.
+    //
+    // <ErrorBoundary>, <Suspense> and <Portal> each return one of these instead
+    // of a DOM tag, and every other render path routes them to a boundary
+    // handler rather than to createElement (dom.js createDOM, and the same
+    // three tags in the server's renderer). Hydration was the one path with no
+    // branch for them, so a marker tag fell through to the ELEMENT branch below
+    // and went looking for a `<__errorBoundary>` element in the server HTML.
+    // What it found was the first node of the boundary's OWN subtree, which it
+    // warned about and destroyed:
+    //
+    //   server:  <div id="x"><p>INNER</p></div>
+    //   client:  <div id="x"><!--eb:start--></div>
+    //
+    // One <ErrorBoundary> anywhere in a server-rendered page blanked everything
+    // under it. The construct whose entire job is to contain a failure was
+    // itself the failure.
+    if (vnode.tag === '__errorBoundary') {
+      const { errorState, fallback, reset, handleError } = vnode.props;
+      return hydrateBoundary(vnode, parent, {
+        startText: 'eb:start',
+        endText: 'eb:end',
+        ctxExtras: { _errorBoundary: handleError },
+        state: errorState,
+        contentFor: (error) => {
+          if (!error) return vnode.children || [];
+          return typeof fallback === 'function' ? fallback({ error, reset }) : fallback;
+        },
+      });
+    }
+
+    if (vnode.tag === '__suspense') {
+      const { boundary, fallback, loading } = vnode.props;
+      return hydrateBoundary(vnode, parent, {
+        startText: 'sb:start',
+        endText: 'sb:end',
+        ctxExtras: { _suspenseBoundary: boundary },
+        state: loading,
+        contentFor: (isLoading) => (isLoading ? fallback : (vnode.children || [])),
+      });
+    }
+
+    // <Portal> renders NOTHING on the server, by the same decision that makes
+    // Portal() return null when there is no document: its content belongs to a
+    // container somewhere else on the page, not to this position. So there is
+    // no server markup here to claim and the portal mounts client-side exactly
+    // as it does in a client-only render.
+    //
+    // The element branch did the opposite. It CLAIMED the next node, which is
+    // the server's next real sibling, warned about a mismatch that never
+    // existed, and replaced that sibling with the portal's placeholder comment.
+    // The claimed node was destroyed and everything after it shifted, so a
+    // portal in the middle of a server-rendered list cost every node behind it:
+    // a modal host declared before the page content rebuilt the entire page.
+    if (vnode.tag === '__portal') {
+      const placeholder = createDOM(vnode, parent);
+      return placeholder ? insertAtCursor(parent, placeholder) : null;
+    }
+
     // Element — claim existing DOM element
+    //
+    // The comparison is case-INSENSITIVE. `nodeName` is uppercased for HTML
+    // elements but case-preserved for everything else, so an SVG element's
+    // nodeName is 'svg' and could never equal `tag.toUpperCase()`. Every inline
+    // SVG on a server-rendered page therefore failed to match, warned
+    // "expected <svg>, got svg", and was destroyed and rebuilt: with
+    // document.createElement, in the HTML namespace, which does not render as
+    // SVG at all. Icons, logos and charts went blank on hydration.
     const existing = claimNode(parent);
-    const expectedTag = vnode.tag.toUpperCase();
+    const expectedTag = vnode.tag.toLowerCase();
 
-    if (existing && existing.nodeType === 1 && existing.nodeName === expectedTag) {
+    if (existing && existing.nodeType === 1 && existing.nodeName.toLowerCase() === expectedTag) {
       // Match! Reuse this element. Apply props/bindings.
       hydrateElementProps(existing, vnode.props || {});
 
@@ -1804,6 +2262,20 @@ function hydrateNode(vnode, parent) {
         for (const child of vnode.children) {
           hydrateNode(child, existing);
         }
+        // Only when the client tree actually declares children here.
+        //
+        // An element the client says is EMPTY is not the same claim as "the
+        // server's content is stale". An island is the counter-example that
+        // matters: it renders a bare host element and fills it in later, when
+        // its trigger fires, from the server HTML still sitting inside it.
+        // Trimming on an empty child list threw that content away and the
+        // island rebuilt it from scratch, which is the exact opposite of what
+        // an island is for (a `mode: 'static'` island, which never hydrates at
+        // all, simply lost its content).
+        //
+        // dangerouslySetInnerHTML is excluded above for the same reason: the
+        // cursor never walks that subtree, so nothing in it is ever claimed.
+        if (vnode.children.length > 0) trimUnclaimed(existing);
       }
 
       _hydrationCursor = savedCursor;
@@ -1817,19 +2289,17 @@ function hydrateNode(vnode, parent) {
       );
     }
 
-    // Create the element from scratch
-    const newEl = document.createElement(vnode.tag);
-    for (const key in vnode.props || {}) {
-      if (key === 'children' || key === 'key') continue;
-      setProp(newEl, key, vnode.props[key]);
-    }
-    for (const child of vnode.children) {
-      reconcileInsert(newEl, child, null, null);
-    }
+    // Create the element from scratch, through the same path a client-only
+    // render uses. The hand-rolled version here called document.createElement
+    // and setProp with no SVG context, so a rebuilt <svg> landed in the XHTML
+    // namespace and rendered as nothing at all, and its attributes were set as
+    // properties rather than attributes. Falling back to a client render has to
+    // mean the client render, not an approximation of it.
+    const newEl = createDOM(vnode, parent, isSvgParent(parent));
     if (existing) {
       parent.replaceChild(newEl, existing);
     } else {
-      parent.appendChild(newEl);
+      insertAtCursor(parent, newEl);
     }
     return newEl;
   }
@@ -1840,9 +2310,361 @@ function hydrateNode(vnode, parent) {
   }
 
   // Fallback — create text node
-  const textNode = document.createTextNode(String(vnode));
-  parent.appendChild(textNode);
-  return textNode;
+  return insertAtCursor(parent, document.createTextNode(String(vnode)));
+}
+
+/**
+ * Hand a thrown thenable to the nearest <Suspense> above `ctx`.
+ *
+ * The twin of the private `suspend()` in dom.js: the same walk up the same
+ * `_parentCtx` chain to the same `_suspenseBoundary`. It is written out again
+ * rather than shared because dom.js keeps its copy module-private, and the two
+ * halves it depends on (the chain, and the boundary's onSuspend) are fixed
+ * shapes that createSuspenseBoundary and hydrateBoundary both build.
+ *
+ * Returns false when nothing above can take the suspension, which makes the
+ * thenable an ordinary unhandled error again.
+ */
+function suspendDuringHydration(promise, ctx) {
+  for (let c = ctx; c; c = c._parentCtx) {
+    if (c._suspenseBoundary) {
+      c._suspenseBoundary.onSuspend(promise);
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Evidence that the node the cursor is parked on is NOT the one `vnode` would
+ * have produced on the server.
+ *
+ * A boundary's region has no delimiter in the server's bytes, so "the markup
+ * here belongs to this boundary" can never be PROVEN from the client. It can
+ * sometimes be refuted, and a refutation is all claimServerArm needs: a plain
+ * element or text vnode names exactly the node it wants, so a <p> facing a
+ * <footer> is a boundary reaching past its own region into its next sibling.
+ *
+ * Anything else — a component, a thunk, a nested boundary marker — cannot
+ * answer without being run, and "cannot tell" is deliberately NOT a refutation.
+ * Refusing there would give up the reuse for `fallback={() => <ErrorMessage />}`,
+ * which is the shape most apps actually write.
+ */
+function contradictsServerNode(vnode, node) {
+  if (typeof vnode === 'string' || typeof vnode === 'number') return node.nodeType !== 3;
+  if (vnode && vnode._vnode && typeof vnode.tag === 'string') {
+    return node.nodeType !== 1 || node.nodeName.toLowerCase() !== vnode.tag.toLowerCase();
+  }
+  return false;
+}
+
+/**
+ * Claim the server's markup for a boundary's FALLBACK, when the server rendered
+ * the fallback too.
+ *
+ * A child that throws during SSR is caught by the server's own boundary branch
+ * (packages/server/src/index.js), so the response carries the fallback and NOT
+ * the children. The same child throws again while hydrating, which flips the
+ * boundary's signal — but by then hydrateBoundary has already walked the happy
+ * arm, and the happy arm does not match a byte of what the server sent. The
+ * fallback markup went unclaimed, the boundary's effect built a second copy of
+ * it, and the first copy was trimmed: the server rendered the fallback and the
+ * client threw it away and rebuilt it.
+ *
+ * What makes this recoverable is that a child which throws before producing
+ * anything claims NOTHING, so the cursor is still parked exactly where the
+ * server's markup for this boundary starts and nothing in the region has been
+ * written over. Then the fallback can hydrate against it like ordinary markup.
+ *
+ * The refusals matter as much as the claim, because the region's extent is not
+ * knowable from the client (see contradictsServerNode):
+ *
+ *   - the failed arm produced something first, so the cursor has moved and
+ *     whatever it moved over has already been claimed or replaced. A child
+ *     ahead of the thrower is the ordinary case here: it claims the server's
+ *     fallback node, calls it a mismatch, and destroys it before the boundary
+ *     ever learns an error happened. Nothing left to reuse.
+ *   - the server left nothing at this position at all. The node at the cursor
+ *     then belongs to the boundary's next SIBLING, and claiming it would be the
+ *     <Portal> failure again: a boundary eating the footer behind it.
+ *   - the node that is there openly disagrees with the fallback's root.
+ *
+ * Every refusal falls back to the boundary's effect rebuilding the region,
+ * which is what this whole path did before and is always correct — a lost
+ * reuse, not a lost node.
+ *
+ * `getContent` is a thunk rather than a value so the refusals above cost
+ * nothing: on a refusal the effect is the one that builds the fallback, and
+ * running a user's `fallback={({ error }) => ...}` twice per catch to throw the
+ * first result away is a side effect this has no business causing.
+ *
+ * Returns true when the region now holds the fallback.
+ */
+function claimServerArm(parent, regionStart, getContent) {
+  // No cursor in this parent means nothing here was being claimed from the
+  // server in the first place.
+  if (regionStart < 0 || !_hydrationCursor || _hydrationCursor.parent !== parent) return false;
+
+  // The failed arm has to have produced NOTHING. Any movement of the cursor is
+  // a node this region has already committed to, claimed or created.
+  if (_hydrationCursor.index !== regionStart) return false;
+
+  // Nothing at this position means there is nothing to reuse. Asked first
+  // because it is the only question answerable without building the fallback.
+  const candidate = peekNode(parent);
+  if (!candidate) return false;
+
+  const content = getContent();
+  const vnodes = Array.isArray(content) ? content : [content];
+  const root = vnodes.find((v) => v != null && typeof v !== 'boolean');
+
+  // A fallback that renders nothing wants an empty region, and an empty region
+  // is what it already has. Claimed, with nothing to claim — and `candidate` is
+  // left for whoever it really belongs to.
+  if (root === undefined) return true;
+
+  if (contradictsServerNode(root, candidate)) return false;
+
+  for (const v of vnodes) hydrateNode(v, parent);
+  return true;
+}
+
+/**
+ * Hydrate an <ErrorBoundary> or a <Suspense>.
+ *
+ * The two are the same machine with a different signal: a marked region whose
+ * contents are the children while the signal is falsy and the fallback once it
+ * is not. The client builds both with createErrorBoundary / createSuspenseBoundary
+ * in dom.js, and this is the hydrating twin of those two functions.
+ *
+ * Three things have to be true when this returns, and each was a separate bug:
+ *
+ *   - the server's markup is still on screen. The children hydrate against it
+ *     in place; nothing is rebuilt.
+ *   - the boundary's context is on the component stack while those children
+ *     hydrate. reportError and suspend() both find their boundary by walking
+ *     `_parentCtx` up from the component that threw, so a boundary missing from
+ *     that chain catches nothing: the error escapes to the console and the page
+ *     dies exactly as it would with no boundary at all.
+ *   - the region is owned by an effect from here on, bounded by real comment
+ *     markers. Without the markers there is no insertion point and no stable
+ *     node to hang the disposer on, which is the same pair of failures the
+ *     reactive-region branch documents above.
+ *
+ * The first effect run is the subtle one. It must NOT rebuild what hydration
+ * just claimed, or hydrating a boundary would be indistinguishable from
+ * client-rendering it. But it cannot skip unconditionally either: a child that
+ * threw or suspended WHILE hydrating flipped the signal before this effect
+ * existed, and in that case the markup between the markers may be the wrong arm
+ * and has to be replaced.
+ *
+ * "May be", not "is", and that is the whole of claimServerArm below. When a
+ * child throws during the SERVER render the server catches it too and puts the
+ * FALLBACK in the HTML, so the two sides agree on the arm and the fallback is
+ * ordinary server markup that hydration should claim like any other. Hydrating
+ * the happy arm first and then rebuilding on the flipped signal threw that
+ * markup away and built a second copy of it, which is exactly the
+ * destroy-and-rebuild these markers exist to stop.
+ */
+function hydrateBoundary(vnode, parent, { startText, endText, ctxExtras, state, contentFor }) {
+  const children = vnode.children || [];
+  const cursorInParent = !!(_hydrationCursor && _hydrationCursor.parent === parent);
+  const startComment = document.createComment(startText);
+  const endComment = document.createComment(endText);
+
+  // Same shape as the contexts the client boundaries build, for the same
+  // reasons: `_parentCtx` keeps useContext resolving through the boundary, and
+  // the marker references let a teardown find the region from the context.
+  const boundaryCtx = {
+    hooks: [],
+    hookIndex: 0,
+    effects: [],
+    cleanups: [],
+    mounted: false,
+    disposed: false,
+    _parentCtx: captureOwner(),
+    _startComment: startComment,
+    _endComment: endComment,
+    ...ctxExtras,
+  };
+
+  // Open the region at the slot the cursor points at, before anything is
+  // hydrated into it, so everything the children claim lands inside the pair.
+  // (Anchoring the markers afterwards to whatever the children produced is
+  // wrong for a boundary that produced nothing, and interleaves nested regions
+  // instead of nesting them. See the reactive-region branch.)
+  if (cursorInParent) {
+    parent.insertBefore(startComment, parent.childNodes[_hydrationCursor.index] || null);
+    _hydrationCursor.index++;
+  } else {
+    parent.appendChild(startComment);
+  }
+
+  // Where the region's content begins, in cursor terms. The start marker has
+  // already consumed its slot, so this is the index the server's first node for
+  // this boundary sits at. claimServerArm needs it to tell "the failed arm
+  // touched nothing" from "the failed arm got part way in".
+  const regionStart = cursorInParent ? _hydrationCursor.index : -1;
+
+  const stack = getComponentStack();
+  stack.push(boundaryCtx);
+  try {
+    for (const child of children) {
+      hydrateNode(child, parent);
+    }
+  } finally {
+    stack.pop();
+  }
+
+  // Which arm the boundary is on now that its children have run.
+  //
+  // Read UNTRACKED. This is the hydration walk, not the effect below, and a
+  // hydrate() reached from inside somebody else's effect would otherwise hand
+  // that effect a subscription to this boundary's private error/loading signal:
+  // an unrelated region upstream would re-render every time a boundary caught.
+  const armAfterWalk = untrack(state);
+
+  // Whether the markup between the markers is already the arm `armAfterWalk`
+  // names. True by construction when nothing flipped the signal (the walk just
+  // claimed the children the server rendered), and true again when the fallback
+  // below is claimed in place.
+  let regionHoldsArm = !armAfterWalk;
+
+  if (armAfterWalk) {
+    // Same re-push as the rebuild in the effect, for the same reason: a
+    // fallback that renders a component of its own must see the boundary in its
+    // parent chain, and contentFor is what runs that fallback.
+    stack.push(boundaryCtx);
+    try {
+      regionHoldsArm = claimServerArm(parent, regionStart, () => contentFor(armAfterWalk));
+    } finally {
+      stack.pop();
+    }
+  }
+
+  if (cursorInParent) {
+    parent.insertBefore(endComment, parent.childNodes[_hydrationCursor.index] || null);
+    _hydrationCursor.index++;
+  } else {
+    parent.appendChild(endComment);
+  }
+
+  let claimedFromServer = true;
+  // Generation guard, carried over from createSuspenseBoundary in dom.js, where
+  // it exists because a child suspending mid-rebuild flips the state signal from
+  // inside the loop below: if that re-entered the effect, the inner run would
+  // replace the region and the outer run would then append the rest of the arm
+  // it was already committed to, putting both arms on screen at once.
+  //
+  // It is honest to say this is currently UNREACHABLE and kept for parity. An
+  // effect cannot re-enter itself here: reactive.js's notify() only executes
+  // subscribers at notifyDepth 0 and queues them otherwise, so a write made
+  // during an effect's own run is always drained after that run returns. Every
+  // shape tried against it (two- and three-deep lazy waterfalls, and a staged
+  // suspender behind a signal so the effect was auto-promoted to _stable and
+  // therefore running INLINE) came back with a nesting depth of 1.
+  //
+  // Keeping it costs four lines and removes a way for the two boundary
+  // implementations to disagree. The invariant it leans on lives in another
+  // module and is not part of any contract this one can see.
+  let generation = 0;
+  const dispose = effect(() => {
+    const current = state();
+
+    if (claimedFromServer) {
+      claimedFromServer = false;
+      // The region already holds the arm this run would build: either the
+      // children the server rendered and the walk claimed (the normal case), or
+      // the fallback claimed in place by claimServerArm. The markup already
+      // there IS the answer, so leave it alone.
+      if (regionHoldsArm && current === armAfterWalk) return;
+    }
+
+    const host = startComment.parentNode;
+    if (!host) return; // region detached before this run; nothing to update
+
+    const gen = ++generation;
+
+    // Same teardown as the client boundaries: everything between the markers
+    // goes, disposed first so nested effects and component contexts die with
+    // the nodes rather than outliving them.
+    while (startComment.nextSibling && startComment.nextSibling !== endComment) {
+      const old = startComment.nextSibling;
+      disposeTree(old);
+      host.removeChild(old);
+    }
+
+    // Re-push the boundary for the rebuild. This effect re-runs long after the
+    // hydration walk has unwound the stack, and anything built with an empty
+    // stack gets `parentCtx = null`: a fallback that itself contains a
+    // component would sit outside every context it was written inside.
+    stack.push(boundaryCtx);
+    try {
+      const content = contentFor(current);
+      const vnodes = Array.isArray(content) ? content : [content];
+      for (const v of vnodes) {
+        const node = createDOM(v, host);
+        if (gen !== generation) {
+          // A newer run already rebuilt the region. Whatever this node is, it
+          // belongs to a superseded arm: dispose it rather than insert it
+          // alongside the arm that won.
+          if (node) disposeTree(node);
+          break;
+        }
+        // endComment can be gone if that newer run tore the region down.
+        if (!node) continue;
+        if (endComment.parentNode) endComment.parentNode.insertBefore(node, endComment);
+        else disposeTree(node);
+      }
+    } finally {
+      stack.pop();
+    }
+  });
+
+  // Put the cursor back where the END MARKER actually ended up.
+  //
+  // The effect above runs SYNCHRONOUSLY, and when the state was already truthy
+  // it has just removed R nodes from the region and inserted I of its own. The
+  // cursor was fixed at endComment+1 a few lines earlier and knows nothing
+  // about that, so it is off by (R - I) and the rest of the walk pays:
+  //
+  //   - drifting forward SKIPS the boundary's next server sibling, which then
+  //     warns "got nothing" and is rendered a SECOND time. A page with a
+  //     boundary above the footer got two footers.
+  //   - drifting backward makes that sibling claim a node it must not, which
+  //     before the marker skip list above meant claiming the boundary's own
+  //     end marker and replaceChild()ing it away.
+  //
+  // Re-reading the marker's real index is the same re-sync the _mapArray branch
+  // does, and for the same reason: once something has moved nodes behind the
+  // walk's back, the only trustworthy answer to "where is the cursor now" is
+  // where the marker physically is.
+  if (cursorInParent && _hydrationCursor && _hydrationCursor.parent === parent) {
+    const endIndex = Array.prototype.indexOf.call(parent.childNodes, endComment);
+    if (endIndex >= 0) _hydrationCursor.index = endIndex + 1;
+  }
+
+  boundaryCtx.effects.push(dispose);
+  // The client registers a boundary context in dom.js's comment->ctx WeakMap;
+  // the hydration disposer registry is the same idea reached from out here, and
+  // disposeTree walks both. Registered on BOTH markers, matching the
+  // reactive-region branch: whichever one a teardown happens to walk, the
+  // boundary dies. disposeComponent latches on ctx.disposed, so being reached
+  // twice is harmless.
+  addHydratedComponent(startComment, boundaryCtx);
+  addHydratedComponent(endComment, boundaryCtx);
+
+  // The START MARKER is the boundary's node, not its current contents.
+  //
+  // This matches the client exactly: createErrorBoundary returns a fragment
+  // whose first node is that same start comment. It also matters for whoever
+  // hydrated us. A component anchors its context to the first node its output
+  // produced, and the contents of a boundary are the one thing that is
+  // guaranteed to be replaced later, so returning them handed the enclosing
+  // component a self-destructing anchor: the boundary catching an error
+  // disposed the very component that wrapped the boundary. The markers outlive
+  // every value the region holds, which is what an anchor has to do.
+  return startComment;
 }
 
 /**