@octanejs/tanstack-router 0.2.9 → 0.3.0

package/README.md

@@ -62,6 +62,16 @@ tree renders **pull-based**: `RouterProvider` renders the first match, and each
 component's `<Outlet/>` looks up the next match via `matchContext` — so navigation
 re-renders only the matches that changed.
 
+## Headless routing
+
+Use `@octanejs/tanstack-router/core` when an application owns its render tree and
+only needs matching, loading, and navigation. It exposes Octane's router adapter,
+the framework-neutral `@tanstack/router-core` APIs, and history constructors
+without importing route components or hooks.
+
+Browser and hash histories created by this package preserve existing application
+fields in History API state objects and Navigation API entry state during initialization.
+
 ## Same-route search navigation
 
 Same-route search navigations now render store updates urgently. If the route
@@ -144,6 +154,12 @@ existing `CompiledRouterProvider`, `CompiledOutlet`, and
 `lazyCompiledRouteComponent` names remain aliases. TanStack owns matching,
 loading, navigation, history and render acknowledgements.
 
+`PreconfiguredRouterProvider` accepts only `{ router }` and owns the provider,
+match projection, and failure presentation in Strong mode. The compiled error
+boundary owns synchronous route error reporting and not-found propagation.
+Configure the router before rendering it. Use `RouterProvider` when provider
+option props need to reconfigure the router synchronously.
+
 ```tsx
 import {
   createRootRoute, createRoute, createRouter, createBrowserHistory,
@@ -191,13 +207,13 @@ Compiled selection removes descriptor creation from route selection, bound
 links and document shells, but does not make the entire binding Strong or
 remove the generic renderer. Link retains synchronous `flushSync` so its
 transition cue is already visible in `onBeforeNavigate` callbacks. Both entries
-share a non-Strong script component that renders host descriptors: new inline and
-external scripts execute, and self-removing hydration data scripts leave no
-template row frames behind. Route scripts retain their managed nodes through
-hydration and are replaced with route ownership. The scroll-restoration
-script remains through adoption and is dropped afterward. Error propagation,
-scroll-script hydration compatibility, and lifecycle dependencies retain their
-existing contracts.
+share a Strong keyed script template. Newly mounted route scripts execute once;
+hydration adopts existing scripts without replaying them, and self-removing
+transport scripts leave no item markers behind. Managed keys, nonces and route
+ownership are retained. Scroll-restoration scripts use a server-owned static
+hydration range, which is removed after hydration and omitted on client-only
+mounts. Error propagation and lifecycle dependencies retain their existing
+contracts.
 
 `Wrap` and `InnerWrap` remain unsupported and produce an explicit diagnostic.
 For returned JSX, host strings, renderable wrappers or mixed route trees, retain

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octanejs/tanstack-router",
-  "version": "0.2.9",
+  "version": "0.3.0",
   "license": "MIT",
   "type": "module",
   "engines": {
@@ -36,6 +36,7 @@
   ],
   "exports": {
     ".": "./src/index.ts",
+    "./core": "./src/core.ts",
     "./history": "./src/history.ts",
     "./compiled": "./src/compiled.ts",
     "./ssr/server": {
@@ -59,13 +60,13 @@
     "isbot": "^5.1.22"
   },
   "peerDependencies": {
-    "octane": "^0.13.0"
+    "octane": "^0.14.0"
   },
   "devDependencies": {
     "@tanstack/react-router": "1.170.41",
     "@tsrx/react": "^0.4.5",
     "esbuild": "^0.28.1",
-    "octane": "0.13.7",
+    "octane": "0.14.0",
     "react": "19.2.7",
     "react-dom": "19.2.7",
     "vitest": "^4.1.10"

package/src/Asset.tsrx

@@ -1,4 +1,4 @@
-import { useRouter } from './context.ts';
+import { useRouter } from './context';
 import { createAsset } from './assetComponent.tsrx';
 
 export const Asset = createAsset(useRouter);

package/src/Await.tsrx

@@ -5,7 +5,7 @@
 // render-prop, so the consumer's `<Await>{(d) => …}</Await>` stays the public API).
 import { use } from 'octane';
 import type { OctaneNode } from 'octane';
-import { toExternalHydrationThenable } from './externalHydration.ts';
+import { toExternalHydrationThenable } from './externalHydration';
 
 function AwaitInner(props: { promise: Promise<any>; render: (data: any) => OctaneNode }) {
 	const data = use(toExternalHydrationThenable(props.promise));

package/src/CatchBoundary.tsrx

@@ -1,4 +1,4 @@
-// react-router's CatchBoundary + default ErrorComponent, rebuilt on octane's
+// react-router's CatchBoundary, rebuilt on octane's
 // `@try`/`@catch` (octane has no class components, so the upstream
 // CatchBoundaryImpl class becomes a catch branch). Contract preserved from
 // upstream CatchBoundary.tsx:
@@ -13,15 +13,18 @@
 //     getDerivedStateFromProps; here a layout effect calls the catch reset — one
 //     commit later, same observable outcome). Match passes the router's `loadedAt`
 //     so navigation clears route error UI.
-import { useState, useRef, useLayoutEffect } from 'octane';
+import { useRef, useLayoutEffect } from 'octane';
 import type { OctaneNode } from 'octane';
-import type { ErrorInfo, ErrorRouteComponent } from './route.ts';
+import type { ErrorInfo, ErrorRouteComponent } from './route';
+import { ErrorComponent } from './ErrorComponent.tsrx';
+
+export { ErrorComponent };
 
 export function CatchBoundary(props: {
 	getResetKey: () => unknown;
 	children: OctaneNode;
-	errorComponent?: ErrorRouteComponent;
-	onCatch?: (error: Error, errorInfo: ErrorInfo) => void;
+	errorComponent?: ErrorRouteComponent | undefined;
+	onCatch?: ((error: Error, errorInfo: ErrorInfo) => void) | undefined;
 }) @{
 	@try {
 		<>{props.children}</>
@@ -39,9 +42,9 @@ export function CatchBoundary(props: {
 function CatchErrorView(props: {
 	error: any;
 	reset: () => void;
-	getResetKey?: () => unknown;
-	errorComponent?: ErrorRouteComponent;
-	onCatch?: (error: Error, errorInfo: ErrorInfo) => void;
+	getResetKey: () => unknown;
+	errorComponent?: ErrorRouteComponent | undefined;
+	onCatch?: ((error: Error, errorInfo: ErrorInfo) => void) | undefined;
 }) @{
 	// componentDidCatch parity — once per distinct caught error, during render so a
 	// rethrow (the notFound-forwarding path) escapes to the parent boundary.
@@ -66,36 +69,3 @@ function CatchErrorView(props: {
 
 	<ErrorComp error={props.error} reset={props.reset} info={{ componentStack: '' }} />
 }
-
-// The default error UI, markup-identical to react-router's ErrorComponent (string
-// styles serialize to the same inline css React produces, so the differential rig
-// can byte-compare it).
-export function ErrorComponent(props: {
-	error: any;
-	reset?: () => void;
-	info?: { componentStack?: string };
-}) @{
-	const [show, setShow] = useState(process.env.NODE_ENV !== 'production');
-
-	<div style="padding:.5rem;max-width:100%">
-		<div style="display:flex;align-items:center;gap:.5rem">
-			<strong style="font-size:1rem">Something went wrong!</strong>
-			<button
-				style="appearance:none;font-size:.6em;border:1px solid currentColor;padding:.1rem .2rem;font-weight:bold;border-radius:.25rem"
-				onClick={() => setShow((d) => !d)}
-			>
-				{show ? 'Hide Error' : 'Show Error'}
-			</button>
-		</div>
-		<div style="height:.25rem"></div>
-		@if (show) {
-			<div>
-				<pre style="font-size:.7em;border:1px solid red;border-radius:.25rem;padding:.3rem;color:red;overflow:auto">
-					@if (props.error?.message) {
-						<code>{props.error.message as string}</code>
-					}
-				</pre>
-			</div>
-		}
-	</div>
-}

package/src/ClientOnly.tsrx

@@ -9,7 +9,7 @@
 // call sites).
 import { useSyncExternalStore } from 'octane';
 import type { OctaneNode } from 'octane';
-import { splitSlot, subSlot } from './internal.ts';
+import { splitSlot, subSlot } from './internal';
 
 const subscribe = () => () => {};
 

package/src/ErrorComponent.tsrx

@@ -0,0 +1,38 @@
+'use strong';
+
+declare const process: { env: { NODE_ENV?: string } };
+
+import { useState } from 'octane';
+
+// The default error UI, markup-identical to react-router's ErrorComponent (string
+// styles serialize to the same inline css React produces, so the differential rig
+// can byte-compare it).
+export function ErrorComponent(props: {
+	error: any;
+	reset?: () => void;
+	info?: { componentStack?: string };
+}) @{
+	const [show, setShow] = useState(process.env.NODE_ENV !== 'production');
+
+	<div style="padding:.5rem;max-width:100%">
+		<div style="display:flex;align-items:center;gap:.5rem">
+			<strong style="font-size:1rem">Something went wrong!</strong>
+			<button
+				style="appearance:none;font-size:.6em;border:1px solid currentColor;padding:.1rem .2rem;font-weight:bold;border-radius:.25rem"
+				onClick={() => setShow((d) => !d)}
+			>
+				{show ? 'Hide Error' : 'Show Error'}
+			</button>
+		</div>
+		<div style="height:.25rem"></div>
+		@if (show) {
+			<div>
+				<pre style="font-size:.7em;border:1px solid red;border-radius:.25rem;padding:.3rem;color:red;overflow:auto">
+					@if (props.error?.message) {
+						<code>{props.error.message as string}</code>
+					}
+				</pre>
+			</div>
+		}
+	</div>
+}

package/src/HeadContent.tsrx

@@ -1,10 +1,12 @@
+declare const process: { env: { NODE_ENV?: string } };
+
 import { createElement, useEffect, useId } from 'octane';
 import { DEV_STYLES_ATTR } from '@tanstack/router-core';
 import type { AssetCrossOriginConfig } from '@tanstack/router-core';
 import { Asset } from './Asset.tsrx';
 import type { AssetProps } from './Asset.tsrx';
-import { getAssetKeys } from './assetKeys.ts';
-import { useTags } from './headContentUtils.ts';
+import { getAssetKeys } from './assetKeys';
+import { useTags } from './headContentUtils';
 import { useHydrated } from './ClientOnly.tsrx';
 
 export interface HeadContentProps {

package/src/Link.tsrx

@@ -1,4 +1,6 @@
-import { useLinkProps } from './link.ts';
+import { useRouter } from './context';
+import { createUseLinkProps } from './linkBinding';
 import { createLinkComponent } from './linkComponent.tsrx';
 
+export const useLinkProps = createUseLinkProps(useRouter);
 export const Link = createLinkComponent(useLinkProps);

package/src/Link.tsrx.d.ts

@@ -1,3 +1,6 @@
+import type { createUseLinkProps } from './linkBinding';
 import type { LinkComponent } from './linkTypes';
 
+export declare const useLinkProps: ReturnType<typeof createUseLinkProps>;
+
 export declare const Link: LinkComponent<'a'>;

package/src/Match.tsrx

@@ -20,9 +20,9 @@
 import { createElement, Suspense } from 'octane';
 import { isNotFound, rootRouteId } from '@tanstack/router-core';
 import type { NotFoundError, RootRouteOptions } from '@tanstack/router-core';
-import type { ErrorInfo, ErrorRouteComponent } from './route.ts';
-import { useStore } from './useStore.ts';
-import { useRouter, matchContext as MatchContext } from './context.ts';
+import type { ErrorInfo, ErrorRouteComponent } from './route';
+import { useStore } from './useStore';
+import { useRouter, matchContext as MatchContext } from './context';
 import { Outlet } from './Outlet.tsrx';
 import { RouteNotFound } from './RouteNotFound.tsrx';
 import { CatchBoundary, ErrorComponent } from './CatchBoundary.tsrx';

package/src/MatchRoute.tsrx

@@ -5,8 +5,8 @@
 // false | matched params. The component renders its children when matched — a
 // render-prop child ALWAYS renders, receiving the params (false when unmatched).
 import { useCallback, isChildrenBlock } from 'octane';
-import { useRouter } from './context.ts';
-import { useStore } from './useStore.ts';
+import { useRouter } from './context';
+import { useStore } from './useStore';
 
 export function useMatchRoute() {
 	const router = useRouter();
@@ -29,10 +29,10 @@ export function MatchRoute(props: Record<string, any>) @{
 	const matchRoute = useMatchRoute();
 	const params = matchRoute(props);
 	const out =
-		typeof props.children === 'function' && !isChildrenBlock(props.children)
-			? props.children(params)
+		typeof props['children'] === 'function' && !isChildrenBlock(props['children'])
+			? props['children'](params)
 			: params
-				? props.children
+				? props['children']
 				: null;
 	<>{out}</>
 }

package/src/Matches.tsrx

@@ -12,9 +12,8 @@
 // ErrorComponent for errors no route boundary caught, reset by `loadedAt`.
 import { useLayoutEffect, createElement, Suspense } from 'octane';
 import { setupScrollRestoration, rootRouteId } from '@tanstack/router-core';
-import { useStore } from './useStore.ts';
-import { useRouter, matchContext as MatchContext } from './context.ts';
-import { useTransitioner, settleOwner } from './Transitioner.tsrx';
+import { useRouter, matchContext as MatchContext } from './context';
+import { useTransitioner, usePresentedMatches } from './Transitioner.tsrx';
 import { Match } from './Match.tsrx';
 import { CatchBoundary, ErrorComponent } from './CatchBoundary.tsrx';
 import { SafeFragment } from './SafeFragment.tsrx';
@@ -32,34 +31,22 @@ export function Matches() @{
 	useLayoutEffect(() => {
 		if (router.options.scrollRestoration) setupScrollRestoration(router);
 	}, [router]);
-	const expectedMatches = useTransitioner(router);
+	useTransitioner(router);
 
 	<InnerWrap>
 		<Suspense fallback={pendingElement}>
-			<MatchesInner expectedMatches={expectedMatches} />
+			<MatchesInner />
 		</Suspense>
 	</InnerWrap>
 }
 
-function MatchesInner(props: { expectedMatches: unknown }) @{
+function MatchesInner() @{
 	const router = useRouter();
-	// router-core 1.171.34 dropped the `firstId`/`loadedAt` stores: the root match
-	// is `matches[0]` and the global error boundary resets on its identity. While a
-	// navigation transition is pending, render the matches router-core expects
-	// (`acknowledgement[0]`) so the committed tree equals what it awaits, then
-	// settle that render acknowledgement from a layout effect once it lands.
-	const acknowledgement: Array<any> = ((router as any)._rendered ??= []);
-	const matches = useStore(router.stores.matches, (m: any) =>
-		acknowledgement[0] === props.expectedMatches ? (props.expectedMatches ?? m) : m,
-	) as any;
+	const matches = usePresentedMatches(router);
 	const rootMatch = matches[0];
 	const routeId = rootMatch?.routeId as string | undefined;
 	const CatchWrap = router.options.disableGlobalCatchBoundary ? SafeFragment : CatchBoundary;
 
-	useLayoutEffect(() => {
-		if (acknowledgement[0] === matches) settleOwner(acknowledgement, true);
-	}, [acknowledgement, matches]);
-
 	<MatchContext value={routeId}>
 		<CatchWrap getResetKey={() => rootMatch} errorComponent={ErrorComponent}>
 			@if (routeId) {

package/src/Navigate.tsrx

@@ -1,7 +1,7 @@
 // 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';
+import { useNavigate } from './hooks';
 
 export function Navigate(props: NavigateOptions) @{
 	const navigate = useNavigate();

package/src/Outlet.tsrx

@@ -11,8 +11,8 @@
 // match — so the 404 lands inside the layout chrome.
 import { useContext, createElement, Suspense } from 'octane';
 import { rootRouteId } from '@tanstack/router-core';
-import { useStore } from './useStore.ts';
-import { useRouter, matchContext } from './context.ts';
+import { useStore } from './useStore';
+import { useRouter, matchContext } from './context';
 import { Match } from './Match.tsrx';
 import { RouteNotFound } from './RouteNotFound.tsrx';
 import { SafeFragment } from './SafeFragment.tsrx';

package/src/RouteNotFound.tsrx

@@ -8,7 +8,7 @@
 // when the match resolved with `status === 'notFound'` (a loader threw
 // `notFound()`). Upstream spreads the NotFoundError onto the component, so a
 // `notFound({ data })` payload arrives as the `data` prop.
-import { useRouter } from './context.ts';
+import { useRouter } from './context';
 
 export function RouteNotFound(props: { routeId: string; error?: any }) @{
 	const router = useRouter();

package/src/RouterProvider.tsrx

@@ -7,7 +7,7 @@
 import { hasKeys } from '@tanstack/router-core';
 import type { AnyRouter } from '@tanstack/router-core';
 import type { OctaneNode } from 'octane';
-import { routerContext as RouterContext } from './context.ts';
+import { routerContext as RouterContext } from './context';
 import { Matches } from './Matches.tsrx';
 import { SafeFragment } from './SafeFragment.tsrx';
 

package/src/ScriptOnce.tsrx

@@ -1,12 +1,12 @@
-// ScriptOnce — port of react-router's ScriptOnce.tsx. The server emits the
-// script; upstream's client renders null because the script removes itself
-// (`document.currentScript.remove()`) before React hydrates. Octane hydration
-// claims the server's structure instead, so the hydration render adopts the
-// server `<script>` without comparing its content (the client never runs it, and
-// may not have it) and the post-hydration render drops it. A client-only mount
-// renders nothing, as upstream does.
+'use strong';
+
+// The browser build has no scroll-script source. Preserve the server-owned
+// range without reconciling its content, then remove it after hydration commits.
+// A client-only mount has no server range and renders nothing.
 import { isServer } from '@tanstack/router-core/isServer';
-import { useRouter } from './context.ts';
+import { Hydrate, trustHTML } from 'octane';
+import { never } from 'octane/hydration';
+import { useRouter } from './context';
 import { useHydrated } from './ClientOnly.tsrx';
 
 export function ScriptOnce(props: { children: string }) @{
@@ -14,13 +14,12 @@ export function ScriptOnce(props: { children: string }) @{
 	const hydrated = useHydrated();
 
 	@if ((isServer ?? router.isServer) || !hydrated) {
-		<script
-			nonce={router.options.ssr?.nonce}
-			suppressHydrationWarning
-			dangerouslySetInnerHTML={{
-				__html: props.children,
-			}}
-		/>
+		<Hydrate split={false} when={never()}>
+			<script
+				nonce={router.options.ssr?.nonce}
+				dangerouslySetInnerHTML={trustHTML(props.children)}
+			/>
+		</Hydrate>
 	} @else {
 		<></>
 	}

package/src/Scripts.tsrx

@@ -1,5 +1,5 @@
 import { createScripts } from './scriptComponent.tsrx';
-import { useScripts } from './scriptContentUtils.ts';
+import { useScripts } from './scriptContentUtils';
 
 // router-core 1.171.34 owns the hydration-script lifecycle: the server appends
 // the initial hydration tags (and the streaming boundary) through

package/src/ScrollRestoration.tsrx

@@ -5,7 +5,7 @@
 // Matches); use one or the other.
 import { useLayoutEffect } from 'octane';
 import { setupScrollRestoration } from '@tanstack/router-core';
-import { useRouter } from './context.ts';
+import { useRouter } from './context';
 
 export function ScrollRestoration() @{
 	const router = useRouter();

package/src/Transitioner.tsrx

@@ -1,3 +1,5 @@
+'use strong';
+
 // The navigation engine — port of react-router's Transitioner. It runs as a hook
 // because a rendered sibling would place an SSR marker before a root route's
 // document-level <html> node and outside the #__app hydration range.
@@ -17,81 +19,97 @@
 //      and kick off the initial load — or, when hydrating an already-resolved SSR
 //      location, acknowledge the first render so `onRendered` consumers (scroll
 //      restoration, devtools) fire.
-import { useLayoutEffect, useState, startTransition } from 'octane';
+import { useInsertionEffect, useLayoutEffect, startTransition } from 'octane';
 import { getLocationChangeInfo, trimPathRight } from '@tanstack/router-core';
-import type { AnyRouter } from '@tanstack/router-core';
+import type { AnyRouteMatch, AnyRouter } from '@tanstack/router-core';
+import { useStore } from './useStore';
 
 // Resolve the pending render acknowledgement with whether the expected matches
 // rendered, then clear the slot. `owner` is `router._rendered`: `[expected, resolve]`.
-export function settleOwner(owner: Array<any>, rendered: boolean) {
-	const settle = owner[1] as ((rendered: boolean) => void) | undefined;
+function settleOwner(owner: NonNullable<AnyRouter['_rendered']>, rendered: boolean) {
+	const settle = owner[1];
 	owner.length = 0;
 	settle?.(rendered);
 }
 
-export function useTransitioner(routerInstance: AnyRouter) {
-	const router = routerInstance as any;
-	const [expectedMatches, setExpectedMatches] = useState<unknown>();
-
-	const acknowledgement: Array<any> = (router._rendered ??= []);
-
-	router.startTransition = (fn: () => void, expected: unknown) =>
+function installTransitioner(router: AnyRouter) {
+	const acknowledgement = (router._rendered ??= []);
+	const previous = router.startTransition;
+	const owned: AnyRouter['startTransition'] = (fn, expected) =>
 		new Promise<boolean>((resolve) => {
-			// A newer transition supersedes an unrendered older one.
 			settleOwner(acknowledgement, false);
-			acknowledgement.push(expected, resolve);
-			// Publish the matches this transaction needs. MatchesInner consumes this
-			// snapshot and acknowledges it only after that exact tree commits.
-			setExpectedMatches(expected);
+			acknowledgement[0] = expected;
+			acknowledgement[1] = resolve;
 			startTransition(fn);
 		});
-
-	useLayoutEffect(() => {
-		const unsub = router.history.subscribe(() => router.load());
-
-		// octane has no StrictMode double-invoke, so this layout effect runs once per
-		// mounted router and re-runs only when the router (or its history) is swapped
-		// on a live provider — exactly when the new router needs its initial load.
-		// Upstream guards this block with a dev-only `mounted` ref purely to absorb
-		// React's StrictMode double-invoke; keeping that ref here would instead skip
-		// the swapped-in router's load.
-		router.updateLatestLocation?.();
-		const location = router.latestLocation;
-		const nextLocation = router.buildLocation({
-			to: location.pathname,
-			search: true,
-			params: true,
-			hash: true,
-			state: true,
-			_includeValidateSearch: true,
-		} as any);
-		if (trimPathRight(location.publicHref) !== trimPathRight(nextLocation.publicHref)) {
-			router.commitLocation({ ...nextLocation, replace: true, ignoreBlocker: true });
-			return unsub;
+	router.startTransition = owned;
+	return () => {
+		if (router.startTransition === owned) {
+			router.startTransition = previous;
+			settleOwner(acknowledgement, false);
 		}
+	};
+}
 
-		const resolvedLocation = router.stores.resolvedLocation.get();
-		if (
-			resolvedLocation?.href === location.href &&
-			resolvedLocation.state.__TSR_key === location.state.__TSR_key
-		) {
-			// Already resolved (SSR hydration): emit `onRendered` for scroll
-			// restoration and devtools. The match tree has already committed by the
-			// time this layout effect runs (child effects fire before the parent's),
-			// so emit directly rather than through the acknowledgement/settle path:
-			// hydration acknowledges the matches already on screen, which — unlike a
-			// navigation that commits the *next* matches — triggers no re-render for
-			// `MatchesInner`'s settle effect to run on.
-			router.emit({
-				type: 'onRendered',
-				...getLocationChangeInfo(resolvedLocation, resolvedLocation),
-			});
-		} else if (!router._tx) {
-			router.load({ sync: true }).catch((err: unknown) => {
-				console.error(err);
-			});
-		}
+function subscribeToHistory(router: AnyRouter, history: AnyRouter['history']) {
+	const unsub = history.subscribe(() => router.load());
+
+	// Re-run for a replacement router or history so the new instance loads.
+	router.updateLatestLocation?.();
+	const location = router.latestLocation;
+	const nextLocation = router.buildLocation({
+		to: location.pathname,
+		search: true,
+		params: true,
+		hash: true,
+		state: true,
+		_includeValidateSearch: true,
+	} as any);
+	if (trimPathRight(location.publicHref) !== trimPathRight(nextLocation.publicHref)) {
+		router.commitLocation({ ...nextLocation, replace: true, ignoreBlocker: true });
 		return unsub;
-	}, [router, router.history]);
-	return expectedMatches;
+	}
+
+	const resolvedLocation = router.stores.resolvedLocation.get();
+	if (
+		resolvedLocation?.href === location.href &&
+		resolvedLocation.state.__TSR_key === location.state.__TSR_key
+	) {
+		// Hydration acknowledges the already-committed tree, which does not trigger
+		// another render for the navigation acknowledgement effect to observe.
+		router.emit({
+			type: 'onRendered',
+			...getLocationChangeInfo(resolvedLocation, resolvedLocation),
+			fromLocation: resolvedLocation,
+		});
+	} else if (!router._tx) {
+		router.load({ sync: true }).catch((err: unknown) => {
+			console.error(err);
+		});
+	}
+	return unsub;
+}
+
+export function useTransitioner(router: AnyRouter) {
+	const history = router.history;
+	// Install before descendant layout effects can navigate, without mutating the
+	// router during render or placing a sibling before a document-level route.
+	useInsertionEffect(() => installTransitioner(router));
+	useLayoutEffect(() => subscribeToHistory(router, history));
+}
+
+function acknowledgeRenderedMatches(router: AnyRouter, matches: Array<AnyRouteMatch>) {
+	const owner = router._rendered;
+	if (owner && owner[0] === matches) settleOwner(owner, true);
+}
+
+// The store may reconstruct its match array, so a navigation must present the
+// exact snapshot offered by router-core until that tree commits. The live owner
+// is observed only by the store snapshot and by the commit acknowledgement.
+// Mirroring it in component state would entangle that update with an async action
+// awaiting navigation, leaving both the action and its render acknowledgement pending.
+export function usePresentedMatches(router: AnyRouter) {
+	const matches = useStore(router.stores.matches, (current) => router._rendered?.[0] ?? current);
+	useLayoutEffect(() => acknowledgeRenderedMatches(router, matches));
+	return matches;
 }

package/src/assetComponent.tsrx

@@ -3,7 +3,7 @@
 import { useLayoutEffect, useMemo, trustHTML } from 'octane';
 import { isServer } from '@tanstack/router-core/isServer';
 import type { RouterManagedTag } from '@tanstack/router-core';
-import type { useRouter as UseRouter } from './context.ts';
+import type { useRouter as UseRouter } from './context';
 import { useHydrated } from './ClientOnly.tsrx';
 
 export type AssetProps = RouterManagedTag & {

package/src/compiled/Document.tsrx

@@ -1,5 +1,7 @@
 'use strong';
 
+declare const process: { env: { NODE_ENV?: string } };
+
 import { useEffect, useId, HYDRATION_RANGE_BOUNDARY, createPortal, useState } from 'octane';
 import { DEV_STYLES_ATTR } from '@tanstack/router-core';
 import type { AssetCrossOriginConfig } from '@tanstack/router-core';