From e0ad73196e17012fc0194990b5ab23396f5ae5b9 Mon Sep 17 00:00:00 2001
From: naoya7076 <naoya7076@gmail.com>
Date: Tue, 10 Jun 2025 21:33:01 +0900
Subject: [PATCH 1/4] fix: update state key references from 'key' to '__key'

---
 .../router/framework/react/guide/scroll-restoration.md |  4 ++--
 packages/history/src/index.ts                          | 10 +++++-----
 packages/react-router/src/Match.tsx                    |  2 +-
 packages/router-core/src/router.ts                     |  6 +++---
 packages/router-core/src/scroll-restoration.ts         |  2 +-
 packages/solid-router/src/Match.tsx                    |  2 +-
 6 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/docs/router/framework/react/guide/scroll-restoration.md b/docs/router/framework/react/guide/scroll-restoration.md
index ffc1387e10..88abd93cd2 100644
--- a/docs/router/framework/react/guide/scroll-restoration.md
+++ b/docs/router/framework/react/guide/scroll-restoration.md
@@ -71,7 +71,7 @@ Falling in behind Remix's own Scroll Restoration APIs, you can also customize th
 
 The `getKey` option receives the relevant `Location` state from TanStack Router and expects you to return a string to uniquely identify the scrollable measurements for that state.
 
-The default `getKey` is `(location) => location.state.key!`, where `key` is the unique key generated for each entry in the history.
+The default `getKey` is `(location) => location.state.__key!`, where `__key` is the unique key generated for each entry in the history.
 
 ## Examples
 
