@tanstack/react-start-client 1.167.3 → 1.168.0

package/dist/esm/hydration/visible.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"visible.js","names":[],"sources":["../../../src/hydration/visible.tsx"],"sourcesContent":["'use client'\n\nimport * as React from 'react'\n\nimport { reactUse } from '@tanstack/react-router'\nimport { isServer } from '@tanstack/router-core/isServer'\nimport type {\n  HydrationPrefetchStrategy,\n  VisibleHydrationOptions,\n} from '@tanstack/start-client-core/hydration'\nimport type {\n  HydrateProps,\n  InternalHydrateProps,\n  ReactHydrationStrategy,\n} from '../Hydrate'\n\ntype VisibleGate = {\n  p: Promise<void>\n  r: boolean\n  s: () => void\n}\n\n/* @__NO_SIDE_EFFECTS__ */\nfunction HydrationBoundary(props: {\n  g: VisibleGate\n  o?: () => void\n  children?: React.ReactNode\n}) {\n  const { g, o } = props\n\n  if (!g.r) {\n    if (!reactUse) {\n      throw g.p\n    }\n\n    reactUse(g.p)\n  }\n\n  React.useEffect(() => {\n    o?.()\n  }, [o])\n\n  return props.children as React.JSX.Element\n}\n\n/* @__NO_SIDE_EFFECTS__ */\nexport function VisibleHydrate(\n  this: ReactHydrationStrategy,\n  props: HydrateProps,\n): React.JSX.Element {\n  const strategy = this as ReactHydrationStrategy<'visible', true>\n  const prefetchStrategy = props.prefetch\n  const preload = (props as InternalHydrateProps).p\n  const markerRef = React.useRef<HTMLDivElement | null>(null)\n  const [gate] = React.useState<VisibleGate>(() => {\n    let resolvePromise!: () => void\n    const nextGate: VisibleGate = {\n      p: new Promise<void>((resolve) => {\n        resolvePromise = resolve\n      }),\n      r: false,\n      s: () => {\n        nextGate.r = true\n        resolvePromise()\n      },\n    }\n    if (\n      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n      isServer ??\n      typeof window === 'undefined'\n    ) {\n      nextGate.s()\n    }\n\n    return nextGate\n  })\n\n  React.useEffect(() => {\n    if (!preload || typeof prefetchStrategy === 'function') {\n      return\n    }\n\n    return prefetchStrategy?._s?.({\n      element: markerRef.current,\n      prefetch: preload,\n    })\n  }, [prefetchStrategy, preload])\n\n  React.useEffect(() => {\n    if (gate.r) return\n\n    return strategy._s?.({\n      element: markerRef.current,\n      gate: gate as never,\n    })\n  }, [gate, strategy])\n\n  return (\n    <div ref={markerRef}>\n      <React.Suspense fallback={props.fallback}>\n        <HydrationBoundary g={gate} o={props.onHydrated}>\n          {props.children}\n        </HydrationBoundary>\n      </React.Suspense>\n    </div>\n  )\n}\n\n/* @__NO_SIDE_EFFECTS__ */\nexport function visible(\n  options?: VisibleHydrationOptions,\n): ReactHydrationStrategy<'visible', true> &\n  HydrationPrefetchStrategy<'visible'> {\n  const rootMargin = options?.rootMargin ?? '600px'\n  const threshold = options?.threshold ?? 0\n\n  return {\n    _s: ({ element, gate, prefetch }) => {\n      const callback = prefetch || (gate as never as VisibleGate).s\n\n      if (!element) {\n        callback()\n        return\n      }\n\n      const observer = new IntersectionObserver(\n        (entries) => {\n          if (!entries[0]!.isIntersecting) return\n          observer.disconnect()\n          callback()\n        },\n        { rootMargin, threshold },\n      )\n      observer.observe(element)\n      return () => observer.disconnect()\n    },\n    _h: VisibleHydrate,\n  }\n}\n"],"mappings":";;;;;;;AAuBA,SAAS,kBAAkB,OAIxB;CACD,MAAM,EAAE,GAAG,MAAM;AAEjB,KAAI,CAAC,EAAE,GAAG;AACR,MAAI,CAAC,SACH,OAAM,EAAE;AAGV,WAAS,EAAE,EAAE;;AAGf,OAAM,gBAAgB;AACpB,OAAK;IACJ,CAAC,EAAE,CAAC;AAEP,QAAO,MAAM;;;AAIf,SAAgB,eAEd,OACmB;CACnB,MAAM,WAAW;CACjB,MAAM,mBAAmB,MAAM;CAC/B,MAAM,UAAW,MAA+B;CAChD,MAAM,YAAY,MAAM,OAA8B,KAAK;CAC3D,MAAM,CAAC,QAAQ,MAAM,eAA4B;EAC/C,IAAI;EACJ,MAAM,WAAwB;GAC5B,GAAG,IAAI,SAAe,YAAY;AAChC,qBAAiB;KACjB;GACF,GAAG;GACH,SAAS;AACP,aAAS,IAAI;AACb,oBAAgB;;GAEnB;AACD,MAEE,YACA,OAAO,WAAW,YAElB,UAAS,GAAG;AAGd,SAAO;GACP;AAEF,OAAM,gBAAgB;AACpB,MAAI,CAAC,WAAW,OAAO,qBAAqB,WAC1C;AAGF,SAAO,kBAAkB,KAAK;GAC5B,SAAS,UAAU;GACnB,UAAU;GACX,CAAC;IACD,CAAC,kBAAkB,QAAQ,CAAC;AAE/B,OAAM,gBAAgB;AACpB,MAAI,KAAK,EAAG;AAEZ,SAAO,SAAS,KAAK;GACnB,SAAS,UAAU;GACb;GACP,CAAC;IACD,CAAC,MAAM,SAAS,CAAC;AAEpB,QACE,oBAAC,OAAD;EAAK,KAAK;YACR,oBAAC,MAAM,UAAP;GAAgB,UAAU,MAAM;aAC9B,oBAAC,mBAAD;IAAmB,GAAG;IAAM,GAAG,MAAM;cAClC,MAAM;IACW,CAAA;GACL,CAAA;EACb,CAAA;;;AAKV,SAAgB,QACd,SAEqC;CACrC,MAAM,aAAa,SAAS,cAAc;CAC1C,MAAM,YAAY,SAAS,aAAa;AAExC,QAAO;EACL,KAAK,EAAE,SAAS,MAAM,eAAe;GACnC,MAAM,WAAW,YAAa,KAA8B;AAE5D,OAAI,CAAC,SAAS;AACZ,cAAU;AACV;;GAGF,MAAM,WAAW,IAAI,sBAClB,YAAY;AACX,QAAI,CAAC,QAAQ,GAAI,eAAgB;AACjC,aAAS,YAAY;AACrB,cAAU;MAEZ;IAAE;IAAY;IAAW,CAC1B;AACD,YAAS,QAAQ,QAAQ;AACzB,gBAAa,SAAS,YAAY;;EAEpC,IAAI;EACL"}

