From 32cfdc1b4de333d9bcfeca2d02224801838f0738 Mon Sep 17 00:00:00 2001
From: tmm <tmm@tmm.dev>
Date: Tue, 7 Apr 2026 20:04:02 -0400
Subject: [PATCH 1/6] fix: preserve unmasked route on reload

---
 .../react-router/src/headContentUtils.tsx     | 113 ++++++++++++++++++
 packages/react-router/tests/Scripts.test.tsx  |  90 ++++++++++++++
 2 files changed, 203 insertions(+)

diff --git a/packages/react-router/src/headContentUtils.tsx b/packages/react-router/src/headContentUtils.tsx
index b180af2941d..5c067fad271 100644
--- a/packages/react-router/src/headContentUtils.tsx
+++ b/packages/react-router/src/headContentUtils.tsx
@@ -169,6 +169,8 @@ function buildTagsFromMatches(
     children,
   }))
 
+  const unmaskOnReloadScript = buildUnmaskOnReloadHeadScript(router, nonce)
+
   return uniqBy(
     [
       ...resultMeta,
@@ -176,6 +178,7 @@ function buildTagsFromMatches(
       ...constructedLinks,
       ...assetLinks,
       ...styles,
+      ...(unmaskOnReloadScript ? [unmaskOnReloadScript] : []),
       ...headScripts,
     ] as Array<RouterManagedTag>,
     (d) => JSON.stringify(d),
@@ -397,12 +400,19 @@ export const useTags = (assetCrossOrigin?: AssetCrossOriginConfig) => {
     deepEqual,
   )
 
+  // eslint-disable-next-line react-hooks/rules-of-hooks -- condition is static
+  const unmaskOnReloadScript = React.useMemo(
+    () => buildUnmaskOnReloadHeadScript(router, nonce),
+    [router, nonce],
+  )
+
   return uniqBy(
     [
       ...meta,
       ...preloadLinks,
       ...links,
       ...styles,
+      ...(unmaskOnReloadScript ? [unmaskOnReloadScript] : []),
       ...headScripts,
     ] as Array<RouterManagedTag>,
     (d) => {
@@ -411,6 +421,109 @@ export const useTags = (assetCrossOrigin?: AssetCrossOriginConfig) => {
   )
 }
 
+function buildUnmaskOnReloadHeadScript(
+  router: ReturnType<typeof useRouter>,
+  nonce: string | undefined,
+) {
+  const routeMaskSources = (router.options.routeMasks ?? [])
+    .filter((routeMask) => routeMask.unmaskOnReload && typeof routeMask.from === 'string')
+    .map((routeMask) => routePathToRegExpSource(routeMask.from))
+
+  if (!routeMaskSources.length) return undefined
+
+  return {
+    tag: 'script',
+    attrs: nonce ? { nonce } : undefined,
+    children: `
+(() => {
+  const maskedRoutePathPatterns = ${JSON.stringify(routeMaskSources)}
+    .map((source) => new RegExp(source))
+  const tempLocation = window.history.state?.__tempLocation
+  if (!tempLocation?.pathname) return
+  if (
+    tempLocation.pathname === window.location.pathname &&
+    (tempLocation.search ?? '') === window.location.search &&
+    (tempLocation.hash ?? '') === window.location.hash
+  ) return
+  if (!maskedRoutePathPatterns.some((pattern) => pattern.test(tempLocation.pathname)))
+    return
+  window.location.replace(
+    tempLocation.pathname + (tempLocation.search ?? '') + (tempLocation.hash ?? ''),
+  )
+})()
+`,
+  } satisfies RouterManagedTag
+}
+
+function routePathToRegExpSource(routePath: string) {
+  let regExpSource = '^'
+
+  for (const segment of routePath.split('/').filter(Boolean)) {
+    const routeSegment = parseRoutePathSegment(segment)
+
+    if (routeSegment.type === 'optional-param') {
+      regExpSource += `(?:/${routeSegment.source})?`
+      continue
+    }
+
+    if (routeSegment.type === 'wildcard') {
+      regExpSource += `(?:/${routeSegment.source})?`
+      continue
+    }
+
+    regExpSource += `/${routeSegment.source}`
+  }
+
+  return `${regExpSource}$`
+}
+
+function parseRoutePathSegment(segment: string) {
+  if (!segment.includes('$')) {
+    return { source: escapeRegExp(segment), type: 'pathname' as const }
+  }
+
+  if (segment === '$') {
+    return { source: '.*', type: 'wildcard' as const }
+  }
+
+  if (segment.startsWith('$')) {
+    return { source: '[^/]+', type: 'param' as const }
+  }
+
+  const openBraceIndex = segment.indexOf('{')
+  if (openBraceIndex === -1) {
+    return { source: escapeRegExp(segment), type: 'pathname' as const }
+  }
+
+  const closeBraceIndex = segment.indexOf('}', openBraceIndex)
+  if (closeBraceIndex === -1) {
+    return { source: escapeRegExp(segment), type: 'pathname' as const }
+  }
+
+  const prefix = segment.slice(0, openBraceIndex)
+  const suffix = segment.slice(closeBraceIndex + 1)
+  const token = segment.slice(openBraceIndex + 1, closeBraceIndex)
+  const source = `${escapeRegExp(prefix)}${token === '$' ? '.*' : '[^/]+'}${escapeRegExp(suffix)}`
+
+  if (token === '$') {
+    return { source, type: 'wildcard' as const }
+  }
+
+  if (token.startsWith('-$') && token.length > 2) {
+    return { source, type: 'optional-param' as const }
+  }
+
+  if (token.startsWith('$') && token.length > 1) {
+    return { source, type: 'param' as const }
+  }
+
+  return { source: escapeRegExp(segment), type: 'pathname' as const }
+}
+
+function escapeRegExp(value: string) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
 export function uniqBy<T>(arr: Array<T>, fn: (item: T) => string) {
   const seen = new Set<string>()
   return arr.filter((item) => {
diff --git a/packages/react-router/tests/Scripts.test.tsx b/packages/react-router/tests/Scripts.test.tsx
index 0ca10b794a5..d677724bf1a 100644
--- a/packages/react-router/tests/Scripts.test.tsx
+++ b/packages/react-router/tests/Scripts.test.tsx
@@ -19,6 +19,7 @@ import {
   createMemoryHistory,
   createRootRoute,
   createRoute,
+  createRouteMask,
   createRouter,
 } from '../src'
 import { Scripts } from '../src/Scripts'
@@ -371,6 +372,95 @@ describe('ssr HeadContent', () => {
     )
   })
 
+  test('injects a nonce-aware preload script for masks that unmask on reload', async () => {
+    const rootRoute = createRootRoute({
+      component: () => <HeadContent />,
+    })
+
+    const indexRoute = createRoute({
+      path: '/',
+      getParentRoute: () => rootRoute,
+    })
+
+    const modalRoute = createRoute({
+      path: '/modal',
+      getParentRoute: () => rootRoute,
+    })
+
+    const routeTree = rootRoute.addChildren([indexRoute, modalRoute])
+
+    const router = createRouter({
+      history: createMemoryHistory({
+        initialEntries: ['/'],
+      }),
+      isServer: true,
+      routeMasks: [
+        createRouteMask({
+          from: '/modal',
+          routeTree,
+          to: '/',
+          unmaskOnReload: true,
+        }),
+      ],
+      routeTree,
+      ssr: {
+        nonce: 'test-nonce',
+      },
+    })
+
+    await router.load()
+
+    const html = ReactDOMServer.renderToString(
+      <RouterProvider router={router} />,
+    )
+
+    expect(html).toContain('<script nonce="test-nonce">')
+    expect(html).toContain('window.history.state?.__tempLocation')
+    expect(html).toContain('window.location.replace(')
+    expect(html).toContain('^/modal$')
+  })
+
+  test('does not inject an unmask-on-reload script for ordinary route masks', async () => {
+    const rootRoute = createRootRoute({
+      component: () => <HeadContent />,
+    })
+
+    const indexRoute = createRoute({
+      path: '/',
+      getParentRoute: () => rootRoute,
+    })
+
+    const modalRoute = createRoute({
+      path: '/modal',
+      getParentRoute: () => rootRoute,
+    })
+
+    const routeTree = rootRoute.addChildren([indexRoute, modalRoute])
+
+    const router = createRouter({
+      history: createMemoryHistory({
+        initialEntries: ['/'],
+      }),
+      isServer: true,
+      routeMasks: [
+        createRouteMask({
+          from: '/modal',
+          routeTree,
+          to: '/',
+        }),
+      ],
+      routeTree,
+    })
+
+    await router.load()
+
+    const html = ReactDOMServer.renderToString(
+      <RouterProvider router={router} />,
+    )
+
+    expect(html).not.toContain('window.history.state?.__tempLocation')
+  })
+
   test('keeps manifest stylesheet links mounted when history state changes', async () => {
     const history = createTestBrowserHistory()
 

From 84d81fdbc786907da2692ea1bb8fcc401ecfe690 Mon Sep 17 00:00:00 2001
From: tmm <tmm@tmm.dev>
Date: Tue, 7 Apr 2026 21:11:45 -0400
Subject: [PATCH 2/6] refactor: share route mask path matching

---
 .../react-router/src/headContentUtils.tsx     | 70 +------------------
 packages/router-core/src/index.ts             |  1 +
 packages/router-core/src/path.ts              | 58 ++++++++++++++-
 packages/router-core/tests/path.test.ts       | 57 +++++++++++++++
 4 files changed, 116 insertions(+), 70 deletions(-)

diff --git a/packages/react-router/src/headContentUtils.tsx b/packages/react-router/src/headContentUtils.tsx
index 5c067fad271..ca6a34ed9e2 100644
--- a/packages/react-router/src/headContentUtils.tsx
+++ b/packages/react-router/src/headContentUtils.tsx
@@ -5,6 +5,7 @@ import {
   escapeHtml,
   getAssetCrossOrigin,
   resolveManifestAssetLink,
+  routePathToRegExpSource,
 } from '@tanstack/router-core'
 import { isServer } from '@tanstack/router-core/isServer'
 import { useRouter } from './useRouter'
@@ -455,75 +456,6 @@ function buildUnmaskOnReloadHeadScript(
   } satisfies RouterManagedTag
 }
 
-function routePathToRegExpSource(routePath: string) {
-  let regExpSource = '^'
-
-  for (const segment of routePath.split('/').filter(Boolean)) {
-    const routeSegment = parseRoutePathSegment(segment)
-
-    if (routeSegment.type === 'optional-param') {
-      regExpSource += `(?:/${routeSegment.source})?`
-      continue
-    }
-
-    if (routeSegment.type === 'wildcard') {
-      regExpSource += `(?:/${routeSegment.source})?`
-      continue
-    }
-
-    regExpSource += `/${routeSegment.source}`
-  }
-
-  return `${regExpSource}$`
-}
-
-function parseRoutePathSegment(segment: string) {
-  if (!segment.includes('$')) {
-    return { source: escapeRegExp(segment), type: 'pathname' as const }
-  }
-
-  if (segment === '$') {
-    return { source: '.*', type: 'wildcard' as const }
-  }
-
-  if (segment.startsWith('$')) {
-    return { source: '[^/]+', type: 'param' as const }
-  }
-
-  const openBraceIndex = segment.indexOf('{')
-  if (openBraceIndex === -1) {
-    return { source: escapeRegExp(segment), type: 'pathname' as const }
-  }
-
-  const closeBraceIndex = segment.indexOf('}', openBraceIndex)
-  if (closeBraceIndex === -1) {
-    return { source: escapeRegExp(segment), type: 'pathname' as const }
-  }
-
-  const prefix = segment.slice(0, openBraceIndex)
-  const suffix = segment.slice(closeBraceIndex + 1)
-  const token = segment.slice(openBraceIndex + 1, closeBraceIndex)
-  const source = `${escapeRegExp(prefix)}${token === '$' ? '.*' : '[^/]+'}${escapeRegExp(suffix)}`
-
-  if (token === '$') {
-    return { source, type: 'wildcard' as const }
-  }
-
-  if (token.startsWith('-$') && token.length > 2) {
-    return { source, type: 'optional-param' as const }
-  }
-
-  if (token.startsWith('$') && token.length > 1) {
-    return { source, type: 'param' as const }
-  }
-
-  return { source: escapeRegExp(segment), type: 'pathname' as const }
-}
-
-function escapeRegExp(value: string) {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-}
-
 export function uniqBy<T>(arr: Array<T>, fn: (item: T) => string) {
   const seen = new Set<string>()
   return arr.filter((item) => {
diff --git a/packages/router-core/src/index.ts b/packages/router-core/src/index.ts
index 86731b944f1..faaee8322b5 100644
--- a/packages/router-core/src/index.ts
+++ b/packages/router-core/src/index.ts
@@ -106,6 +106,7 @@ export {
   exactPathTest,
   resolvePath,
   interpolatePath,
+  routePathToRegExpSource,
 } from './path'
 export { encode, decode } from './qss'
 export { rootRouteId } from './root'
diff --git a/packages/router-core/src/path.ts b/packages/router-core/src/path.ts
index 70709e60454..1cfe92a9883 100644
--- a/packages/router-core/src/path.ts
+++ b/packages/router-core/src/path.ts
@@ -198,6 +198,58 @@ export function resolvePath({
   return result
 }
 
+/**
+ * Convert a route path template into a regular expression source that matches
+ * concrete pathnames for that route.
+ */
+export function routePathToRegExpSource(routePath: string) {
+  if (!routePath || routePath === '/') {
+    return '^/$'
+  }
+
+  let cursor = 0
+  let regExpSource = ''
+  let segment
+
+  while (cursor < routePath.length) {
+    const start = cursor
+    segment = parseSegment(routePath, start, segment)
+    const end = segment[5]
+    cursor = end + 1
+
+    if (start === end) continue
+
+    const kind = segment[0]
+
+    if (kind === SEGMENT_TYPE_PATHNAME) {
+      regExpSource += `/${escapeRegExp(routePath.substring(start, end))}`
+      continue
+    }
+
+    const prefix = routePath.substring(start, segment[1])
+    const suffix = routePath.substring(segment[4], end)
+
+    if (kind === SEGMENT_TYPE_OPTIONAL_PARAM) {
+      regExpSource += `(?:/${escapeRegExp(prefix)}[^/]+${escapeRegExp(suffix)})?`
+      continue
+    }
+
+    if (kind === SEGMENT_TYPE_WILDCARD) {
+      if (!prefix && !suffix) {
+        regExpSource += '(?:/.*)?'
+        continue
+      }
+
+      regExpSource += `/${escapeRegExp(prefix)}.*${escapeRegExp(suffix)}`
+      continue
+    }
+
+    regExpSource += `/${escapeRegExp(prefix)}[^/]+${escapeRegExp(suffix)}`
+  }
+
+  return `^${regExpSource}$`
+}
+
 /**
  * Create a pre-compiled decode config from allowed characters.
  * This should be called once at router initialization.
@@ -210,7 +262,7 @@ export function compileDecodeCharMap(
   )
   // Escape special regex characters and join with |
   const pattern = Array.from(charMap.keys())
-    .map((key) => key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+    .map((key) => escapeRegExp(key))
     .join('|')
   const regex = new RegExp(pattern, 'g')
   return (encoded: string) =>
@@ -434,3 +486,7 @@ function encodePathParam(
   const encoded = encodeURIComponent(value)
   return decoder?.(encoded) ?? encoded
 }
+
+function escapeRegExp(value: string) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
diff --git a/packages/router-core/tests/path.test.ts b/packages/router-core/tests/path.test.ts
index 1eab00f04f4..477f8d8baf4 100644
--- a/packages/router-core/tests/path.test.ts
+++ b/packages/router-core/tests/path.test.ts
@@ -4,6 +4,7 @@ import {
   exactPathTest,
   interpolatePath,
   removeTrailingSlash,
+  routePathToRegExpSource,
   resolvePath,
   trimPathLeft,
 } from '../src/path'
@@ -242,6 +243,62 @@ describe('resolvePath', () => {
   )
 })
 
+describe('routePathToRegExpSource', () => {
+  it('matches static paths', () => {
+    const pattern = new RegExp(routePathToRegExpSource('/modal'))
+
+    expect(pattern.test('/modal')).toBe(true)
+    expect(pattern.test('/billing')).toBe(false)
+  })
+
+  it('matches params', () => {
+    const pattern = new RegExp(
+      routePathToRegExpSource('/photos/$photoId/modal'),
+    )
+
+    expect(pattern.test('/photos/123/modal')).toBe(true)
+    expect(pattern.test('/photos/123')).toBe(false)
+  })
+
+  it('matches optional params with and without the segment', () => {
+    const pattern = new RegExp(
+      routePathToRegExpSource('/docs/{-$lang}/install'),
+    )
+
+    expect(pattern.test('/docs/install')).toBe(true)
+    expect(pattern.test('/docs/en/install')).toBe(true)
+    expect(pattern.test('/docs/en')).toBe(false)
+  })
+
+  it('matches wildcard segments with and without a splat', () => {
+    const pattern = new RegExp(routePathToRegExpSource('/files/$'))
+
+    expect(pattern.test('/files')).toBe(true)
+    expect(pattern.test('/files/readme.md')).toBe(true)
+    expect(pattern.test('/files/nested/path')).toBe(true)
+    expect(pattern.test('/file')).toBe(false)
+  })
+
+  it('keeps wildcard prefix and suffix segments required', () => {
+    const pattern = new RegExp(
+      routePathToRegExpSource('/docs/prefix{$}suffix'),
+    )
+
+    expect(pattern.test('/docs/prefixsuffix')).toBe(true)
+    expect(pattern.test('/docs/prefixnested/pathsuffix')).toBe(true)
+    expect(pattern.test('/docs')).toBe(false)
+  })
+
+  it('matches param segments with prefixes and suffixes', () => {
+    const pattern = new RegExp(
+      routePathToRegExpSource('/blog/prefix{$slug}suffix'),
+    )
+
+    expect(pattern.test('/blog/prefixpostsuffix')).toBe(true)
+    expect(pattern.test('/blog/prefixsuffix')).toBe(false)
+  })
+})
+
 describe.each([{ server: true }, { server: false }])(
   'interpolatePath (server: $server)',
   ({ server }) => {

From cf19c21f19a5b7b5e3ed49f2017818ceeff72f02 Mon Sep 17 00:00:00 2001
From: tmm <tmm@tmm.dev>
Date: Tue, 7 Apr 2026 22:58:23 -0400
Subject: [PATCH 3/6] refactor: move unmask-on-reload script to router-core

---
 .../react-router/src/headContentUtils.tsx     | 23 ++++---------------
 packages/router-core/src/index.ts             |  1 +
 .../src/unmask-on-reload-inline.ts            | 22 ++++++++++++++++++
 .../src/unmask-on-reload-script.ts            | 16 +++++++++++++
 .../tests/unmask-on-reload-script.test.ts     | 16 +++++++++++++
 5 files changed, 60 insertions(+), 18 deletions(-)
 create mode 100644 packages/router-core/src/unmask-on-reload-inline.ts
 create mode 100644 packages/router-core/src/unmask-on-reload-script.ts
 create mode 100644 packages/router-core/tests/unmask-on-reload-script.test.ts

diff --git a/packages/react-router/src/headContentUtils.tsx b/packages/react-router/src/headContentUtils.tsx
index ca6a34ed9e2..5fefaff124a 100644
--- a/packages/react-router/src/headContentUtils.tsx
+++ b/packages/react-router/src/headContentUtils.tsx
@@ -4,6 +4,7 @@ import {
   deepEqual,
   escapeHtml,
   getAssetCrossOrigin,
+  getUnmaskOnReloadScript,
   resolveManifestAssetLink,
   routePathToRegExpSource,
 } from '@tanstack/router-core'
@@ -432,27 +433,13 @@ function buildUnmaskOnReloadHeadScript(
 
   if (!routeMaskSources.length) return undefined
 
+  const script = getUnmaskOnReloadScript(routeMaskSources)
+  if (!script) return undefined
+
   return {
     tag: 'script',
     attrs: nonce ? { nonce } : undefined,
-    children: `
-(() => {
-  const maskedRoutePathPatterns = ${JSON.stringify(routeMaskSources)}
-    .map((source) => new RegExp(source))
-  const tempLocation = window.history.state?.__tempLocation
-  if (!tempLocation?.pathname) return
-  if (
-    tempLocation.pathname === window.location.pathname &&
-    (tempLocation.search ?? '') === window.location.search &&
-    (tempLocation.hash ?? '') === window.location.hash
-  ) return
-  if (!maskedRoutePathPatterns.some((pattern) => pattern.test(tempLocation.pathname)))
-    return
-  window.location.replace(
-    tempLocation.pathname + (tempLocation.search ?? '') + (tempLocation.hash ?? ''),
-  )
-})()
-`,
+    children: script,
   } satisfies RouterManagedTag
 }
 
diff --git a/packages/router-core/src/index.ts b/packages/router-core/src/index.ts
index faaee8322b5..38d9a59d45d 100644
--- a/packages/router-core/src/index.ts
+++ b/packages/router-core/src/index.ts
@@ -111,6 +111,7 @@ export {
 export { encode, decode } from './qss'
 export { rootRouteId } from './root'
 export type { RootRouteId } from './root'
+export { getUnmaskOnReloadScript } from './unmask-on-reload-script'
 
 export { BaseRoute, BaseRouteApi, BaseRootRoute } from './route'
 export type {
diff --git a/packages/router-core/src/unmask-on-reload-inline.ts b/packages/router-core/src/unmask-on-reload-inline.ts
new file mode 100644
index 00000000000..73c8c9eff1a
--- /dev/null
+++ b/packages/router-core/src/unmask-on-reload-inline.ts
@@ -0,0 +1,22 @@
+export default function (options: { routeMaskSources: Array<string> }) {
+  const maskedRoutePathPatterns = options.routeMaskSources.map(
+    (source) => new RegExp(source),
+  )
+  const tempLocation = window.history.state?.__tempLocation
+
+  if (!tempLocation?.pathname) return
+
+  if (
+    tempLocation.pathname === window.location.pathname &&
+    (tempLocation.search ?? '') === window.location.search &&
+    (tempLocation.hash ?? '') === window.location.hash
+  )
+    return
+
+  if (!maskedRoutePathPatterns.some((pattern) => pattern.test(tempLocation.pathname)))
+    return
+
+  window.location.replace(
+    tempLocation.pathname + (tempLocation.search ?? '') + (tempLocation.hash ?? ''),
+  )
+}
diff --git a/packages/router-core/src/unmask-on-reload-script.ts b/packages/router-core/src/unmask-on-reload-script.ts
new file mode 100644
index 00000000000..ce2bf581e60
--- /dev/null
+++ b/packages/router-core/src/unmask-on-reload-script.ts
@@ -0,0 +1,16 @@
+import minifiedUnmaskOnReloadScript from './unmask-on-reload-inline?script-string'
+import { escapeHtml } from './utils'
+
+type InlineUnmaskOnReloadScriptOptions = {
+  routeMaskSources: Array<string>
+}
+
+export function getUnmaskOnReloadScript(routeMaskSources: Array<string>) {
+  if (!routeMaskSources.length) return null
+
+  return `(${minifiedUnmaskOnReloadScript})(${escapeHtml(
+    JSON.stringify({
+      routeMaskSources,
+    } satisfies InlineUnmaskOnReloadScriptOptions),
+  )})`
+}
diff --git a/packages/router-core/tests/unmask-on-reload-script.test.ts b/packages/router-core/tests/unmask-on-reload-script.test.ts
new file mode 100644
index 00000000000..b40596dbedc
--- /dev/null
+++ b/packages/router-core/tests/unmask-on-reload-script.test.ts
@@ -0,0 +1,16 @@
+import { describe, expect, test } from 'vitest'
+import { getUnmaskOnReloadScript } from '../src'
+
+describe('getUnmaskOnReloadScript', () => {
+  test('returns null when no route mask sources are provided', () => {
+    expect(getUnmaskOnReloadScript([])).toBeNull()
+  })
+
+  test('serializes the inline unmask-on-reload script', () => {
+    const script = getUnmaskOnReloadScript(['^/modal$'])
+
+    expect(script).toContain('window.history.state?.__tempLocation')
+    expect(script).toContain('window.location.replace')
+    expect(script).toContain('"routeMaskSources":["^/modal$"]')
+  })
+})

From ba067287c19625bfc331c6db04b23ddaaec246ae Mon Sep 17 00:00:00 2001
From: tmm <tmm@tmm.dev>
Date: Tue, 7 Apr 2026 23:05:48 -0400
Subject: [PATCH 4/6] refactor: inline unmask-on-reload payload

---
 packages/router-core/src/unmask-on-reload-script.ts | 8 +-------
 1 file changed, 1 insertion(+), 7 deletions(-)

diff --git a/packages/router-core/src/unmask-on-reload-script.ts b/packages/router-core/src/unmask-on-reload-script.ts
index ce2bf581e60..70b8cc95bfb 100644
--- a/packages/router-core/src/unmask-on-reload-script.ts
+++ b/packages/router-core/src/unmask-on-reload-script.ts
@@ -1,16 +1,10 @@
 import minifiedUnmaskOnReloadScript from './unmask-on-reload-inline?script-string'
 import { escapeHtml } from './utils'
 
-type InlineUnmaskOnReloadScriptOptions = {
-  routeMaskSources: Array<string>
-}
-
 export function getUnmaskOnReloadScript(routeMaskSources: Array<string>) {
   if (!routeMaskSources.length) return null
 
   return `(${minifiedUnmaskOnReloadScript})(${escapeHtml(
-    JSON.stringify({
-      routeMaskSources,
-    } satisfies InlineUnmaskOnReloadScriptOptions),
+    JSON.stringify({ routeMaskSources }),
   )})`
 }

From b9bcdbf5eef7dd808d23b2d29150ca3844304649 Mon Sep 17 00:00:00 2001
From: tmm <tmm@tmm.dev>
Date: Wed, 8 Apr 2026 11:11:18 -0400
Subject: [PATCH 5/6] chore: changeset

---
 .changeset/calmly-fox-smiled.md               |  5 ++++
 .changeset/swiftly-otter-jumped.md            |  5 ++++
 .../react-router/src/headContentUtils.tsx     | 11 ++------
 packages/router-core/src/index.ts             |  5 +++-
 .../src/unmask-on-reload-script.ts            | 22 +++++++++++++++
 .../tests/unmask-on-reload-script.test.ts     | 27 ++++++++++++++++++-
 6 files changed, 64 insertions(+), 11 deletions(-)
 create mode 100644 .changeset/calmly-fox-smiled.md
 create mode 100644 .changeset/swiftly-otter-jumped.md

diff --git a/.changeset/calmly-fox-smiled.md b/.changeset/calmly-fox-smiled.md
new file mode 100644
index 00000000000..d7fdc713b7b
--- /dev/null
+++ b/.changeset/calmly-fox-smiled.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/react-router': patch
+---
+
+Injected `unmaskOnReload` pre-hydration script during SSR so hard reloads preserved the unmasked route.
diff --git a/.changeset/swiftly-otter-jumped.md b/.changeset/swiftly-otter-jumped.md
new file mode 100644
index 00000000000..b6b94284768
--- /dev/null
+++ b/.changeset/swiftly-otter-jumped.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/router-core': patch
+---
+
+Added helpers for building `unmaskOnReload` reload scripts and route mask match patterns. This enabled SSR hard reload recovery for masked routes.
diff --git a/packages/react-router/src/headContentUtils.tsx b/packages/react-router/src/headContentUtils.tsx
index 5fefaff124a..af068aca714 100644
--- a/packages/react-router/src/headContentUtils.tsx
+++ b/packages/react-router/src/headContentUtils.tsx
@@ -4,9 +4,8 @@ import {
   deepEqual,
   escapeHtml,
   getAssetCrossOrigin,
-  getUnmaskOnReloadScript,
+  getUnmaskOnReloadScriptFromRouteMasks,
   resolveManifestAssetLink,
-  routePathToRegExpSource,
 } from '@tanstack/router-core'
 import { isServer } from '@tanstack/router-core/isServer'
 import { useRouter } from './useRouter'
@@ -427,13 +426,7 @@ function buildUnmaskOnReloadHeadScript(
   router: ReturnType<typeof useRouter>,
   nonce: string | undefined,
 ) {
-  const routeMaskSources = (router.options.routeMasks ?? [])
-    .filter((routeMask) => routeMask.unmaskOnReload && typeof routeMask.from === 'string')
-    .map((routeMask) => routePathToRegExpSource(routeMask.from))
-
-  if (!routeMaskSources.length) return undefined
-
-  const script = getUnmaskOnReloadScript(routeMaskSources)
+  const script = getUnmaskOnReloadScriptFromRouteMasks(router.options.routeMasks)
   if (!script) return undefined
 
   return {
diff --git a/packages/router-core/src/index.ts b/packages/router-core/src/index.ts
index 38d9a59d45d..b2677d38fd4 100644
--- a/packages/router-core/src/index.ts
+++ b/packages/router-core/src/index.ts
@@ -111,7 +111,10 @@ export {
 export { encode, decode } from './qss'
 export { rootRouteId } from './root'
 export type { RootRouteId } from './root'
-export { getUnmaskOnReloadScript } from './unmask-on-reload-script'
+export {
+  getUnmaskOnReloadScript,
+  getUnmaskOnReloadScriptFromRouteMasks,
+} from './unmask-on-reload-script'
 
 export { BaseRoute, BaseRouteApi, BaseRootRoute } from './route'
 export type {
diff --git a/packages/router-core/src/unmask-on-reload-script.ts b/packages/router-core/src/unmask-on-reload-script.ts
index 70b8cc95bfb..d975a047920 100644
--- a/packages/router-core/src/unmask-on-reload-script.ts
+++ b/packages/router-core/src/unmask-on-reload-script.ts
@@ -1,6 +1,28 @@
 import minifiedUnmaskOnReloadScript from './unmask-on-reload-inline?script-string'
+import { routePathToRegExpSource } from './path'
+import type { AnyRoute, RouteMask } from './route'
 import { escapeHtml } from './utils'
 
+export function getUnmaskOnReloadScriptFromRouteMasks(
+  routeMasks?: ReadonlyArray<
+    Pick<RouteMask<AnyRoute>, 'from' | 'unmaskOnReload'>
+  >,
+) {
+  return getUnmaskOnReloadScript(
+    (routeMasks ?? [])
+      .filter(
+        (
+          routeMask,
+        ): routeMask is {
+          from: RouteMask<AnyRoute>['from']
+          unmaskOnReload: true
+        } =>
+          routeMask.unmaskOnReload === true && typeof routeMask.from === 'string',
+      )
+      .map((routeMask) => routePathToRegExpSource(routeMask.from)),
+  )
+}
+
 export function getUnmaskOnReloadScript(routeMaskSources: Array<string>) {
   if (!routeMaskSources.length) return null
 
diff --git a/packages/router-core/tests/unmask-on-reload-script.test.ts b/packages/router-core/tests/unmask-on-reload-script.test.ts
index b40596dbedc..0fe1f562d07 100644
--- a/packages/router-core/tests/unmask-on-reload-script.test.ts
+++ b/packages/router-core/tests/unmask-on-reload-script.test.ts
@@ -1,5 +1,8 @@
 import { describe, expect, test } from 'vitest'
-import { getUnmaskOnReloadScript } from '../src'
+import {
+  getUnmaskOnReloadScript,
+  getUnmaskOnReloadScriptFromRouteMasks,
+} from '../src'
 
 describe('getUnmaskOnReloadScript', () => {
   test('returns null when no route mask sources are provided', () => {
@@ -14,3 +17,25 @@ describe('getUnmaskOnReloadScript', () => {
     expect(script).toContain('"routeMaskSources":["^/modal$"]')
   })
 })
+
+describe('getUnmaskOnReloadScriptFromRouteMasks', () => {
+  test('serializes unmask-on-reload route masks into the inline script', () => {
+    const script = getUnmaskOnReloadScriptFromRouteMasks([
+      { from: '/modal', unmaskOnReload: true },
+      { from: '/ignored', unmaskOnReload: false },
+    ])
+
+    expect(script).toContain('window.history.state?.__tempLocation')
+    expect(script).toContain('window.location.replace')
+    expect(script).toContain('"routeMaskSources":["^/modal$"]')
+    expect(script).not.toContain('/ignored')
+  })
+
+  test('returns null when no route masks opt into unmask-on-reload', () => {
+    expect(
+      getUnmaskOnReloadScriptFromRouteMasks([
+        { from: '/modal', unmaskOnReload: false },
+      ]),
+    ).toBeNull()
+  })
+})

From 6d619ac76327020276b8d82fec7c9c6e7bd3941c Mon Sep 17 00:00:00 2001
From: tmm <tmm@tmm.dev>
Date: Wed, 8 Apr 2026 11:40:54 -0400
Subject: [PATCH 6/6] chore: coderabbit tweaks

---
 packages/react-router/src/headContentUtils.tsx      | 2 +-
 packages/router-core/src/unmask-on-reload-script.ts | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/react-router/src/headContentUtils.tsx b/packages/react-router/src/headContentUtils.tsx
index af068aca714..8b5d7281f49 100644
--- a/packages/react-router/src/headContentUtils.tsx
+++ b/packages/react-router/src/headContentUtils.tsx
@@ -431,7 +431,7 @@ function buildUnmaskOnReloadHeadScript(
 
   return {
     tag: 'script',
-    attrs: nonce ? { nonce } : undefined,
+    ...(nonce ? { attrs: { nonce } } : {}),
     children: script,
   } satisfies RouterManagedTag
 }
diff --git a/packages/router-core/src/unmask-on-reload-script.ts b/packages/router-core/src/unmask-on-reload-script.ts
index d975a047920..fe763a835e1 100644
--- a/packages/router-core/src/unmask-on-reload-script.ts
+++ b/packages/router-core/src/unmask-on-reload-script.ts
@@ -1,7 +1,7 @@
 import minifiedUnmaskOnReloadScript from './unmask-on-reload-inline?script-string'
 import { routePathToRegExpSource } from './path'
-import type { AnyRoute, RouteMask } from './route'
 import { escapeHtml } from './utils'
+import type { AnyRoute, RouteMask } from './route'
 
 export function getUnmaskOnReloadScriptFromRouteMasks(
   routeMasks?: ReadonlyArray<