@octanejs/tanstack-router 0.1.9 → 0.1.11

package/src/Match.tsrx

@@ -24,6 +24,8 @@ import {
 	isNotFound,
 	rootRouteId,
 } from '@tanstack/router-core';
+import type { NotFoundError, ParsedLocation, RootRouteOptions } from '@tanstack/router-core';
+import type { ErrorInfo, ErrorRouteComponent } from './route.ts';
 import { useStore } from './useStore.ts';
 import { useRouter, matchContext } from './context.ts';
 import { Outlet } from './Outlet.tsrx';
@@ -31,13 +33,26 @@ import { RouteNotFound } from './RouteNotFound.tsrx';
 import { CatchBoundary, ErrorComponent } from './CatchBoundary.tsrx';
 import { CatchNotFound } from './not-found.tsrx';
 import { SafeFragment } from './SafeFragment.tsrx';
+import { ClientOnly } from './ClientOnly.tsrx';
+import { ScrollRestorationScript } from './scroll-restoration.tsrx';
 
-export function Match(props) @{
+export function Match(props: { matchId: string }) @{
 	const router = useRouter();
-	const matchStore = router.stores.matchStores.get(props.matchId);
-	const resetKey = useStore(router.stores.loadedAt, (l) => l);
-	const routeId = useStore(matchStore, (m) => m.routeId);
-	const route = router.routesById[routeId];
+	const matchStore = router.stores.matchStores.get(props.matchId)!;
+	const resetKey = useStore(router.stores.loadedAt, (l: any) => l as number | string);
+	const matchState = useStore(
+		matchStore,
+		(m: any) => ({
+			routeId: m.routeId,
+			ssr: m.ssr,
+			_displayPending: m._displayPending,
+		}),
+		(previous, next) =>
+			previous.routeId === next.routeId && previous.ssr === next.ssr &&
+				previous._displayPending === next._displayPending,
+	);
+	const routeId = matchState.routeId as string;
+	const route = (router.routesById as Record<string, any>)[routeId];
 
 	const PendingComponent = route.options.pendingComponent ?? router.options.defaultPendingComponent;
 	const routeErrorComponent = route.options.errorComponent ?? router.options.defaultErrorComponent;
@@ -45,17 +60,23 @@ export function Match(props) @{
 	const routeNotFoundComponent = route.isRoot
 		? route.options.notFoundComponent ?? router.options.notFoundRoute?.options.component
 		: route.options.notFoundComponent;
+	const resolvedNoSsr = matchState.ssr === false || matchState.ssr === 'data-only';
 
 	// Boundary presence, per upstream MatchView. The root route only gets a
 	// Suspense boundary when explicitly opted in via wrapInSuspense.
+	const suspenseSignal =
+		route.options.wrapInSuspense ?? PendingComponent ??
+			(routeErrorComponent as ErrorRouteComponent | undefined)?.preload;
 	const SuspenseWrap =
-		(!route.isRoot || route.options.wrapInSuspense) &&
-		(route.options.wrapInSuspense ?? PendingComponent ?? routeErrorComponent?.preload)
+		(!route.isRoot || route.options.wrapInSuspense || resolvedNoSsr) &&
+		(suspenseSignal || resolvedNoSsr)
 			? Suspense
 			: SafeFragment;
 	const CatchWrap = routeErrorComponent ? CatchBoundary : SafeFragment;
 	const NotFoundWrap = routeNotFoundComponent ? CatchNotFound : SafeFragment;
-	const ShellComponent = route.isRoot ? route.options.shellComponent ?? SafeFragment : SafeFragment;
+	const ShellComponent = route.isRoot
+		? (route.options as RootRouteOptions).shellComponent ?? SafeFragment
+		: SafeFragment;
 
 	const pendingElement =
 		PendingComponent ? createElement(PendingComponent, {}) : null;
@@ -67,17 +88,17 @@ export function Match(props) @{
 				<CatchWrap
 					getResetKey={() => resetKey}
 					errorComponent={routeErrorComponent || ErrorComponent}
-					onCatch={(error, errorInfo) => {
+					onCatch={(error: Error, errorInfo: ErrorInfo) => {
 						if (isNotFound(error)) {
-							error.routeId ??= routeId;
+							(error as any).routeId ??= routeId;
 							throw error;
 						}
 						if (routeOnCatch) routeOnCatch(error, errorInfo);
 					}}
 				>
 					<NotFoundWrap
-						fallback={(error) => {
-							error.routeId ??= routeId;
+						fallback={(error: NotFoundError) => {
+							(error as any).routeId ??= routeId;
 
 							if (
 								!routeNotFoundComponent || error.routeId && error.routeId !== routeId ||
@@ -85,38 +106,49 @@ export function Match(props) @{
 							) {
 								throw error;
 							}
-							return createElement(routeNotFoundComponent, error);
+							return createElement(routeNotFoundComponent, error as any);
 						}}
 					>
-						<MatchInner matchId={props.matchId} />
+						@if (resolvedNoSsr || matchState._displayPending) {
+							<ClientOnly fallback={pendingElement}>
+								<MatchInner matchId={props.matchId} />
+							</ClientOnly>
+						} @else {
+							<MatchInner matchId={props.matchId} />
+						}
 					</NotFoundWrap>
 				</CatchWrap>
 			</SuspenseWrap>
 		</matchContext.Provider>
 		@if (parentRouteId === rootRouteId) {
-			<OnRendered />
+			<>
+				<OnRendered />
+				@if (router.options.scrollRestoration) {
+					<ScrollRestorationScript />
+				}
+			</>
 		}
 	</ShellComponent>
 }
 
-function MatchInner(props) {
+function MatchInner(props: { matchId: string }) {
 	const router = useRouter();
-	const matchStore = router.stores.matchStores.get(props.matchId);
-	const match = useStore(matchStore, (m) => m);
-	const routeId = match.routeId;
-	const route = router.routesById[routeId];
+	const matchStore = router.stores.matchStores.get(props.matchId)!;
+	const match = useStore(matchStore, (m: any) => m);
+	const routeId = match.routeId as string;
+	const route = (router.routesById as Record<string, any>)[routeId];
 
 	// The live match in the router (if still mounted there) wins over the
 	// snapshot for promise lookups, per upstream getMatchPromise.
-	const getMatchPromise = (key) => router.getMatch(match.id)?._nonReactive[key] ??
-		match._nonReactive[key];
+	const getMatchPromise = (key: 'displayPendingPromise' | 'minPendingPromise' | 'loadPromise') =>
+		router.getMatch(match.id)?._nonReactive[key] ?? match._nonReactive[key];
 
 	if (match._displayPending) {
-		use(getMatchPromise('displayPendingPromise'));
+		use(getMatchPromise('displayPendingPromise')!);
 	}
 
 	if (match._forcePending) {
-		use(getMatchPromise('minPendingPromise'));
+		use(getMatchPromise('minPendingPromise')!);
 	}
 
 	if (match.status === 'pending') {
@@ -125,7 +157,7 @@ function MatchInner(props) {
 		if (pendingMinMs) {
 			const routerMatch = router.getMatch(match.id);
 			if (routerMatch && !routerMatch._nonReactive.minPendingPromise) {
-				const minPendingPromise = createControlledPromise();
+				const minPendingPromise = createControlledPromise<void>();
 				routerMatch._nonReactive.minPendingPromise = minPendingPromise;
 				setTimeout(() => {
 					minPendingPromise.resolve();
@@ -133,7 +165,7 @@ function MatchInner(props) {
 				}, pendingMinMs);
 			}
 		}
-		use(getMatchPromise('loadPromise'));
+		use(getMatchPromise('loadPromise')!);
 	}
 
 	if (match.status === 'notFound') {
@@ -143,7 +175,7 @@ function MatchInner(props) {
 	if (match.status === 'redirected') {
 		// Observed mid-transition while a redirect is in flight — suspend on the
 		// load so this stale render is abandoned and the redirect completes.
-		use(getMatchPromise('loadPromise'));
+		use(getMatchPromise('loadPromise')!);
 	}
 
 	if (match.status === 'error') {
@@ -174,10 +206,10 @@ function MatchInner(props) {
 // `resolvedLocation` to the new location.
 function OnRendered() @{
 	const router = useRouter();
-	const prevResolvedLocationRef = useRef(undefined);
+	const prevResolvedLocationRef = useRef<ParsedLocation<any> | undefined>(undefined);
 	const renderedLocationKey = useStore(
 		router.stores.resolvedLocation,
-		(loc) => loc?.state.__TSR_key,
+		(loc: ParsedLocation<any> | undefined) => loc?.state.__TSR_key,
 	);
 
 	useLayoutEffect(() => {

package/src/MatchRoute.tsrx

@@ -11,13 +11,16 @@ import { useStore } from './useStore.ts';
 export function useMatchRoute() {
 	const router = useRouter();
 	useStore(router.stores.matchRouteDeps, (d) => d);
-	return useCallback((opts) => {
+	return useCallback((opts: Record<string, any>) => {
 		const { pending, caseSensitive, fuzzy, includeSearch, ...rest } = opts;
-		return router.matchRoute(rest, { pending, caseSensitive, fuzzy, includeSearch });
+		return router.matchRoute(rest as any, { pending, caseSensitive, fuzzy, includeSearch });
 	}, [router]);
 }
 
-export function MatchRoute(props) @{
+// Props are permissive (`Record<string, any>` + optional render-prop children) —
+// upstream's MakeMatchRouteOptions generics are the type-safe facade; the octane
+// binding keeps the loose v1 surface (see Link).
+export function MatchRoute(props: Record<string, any>) @{
 	const matchRoute = useMatchRoute();
 	const params = matchRoute(props);
 	const out =

package/src/Matches.tsrx

@@ -1,7 +1,7 @@
-// Renders the navigation engine + the match tree root — port of react-router's
+// Runs the navigation engine and renders the match tree root — port of react-router's
 // Matches.tsx. Structure mirrors upstream:
 //
-//   InnerWrap? > Suspense(root pending) > Transitioner + MatchesInner
+//   useTransitioner + InnerWrap? > Suspense(root pending) > MatchesInner
 //   MatchesInner: matchContext(firstId) > global CatchBoundary? > Match(firstId)
 //
 // The root Suspense is ALWAYS present on the client (fallback is the root
@@ -14,14 +14,14 @@ import { useLayoutEffect, createElement, Suspense } from 'octane';
 import { setupScrollRestoration, rootRouteId } from '@tanstack/router-core';
 import { useStore } from './useStore.ts';
 import { useRouter, matchContext } from './context.ts';
-import { Transitioner } from './Transitioner.tsrx';
+import { useTransitioner } from './Transitioner.tsrx';
 import { Match } from './Match.tsrx';
 import { CatchBoundary, ErrorComponent } from './CatchBoundary.tsrx';
 import { SafeFragment } from './SafeFragment.tsrx';
 
 export function Matches() @{
 	const router = useRouter();
-	const rootRoute = router.routesById[rootRouteId];
+	const rootRoute = (router.routesById as any)[rootRouteId];
 	const PendingComponent =
 		rootRoute.options.pendingComponent ?? router.options.defaultPendingComponent;
 	const pendingElement =
@@ -33,10 +33,10 @@ export function Matches() @{
 	useLayoutEffect(() => {
 		if (router.options.scrollRestoration) setupScrollRestoration(router);
 	}, [router]);
+	useTransitioner();
 
 	<InnerWrap>
 		<Suspense fallback={pendingElement}>
-			<Transitioner />
 			<MatchesInner />
 		</Suspense>
 	</InnerWrap>
@@ -44,8 +44,8 @@ export function Matches() @{
 
 function MatchesInner() @{
 	const router = useRouter();
-	const matchId = useStore(router.stores.firstId, (id) => id);
-	const resetKey = useStore(router.stores.loadedAt, (l) => l);
+	const matchId = useStore(router.stores.firstId, (id: any) => id as string | undefined);
+	const resetKey = useStore(router.stores.loadedAt, (l: any) => l as number | string);
 	const CatchWrap = router.options.disableGlobalCatchBoundary ? SafeFragment : CatchBoundary;
 
 	<matchContext.Provider value={matchId}>

package/src/Navigate.tsrx

@@ -1,8 +1,9 @@
 // Imperative navigation as a component: navigates once on mount, renders nothing.
 import { useLayoutEffect, useRef } from 'octane';
+import type { NavigateOptions } from '@tanstack/router-core';
 import { useNavigate } from './hooks.ts';
 
-export function Navigate(props) @{
+export function Navigate(props: NavigateOptions) @{
 	const navigate = useNavigate();
 	const done = useRef(false);
 

package/src/Outlet.tsrx

@@ -19,11 +19,13 @@ import { SafeFragment } from './SafeFragment.tsrx';
 
 export function Outlet() @{
 	const router = useRouter();
-	const parentId = useContext(matchContext);
-	const parentStore = router.stores.matchStores.get(parentId);
-	const parentRouteId = useStore(parentStore, (m) => m?.routeId);
-	const globalNotFound = useStore(parentStore, (m) => m?.globalNotFound ?? false);
-	const childId = useStore(router.stores.matchesId, (ids) => {
+	// Outlet only renders inside a match's component, so the context id (and its
+	// pooled store) are present — same invariant upstream asserts with invariant().
+	const parentId = useContext(matchContext)!;
+	const parentStore = router.stores.matchStores.get(parentId)!;
+	const parentRouteId = useStore(parentStore, (m: any) => m?.routeId as string | undefined);
+	const globalNotFound = useStore(parentStore, (m: any) => m?.globalNotFound ?? false as boolean);
+	const childId = useStore(router.stores.matchesId, (ids: Array<string>) => {
 		const i = ids.indexOf(parentId);
 		return i >= 0 ? ids[i + 1] : undefined;
 	});
@@ -38,7 +40,7 @@ export function Outlet() @{
 		DefaultPending ? createElement(DefaultPending, {}) : null;
 
 	@if (globalNotFound) {
-		<RouteNotFound routeId={parentRouteId} />
+		<RouteNotFound routeId={parentRouteId!} />
 	} @else {
 		@if (childId) {
 			<RootSuspense fallback={pendingElement}>

package/src/RouteNotFound.tsrx

@@ -10,9 +10,9 @@
 // `notFound({ data })` payload arrives as the `data` prop.
 import { useRouter } from './context.ts';
 
-export function RouteNotFound(props) @{
+export function RouteNotFound(props: { routeId: string; error?: any }) @{
 	const router = useRouter();
-	const route = router.routesById[props.routeId];
+	const route = (router.routesById as any)[props.routeId];
 	const NotFound = route.options.notFoundComponent ?? router.options.defaultNotFoundComponent;
 
 	@if (NotFound) {

package/src/RouterProvider.tsrx

@@ -5,11 +5,21 @@
 // instance), wraps in `router.options.Wrap` when configured, and provides the
 // router; `RouterProvider` renders `<Matches/>` inside it.
 import { hasKeys } from '@tanstack/router-core';
+import type { AnyRouter } from '@tanstack/router-core';
+import type { OctaneNode } from 'octane';
 import { routerContext } from './context.ts';
 import { Matches } from './Matches.tsrx';
 import { SafeFragment } from './SafeFragment.tsrx';
 
-export function RouterContextProvider(props) @{
+// Upstream's `RouterProps` is `Omit<RouterOptions<…>, 'context'> & { router }` —
+// extra props reconfigure the instance via `router.update()`. The octane binding
+// keeps the router-typed member strict and the option passthrough permissive.
+export type RouterProps = {
+		router: AnyRouter;
+		context?: Record<string, any>;
+	} & Record<string, any>;
+
+export function RouterContextProvider(props: RouterProps & { children?: OctaneNode }) @{
 	const { router, children, ...rest } = props;
 	if (hasKeys(rest)) {
 		router.update({
@@ -28,7 +38,7 @@ export function RouterContextProvider(props) @{
 	</Wrap>
 }
 
-export function RouterProvider(props) @{
+export function RouterProvider(props: RouterProps) @{
 	const { router, ...rest } = props;
 
 	<RouterContextProvider router={router} {...rest}>

package/src/RouterProvider.tsrx.d.ts

@@ -1,8 +1,12 @@
 // Type declaration for the .tsrx component (resolved by relative path).
 import type { AnyRouter } from '@tanstack/router-core';
 
-export declare const RouterProvider: (props: { router: AnyRouter; children?: unknown }) => unknown;
-export declare const RouterContextProvider: (props: {
-	router: import('@tanstack/router-core').AnyRouter;
-	children?: unknown;
-}) => unknown;
+export type RouterProps = {
+	router: AnyRouter;
+	context?: Record<string, any>;
+} & Record<string, any>;
+
+export declare const RouterProvider: (props: RouterProps) => unknown;
+export declare const RouterContextProvider: (
+	props: RouterProps & { children?: unknown },
+) => unknown;

package/src/SafeFragment.tsrx

@@ -5,7 +5,10 @@
 // — crucially — means a route WITHOUT a pendingComponent/errorComponent does not
 // create a boundary at all, so suspensions and errors bubble to the nearest
 // ancestor that has one (react-router parity).
-export function SafeFragment(props) @{
+// Props are `any` (upstream parity: react-router's `SafeFragment(props: any)`) —
+// it stands in for Suspense/CatchBoundary/CatchNotFound/shellComponent at dynamic
+// boundary slots, so it must accept any boundary's props and render only children.
+export function SafeFragment(props: any) @{
 	<>
 		{props.children}
 	</>

package/src/ScriptOnce.tsrx

@@ -0,0 +1,23 @@
+import { useEffect, useState } from 'octane';
+import { isServer } from '@tanstack/router-core/isServer';
+import { useRouter } from './context.ts';
+
+export function ScriptOnce(props: { children: string }) @{
+	const router = useRouter();
+	const server = isServer ?? router.isServer;
+	const [hydrating, setHydrating] = useState(true);
+	useEffect(() => {
+		setHydrating(false);
+	}, []);
+
+	@if (server || hydrating) {
+		<script
+			nonce={router.options.ssr?.nonce}
+			dangerouslySetInnerHTML={{
+				__html: props.children,
+			}}
+		/>
+	} @else {
+		<></>
+	}
+}

package/src/ScriptOnce.tsrx.d.ts

@@ -0,0 +1,3 @@
+import type { ComponentBody } from 'octane';
+
+export declare const ScriptOnce: ComponentBody<{ children: string }>;

package/src/Scripts.tsrx

@@ -0,0 +1,42 @@
+import { createElement, useEffect, useState } from 'octane';
+import { isServer } from '@tanstack/router-core/isServer';
+import type { RouterManagedTag } from '@tanstack/router-core';
+import { getAssetKey } from './assetKeys.ts';
+import { useRouter } from './context.ts';
+import { useScripts } from './scriptContentUtils.ts';
+
+export function Scripts() @{
+	const router = useRouter();
+	const scripts = useScripts();
+	const [hydrating, setHydrating] = useState(true);
+	useEffect(() => {
+		setHydrating(false);
+	}, []);
+	const renderScripts: Array<RouterManagedTag> =
+		!(isServer ?? router.isServer) && hydrating
+			? [
+					{
+						tag: 'script',
+						attrs: {
+							nonce: router.options.ssr?.nonce,
+							className: '$tsr',
+							id: '$tsr-stream-barrier',
+							suppressHydrationWarning: true,
+						},
+						children: '',
+					},
+					...scripts,
+				]
+			: scripts;
+	<>
+		{renderScripts.map((script, index) => {
+			const assetKey = getAssetKey('body', script, index);
+			return createElement('script', {
+				...script.attrs,
+				key: assetKey,
+				'data-tsr-managed-key': assetKey,
+				dangerouslySetInnerHTML: { __html: script.children ?? '' },
+			});
+		})}
+	</>
+}

package/src/Scripts.tsrx.d.ts

@@ -0,0 +1,3 @@
+import type { ComponentBody } from 'octane';
+
+export declare const Scripts: ComponentBody<Record<never, never>>;

package/src/Transitioner.tsrx

@@ -1,4 +1,6 @@
-// The navigation engine (renders nothing) — port of react-router's Transitioner.
+// The navigation engine — port of react-router's Transitioner. It runs as a
+// hook because a rendered sibling would put an SSR marker before a root route's
+// document-level <html> node and outside the #__app hydration range.
 // It (1) supplies `router.startTransition` so every navigation state update rides
 // an octane transition (concurrent navigation: the current page holds while the
 // next route suspends), (2) subscribes to history so back/forward and `Link`
@@ -18,7 +20,7 @@ import { useRouter } from './context.ts';
 import { useStore } from './useStore.ts';
 import { usePrevious } from './utils.ts';
 
-export function Transitioner() @{
+export function useTransitioner() {
 	const router = useRouter();
 	const mountLoadForRouter = useRef({ router, mounted: false });
 	const [isTransitioning, setIsTransitioning] = useState(false);
@@ -32,7 +34,7 @@ export function Transitioner() @{
 	const isPagePending = isLoading || hasPending;
 	const previousIsPagePending = usePrevious(isPagePending);
 
-	router.startTransition = (fn) => {
+	router.startTransition = (fn: () => void) => {
 		setIsTransitioning(true);
 		startTransition(() => {
 			fn();
@@ -47,14 +49,16 @@ export function Transitioner() @{
 	useEffect(() => {
 		const unsub = router.history.subscribe(() => router.load());
 
-		const nextLocation = router.buildLocation({
-			to: router.latestLocation.pathname,
-			search: true,
-			params: true,
-			hash: true,
-			state: true,
-			_includeValidateSearch: true,
-		});
+		const nextLocation = router.buildLocation(
+			{
+				to: router.latestLocation.pathname,
+				search: true,
+				params: true,
+				hash: true,
+				state: true,
+				_includeValidateSearch: true,
+			} as any,
+		);
 		if (
 			trimPathRight(router.latestLocation.publicHref) !== trimPathRight(nextLocation.publicHref)
 		) {
@@ -121,6 +125,4 @@ export function Transitioner() @{
 			});
 		}
 	}, [isAnyPending, previousIsAnyPending, router]);
-
-	<></>
 }

package/src/assetKeys.ts

@@ -0,0 +1,11 @@
+import type { RouterManagedTag } from '@tanstack/router-core';
+
+export function getAssetKey(scope: 'head' | 'body', asset: RouterManagedTag, index: number) {
+	const inlineCss = asset.tag === 'style' && asset.inlineCss;
+	return `${scope}:${index}:${JSON.stringify({
+		tag: asset.tag,
+		attrs: asset.attrs,
+		children: inlineCss ? undefined : asset.children,
+		inlineCss,
+	})}`;
+}

package/src/context.ts

@@ -3,7 +3,7 @@
 // match id down the render tree so `Outlet` can find the NEXT match to render —
 // the pull-based chaining that replaces a top-down state diff.
 import { createContext, useContext } from 'octane';
-import type { AnyRouter } from '@tanstack/router-core';
+import type { AnyRouter, RegisteredRouter } from '@tanstack/router-core';
 
 export const routerContext = createContext<AnyRouter | undefined>(undefined);
 export const getRouterContext = (): typeof routerContext => routerContext;
@@ -14,6 +14,10 @@ export const matchContext = createContext<string | undefined>(undefined);
 // Resolve the active router: an explicitly-passed one wins, else the context.
 // `useContext` is keyed by context identity (not a per-call-site slot), so it's
 // safe to call from this binding code without a slot.
+export function useRouter<TRouter extends AnyRouter = RegisteredRouter>(opts?: {
+	router?: TRouter;
+	warn?: boolean;
+}): TRouter;
 export function useRouter(...args: unknown[]): AnyRouter {
 	const opts = (args.length && typeof args[0] !== 'symbol' ? args[0] : undefined) as
 		| { router?: AnyRouter; warn?: boolean }

package/src/externalHydration.ts

@@ -0,0 +1,77 @@
+const EXTERNAL_HYDRATION_PROMISE = Symbol.for('octane.external-hydration-promise');
+
+type ExternalHydrationThenable<T> = PromiseLike<T> & {
+	[EXTERNAL_HYDRATION_PROMISE]: true;
+	status?: ThenableStatus;
+	value?: T;
+	reason?: unknown;
+};
+
+type ThenableStatus = 'pending' | 'fulfilled' | 'rejected';
+
+const externalHydrationThenables = new WeakMap<object, ExternalHydrationThenable<unknown>>();
+
+/**
+ * Wrap a router-owned promise so Octane still schedules its suspense boundary,
+ * while TanStack's serializer remains the only owner of its hydration value.
+ */
+export function toExternalHydrationThenable<T>(thenable: PromiseLike<T>): PromiseLike<T> {
+	const key = thenable as object;
+	const existing = externalHydrationThenables.get(key);
+	if (existing) {
+		return existing as ExternalHydrationThenable<T>;
+	}
+
+	let localStatus: ThenableStatus | undefined;
+	let localValue: T | undefined;
+	let localReason: unknown;
+	let hasLocalValue = false;
+	let hasLocalReason = false;
+
+	const externalThenable: ExternalHydrationThenable<T> = {
+		[EXTERNAL_HYDRATION_PROMISE]: true,
+		get status() {
+			return localStatus ?? readThenableStatus(thenable);
+		},
+		set status(status) {
+			localStatus = status;
+		},
+		get value(): T | undefined {
+			return hasLocalValue ? localValue : readThenableProperty<T>(thenable, 'value');
+		},
+		set value(value: T | undefined) {
+			hasLocalValue = true;
+			localValue = value;
+		},
+		get reason(): unknown {
+			return hasLocalReason ? localReason : readThenableProperty<unknown>(thenable, 'reason');
+		},
+		set reason(reason) {
+			hasLocalReason = true;
+			localReason = reason;
+		},
+		then(onfulfilled, onrejected) {
+			return thenable.then(onfulfilled, onrejected);
+		},
+	};
+	externalHydrationThenables.set(key, externalThenable);
+	return externalThenable;
+}
+
+function readThenableStatus(thenable: PromiseLike<unknown>) {
+	const status = readThenableProperty(thenable, 'status');
+	return status === 'pending' || status === 'fulfilled' || status === 'rejected'
+		? status
+		: undefined;
+}
+
+function readThenableProperty<T>(
+	thenable: PromiseLike<unknown>,
+	property: 'status' | 'value' | 'reason',
+): T | undefined {
+	try {
+		return (thenable as PromiseLike<unknown> & Record<string, T>)[property];
+	} catch {
+		return undefined;
+	}
+}