@@ -95,7 +95,7 @@ const router = createRouter({
     const paths = ['/', '/chat']
     return paths.includes(location.pathname)
       ? location.pathname
-      : location.state.key!
+      : location.state.__key!
   },
 })
 ```
diff --git a/packages/history/src/index.ts b/packages/history/src/index.ts
index 3428c41939..61b4784f6e 100644
--- a/packages/history/src/index.ts
+++ b/packages/history/src/index.ts
@@ -53,7 +53,7 @@ export interface ParsedPath {
 export interface HistoryState {}
 
 export type ParsedHistoryState = HistoryState & {
-  key?: string
+  __key?: string
   __TSR_index: number
 }
 
@@ -254,7 +254,7 @@ function assignKeyAndIndex(index: number, state: HistoryState | undefined) {
   }
   return {
     ...state,
-    key: createRandomKey(),
+    __key: createRandomKey(),
     [stateIndexKey]: index,
   } as ParsedHistoryState
 }
@@ -302,11 +302,11 @@ export function createBrowserHistory(opts?: {
       ))
 
   // Ensure there is always a key to start
-  if (!win.history.state?.key) {
+  if (!win.history.state?.__key) {
     win.history.replaceState(
       {
         [stateIndexKey]: 0,
-        key: createRandomKey(),
+        __key: createRandomKey(),
       },
       '',
     )
@@ -632,7 +632,7 @@ export function parseHref(
       searchIndex > -1
         ? href.slice(searchIndex, hashIndex === -1 ? undefined : hashIndex)
         : '',
-    state: state || { [stateIndexKey]: 0, key: createRandomKey() },
+    state: state || { [stateIndexKey]: 0, __key: createRandomKey() },
   }
 }
 
diff --git a/packages/react-router/src/Match.tsx b/packages/react-router/src/Match.tsx
index 79dd4ed01a..efc9dff395 100644
--- a/packages/react-router/src/Match.tsx
+++ b/packages/react-router/src/Match.tsx
@@ -139,7 +139,7 @@ function OnRendered() {
 
   return (
     <script
-      key={router.latestLocation.state.key}
+      key={router.latestLocation.state.__key}
       suppressHydrationWarning
       ref={(el) => {
         if (
diff --git a/packages/router-core/src/router.ts b/packages/router-core/src/router.ts
index ed2fb689b7..4a2f06faf2 100644
--- a/packages/router-core/src/router.ts
+++ b/packages/router-core/src/router.ts
@@ -1102,7 +1102,7 @@ export class RouterCore<
     if (__tempLocation && (!__tempKey || __tempKey === this.tempLocationKey)) {
       // Sync up the location keys
       const parsedTempLocation = parse(__tempLocation) as any
-      parsedTempLocation.state.key = location.state.key
+      parsedTempLocation.state.__key = location.state.__key
 
       delete parsedTempLocation.state.__tempLocation
 
@@ -1823,7 +1823,7 @@ export class RouterCore<
       // temporarily add the previous values to the next state so they don't affect
       // the comparison
       const ignoredProps = [
-        'key',
+        '__key',
         '__TSR_index',
         '__hashScrollIntoViewOptions',
       ] as const
@@ -1864,7 +1864,7 @@ export class RouterCore<
                 ...nextHistory.state,
                 __tempKey: undefined!,
                 __tempLocation: undefined!,
-                key: undefined!,
+                __key: undefined!,
               },
             },
           },
diff --git a/packages/router-core/src/scroll-restoration.ts b/packages/router-core/src/scroll-restoration.ts
index 280df14e6a..e88b9781c0 100644
--- a/packages/router-core/src/scroll-restoration.ts
+++ b/packages/router-core/src/scroll-restoration.ts
@@ -79,7 +79,7 @@ export const scrollRestorationCache = createScrollRestorationCache()
  */
 
 export const defaultGetScrollRestorationKey = (location: ParsedLocation) => {
-  return location.state.key! || location.href
+  return location.state.__key! || location.href
 }
 
 export function getCssSelector(el: any): string {
diff --git a/packages/solid-router/src/Match.tsx b/packages/solid-router/src/Match.tsx
index e4d6dc91e3..2d18bf7938 100644
--- a/packages/solid-router/src/Match.tsx
+++ b/packages/solid-router/src/Match.tsx
@@ -140,7 +140,7 @@ function OnRendered() {
 
   const location = useRouterState({
     select: (s) => {
-      return s.resolvedLocation?.state.key
+      return s.resolvedLocation?.state.__key
     },
   })
   Solid.createEffect(

From 0245d3734c5a3b835e43a48f6021c08f07d6d651 Mon Sep 17 00:00:00 2001
From: naoya7076 <naoya7076@gmail.com>
Date: Tue, 10 Jun 2025 22:28:24 +0900
Subject: [PATCH 2/4] Rename 'key' in markdown and comments to __key

---
 .../router/framework/react/api/router/ParsedHistoryStateType.md | 2 +-
 packages/react-router/src/Match.tsx                             | 2 +-
 packages/solid-router/src/Match.tsx                             | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/router/framework/react/api/router/ParsedHistoryStateType.md b/docs/router/framework/react/api/router/ParsedHistoryStateType.md
index acf76739a8..73600ad1bf 100644
--- a/docs/router/framework/react/api/router/ParsedHistoryStateType.md
+++ b/docs/router/framework/react/api/router/ParsedHistoryStateType.md
@@ -7,7 +7,7 @@ The `ParsedHistoryState` type represents a parsed state object. Additionally to
 
 ```tsx
 export type ParsedHistoryState = HistoryState & {
-  key?: string
+  __key?: string
   __TSR_index: number
 }
 ```
diff --git a/packages/react-router/src/Match.tsx b/packages/react-router/src/Match.tsx
index efc9dff395..bd303223ad 100644
--- a/packages/react-router/src/Match.tsx
+++ b/packages/react-router/src/Match.tsx
@@ -126,7 +126,7 @@ export const Match = React.memo(function MatchImpl({
 // On Rendered can't happen above the root layout because it actually
 // renders a dummy dom element to track the rendered state of the app.
 // We render a script tag with a key that changes based on the current
-// location state.key. Also, because it's below the root layout, it
+// location state.__key. Also, because it's below the root layout, it
 // allows us to fire onRendered events even after a hydration mismatch
 // error that occurred above the root layout (like bad head/link tags,
 // which is common).
diff --git a/packages/solid-router/src/Match.tsx b/packages/solid-router/src/Match.tsx
index 2d18bf7938..3dbb120e77 100644
--- a/packages/solid-router/src/Match.tsx
+++ b/packages/solid-router/src/Match.tsx
@@ -131,7 +131,7 @@ export const Match = (props: { matchId: string }) => {
 // On Rendered can't happen above the root layout because it actually
 // renders a dummy dom element to track the rendered state of the app.
 // We render a script tag with a key that changes based on the current
-// location state.key. Also, because it's below the root layout, it
+// location state.__key. Also, because it's below the root layout, it
 // allows us to fire onRendered events even after a hydration mismatch
 // error that occurred above the root layout (like bad head/link tags,
 // which is common).

From 95719dcaa097aa96cf870929b87ef444b62b9e8b Mon Sep 17 00:00:00 2001
From: naoya7076 <naoya7076@gmail.com>
Date: Fri, 13 Jun 2025 14:36:36 +0900
Subject: [PATCH 3/4] fix: rename '__key' to '__TSR_key' in ParsedHistoryState
 and related references

---
 .../react/api/router/ParsedHistoryStateType.md         |  2 +-
 .../router/framework/react/guide/scroll-restoration.md |  4 ++--
 packages/history/src/index.ts                          | 10 +++++-----
 packages/react-router/src/Match.tsx                    |  4 ++--
 packages/router-core/src/router.ts                     |  6 +++---
 packages/router-core/src/scroll-restoration.ts         |  2 +-
 packages/solid-router/src/Match.tsx                    |  4 ++--
 7 files changed, 16 insertions(+), 16 deletions(-)

diff --git a/docs/router/framework/react/api/router/ParsedHistoryStateType.md b/docs/router/framework/react/api/router/ParsedHistoryStateType.md
index 73600ad1bf..130085c6f6 100644
--- a/docs/router/framework/react/api/router/ParsedHistoryStateType.md
+++ b/docs/router/framework/react/api/router/ParsedHistoryStateType.md
@@ -7,7 +7,7 @@ The `ParsedHistoryState` type represents a parsed state object. Additionally to
 
 ```tsx
 export type ParsedHistoryState = HistoryState & {
-  __key?: string
+  __TSR_key?: string
   __TSR_index: number
 }
 ```
diff --git a/docs/router/framework/react/guide/scroll-restoration.md b/docs/router/framework/react/guide/scroll-restoration.md
index 88abd93cd2..da9f3d4bf5 100644
--- a/docs/router/framework/react/guide/scroll-restoration.md
+++ b/docs/router/framework/react/guide/scroll-restoration.md
@@ -71,7 +71,7 @@ Falling in behind Remix's own Scroll Restoration APIs, you can also customize th
 
 The `getKey` option receives the relevant `Location` state from TanStack Router and expects you to return a string to uniquely identify the scrollable measurements for that state.
 
-The default `getKey` is `(location) => location.state.__key!`, where `__key` is the unique key generated for each entry in the history.
+The default `getKey` is `(location) => location.state.__TSR_key!`, where `__TSR_key` is the unique key generated for each entry in the history.
 
 ## Examples
 
@@ -95,7 +95,7 @@ const router = createRouter({
     const paths = ['/', '/chat']
     return paths.includes(location.pathname)
       ? location.pathname
-      : location.state.__key!
+      : location.state.__TSR_key!
   },
 })
 ```