package/dist/esm/hydration.d.ts

@@ -0,0 +1,7 @@
+export { condition, interaction, media } from './hydration/generic.js';
+export { idle } from './hydration/idle.js';
+export { load } from './hydration/load.js';
+export { never } from './hydration/never.js';
+export { visible } from './hydration/visible.js';
+export type { HydrationCondition, HydrationInteractionEvent, HydrationInteractionEvents, IdleHydrationOptions, HydrationPrefetchContext, HydrationPrefetchFunction, HydrationPrefetchWhen, HydrationPrefetchStrategy, HydrationPrefetchWaitReason, HydrationStrategyTypes, HydrationWhen, VisibleHydrationOptions, } from '@tanstack/start-client-core/hydration';
+export type { HydrationStrategy, ReactHydrationStrategy } from './Hydrate.js';

package/dist/esm/hydration.js

@@ -0,0 +1,7 @@
+"use client";
+import { condition, interaction, media } from "./hydration/generic.js";
+import { idle } from "./hydration/idle.js";
+import { load } from "./hydration/load.js";
+import { never } from "./hydration/never.js";
+import { visible } from "./hydration/visible.js";
+export { condition, idle, interaction, load, media, never, visible };

package/dist/esm/index.d.ts

@@ -1,2 +1,4 @@
 export { StartClient } from './StartClient.js';
 export { hydrateStart } from './hydrateStart.js';
