fix: preserve metadata ownership when hydrating element roots

.changeset/element-root-metadata.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/redact': patch
+---
+
+Adopt server-hoisted title and metadata from the owning document when hydrating an Element root, preserving nested Suspense content and its interactivity. Release claims after abandoned root hydration, and restrict inline metadata searches to the active Suspense range.

packages/redact/src/dom/document-metadata.ts

@@ -12,16 +12,19 @@ export function clearAttributes(node: Element): void {
 // React's document server renderer hoists metadata even when a component
 // returns it inside a body wrapper or a Suspense boundary.
 export function documentMetadataParent(fiber: Fiber): HTMLHeadElement | null {
-    if (fiber.r?.c.nodeType !== 9 || fiber.v?.itemProp != null ||
-        !['title', 'meta', 'base', 'link'].includes(fiber.type))
+    const container = fiber.r?.c;
+    const doc = container?.nodeType === 9 ? container as unknown as Document : container?.ownerDocument;
+    if (!doc?.head || fiber.v?.itemProp != null ||
+        !['title', 'meta', 'base', 'link'].includes(fiber.type) ||
+        fiber.type === 'link' && fiber.v?.rel === 'stylesheet')
         return null;
     for (let parent = fiber.p; parent; parent = parent.p) {
         if (parent.t === FiberTag.Portal || parent.type === 'svg')
             return null;
         if (parent.type === 'foreignObject')
             break;
     }
-    return (fiber.r.c as unknown as Document).head;
+    return doc.head;
 }
 export function clearHostContainer(container: Node): void {
     if (container.nodeType !== 9 && !DOCUMENT_SHELL_TAGS.test((container as Element).localName)) {

packages/redact/src/dom/features/hydration/full.ts

@@ -10,7 +10,7 @@ import { componentStack } from '../../error-info';
 export { reactId, forkId, assignReactIds } from '../../react-ids';
 import { FiberTag, type Fiber, type FiberRoot, type ReactNode, } from '../../../core';
 import { hydratedFormStates } from '../../../react/form-state';
-import { queueBeforeMutation, queueMutation, queueProp, queueText, onCommitRollback } from '../../commit';
+import { queueBeforeMutation, queueMutation, queueProp, queueText, onCommitRollback, onCommitFailure } from '../../commit';
 import { syncTextareaValue } from '../../form-controls';
 // Re-export from event-replay so all hydration concerns live behind one
 // feature boundary — the plugin's stub swap strips drainReplayQueue too.
@@ -76,11 +76,13 @@ export class HydrationCursor {
  * name/property for meta, src for script). Non-matching nodes stay in
  * place so the SSR'd stylesheet/script order is preserved.
  */
-function findMetadata(parent: Node | undefined, tag: string, props: Record<string, any>, fallback?: Node): ChildNode | null {
+function findMetadata(parent: Node | undefined, tag: string, props: Record<string, any>, fallback?: HydrationCursor): ChildNode | null {
     const keys = HEAD_KEY_ATTRS[tag] ?? [];
     for (const location of [parent, fallback]) {
         if (!location) continue;
-        scan: for (const el of (location as Element).children) {
+        const cursor = location instanceof HydrationCursor ? location : null;
+        scan: for (let node = cursor ? cursor.n : (location as Node).firstChild; node && node !== cursor?.e; node = node.nextSibling) {
+            const el = node as Element;
             if (el.localName !== tag || CLAIMED.has(el))
                 continue;
             for (const key of keys) {
@@ -137,7 +139,9 @@ const HEAD_KEY_ATTRS: Record<string, ReadonlyArray<string>> = {
 const CLAIMED = new WeakSet<Node>();
 function claimHydrationNode(node: Node): void {
     CLAIMED.add(node);
-    onCommitRollback(() => CLAIMED.delete(node));
+    const release = () => { CLAIMED.delete(node); };
+    onCommitRollback(release);
+    onCommitFailure(release);
 }
 const hydrationAttribute = (el: Element, name: string): string | null => (name === 'nonce' && 'nonce' in el && el.hasAttribute(name)
     ? (el as HTMLElement).nonce ?? ''
@@ -262,7 +266,7 @@ export function adoptHostDom(fiber: Fiber, parent: Fiber): boolean {
     const metadataParent = documentHeadParent || (isHeadish ? cursor.p
         : cursor.p.nodeType === 9 && tag !== 'html' ? (cursor.p as Document).body : null);
     // Prefer hoisted metadata, then claim its original host position.
-    const candidate = metadataParent ? findMetadata(metadataParent, tag, props, documentHeadParent ? cursor.p : undefined) : cursor.take();
+    const candidate = metadataParent ? findMetadata(metadataParent, tag, props, documentHeadParent ? cursor : undefined) : cursor.take();
     if (!candidate) {
         // Client expected a host here but the cursor is exhausted — server gave
         // fewer children than the client tree. Report the structural gap (React

scripts/size-check.mjs

@@ -63,11 +63,17 @@ const STORE_HYDRATION_SIZE_ALLOWANCE = {
   'redact/dom-client (hydration=stub)': [3, 0],
 }
 
+// Measured Element-root metadata correctness cost, [source, built] gzip bytes.
+// Only the hydration-disabled build exceeds its existing cap.
+const ELEMENT_METADATA_SIZE_ALLOWANCE = {
+  'redact/dom-client (hydration=stub)': [28, 28],
+}
+
 let failed = false
 for (const tree of ['src', 'dist']) {
   for (const row of await measureSizes(tree)) {
     const baseBudget = BUDGETS[row.name]
-    const budget = baseBudget === undefined ? undefined : baseBudget + (STORE_HYDRATION_SIZE_ALLOWANCE[row.name]?.[tree === 'src' ? 0 : 1] ?? 0) + (ROOT_TRANSITION_SIZE_ALLOWANCE[row.name]?.[tree === 'src' ? 0 : 1] ?? 0) + (QUEUE_SIZE_ALLOWANCE[row.name]?.[tree === 'src' ? 0 : 1] ?? 0)
+    const budget = baseBudget === undefined ? undefined : baseBudget + (ELEMENT_METADATA_SIZE_ALLOWANCE[row.name]?.[tree === 'src' ? 0 : 1] ?? 0) + (STORE_HYDRATION_SIZE_ALLOWANCE[row.name]?.[tree === 'src' ? 0 : 1] ?? 0) + (ROOT_TRANSITION_SIZE_ALLOWANCE[row.name]?.[tree === 'src' ? 0 : 1] ?? 0) + (QUEUE_SIZE_ALLOWANCE[row.name]?.[tree === 'src' ? 0 : 1] ?? 0)
     const ok = budget !== undefined && row.gz <= budget
     failed ||= !ok
     console.log(`${ok ? 'PASS' : 'FAIL'} ${tree} ${row.name}: ${row.gz} B gzip, budget ${budget ?? 'missing'}`)

tests/element-root-metadata.test.tsx

@@ -0,0 +1,48 @@
+import { afterEach, expect, it, vi } from 'vitest'
+import { Suspense, lazy, useEffect, useState } from 'react'
+import { hydrateRoot } from 'react-dom/client'
+import { flushSync } from 'react-dom'
+
+const cleanups: Array<() => void> = []
+afterEach(() => { for (const cleanup of cleanups.splice(0)) cleanup() })
+
+it.each([false, true])('adopts hoisted metadata with an Element root and lazy=%s', async pending => {
+  const doc = new DOMParser().parseFromString('<!doctype html><html><head><title>Page</title><meta name="description" content="Page"></head><body><main><!--$--><section><h1>Page</h1><!--$--><aside><button>0</button></aside><!--/$--></section><!--/$--></main></body></html>', 'text/html')
+  const container = doc.querySelector('main')!
+  const section = doc.querySelector('section'), aside = doc.querySelector('aside')
+  const title = doc.querySelector('title'), meta = doc.querySelector('meta')
+  const error = vi.fn(), mounted = vi.fn()
+  function Counter() {
+    useEffect(mounted, [])
+    const [count, setCount] = useState(0)
+    return <aside><button onClick={() => setCount(value => value + 1)}>{count}</button></aside>
+  }
+  let resolve!: (value: { default: typeof Counter }) => void
+  const load = vi.fn(() => new Promise<{ default: typeof Counter }>(yes => { resolve = yes }))
+  const Lazy = lazy(load)
+  function Page({ updated = false }: { updated?: boolean }) {
+    return <Suspense fallback={null}><section><title>{updated ? 'Updated' : 'Page'}</title><meta name="description" content={updated ? 'Updated' : 'Page'} /><h1>Page</h1><Suspense fallback={<i>Loading</i>}>{pending ? <Lazy /> : <Counter />}</Suspense></section></Suspense>
+  }
+  const root = hydrateRoot(container, <Page />, { onRecoverableError: error, onUncaughtError: error })
+  cleanups.push(() => root.unmount())
+  expect(doc.querySelector('section')).toBe(section)
+  expect(doc.querySelector('aside')).toBe(aside)
+  expect(doc.querySelector('title')).toBe(title)
+  expect(doc.querySelector('meta')).toBe(meta)
+  expect(container.querySelector('title,meta')).toBeNull()
+  expect(error).not.toHaveBeenCalled()
+  if (pending) {
+    expect(load).toHaveBeenCalledTimes(1)
+    resolve({ default: Counter })
+    await vi.waitFor(() => expect(mounted).toHaveBeenCalledTimes(1))
+  }
+  flushSync(() => doc.querySelector('button')!.click())
+  expect(doc.querySelector('button')?.textContent).toBe('1')
+  expect(doc.querySelector('aside')).toBe(aside)
+  flushSync(() => root.render(<Page updated />))
+  expect(doc.querySelector('title')).toBe(title)
+  expect(doc.querySelector('meta')).toBe(meta)
+  expect(title?.textContent).toBe('Updated')
+  expect(meta?.getAttribute('content')).toBe('Updated')
+  expect(error).not.toHaveBeenCalled()
+})

tests/hydration-attribute-probes.test.tsx

@@ -129,7 +129,9 @@ describe('hydration attribute comparison', () => {
     })
     const { original, errors, container } = hydrate()
     expect(errors).toEqual([])
-    expect(container.firstChild).toBe(original)
+    // Metadata follows React's head placement, preserving the existing node
+    // even when Redact's server renderer emitted it inline.
+    expect(tag === 'link' ? document.head.querySelector('link[href="/preload.gif"]') : container.firstChild).toBe(original)
     const matchingWrites = writes.filter(write => write.name === attr)
     expect(matchingWrites.filter(write => write.element.ownerDocument.defaultView !== null)).toEqual([])
     expect(matchingWrites).toEqual([])

tests/metadata-hydration-ownership.test.tsx

@@ -0,0 +1,61 @@
+import { afterEach, expect, it, vi } from 'vitest'
+import { Suspense, lazy, useEffect, useLayoutEffect } from 'react'
+import { hydrateRoot } from 'react-dom/client'
+import { flushSync } from 'react-dom'
+import { renderToString } from 'react-dom/server'
+
+const cleanup: Array<() => void> = []
+afterEach(() => { for (const dispose of cleanup.splice(0)) dispose() })
+
+it.each(['resolve', 'replace'])('releases head claims from abandoned root hydration before %s', async action => {
+  const doc = new DOMParser().parseFromString('<html><head><title>Page</title><meta name="description" content="Page"></head><body><main><button>ready</button></main></body></html>', 'text/html')
+  const container = doc.querySelector('main')!, title = doc.querySelector('title')!, meta = doc.querySelector('meta')!
+  let resolve!: (value: { default: typeof Child }) => void
+  const mounted = vi.fn(), errors = vi.fn()
+  function Child() { useEffect(mounted, []); return <button>ready</button> }
+  const Lazy = lazy(() => new Promise<{ default: typeof Child }>(yes => { resolve = yes }))
+  const tree = <><title>Page</title><meta name="description" content="Page" /><Lazy /></>
+  const root = hydrateRoot(container, tree, { onRecoverableError: errors })
+  cleanup.push(() => root.unmount())
+  expect(mounted).not.toHaveBeenCalled()
+  if (action === 'resolve') resolve({ default: Child })
+  else flushSync(() => root.render(<><title>Page</title><meta name="description" content="Page" /><Child /></>))
+  await vi.waitFor(() => expect(mounted).toHaveBeenCalledTimes(1))
+  expect(doc.querySelectorAll('title')).toHaveLength(1)
+  expect(doc.querySelectorAll('meta')).toHaveLength(1)
+  expect(doc.querySelector('title')).toBe(title)
+  expect(doc.querySelector('meta')).toBe(meta)
+  flushSync(() => root.render(<><title>Updated</title><meta name="description" content="Updated" /><Child /></>))
+  expect(doc.title).toBe('Updated')
+  expect(title.textContent).toBe('Updated')
+  expect(meta.getAttribute('content')).toBe('Updated')
+  expect(errors).not.toHaveBeenCalled()
+  if (action === 'replace') { resolve({ default: Child }); await Promise.resolve(); expect(doc.title).toBe('Updated') }
+})
+
+it('keeps inline metadata adoption inside the active Suspense cursor', async () => {
+  function First() { return <><title>first</title><meta name="description" content="first" /><button>first</button></> }
+  function Second() { return <><title>second</title><meta name="description" content="second" /><button>second</button></> }
+  const tree = <main><Suspense fallback={null}><First /></Suspense><Suspense fallback={null}><Second /></Suspense></main>
+  const doc = new DOMParser().parseFromString('<html><head></head><body><div></div></body></html>', 'text/html')
+  const container = doc.querySelector('div')!
+  container.innerHTML = renderToString(tree)
+  const titles = Array.from(container.querySelectorAll('title')), metas = Array.from(container.querySelectorAll('meta')), buttons = Array.from(container.querySelectorAll('button'))
+  let resolve!: (value: { default: typeof First }) => void
+  const Lazy = lazy(() => new Promise<{ default: typeof First }>(yes => { resolve = yes }))
+  const errors = vi.fn(), mounted = vi.fn()
+  function ReadySecond() { useLayoutEffect(mounted, []); return <Second /> }
+  const root = hydrateRoot(container, <main><Suspense fallback={null}><Lazy /></Suspense><Suspense fallback={null}><ReadySecond /></Suspense></main>, { onRecoverableError: errors })
+  cleanup.push(() => root.unmount())
+  expect(mounted).toHaveBeenCalledTimes(1)
+  expect(doc.head.querySelector('title')).toBe(titles[1])
+  expect(container.querySelector('title')).toBe(titles[0])
+  expect(doc.head.querySelector('meta')).toBe(metas[1])
+  expect(errors).not.toHaveBeenCalled()
+  resolve({ default: First })
+  await vi.waitFor(() => expect(doc.head.querySelectorAll('title')).toHaveLength(2))
+  for (const title of titles) expect(title.parentNode).toBe(doc.head)
+  for (const meta of metas) expect(meta.parentNode).toBe(doc.head)
+  Array.from(container.querySelectorAll('button')).forEach((button, index) => expect(button).toBe(buttons[index]))
+  expect(errors).not.toHaveBeenCalled()
+})