feat(html): adoption-style hydration with mismatch reporting

hydrate(oldNode, newNode) normalizes the client tree to parser text-node granularity, walks both trees to report the first server/client markup disagreement (node, text, attribute, or child count, with a path), then morphs — matching nodes are adopted in place, the client render wins. choo.mount() now hydrates and console.warns on mismatch. Building this surfaced two real isomorphism divergences, both fixed: adjacent text nodes from template holes vs the parser's merged runs (folded via Node.normalize), and the server serializing onclick="" where the browser sets a property — event handlers now leave no trace in server markup at all. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014NgfSjHE11oFpoSnLVKLXd
2026-09-08 17:49:32 +02:00
parent 37bd8adf81
commit 13155a3469
7 changed files with 323 additions and 3 deletions
@@ -0,0 +1,119 @@
+// Hydration: adopt server-rendered DOM instead of replacing it.
+//
+// Because the server and browser renderers serialize identically, morphing
+// the first client render onto the server DOM leaves matching nodes
+// untouched — the server DOM is adopted in place (same element references,
+// form state preserved) and only real differences mutate. What hydrate
+// adds over a bare morph is detection: before morphing it walks both trees
+// and reports the first place server and client markup disagree, which is
+// exactly the class of bug (Date.now() in views, user-specific content,
+// stale caches) that otherwise surfaces as a silent flash of changed
+// content. The client render always wins.
+
+import morph from './morph.js'
+
+export default function hydrate (oldNode, newNode, opts) {
+  // The client tree can hold adjacent text nodes ("count is " + "0")
+  // where the parsed server HTML has one merged run ("count is 0") —
+  // identical serialization, different granularity. Fold the client tree
+  // to parser granularity so comparison and morph see matching shapes.
+  if (newNode.normalize) newNode.normalize()
+
+  const onMismatch = opts && opts.onMismatch
+  if (onMismatch) {
+    const diff = firstDifference(oldNode, newNode, [])
+    if (diff) onMismatch(diff)
+  }
+  return morph(oldNode, newNode)
+}
+
+export { hydrate }
+
+// Depth-first parallel walk; returns { path, reason, server, client } for
+// the first disagreement, or null when the trees agree.
+function firstDifference (a, b, path) {
+  if (a.nodeType !== b.nodeType || a.nodeName !== b.nodeName) {
+    return {
+      path: pathString(path),
+      reason: 'node',
+      server: describe(a),
+      client: describe(b)
+    }
+  }
+
+  if (a.nodeType === 3 || a.nodeType === 8) { // text, comment
+    if (a.nodeValue !== b.nodeValue) {
+      return {
+        path: pathString(path),
+        reason: 'text',
+        server: a.nodeValue,
+        client: b.nodeValue
+      }
+    }
+    return null
+  }
+
+  if (a.nodeType === 1) {
+    const attrDiff = attrDifference(a, b)
+    if (attrDiff) {
+      return {
+        path: pathString(path.concat(a.nodeName.toLowerCase())),
+        reason: 'attribute',
+        server: attrDiff.server,
+        client: attrDiff.client
+      }
+    }
+
+    const aKids = a.childNodes
+    const bKids = b.childNodes
+    if (aKids.length !== bKids.length) {
+      return {
+        path: pathString(path.concat(a.nodeName.toLowerCase())),
+        reason: 'children',
+        server: aKids.length + ' child node(s)',
+        client: bKids.length + ' child node(s)'
+      }
+    }
+    for (let i = 0; i < aKids.length; i++) {
+      const diff = firstDifference(aKids[i], bKids[i], path.concat(a.nodeName.toLowerCase()))
+      if (diff) return diff
+    }
+  }
+
+  return null
+}
+
+function attrDifference (a, b) {
+  const aAttrs = a.attributes
+  const bAttrs = b.attributes
+  for (let i = 0; i < bAttrs.length; i++) {
+    const name = bAttrs[i].name
+    if (a.getAttribute(name) !== bAttrs[i].value) {
+      return {
+        server: name + '=' + JSON.stringify(a.getAttribute(name)),
+        client: name + '=' + JSON.stringify(bAttrs[i].value)
+      }
+    }
+  }
+  for (let i = 0; i < aAttrs.length; i++) {
+    const name = aAttrs[i].name
+    if (!b.hasAttribute(name)) {
+      return {
+        server: name + '=' + JSON.stringify(aAttrs[i].value),
+        client: name + ' (absent)'
+      }
+    }
+  }
+  return null
+}
+
+function describe (node) {
+  if (!node) return '(missing)'
+  if (node.nodeType === 3) return 'text ' + JSON.stringify(node.nodeValue)
+  if (node.nodeType === 8) return 'comment'
+  return '<' + node.nodeName.toLowerCase() + '>'
+}
+
+function pathString (path) {
+  return path.length ? path.join(' > ') : '(root)'
+}