+export { Hydrate } from './Hydrate.js';
+export type { HydrateOptions, HydrateProps, HydrateWhen, HydrationInteractionEvent, HydrationInteractionEvents, HydrationPrefetchContext, HydrationPrefetchFunction, HydrationPrefetchStrategy, HydrationPrefetchWaitReason, HydrationStrategy, HydrationWhen, } from './Hydrate.js';

package/dist/esm/index.js

@@ -1,3 +1,5 @@
+"use client";
 import { hydrateStart } from "./hydrateStart.js";
 import { StartClient } from "./StartClient.js";
-export { StartClient, hydrateStart };
+import { Hydrate } from "./Hydrate.js";
+export { Hydrate, StartClient, hydrateStart };

package/dist/esm/tests/Hydrate.test-d.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/esm/tests/Hydrate.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/react-start-client",
-  "version": "1.167.3",
+  "version": "1.168.0",
   "description": "Modern and scalable routing for React applications",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -32,6 +32,12 @@
         "default": "./dist/esm/index.js"
       }
     },
+    "./hydration": {
+      "import": {
+        "types": "./dist/esm/hydration.d.ts",
+        "default": "./dist/esm/hydration.js"
+      }
+    },
     "./package.json": "./package.json"
   },
   "sideEffects": false,
@@ -43,9 +49,9 @@
     "node": ">=22.12.0"
   },
   "dependencies": {
-    "@tanstack/react-router": "1.170.3",
-    "@tanstack/router-core": "1.171.1",
-    "@tanstack/start-client-core": "1.169.3"
+    "@tanstack/react-router": "1.170.5",
+    "@tanstack/router-core": "1.171.3",
+    "@tanstack/start-client-core": "1.170.0"
   },
   "devDependencies": {
     "@testing-library/react": "^16.2.0",

package/src/GenericHydrate.tsx

@@ -0,0 +1,436 @@
+'use client'
+
+import * as React from 'react'
+
+import { reactUse, useHydrated, useLayoutEffect } from '@tanstack/react-router'
+import { isServer } from '@tanstack/router-core/isServer'
+import {
+  hydrateIdAttribute,
+  hydrateWhenAttribute,
+} from '@tanstack/start-client-core/hydration/constants'
+import {
+  createResolvedGate,
+  getFallbackHtml,
+  getOrCreateGate,
+  onGateResolve,
+  releaseGate,
+  runHydrationStrategyCleanup,
+  saveFallbackHtml,
+  waitForHydrationPrefetchStrategy,
+} from '@tanstack/start-client-core/hydration/runtime'
+import { listenForDelegatedHydrationIntent } from '@tanstack/start-client-core/hydration'
+import type {
+  HydrationRuntimeContext,
+  HydrationStrategy,
+  HydrationWhen,
+} from '@tanstack/start-client-core/hydration'
+import type { HydrationGateRecord } from '@tanstack/start-client-core/hydration/runtime'
+import type { HydrateProps, InternalHydrateProps } from './Hydrate'
+
+type Gate = HydrationGateRecord & { promise: Promise<void> }
+type PrefetchController = {
+  abortController: AbortController
+  hydrationRequested: boolean
+  hydrationListeners: Set<() => void>
+  hydrationResolvePending: boolean
+  started: boolean
+  promise?: Promise<void>
+  cleanup?: () => void
+}
+
+const dynamicType = 'dynamic'
+const dynamicHydrateStrategy = {
+  _t: dynamicType,
+  _d: () => true,
+} satisfies HydrationStrategy<typeof dynamicType, false>
+
+function shouldDeferHydration(strategy: HydrationStrategy) {
+  return strategy._d ? strategy._d() : strategy._t !== 'load'
+}
+
+function useLatest<T>(value: T) {
+  const ref = React.useRef(value)
+  ref.current = value
+  return ref
+}
+
+function useHydrationGate(props: InternalHydrateProps) {
+  const hydrated = useHydrated()
+  const reactId = React.useId()
+  const id = props.h ? `${props.h}${reactId}` : reactId
+  const when = props.when
+  const isDynamicHydrate = typeof when === 'function'
+  const dynamicHydrateStrategyRef = React.useRef<HydrationStrategy | undefined>(
+    undefined,
+  )
+  if (isDynamicHydrate) {
+    dynamicHydrateStrategyRef.current ??=
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+      (isServer ?? typeof window === 'undefined')
+        ? dynamicHydrateStrategy
+        : when()
+  }
+  const hydrateStrategy = isDynamicHydrate
+    ? dynamicHydrateStrategyRef.current!
+    : when
+  const markerHydrateType: HydrationWhen = isDynamicHydrate
+    ? dynamicType
+    : hydrateStrategy._t!
+  const [prefetchError, setPrefetchError] = React.useState<unknown>()
+  const latestRef = useLatest({
+    prefetch: props.prefetch,
+    preload: props.p,
+  })
+  const gateRef = React.useRef<HydrationGateRecord | undefined>(undefined)
+  const markerElementRef = React.useRef<HTMLDivElement | null>(null)
+  const shouldPreserveServerHTMLRef = React.useRef<boolean | undefined>(
+    undefined,
+  )
+  const shouldDeferInitialHydrationRef = React.useRef<boolean | undefined>(
+    undefined,
+  )
+  const didPrefetchRef = React.useRef(false)
+  const prefetchControllerRef = React.useRef<PrefetchController | undefined>(
+    undefined,
+  )
+
+  prefetchControllerRef.current ??= {
+    abortController: new AbortController(),
+    hydrationRequested: false,
+    hydrationListeners: new Set<() => void>(),
+    hydrationResolvePending: false,
+    started: false,
+  }
+
+  shouldPreserveServerHTMLRef.current ??=
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    (isServer ?? typeof window === 'undefined') || !hydrated
+  shouldDeferInitialHydrationRef.current ??=
+    !hydrated && shouldDeferHydration(hydrateStrategy)
+
+  if (!gateRef.current) {
+    gateRef.current =
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+      (isServer ?? typeof window === 'undefined')
+        ? createResolvedGate(id, hydrateStrategy._t!)
+        : getOrCreateGate(id, hydrateStrategy._t!)
+  }
+
+  gateRef.current.when = hydrateStrategy._t!
+
+  if (
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    !(isServer ?? typeof window === 'undefined') &&
+    hydrateStrategy._t !== 'never' &&
+    (!shouldDeferInitialHydrationRef.current ||
+      !shouldDeferHydration(hydrateStrategy))
+  ) {
+    gateRef.current.resolve()
+  }
+
+  const markerRef = React.useCallback(
+    (element: HTMLDivElement | null) => {
+      markerElementRef.current = element
+      if (element) {
+        if (
+          hydrateStrategy._t === 'never' &&
+          !shouldPreserveServerHTMLRef.current
+        ) {
+          element.replaceChildren()
+        }
+        saveFallbackHtml(id, element)
+      }
+    },
+    [hydrateStrategy._t, id],
+  )
+
+  React.useEffect(() => {
+    const gate = gateRef.current!
+    return () => {
+      const controller = prefetchControllerRef.current
+      controller?.abortController.abort()
+      controller?.cleanup?.()
+      controller?.hydrationListeners.clear()
+      releaseGate(gate)
+    }
+  }, [])
+
+  React.useEffect(() => {
+    if (
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+      (isServer ?? typeof window === 'undefined') ||
+      !latestRef.current.prefetch
+    ) {
+      return
+    }
+
+    const controller = prefetchControllerRef.current!
+    if (controller.started) return
+    controller.started = true
+
+    const onHydrate = (listener: () => void) => {
+      if (controller.hydrationRequested) {
+        listener()
+        return () => {}
+      }
+
+      controller.hydrationListeners.add(listener)
+      return () => {
+        controller.hydrationListeners.delete(listener)
+      }
+    }
+
+    const preload = () => latestRef.current.preload?.() ?? Promise.resolve()
+    const prefetchInput = latestRef.current.prefetch
+
+    if (typeof prefetchInput === 'function') {
+      const promise = Promise.resolve()
+        .then(() =>
+          prefetchInput({
+            element: markerElementRef.current,
+            signal: controller.abortController.signal,
+            preload,
+            waitFor: (strategy) =>
+              waitForHydrationPrefetchStrategy(strategy, {
+                element: markerElementRef.current,
+                signal: controller.abortController.signal,
+                onHydrate,
+              }),
+          }),
+        )
+        .then(() => undefined)
+
+      controller.promise = promise
+      promise.catch((error) => {
+        if (!controller.abortController.signal.aborted) {
+          setPrefetchError(error)
+        }
+      })
+      return
+    }
+
+    if (!latestRef.current.preload) return
+
+    const prefetch = () => {
+      if (didPrefetchRef.current) return
+      didPrefetchRef.current = true
+      void preload()
+    }
+
+    controller.cleanup = runHydrationStrategyCleanup(
+      prefetchInput._s?.({
+        element: markerElementRef.current,
+        prefetch,
+      }),
+    )
+  }, [hydrateStrategy, latestRef])
+
+  useLayoutEffect(() => {
+    const gate = gateRef.current!
+    if (
+      !shouldDeferInitialHydrationRef.current ||
+      hydrateStrategy._t === 'never'
+    ) {
+      return
+    }
+
+    if (gate.resolved) {
+      return
+    }
+
+    const cleanups: Array<() => void> = []
+    let removeResolveListener = () => {}
+    let disposed = false
+    const resolveGate = gate.resolve
+
+    const cleanup = () => {
+      if (disposed) return
+      disposed = true
+      if (gate.resolve === requestHydration) {
+        gate.resolve = resolveGate
+      }
+      removeResolveListener()
+      cleanups.forEach((fn) => fn())
+    }
+
+    const addCleanup = (fn: void | (() => void)) => {
+      if (!fn) return
+      if (disposed || gate.resolved) {
+        fn()
+        return
+      }
+      cleanups.push(fn)
+    }
+
+    const requestHydration = () => {
+      const controller = prefetchControllerRef.current!
+      if (!controller.hydrationRequested) {
+        controller.hydrationRequested = true
+        controller.hydrationListeners.forEach((listener) => listener())
+        controller.hydrationListeners.clear()
+      }
+
+      if (!controller.promise) {
+        resolveGate()
+        return
+      }
+      if (controller.hydrationResolvePending) return
+      controller.hydrationResolvePending = true
+
+      controller.promise.then(
+        () => resolveGate(),
+        (error) => {
+          if (!controller.abortController.signal.aborted) {
+            setPrefetchError(error)
+          }
+        },
+      )
+    }
+
+    gate.resolve = requestHydration
+    removeResolveListener = onGateResolve(gate, cleanup)
+
+    const context: HydrationRuntimeContext = {
+      element: markerElementRef.current,
+      gate,
+    }
+    addCleanup(runHydrationStrategyCleanup(hydrateStrategy._s?.(context)))
+
+    if (hydrateStrategy._t !== 'interaction') {
+      addCleanup(
+        runHydrationStrategyCleanup(
+          markerElementRef.current
+            ? listenForDelegatedHydrationIntent(
+                markerElementRef.current,
+                context,
+              )
+            : undefined,
+        ),
+      )
+    }
+
+    return cleanup
+  }, [hydrateStrategy, latestRef])
+
+  return {
+    gate: gateRef.current,
+    markerRef,
+    markerElementRef,
+    hydrateStrategy,
+    markerHydrateType,
+    prefetchError,
+    shouldPreserveServerHTML: shouldPreserveServerHTMLRef.current,
+  }
+}
+
+function HydrationGate(props: { gate: Gate; children: React.ReactNode }) {
+  if (
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    isServer ??
+    typeof window === 'undefined'
+  ) {
+    return props.children as React.JSX.Element
+  }
+
+  if (props.gate.resolved) {
+    return props.children as React.JSX.Element
+  }
+
+  if (!reactUse) {
+    throw props.gate.promise
+  }
+
+  reactUse(props.gate.promise)
+
+  return props.children as React.JSX.Element
+}
+
+function HydratedBoundary(props: {
+  id: string
+  onHydrated?: () => void
+  onStrategyHydrated?: (id: string) => void
+  children: React.ReactNode
+}) {
+  const { id, onHydrated, onStrategyHydrated } = props
+  const didHydrateRef = React.useRef(false)
+
+  React.useEffect(() => {
+    if (didHydrateRef.current) return
+    didHydrateRef.current = true
+    onHydrated?.()
+    onStrategyHydrated?.(id)
+  }, [id, onHydrated, onStrategyHydrated])
+
+  return props.children as React.JSX.Element
+}
+
+export function GenericHydrate(props: HydrateProps): React.JSX.Element {
+  const internalProps = props as InternalHydrateProps
+  const {
+    gate,
+    hydrateStrategy,
+    markerHydrateType,
+    markerElementRef,
+    markerRef,
+    prefetchError,
+    shouldPreserveServerHTML,
+  } = useHydrationGate(internalProps)
+  if (prefetchError) throw prefetchError
+
+  const fallback = shouldPreserveServerHTML
+    ? (() => {
+        const html = getFallbackHtml(gate.id)
+        return html ? (
+          <div
+            style={{ display: 'contents' }}
+            dangerouslySetInnerHTML={{ __html: html }}
+          />
+        ) : null
+      })()
+    : (props.fallback ?? null)
+  const markerAttributes =
+    markerHydrateType === dynamicType ? undefined : hydrateStrategy._a?.()
+
+  const hydrateType = hydrateStrategy._t!
+
+  if (hydrateType === 'never' && !shouldPreserveServerHTML) {
+    return (
+      <div
+        ref={markerRef}
+        {...{
+          [hydrateIdAttribute]: gate.id,
+          [hydrateWhenAttribute]: markerHydrateType,
+          ...markerAttributes,
+        }}
+      >
+        {props.fallback ?? null}
+      </div>
+    )
+  }
+
+  return (
+    <div
+      ref={markerRef}
+      {...{
+        [hydrateIdAttribute]: gate.id,
+        [hydrateWhenAttribute]: markerHydrateType,
+        ...markerAttributes,
+      }}
+    >
+      <React.Suspense fallback={fallback}>
+        <HydrationGate gate={gate}>
+          <HydratedBoundary
+            id={gate.id}
+            onHydrated={props.onHydrated}
+            onStrategyHydrated={(id) => {
+              markerElementRef.current?.removeAttribute(hydrateWhenAttribute)
+              hydrateStrategy._o?.(id)
+            }}
+          >
+            {props.children}
+          </HydratedBoundary>
+        </HydrationGate>
+      </React.Suspense>
+    </div>
+  )
+}

package/src/Hydrate.tsx

@@ -0,0 +1,107 @@
+'use client'
+
+import * as React from 'react'
+
+import { isServer } from '@tanstack/router-core/isServer'
+import type {
+  HydrationStrategy as CoreHydrationStrategy,
+  HydrationPrefetchFunction,
+  HydrationPrefetchStrategy,
+  HydrationWhen,
+} from '@tanstack/start-client-core/hydration'
+
+export type {
+  HydrationInteractionEvent,
+  HydrationInteractionEvents,
+  HydrationPrefetchContext,
+  HydrationPrefetchFunction,
+  HydrationPrefetchStrategy,
+  HydrationPrefetchWaitReason,
+  HydrationWhen,
+} from '@tanstack/start-client-core/hydration'
+
+export type ReactHydrationStrategy<
+  TWhen extends HydrationWhen = HydrationWhen,
+  TCanPrefetch extends boolean = boolean,
+> = CoreHydrationStrategy<TWhen, TCanPrefetch> & {
+  _h: (this: ReactHydrationStrategy, props: HydrateProps) => React.JSX.Element
+}
+
+export type HydrationStrategy<
+  TWhen extends HydrationWhen = HydrationWhen,
+  TCanPrefetch extends boolean = boolean,
+> = ReactHydrationStrategy<TWhen, TCanPrefetch>
+
+export type HydrateWhen =
+  | ReactHydrationStrategy
+  | (() => ReactHydrationStrategy)
+
+type HydrateCommonOptions = {
+  when: HydrateWhen
+  fallback?: React.ReactNode
+  onHydrated?: () => void
+}
+
+export type HydrateOptions =
+  | (HydrateCommonOptions & {
+      prefetch?: never
+      split?: boolean
+    })
+  | (HydrateCommonOptions & {
+      prefetch: HydrationPrefetchStrategy
+      split?: true
+    })
+  | (HydrateCommonOptions & {
+      prefetch: HydrationPrefetchFunction
+      split?: boolean
+    })
+
+export type HydrateProps = HydrateOptions & {
+  children: React.ReactNode
+}
+
+export type InternalHydrateProps = HydrateProps & {
+  h?: string
+  p?: () => Promise<void>
+}
+
+const dynamicType = 'dynamic'
+const hydrateIdAttribute = 'data-ts-hydrate-id'
+const hydrateWhenAttribute = 'data-ts-hydrate-when'
+
+/* @__NO_SIDE_EFFECTS__ */
+function ServerDynamicHydrate(props: HydrateProps): React.JSX.Element {
+  const internalProps = props as InternalHydrateProps
+  const reactId = React.useId()
+  const id = internalProps.h ? `${internalProps.h}${reactId}` : reactId
+
+  return (
+    <div
+      {...{
+        [hydrateIdAttribute]: id,
+        [hydrateWhenAttribute]: dynamicType,
+      }}
+    >
+      <React.Suspense fallback={props.fallback ?? null}>
+        {props.children}
+      </React.Suspense>
+    </div>
+  )
+}
+
+/* @__NO_SIDE_EFFECTS__ */
+export function Hydrate(props: HydrateProps): React.JSX.Element {
+  if (typeof props.when === 'function') {
+    if (
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+      isServer ??
+      typeof window === 'undefined'
+    ) {
+      return <ServerDynamicHydrate {...props} />
+    }
+
+    return props.when()._h(props)
+  }
+
+  return props.when._h(props)
+}

package/src/hydration/generic.ts

@@ -0,0 +1,43 @@
+'use client'
+
+import {
+  condition as coreCondition,
+  interaction as coreInteraction,
+  media as coreMedia,
+  withHydrationRenderer,
+} from '@tanstack/start-client-core/hydration'
+import { GenericHydrate } from '../GenericHydrate'
+import type {
+  HydrationCondition,
+  HydrationInteractionEvents,
+  HydrationPrefetchStrategy,
+} from '@tanstack/start-client-core/hydration'
+import type { ReactHydrationStrategy } from '../Hydrate'
+
+/* @__NO_SIDE_EFFECTS__ */
+export function media(
+  query: string,
+): ReactHydrationStrategy<'media', true> & HydrationPrefetchStrategy<'media'> {
+  return /* @__PURE__ */ withHydrationRenderer(coreMedia(query), GenericHydrate)
+}
+
+/* @__NO_SIDE_EFFECTS__ */
+export function condition(
+  condition: HydrationCondition,
+): ReactHydrationStrategy<'condition', false> {
+  return /* @__PURE__ */ withHydrationRenderer(
+    coreCondition(condition),
+    GenericHydrate,
+  )
+}
+
+/* @__NO_SIDE_EFFECTS__ */
+export function interaction(options?: {
+  events?: HydrationInteractionEvents
+}): ReactHydrationStrategy<'interaction', true> &
+  HydrationPrefetchStrategy<'interaction'> {
+  return /* @__PURE__ */ withHydrationRenderer(
+    coreInteraction(options),
+    GenericHydrate,
+  )
+}

package/src/hydration/idle.ts

@@ -0,0 +1,22 @@
+'use client'
+
+import {
+  idle as coreIdle,
+  withHydrationRenderer,
+} from '@tanstack/start-client-core/hydration'
+import { GenericHydrate } from '../GenericHydrate'
+import type {
+  HydrationPrefetchStrategy,
+  IdleHydrationOptions,
+} from '@tanstack/start-client-core/hydration'
+import type { ReactHydrationStrategy } from '../Hydrate'
+
+/* @__NO_SIDE_EFFECTS__ */
+export function idle(
+  options: IdleHydrationOptions = {},
+): ReactHydrationStrategy<'idle', true> & HydrationPrefetchStrategy<'idle'> {
+  return /* @__PURE__ */ withHydrationRenderer(
+    coreIdle(options),
+    GenericHydrate,
+  )
+}