diff --git a/packages/history/src/index.ts b/packages/history/src/index.ts
index 61b4784f6e..cc640fc27e 100644
--- a/packages/history/src/index.ts
+++ b/packages/history/src/index.ts
@@ -53,7 +53,7 @@ export interface ParsedPath {
 export interface HistoryState {}
 
 export type ParsedHistoryState = HistoryState & {
-  __key?: string
+  __TSR_key?: string
   __TSR_index: number
 }
 
@@ -254,7 +254,7 @@ function assignKeyAndIndex(index: number, state: HistoryState | undefined) {
   }
   return {
     ...state,
-    __key: createRandomKey(),
+    __TSR_key: createRandomKey(),
     [stateIndexKey]: index,
   } as ParsedHistoryState
 }
@@ -302,11 +302,11 @@ export function createBrowserHistory(opts?: {
       ))
 
   // Ensure there is always a key to start
-  if (!win.history.state?.__key) {
+  if (!win.history.state?.__TSR_key) {
     win.history.replaceState(
       {
         [stateIndexKey]: 0,
-        __key: createRandomKey(),
+        __TSR_key: createRandomKey(),
       },
       '',
     )
@@ -632,7 +632,7 @@ export function parseHref(
       searchIndex > -1
         ? href.slice(searchIndex, hashIndex === -1 ? undefined : hashIndex)
         : '',
-    state: state || { [stateIndexKey]: 0, __key: createRandomKey() },
+    state: state || { [stateIndexKey]: 0, __TSR_key: createRandomKey() },
   }
 }
 
diff --git a/packages/react-router/src/Match.tsx b/packages/react-router/src/Match.tsx
index bd303223ad..1f6c03daf9 100644
--- a/packages/react-router/src/Match.tsx
+++ b/packages/react-router/src/Match.tsx
@@ -126,7 +126,7 @@ export const Match = React.memo(function MatchImpl({
 // On Rendered can't happen above the root layout because it actually
 // renders a dummy dom element to track the rendered state of the app.
 // We render a script tag with a key that changes based on the current
-// location state.__key. Also, because it's below the root layout, it
+// location state.__TSR_key. Also, because it's below the root layout, it
 // allows us to fire onRendered events even after a hydration mismatch
 // error that occurred above the root layout (like bad head/link tags,
 // which is common).
@@ -139,7 +139,7 @@ function OnRendered() {
 
   return (
     <script
-      key={router.latestLocation.state.__key}
+      key={router.latestLocation.state.__TSR_key}
       suppressHydrationWarning
       ref={(el) => {
         if (
diff --git a/packages/router-core/src/router.ts b/packages/router-core/src/router.ts
index 4a2f06faf2..a88f7707ba 100644
--- a/packages/router-core/src/router.ts
+++ b/packages/router-core/src/router.ts
@@ -1102,7 +1102,7 @@ export class RouterCore<
     if (__tempLocation && (!__tempKey || __tempKey === this.tempLocationKey)) {
       // Sync up the location keys
       const parsedTempLocation = parse(__tempLocation) as any
-      parsedTempLocation.state.__key = location.state.__key
+      parsedTempLocation.state.__TSR_key = location.state.__TSR_key
 
       delete parsedTempLocation.state.__tempLocation
 
@@ -1823,7 +1823,7 @@ export class RouterCore<
       // temporarily add the previous values to the next state so they don't affect
       // the comparison
       const ignoredProps = [
-        '__key',
+        '__TSR_key',
         '__TSR_index',
         '__hashScrollIntoViewOptions',
       ] as const
@@ -1864,7 +1864,7 @@ export class RouterCore<
                 ...nextHistory.state,
                 __tempKey: undefined!,
                 __tempLocation: undefined!,
-                __key: undefined!,
+                __TSR_key: undefined!,
               },
             },
           },
diff --git a/packages/router-core/src/scroll-restoration.ts b/packages/router-core/src/scroll-restoration.ts
index e88b9781c0..39cb6d29ff 100644
--- a/packages/router-core/src/scroll-restoration.ts
+++ b/packages/router-core/src/scroll-restoration.ts
@@ -79,7 +79,7 @@ export const scrollRestorationCache = createScrollRestorationCache()
  */
 
 export const defaultGetScrollRestorationKey = (location: ParsedLocation) => {
-  return location.state.__key! || location.href
+  return location.state.__TSR_key! || location.href
 }
 
 export function getCssSelector(el: any): string {
diff --git a/packages/solid-router/src/Match.tsx b/packages/solid-router/src/Match.tsx
index 3dbb120e77..17074db782 100644
--- a/packages/solid-router/src/Match.tsx
+++ b/packages/solid-router/src/Match.tsx
@@ -131,7 +131,7 @@ export const Match = (props: { matchId: string }) => {
 // On Rendered can't happen above the root layout because it actually
 // renders a dummy dom element to track the rendered state of the app.
 // We render a script tag with a key that changes based on the current
-// location state.__key. Also, because it's below the root layout, it
+// location state.__TSR_key. Also, because it's below the root layout, it
 // allows us to fire onRendered events even after a hydration mismatch
 // error that occurred above the root layout (like bad head/link tags,
 // which is common).
@@ -140,7 +140,7 @@ function OnRendered() {
 
   const location = useRouterState({
     select: (s) => {
-      return s.resolvedLocation?.state.__key
+      return s.resolvedLocation?.state.__TSR_key
     },
   })
   Solid.createEffect(

From d98bd9b8deb7a79c8b9c38f9011d50b2812777dd Mon Sep 17 00:00:00 2001
From: naoya7076 <naoya7076@gmail.com>
Date: Fri, 13 Jun 2025 22:36:34 +0900
Subject: [PATCH 4/4] feat: support both `key` and `__TSR_key` properties

---
 .../react/api/router/ParsedHistoryStateType.md   |  1 +
 .../framework/react/guide/scroll-restoration.md  |  4 ++--
 packages/history/src/index.ts                    | 16 ++++++++++++----
 packages/react-router/src/Match.tsx              |  4 ++--
 packages/router-core/src/router.ts               |  3 +++
 packages/router-core/src/scroll-restoration.ts   |  2 +-
 packages/solid-router/src/Match.tsx              |  4 ++--
 7 files changed, 23 insertions(+), 11 deletions(-)

diff --git a/docs/router/framework/react/api/router/ParsedHistoryStateType.md b/docs/router/framework/react/api/router/ParsedHistoryStateType.md
index 130085c6f6..bbc398e7a2 100644
--- a/docs/router/framework/react/api/router/ParsedHistoryStateType.md
+++ b/docs/router/framework/react/api/router/ParsedHistoryStateType.md
@@ -7,6 +7,7 @@ The `ParsedHistoryState` type represents a parsed state object. Additionally to
 
 ```tsx
 export type ParsedHistoryState = HistoryState & {
+  key?: string // TODO: Remove in v2 - use __TSR_key instead
   __TSR_key?: string
   __TSR_index: number
 }
diff --git a/docs/router/framework/react/guide/scroll-restoration.md b/docs/router/framework/react/guide/scroll-restoration.md
index da9f3d4bf5..ffc1387e10 100644
--- a/docs/router/framework/react/guide/scroll-restoration.md
+++ b/docs/router/framework/react/guide/scroll-restoration.md
@@ -71,7 +71,7 @@ Falling in behind Remix's own Scroll Restoration APIs, you can also customize th
 
 The `getKey` option receives the relevant `Location` state from TanStack Router and expects you to return a string to uniquely identify the scrollable measurements for that state.
 
-The default `getKey` is `(location) => location.state.__TSR_key!`, where `__TSR_key` is the unique key generated for each entry in the history.
+The default `getKey` is `(location) => location.state.key!`, where `key` is the unique key generated for each entry in the history.
 
 ## Examples
 
@@ -95,7 +95,7 @@ const router = createRouter({
     const paths = ['/', '/chat']
     return paths.includes(location.pathname)
       ? location.pathname
-      : location.state.__TSR_key!
+      : location.state.key!
   },
 })
 ```
diff --git a/packages/history/src/index.ts b/packages/history/src/index.ts
index cc640fc27e..c33ee24feb 100644
--- a/packages/history/src/index.ts
+++ b/packages/history/src/index.ts
@@ -53,6 +53,7 @@ export interface ParsedPath {
 export interface HistoryState {}
 
 export type ParsedHistoryState = HistoryState & {
+  key?: string // TODO: Remove in v2 - use __TSR_key instead
   __TSR_key?: string
   __TSR_index: number
 }
@@ -252,9 +253,11 @@ function assignKeyAndIndex(index: number, state: HistoryState | undefined) {
   if (!state) {
     state = {} as HistoryState
   }
+  const key = createRandomKey()
   return {
     ...state,
-    __TSR_key: createRandomKey(),
+    key, // TODO: Remove in v2 - use __TSR_key instead
+    __TSR_key: key,
     [stateIndexKey]: index,
   } as ParsedHistoryState
 }
@@ -302,11 +305,13 @@ export function createBrowserHistory(opts?: {
       ))
 
   // Ensure there is always a key to start
-  if (!win.history.state?.__TSR_key) {
+  if (!win.history.state?.__TSR_key && !win.history.state?.key) {
+    const key = createRandomKey()
     win.history.replaceState(
       {
         [stateIndexKey]: 0,
-        __TSR_key: createRandomKey(),
+        key, // TODO: Remove in v2 - use __TSR_key instead
+        __TSR_key: key,
       },
       '',
     )
@@ -632,7 +637,10 @@ export function parseHref(
       searchIndex > -1
         ? href.slice(searchIndex, hashIndex === -1 ? undefined : hashIndex)
         : '',
-    state: state || { [stateIndexKey]: 0, __TSR_key: createRandomKey() },
+    state: state || (() => {
+      const key = createRandomKey()
+      return { [stateIndexKey]: 0, key, __TSR_key: key } // TODO: Remove key in v2 - use __TSR_key instead
+    })(),
   }
 }
 
diff --git a/packages/react-router/src/Match.tsx b/packages/react-router/src/Match.tsx
index 1f6c03daf9..79dd4ed01a 100644
--- a/packages/react-router/src/Match.tsx
+++ b/packages/react-router/src/Match.tsx
@@ -126,7 +126,7 @@ export const Match = React.memo(function MatchImpl({
 // On Rendered can't happen above the root layout because it actually
 // renders a dummy dom element to track the rendered state of the app.
 // We render a script tag with a key that changes based on the current
-// location state.__TSR_key. Also, because it's below the root layout, it
+// location state.key. Also, because it's below the root layout, it
 // allows us to fire onRendered events even after a hydration mismatch
 // error that occurred above the root layout (like bad head/link tags,
 // which is common).
@@ -139,7 +139,7 @@ function OnRendered() {
 
   return (
     <script
-      key={router.latestLocation.state.__TSR_key}
+      key={router.latestLocation.state.key}
       suppressHydrationWarning
       ref={(el) => {
         if (
diff --git a/packages/router-core/src/router.ts b/packages/router-core/src/router.ts
index a88f7707ba..aafd3e8903 100644
--- a/packages/router-core/src/router.ts
+++ b/packages/router-core/src/router.ts
@@ -1102,6 +1102,7 @@ export class RouterCore<
     if (__tempLocation && (!__tempKey || __tempKey === this.tempLocationKey)) {
       // Sync up the location keys
       const parsedTempLocation = parse(__tempLocation) as any
+      parsedTempLocation.state.key = location.state.key // TODO: Remove in v2 - use __TSR_key instead
       parsedTempLocation.state.__TSR_key = location.state.__TSR_key
 
       delete parsedTempLocation.state.__tempLocation
@@ -1823,6 +1824,7 @@ export class RouterCore<
       // temporarily add the previous values to the next state so they don't affect
       // the comparison
       const ignoredProps = [
+        'key', // TODO: Remove in v2 - use __TSR_key instead
         '__TSR_key',
         '__TSR_index',
         '__hashScrollIntoViewOptions',
@@ -1865,6 +1867,7 @@ export class RouterCore<
                 __tempKey: undefined!,
                 __tempLocation: undefined!,
                 __TSR_key: undefined!,
+                key: undefined!, // TODO: Remove in v2 - use __TSR_key instead
               },
             },
           },
diff --git a/packages/router-core/src/scroll-restoration.ts b/packages/router-core/src/scroll-restoration.ts
index 39cb6d29ff..280df14e6a 100644
--- a/packages/router-core/src/scroll-restoration.ts
+++ b/packages/router-core/src/scroll-restoration.ts
@@ -79,7 +79,7 @@ export const scrollRestorationCache = createScrollRestorationCache()
  */
 
 export const defaultGetScrollRestorationKey = (location: ParsedLocation) => {
-  return location.state.__TSR_key! || location.href
+  return location.state.key! || location.href
 }
 
 export function getCssSelector(el: any): string {
diff --git a/packages/solid-router/src/Match.tsx b/packages/solid-router/src/Match.tsx
index 17074db782..e4d6dc91e3 100644
--- a/packages/solid-router/src/Match.tsx
+++ b/packages/solid-router/src/Match.tsx
@@ -131,7 +131,7 @@ export const Match = (props: { matchId: string }) => {
 // On Rendered can't happen above the root layout because it actually
 // renders a dummy dom element to track the rendered state of the app.
 // We render a script tag with a key that changes based on the current
-// location state.__TSR_key. Also, because it's below the root layout, it
+// location state.key. Also, because it's below the root layout, it
 // allows us to fire onRendered events even after a hydration mismatch
 // error that occurred above the root layout (like bad head/link tags,
 // which is common).
@@ -140,7 +140,7 @@ function OnRendered() {
 
   const location = useRouterState({
     select: (s) => {
-      return s.resolvedLocation?.state.__TSR_key
+      return s.resolvedLocation?.state.key
     },
   })
   Solid.createEffect(