@tanstack/redact 0.0.10 → 0.0.12

package/src/dom/features/suspense/full.ts

@@ -1,4 +1,4 @@
-import { FiberTag, type Fiber } from '../../../core'
+import { FiberTag, createFiber, type Fiber } from '../../../core'
 import { REACT_SUSPENSE_TYPE } from '../../../react'
 import {
   registerRenderer,
@@ -6,8 +6,10 @@ import {
   installCapability,
   reconcileChildren,
   childrenToArray,
+  renderFiber,
   scheduleUpdate,
   unmountAllChildren,
+  unmountFiber,
   findRoot,
   runEffects,
   getCurrentRoot,
@@ -36,9 +38,40 @@ function realHandleSuspended(fiber: Fiber, thenable: Promise<any>): void {
   )
 }
 
+// React's Suspense semantics: when a re-render of an already-committed
+// boundary suspends, the previously-committed children are kept in the DOM
+// (hidden) so their scroll position, focus, selection, native form state,
+// and component state survive across the suspension. The fallback is mounted
+// alongside the hidden primary until the pending promise resolves.
+//
+// We track the hidden subtree DOM in `state.hiddenDoms` (root host nodes +
+// their original `display` so we can restore it) and the fallback as a
+// detached Fragment fiber in `state.fallbackFiber` (deliberately kept OUT of
+// `fiber.child` so reconciles against `props.children` don't trip on it).
+// First-mount suspensions have no committed DOM worth preserving, so they
+// keep the original unmount-and-render-fallback behavior.
+interface SuspenseState {
+  suspended: boolean
+  pending: Promise<any> | null
+  hydrated?: boolean
+  boundaryId?: number
+  startMark?: Comment
+  endMark?: Comment
+  realChildren?: any
+  _awaitingLazyHydration?: boolean
+  // Re-suspend preservation:
+  hiddenDoms: Array<[HTMLElement, string]> | null
+  fallbackFiber: Fiber | null
+}
+
 function renderSuspense(fiber: Fiber, domParent: Node, anchor: Node | null): void {
   const props = fiber.pendingProps ?? {}
-  const state = (fiber.memoizedState ??= { suspended: false, pending: null as Promise<any> | null })
+  const state = (fiber.memoizedState ??= {
+    suspended: false,
+    pending: null as Promise<any> | null,
+    hiddenDoms: null,
+    fallbackFiber: null,
+  }) as SuspenseState
 
   // Streaming hydration: if the next DOM node is a server-emitted boundary
   // marker, route through the boundary-aware hydration path.
@@ -58,55 +91,125 @@ function renderSuspense(fiber: Fiber, domParent: Node, anchor: Node | null): voi
   // yet. Until the Lazy's resume fires, skip our own tryChildren pass so
   // an unrelated re-render can't accidentally flip us into the suspended
   // path and mount a duplicate fallback on top of the SSR content.
-  if ((state as any)._awaitingLazyHydration) {
+  if (state._awaitingLazyHydration) {
     fiber.memoizedProps = props
     return
   }
 
-  const tryChildren = () => {
-    reconcileChildren(fiber, childrenToArray(props.children), domParent, anchor)
+  // We were already in the suspended-with-preserved-primary state. Don't
+  // re-attempt primary children (would re-throw and churn the tree). Just
+  // refresh the fallback in case its JSX changed, and wait for the pending
+  // promise to fire scheduleUpdate.
+  if (state.suspended && state.pending && state.fallbackFiber) {
+    state.fallbackFiber.pendingProps = { children: props.fallback }
+    renderFiber(state.fallbackFiber, domParent, anchor)
+    fiber.memoizedProps = props
+    return
   }
 
-  if (state.suspended && state.pending) {
-    // Render fallback while waiting; pending promise will reschedule
+  // Initial-mount suspended path: no committed primary to preserve. Old
+  // behavior — render fallback into fiber.child directly.
+  if (state.suspended && state.pending && !state.fallbackFiber) {
     reconcileChildren(fiber, childrenToArray(props.fallback), domParent, anchor)
     fiber.memoizedProps = props
     return
   }
 
-  // Attempt children — suspension is handled by the pushed handler below
+  // Snapshot whether we have an existing committed primary tree before
+  // attempting the new render. If the new attempt suspends and we did have a
+  // committed primary, we keep it (hidden) rather than destroying it.
+  const hadCommittedPrimary = fiber.memoizedProps !== undefined && fiber.child !== null
+
   const savedHandler = suspendHandlerStack[suspendHandlerStack.length - 1]
+  let suspendedThisRender = false
+  let suspendedThenable: Promise<any> | null = null
   suspendHandlerStack.push((thenable) => {
-    state.suspended = true
-    state.pending = thenable
-    thenable.then(
-      () => {
-        state.suspended = false
-        state.pending = null
-        scheduleUpdate(fiber)
-      },
-      () => {
-        state.suspended = false
-        state.pending = null
-        scheduleUpdate(fiber)
-      },
-    )
+    suspendedThisRender = true
+    suspendedThenable = thenable
   })
   try {
-    tryChildren()
+    reconcileChildren(fiber, childrenToArray(props.children), domParent, anchor)
   } finally {
     suspendHandlerStack.pop()
     void savedHandler
   }
 
-  if (state.suspended) {
-    // Replace children with fallback
-    unmountAllChildren(fiber, domParent)
-    reconcileChildren(fiber, childrenToArray(props.fallback), domParent, anchor)
+  if (suspendedThisRender && suspendedThenable) {
+    state.suspended = true
+    state.pending = suspendedThenable
+    const onSettle = () => {
+      state.suspended = false
+      state.pending = null
+      scheduleUpdate(fiber)
+    }
+    suspendedThenable.then(onSettle, onSettle)
+
+    if (hadCommittedPrimary && fiber.child) {
+      // Hide the primary subtree's root host doms so the fallback is the only
+      // thing visible, but the underlying nodes (and their scroll/state/focus)
+      // survive. Save original `display` for the resume path.
+      const hostDoms: Node[] = []
+      let c: Fiber | null = fiber.child
+      while (c) {
+        collectRootHostDoms(c, hostDoms)
+        c = c.sibling
+      }
+      const hidden: Array<[HTMLElement, string]> = []
+      for (const d of hostDoms) {
+        if (d.nodeType === 1) {
+          const el = d as HTMLElement
+          hidden.push([el, el.style.display])
+          el.style.display = 'none'
+        }
+      }
+      state.hiddenDoms = hidden
+
+      // Mount fallback in a detached Fragment fiber. Kept off `fiber.child`
+      // so reconciles of primary don't see it as a stale match candidate.
+      if (!state.fallbackFiber) {
+        state.fallbackFiber = createFiber(FiberTag.Fragment, null, null)
+        state.fallbackFiber.parent = fiber
+      }
+      state.fallbackFiber.pendingProps = { children: props.fallback }
+      renderFiber(state.fallbackFiber, domParent, anchor)
+    } else {
+      // First-mount suspension — nothing to preserve.
+      unmountAllChildren(fiber, domParent)
+      reconcileChildren(fiber, childrenToArray(props.fallback), domParent, anchor)
+    }
+  } else {
+    // Render succeeded. Clean up any preserved-suspend state from a prior
+    // suspension cycle: unhide primary, unmount the orphan fallback fiber.
+    if (state.hiddenDoms) {
+      for (const [el, origDisplay] of state.hiddenDoms) {
+        el.style.display = origDisplay
+      }
+      state.hiddenDoms = null
+    }
+    if (state.fallbackFiber) {
+      unmountFiber(state.fallbackFiber, domParent)
+      state.fallbackFiber = null
+    }
   }
   fiber.memoizedProps = props
 }
 
+// Walk a fiber subtree collecting host/text DOM nodes that sit at the root
+// of the subtree (do not descend through their children — display:none on
+// the root hides the whole element). Used by the hide-on-suspend path.
+function collectRootHostDoms(fiber: Fiber, out: Node[]): void {
+  if (fiber.tag === FiberTag.Host || fiber.tag === FiberTag.Text) {
+    if (fiber.dom) out.push(fiber.dom)
+    return
+  }
+  if (fiber.tag === FiberTag.Portal) return
+  let c = fiber.child
+  while (c) {
+    collectRootHostDoms(c, out)
+    c = c.sibling
+  }
+}
+
 function hydrateSuspenseBoundary(
   fiber: Fiber,
   props: any,

package/src/dom/index.ts

@@ -14,6 +14,22 @@ export function preinit(_href: string, _opts?: any): void {}
 export function preloadModule(_href: string, _opts?: any): void {}
 export function preinitModule(_href: string, _opts?: any): void {}
 
+export const __DOM_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE = {
+  d: {
+    f() {},
+    r() {},
+    D() {},
+    C() {},
+    L() {},
+    m() {},
+    X() {},
+    S() {},
+    M() {},
+  },
+  p: 0,
+  findDOMNode: null,
+}
+
 export const version = '19.2.3'
 
 // Required by React's default export consumers
@@ -29,5 +45,6 @@ export default {
   preinit,
   preloadModule,
   preinitModule,
+  __DOM_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE,
   version: '19.2.3',
 }

package/src/dom/reconcile.ts

@@ -1014,7 +1014,7 @@ export function isThenable(x: any): x is Promise<any> {
 // Unmount
 // ---------------------------------------------------------------------------
 
-function unmountFiber(fiber: Fiber, domParent: Node): void {
+export function unmountFiber(fiber: Fiber, domParent: Node): void {
   fiber.unmounted = true
   // Recurse first
   let c = fiber.child
@@ -1074,6 +1074,12 @@ export function unmountAllChildren(parent: Fiber, domParent: Node): void {
 // ---------------------------------------------------------------------------
 
 function insertInto(parent: Node, node: Node, anchor: Node | null): void {
+  const projectedHeadParent = getDocumentHeadInsertionParent(parent, node)
+  if (projectedHeadParent) {
+    projectedHeadParent.appendChild(node)
+    return
+  }
+
   // Anchor may have been removed or moved since it was computed (mutations
   // from unmount, boundary reveal, user code, HMR). If it's no longer a child
   // of `parent`, fall back to append — trying to insertBefore a non-child
@@ -1085,6 +1091,15 @@ function insertInto(parent: Node, node: Node, anchor: Node | null): void {
   }
 }
 
+const DOCUMENT_HEAD_TAGS = new Set(['base', 'link', 'meta', 'script', 'style', 'title'])
+
+function getDocumentHeadInsertionParent(parent: Node, node: Node): HTMLHeadElement | null {
+  if (parent.nodeType !== 9 || node.nodeType !== 1) return null
+  const tag = (node as Element).tagName.toLowerCase()
+  if (!DOCUMENT_HEAD_TAGS.has(tag)) return null
+  return (parent as Document).head
+}
+
 function getHostParent(fiber: Fiber): Node {
   let p = fiber.parent
   while (p) {
@@ -1260,4 +1275,3 @@ function isEventProp(name: string): boolean {
     name.charCodeAt(2) >= 65 /* 'A'-ish: any uppercase start (onClick, onChange, …) */
   )
 }
-

package/src/dom/root.ts

@@ -1,4 +1,11 @@
-import { FiberTag, createFiber, type FiberRoot, type ReactNode } from '../core'
+import {
+  FiberTag,
+  REACT_ELEMENT_TYPE,
+  createFiber,
+  type FiberRoot,
+  type ReactElement,
+  type ReactNode,
+} from '../core'
 import { renderRoot, flushSyncWork, batchedUpdates } from './reconcile'
 import {
   beginHydration,
@@ -92,8 +99,10 @@ export function hydrateRoot(
 
   beginHydration(root)
   try {
+    const normalizedInitialChildren =
+      isDocumentContainer(container) ? normalizeDocumentChildren(initialChildren) : initialChildren
     flushSyncWork(() => {
-      renderRoot(root, initialChildren)
+      renderRoot(root, normalizedInitialChildren)
     })
   } finally {
     endHydration(root)
@@ -103,7 +112,7 @@ export function hydrateRoot(
   return {
     render(children) {
       flushSyncWork(() => {
-        renderRoot(root, children)
+        renderRoot(root, isDocumentContainer(container) ? normalizeDocumentChildren(children) : children)
       })
     },
     unmount() {
@@ -114,4 +123,91 @@ export function hydrateRoot(
   }
 }
 
+const HEAD_TAGS = new Set(['base', 'link', 'meta', 'script', 'style', 'title'])
+
+function isDocumentContainer(container: unknown): container is Document {
+  return !!container && (container as Node).nodeType === 9
+}
+
+function normalizeDocumentChildren(children: ReactNode): ReactNode {
+  const list = toChildArray(children)
+  const htmlIndex = list.findIndex((child) => isHostElement(child, 'html'))
+  if (htmlIndex === -1) return children
+
+  const headNodes = list.filter(isHeadElement)
+  if (headNodes.length === 0) return children
+
+  const htmlElement = list[htmlIndex] as ReactElement
+  const normalizedHtml = hoistIntoHtmlHead(htmlElement, headNodes)
+  return list
+    .filter((child, index) => index === htmlIndex || !isHeadElement(child))
+    .map((child) => (child === htmlElement ? normalizedHtml : child))
+}
+
+function hoistIntoHtmlHead(htmlElement: ReactElement, headNodes: ReactNode[]): ReactElement {
+  const htmlChildren = toChildArray(htmlElement.props?.children)
+  const headIndex = htmlChildren.findIndex((child) => isHostElement(child, 'head'))
+  let nextChildren: ReactNode[]
+
+  if (headIndex === -1) {
+    nextChildren = [
+      createHostElement('head', { children: headNodes }),
+      ...htmlChildren,
+    ]
+  } else {
+    const headElement = htmlChildren[headIndex] as ReactElement
+    const existingHeadChildren = toChildArray(headElement.props?.children)
+    const nextHead = {
+      ...headElement,
+      props: {
+        ...headElement.props,
+        children: [...headNodes, ...existingHeadChildren],
+      },
+    }
+    nextChildren = htmlChildren.map((child, index) => (index === headIndex ? nextHead : child))
+  }
+
+  return {
+    ...htmlElement,
+    props: {
+      ...htmlElement.props,
+      children: nextChildren,
+    },
+  }
+}
+
+function toChildArray(children: unknown): ReactNode[] {
+  if (children == null || typeof children === 'boolean') return []
+  if (Array.isArray(children)) return children as ReactNode[]
+  if (isReactElement(children)) return [children]
+  if (typeof children !== 'string' && isIterable(children)) return Array.from(children) as ReactNode[]
+  return [children as ReactNode]
+}
+
+function isHeadElement(value: ReactNode): boolean {
+  return isReactElement(value) && typeof value.type === 'string' && HEAD_TAGS.has(value.type)
+}
+
+function isHostElement(value: ReactNode, tag: string): boolean {
+  return isReactElement(value) && value.type === tag
+}
+
+function isReactElement(value: unknown): value is ReactElement {
+  return !!value && typeof value === 'object' && (value as ReactElement).$$typeof === REACT_ELEMENT_TYPE
+}
+
+function isIterable(value: unknown): value is Iterable<ReactNode> {
+  return !!value && typeof (value as { [Symbol.iterator]?: unknown })[Symbol.iterator] === 'function'
+}
+
+function createHostElement(type: string, props: Record<string, unknown>): ReactElement {
+  return {
+    $$typeof: REACT_ELEMENT_TYPE,
+    type,
+    key: null,
+    ref: null,
+    props,
+  }
+}
+
 export { flushSyncWork as flushSync, batchedUpdates }

package/src/server/bootstrap-script.ts

@@ -6,9 +6,12 @@
  *     main bundle can replay them against un-hydrated subtrees ($RE_q buffer).
  *
  * Wire format:
- *   Fallback:  <!--$?ID--><div hidden id="B:ID">fallback</div><!--/$-->
+ *   Fallback:  <!--$?ID--><div id="B:ID">fallback</div><!--/$-->
  *   Resolved:  emits <div hidden id="S:ID">real</div><script>$RC(ID)</script>
  *              which splices real into place and rewrites the comment to <!--$ID-->.
+ *              The fallback div is visible (it's the user-visible loading
+ *              state); only the resolved-content staging div is `hidden`
+ *              before $RC moves its children inline.
  *
  * Client hydration calls $RH(ID, cb) to register a callback invoked once the
  * boundary has been revealed (or immediately, if it was already revealed).

package/src/server/stream.ts

@@ -8,10 +8,12 @@ import {
 } from './dispatcher'
 import { walk, type SuspendedBoundary } from './walk'
 import { BOUNDARY_REVEAL_RUNTIME, revealScript } from './bootstrap-script'
+import { escapeScript } from './escape'
 
 export interface StreamOptions {
   identifierPrefix?: string
   nonce?: string
+  bootstrapScriptContent?: string | ReadonlyArray<string>
   bootstrapScripts?: ReadonlyArray<string | { src: string; async?: boolean; nonce?: string }>
   bootstrapModules?: ReadonlyArray<string | { src: string; nonce?: string }>
   onError?: (error: unknown) => string | void
@@ -57,12 +59,34 @@ export async function streamHtml(
       shellChunks.push(chunk)
     }
 
-    // 1. Render the shell
-    walk(children, {
-      emit: bufferedEmit,
-      onSuspend: (b) => boundaries.push(b),
-      nextBoundaryId: () => state.nextId++,
-    })
+    // 1. Render the shell. A root-level `use(promise)` has no Suspense
+    // boundary to capture it, but App Router SSR commonly suspends at this
+    // level while resolving the RSC stream. Wait and retry without leaking
+    // partial shell chunks or boundary ids from the aborted attempt.
+    let shellRendered = false
+    let rootRetries = 0
+    while (!shellRendered) {
+      const chunkCount = shellChunks.length
+      const boundaryCount = boundaries.length
+      const nextId = state.nextId
+      try {
+        walk(children, {
+          emit: bufferedEmit,
+          onSuspend: (b) => boundaries.push(b),
+          nextBoundaryId: () => state.nextId++,
+        })
+        shellRendered = true
+      } catch (err) {
+        shellChunks.length = chunkCount
+        boundaries.length = boundaryCount
+        state.nextId = nextId
+        if (!isThenable(err)) throw err
+        if (++rootRetries > 50) {
+          throw new Error('renderToReadableStream exceeded 50 root suspension retries.')
+        }
+        await err
+      }
+    }
 
     // 2. Inject runtime + bootstrap scripts (once, after shell). Skip the
     // reveal/event-replay runtime when nothing needs it — no suspensions to
@@ -71,10 +95,14 @@ export async function streamHtml(
     // matches React's behavior where `renderToReadableStream` of a static
     // tree emits only the markup.
     const hasBootstrap =
+      bootstrapScriptContentToArray(options.bootstrapScriptContent).length > 0 ||
       (options.bootstrapScripts?.length ?? 0) > 0 ||
       (options.bootstrapModules?.length ?? 0) > 0
     if (boundaries.length > 0 || hasBootstrap) {
       shellChunks.push(`<script${nonce ? ` nonce="${nonce}"` : ''}>${BOUNDARY_REVEAL_RUNTIME}</script>`)
+      for (const content of bootstrapScriptContentToArray(options.bootstrapScriptContent)) {
+        shellChunks.push(inlineBootstrapTag(content, nonce))
+      }
       for (const s of options.bootstrapScripts ?? []) {
         shellChunks.push(bootstrapTag(s, 'script', nonce))
       }
@@ -83,7 +111,7 @@ export async function streamHtml(
       }
     }
 
-    if (shellChunks.length) emit(shellChunks.join(''))
+    if (shellChunks.length) emit(normalizeDocumentShell(shellChunks.join('')))
 
     // 3. Stream suspended boundaries as they resolve
     for (const b of boundaries) streamBoundary(b, emit, options, state)
@@ -146,6 +174,59 @@ async function drain(state: OrchestratorState): Promise<void> {
   }
 }
 
+function isThenable(value: unknown): value is Promise<unknown> {
+  return !!value && typeof (value as { then?: unknown }).then === 'function'
+}
+
+function bootstrapScriptContentToArray(
+  content: StreamOptions['bootstrapScriptContent'],
+): string[] {
+  if (content === undefined) return []
+  return typeof content === 'string' ? [content] : [...content]
+}
+
+function inlineBootstrapTag(content: string, defaultNonce: string | undefined): string {
+  const nAttr = defaultNonce ? ` nonce="${defaultNonce}"` : ''
+  return `<script${nAttr}>${escapeScript(content)}</script>`
+}
+
+function normalizeDocumentShell(html: string): string {
+  const doctypeIndex = html.indexOf('<!DOCTYPE html><html')
+  if (doctypeIndex <= 0) return html
+
+  const headPrefix = html.slice(0, doctypeIndex)
+  if (!isHeadPrefix(headPrefix)) return html
+
+  const documentHtml = html.slice(doctypeIndex)
+  const headOpen = documentHtml.match(/<head(?:\s[^>]*)?>/)
+  if (!headOpen || headOpen.index === undefined) return html
+
+  const insertAt = headOpen.index + headOpen[0].length
+  return documentHtml.slice(0, insertAt) + headPrefix + documentHtml.slice(insertAt)
+}
+
+function isHeadPrefix(value: string): boolean {
+  if (!value) return false
+  return stripLeadingHeadTags(value).trim() === ''
+}
+
+function stripLeadingHeadTags(value: string): string {
+  let rest = value
+  let changed = true
+  while (changed) {
+    changed = false
+    const next = rest.replace(
+      /^\s*(?:<meta\b[^>]*>|<link\b[^>]*>|<base\b[^>]*>|<title\b[^>]*>[\s\S]*?<\/title>|<style\b[^>]*>[\s\S]*?<\/style>|<script\b[^>]*>[\s\S]*?<\/script>)/i,
+      '',
+    )
+    if (next !== rest) {
+      rest = next
+      changed = true
+    }
+  }
+  return rest
+}
+
 function bootstrapTag(
   entry: string | { src: string; async?: boolean; nonce?: string },
   kind: 'script' | 'module',

package/src/server/walk.ts

@@ -315,6 +315,10 @@ function walkHost(
   const parentTextState = opts.textState
   const childOpts: WalkOptions = { ...opts, textState: { lastWasText: false } }
 
+  if (tag === 'html' && !hasHeadChild(props.children)) {
+    opts.emit('<head></head>')
+  }
+
   const dangerouslyHtml = props.dangerouslySetInnerHTML?.__html
 
   if (isTextarea && textareaValue != null) {
@@ -353,6 +357,32 @@ function walkHost(
   if (parentTextState) parentTextState.lastWasText = false
 }
 
+function hasHeadChild(children: unknown): boolean {
+  if (children == null || typeof children === 'boolean') return false
+  if (Array.isArray(children)) return children.some(hasHeadChild)
+  if (typeof children !== 'string' && isIterable(children)) {
+    for (const child of children as Iterable<unknown>) {
+      if (hasHeadChild(child)) return true
+    }
+    return false
+  }
+  return isElementOfType(children, 'head')
+}
+
+function isElementOfType(value: unknown, type: string): value is ReactElement {
+  const marker = (value as ReactElement | null)?.$$typeof as unknown
+  return (
+    !!value &&
+    typeof value === 'object' &&
+    (marker === REACT_ELEMENT_TYPE || marker === REACT_LEGACY_ELEMENT_TYPE) &&
+    (value as ReactElement).type === type
+  )
+}
+
+function isIterable(value: unknown): value is Iterable<unknown> {
+  return !!value && typeof (value as { [Symbol.iterator]?: unknown })[Symbol.iterator] === 'function'
+}
+
 function walkComponent(
   fn: Function,
   props: Record<string, any>,

package/src/vite/index.ts

@@ -166,6 +166,8 @@ const ALIASES: Record<string, string> = {
   'react/jsx-dev-runtime': '@tanstack/redact/jsx-dev-runtime',
   'react/compiler-runtime': '@tanstack/redact/compiler-runtime',
   'react-dom/client': '@tanstack/redact/dom-client',
+  'react-dom/server.edge': '@tanstack/redact/server',
+  'react-dom/static.edge': '@tanstack/redact/server',
   'react-dom/server': '@tanstack/redact/server',
   'react-dom/test-utils': '@tanstack/redact/dom-test-utils',
   'react-dom': '@tanstack/redact/dom',