refactor(solid-router): move hydration off sharedConfig onto public Solid 2.0 APIs

Replace solid-js internals with the public hydration surface shipped in
solid-js / @solidjs/web 2.0.0-rc.13 (solidjs/solid#3718):

- useHydrated: sharedConfig.hydrating -> isHydrating()
- serializeMatchTransfer: sharedConfig.context.serialize ->
  getHydrationWriter().write, gated on isHydratable() (the old
  context.noHydrate guard was dead in 2.0)
- primeRouterFromRegistry: raw _$HY.r reads, the tsr: prefix scan and
  s/v unwrapping -> per-match takeHydrationValue()
- tests / external-SSR repro: drop the sharedConfig reset and _$HY
  enumeration; the repro asserts entries server-side and consumption
  through takeHydrationValue

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

Author: 3 people

.changeset/solid-router-public-hydration-api.md

@@ -0,0 +1,12 @@
+---
+'@tanstack/solid-router': patch
+'@tanstack/solid-router-devtools': patch
+'@tanstack/solid-router-ssr-query': patch
+'@tanstack/solid-start': patch
+'@tanstack/solid-start-client': patch
+'@tanstack/solid-start-server': patch
+---
+
+Bump solid-js and @solidjs/web to ^2.0.0-rc.13 (and @solidjs/vite-plugin to ^3.0.0-next.46), and raise the Solid peer floors to 2.0.0-rc.13.
+
+@tanstack/solid-router moves off Solid's internal `sharedConfig` and the raw `_$HY` registry onto the public hydration API rc.13 ships (solidjs/solid#3718): `useHydrated` reads `isHydrating()`; the native SSR match transfer writes through `getHydrationWriter()` gated on `isHydratable()`, so it now respects `<NoHydration>`; and the client boot takes each match's entry with `takeHydrationValue()`.

packages/solid-router/repro-external-ssr/entry-client.tsx

@@ -1,4 +1,4 @@
-import { hydrate } from 'solid-js/web'
+import { hydrate, takeHydrationValue } from 'solid-js/web'
 import { RouterProvider } from '../src'
 import { createAppRouter, loaderRuns } from './app.shared'
 import { MATCH_KEY_PREFIX } from '../src/registryTransfer'
@@ -38,23 +38,18 @@ async function main() {
   const root = document.getElementById('root')!
   const serverNode = document.getElementById('home')
 
-  // The registry entries the server's RouterProvider wrote, populated at
-  // document parse — createRouter's boot consumes (and deletes) them, so
-  // sample before construction.
-  const hasMatchEntries = () =>
-    Object.keys((window as any)._$HY?.r ?? {}).some((key) =>
-      key.startsWith(MATCH_KEY_PREFIX),
-    )
-  results.registryHadMatchEntries = hasMatchEntries()
-
   const { router, resolveAboutChunk } = createAppRouter()
   results.loaderRunsBeforeHydrate = loaderRuns.count
-  // Phase 1 boot happened at router creation: entries consumed, matches
-  // committed, zero loader runs — nothing left for the app to wire.
+  // Phase 1 boot happened at router creation: the server's entries taken,
+  // matches committed, zero loader runs — nothing left for the app to wire.
+  // The boot commits only when every match took its entry, so a committed
+  // match whose key is gone was primed from the registry.
+  const committed = router.stores.matches.get()
   results.registryPrimed =
-    results.registryHadMatchEntries &&
-    !hasMatchEntries() &&
-    router.stores.matches.get().length > 0
+    committed.length > 0 &&
+    committed.every(
+      (match) => takeHydrationValue(MATCH_KEY_PREFIX + match.id) === undefined,
+    )
 
   results.htmlBeforeHydrate = root.innerHTML
   hydrate(() => <RouterProvider router={router} />, root)

packages/solid-router/repro-external-ssr/run.mjs

@@ -107,6 +107,10 @@ for (const key of [
   'Request',
   'Headers',
   'fetch',
+  // @solidjs/web's server-function protocol module encodes its event-stream
+  // heartbeat at module scope; jsdom has no encoding globals.
+  'TextEncoder',
+  'TextDecoder',
 ]) {
   if (dom.window[key] === undefined && globalThis[key] !== undefined) {
     dom.window[key] = globalThis[key]
@@ -135,6 +139,8 @@ if (results.pendingFlashDuringHydrate === true)
   failures.push('pending UI flashed during hydration')
 if (results.serverNodeReused !== true)
   failures.push('server-rendered node was NOT reused (mismatch re-render)')
+if (!chunks[0]?.includes('tsr:'))
+  failures.push('server wrote no match entries into the shell chunk')
 if (results.registryPrimed !== true)
   failures.push('registry transfer did not prime the router (fell through)')
 if (results.loaderRunsAfterHydrate !== 0)

packages/solid-router/src/ClientOnly.tsx

@@ -61,7 +61,7 @@ let globalHydrated = false
 
 export function useHydrated(): Solid.Accessor<boolean> {
   const [hydrated, setHydrated] = Solid.createSignal(
-    globalHydrated && !Solid.sharedConfig.hydrating,
+    globalHydrated && !Solid.isHydrating(),
   )
 
   Solid.createEffect(

packages/solid-router/src/registryTransfer.ts

@@ -1,4 +1,5 @@
-import * as Solid from 'solid-js'
+import { isHydratable } from 'solid-js'
+import { getHydrationWriter, takeHydrationValue } from '@solidjs/web'
 import type { AnyRouteMatch, AnyRouter } from '@tanstack/router-core'
 
 /**
@@ -9,7 +10,7 @@ import type { AnyRouteMatch, AnyRouter } from '@tanstack/router-core'
  * derive the same key from the same URL), the identical mechanism
  * solid-query v6 ships query payloads through (`sq:<queryHash>`).
  *
- * Server half: while the render's serialization context is live, the
+ * Server half: while the render takes values (`getHydrationWriter`), the
  * provider writes each settled match's transferable state. Client half: the
  * hydration-claiming boot — matching is synchronous, so the provider primes
  * match state from the registry and commits before rendering, without
@@ -42,17 +43,10 @@ type MatchWithBeforeLoadContext = AnyRouteMatch & {
   __beforeLoadContext?: Record<string, unknown>
 }
 
-interface SerializationContext {
-  noHydrate?: boolean
-  serialize: (key: string, value: unknown) => void
-}
-
 export function serializeMatchTransfer(router: AnyRouter): void {
   if (router.serverSsr) return
-  const ctx = (
-    Solid.sharedConfig as unknown as { context?: SerializationContext }
-  ).context
-  if (!ctx || typeof ctx.serialize !== 'function' || ctx.noHydrate) return
+  const writer = getHydrationWriter()
+  if (!writer || !isHydratable()) return
 
   for (const match of router.stores.matches.get()) {
     // Pending matches are skipped, not deferred: this core has no per-match
@@ -73,56 +67,37 @@ export function serializeMatchTransfer(router: AnyRouter): void {
     if (beforeLoadContext !== undefined)
       entry.beforeLoadContext = beforeLoadContext
     if (match.ssr !== undefined) entry.ssr = match.ssr
-    ctx.serialize(MATCH_KEY_PREFIX + match.id, entry)
+    writer.write(MATCH_KEY_PREFIX + match.id, entry)
   }
 }
 
 /**
  * The hydration-claiming boot. Returns true when every synchronously
  * matched route found its registry entry and the matches were committed;
  * false falls back to the caller's existing behavior (no entries — a
- * non-registry server, `noHydrate`, or a pending match the server skipped).
+ * non-registry server, `<NoHydration>`, or a pending match the server
+ * skipped).
  *
- * Reads the raw registry rather than sharedConfig's accessors: entries
- * arrive as inline scripts that execute at document parse, so they are
- * complete before any client code runs — and the boot must commit BEFORE
- * the hydration render (store writes inside it are owned-scope writes).
+ * Entries arrive as inline scripts that execute at document parse, so they
+ * are complete before any client code runs and `takeHydrationValue` reads
+ * them before `hydrate()` — the boot must commit BEFORE the hydration
+ * render (store writes inside it are owned-scope writes). Each matched
+ * route takes its own key: a page without entries (SPA, or Start's own
+ * channel) falls through at the first match.
  */
 export function primeRouterFromRegistry(router: AnyRouter): boolean {
   if (router.stores.matches.get().length > 0) return false
-  const registry = (
-    globalThis as unknown as { _$HY?: { r: Record<string, unknown> } }
-  )._$HY?.r
-  if (!registry) return false
-  // A page with no match entries (SPA, or Start's own channel) skips before
-  // paying for a match pass.
-  let hasMatchEntries = false
-  for (const key in registry) {
-    if (key.startsWith(MATCH_KEY_PREFIX)) {
-      hasMatchEntries = true
-      break
-    }
-  }
-  if (!hasMatchEntries) return false
 
   const matches = router.matchRoutes(router.latestLocation)
   if (matches.length === 0) return false
 
   const primed: Array<AnyRouteMatch> = []
   for (const match of matches) {
-    const key = MATCH_KEY_PREFIX + match.id
-    if (!(key in registry)) return false
-    const raw = registry[key] as
-      | TransferredMatch
-      | { s: number; v?: TransferredMatch }
-      | null
-    delete registry[key]
-    // Settled serialization refs are stamped `s`/`v`; sync-serialized
-    // entries are the value itself.
-    const entry =
-      raw != null && typeof raw === 'object' && 's' in raw && raw.s === 1
-        ? raw.v
-        : (raw as TransferredMatch | null)
+    const taken = takeHydrationValue<TransferredMatch | null>(
+      MATCH_KEY_PREFIX + match.id,
+    )
+    if (taken?.status !== 'resolved') return false
+    const entry = taken.value
     if (!entry || typeof entry.status !== 'string') return false
     primed.push(applyTransferredMatch(match, entry))
   }

packages/solid-router/tests/matches-hydration-boundary.test.tsx

@@ -1,5 +1,4 @@
 import { afterEach, describe, expect, test, vi } from 'vitest'
-import { sharedConfig } from 'solid-js'
 import { cleanup, render, screen } from '@solidjs/testing-library'
 import { hydrate } from '@tanstack/router-core/ssr/client'
 import { dehydrateSsrMatchId } from '../../router-core/src/ssr/ssr-match-id'
@@ -13,7 +12,6 @@ import {
 import { lazyRouteComponent } from '../src/lazyRouteComponent'
 
 afterEach(() => {
-  sharedConfig.hydrating = false
   delete (window as any).$_TSR
   vi.restoreAllMocks()
   cleanup()