@octanejs/tanstack-router 0.1.59 → 0.1.60

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octanejs/tanstack-router",
-  "version": "0.1.59",
+  "version": "0.1.60",
   "license": "MIT",
   "type": "module",
   "engines": {
@@ -58,7 +58,7 @@
     "isbot": "^5.1.22"
   },
   "peerDependencies": {
-    "octane": "^0.6.0"
+    "octane": "^0.7.0"
   },
   "devDependencies": {
     "@tanstack/react-router": "1.170.18",
@@ -67,7 +67,7 @@
     "react": "19.2.7",
     "react-dom": "19.2.7",
     "vitest": "^4.1.10",
-    "octane": "0.6.0"
+    "octane": "0.7.0"
   },
   "scripts": {
     "test": "vitest run"

package/src/Asset.tsrx

@@ -14,6 +14,11 @@ type ManagedAssetProps = AssetProps & { managedKey?: string };
 
 const MANAGED_KEY_ATTR = 'data-tsr-managed-key';
 
+// Elements currently owned by a mounted Asset. A managed key is a 32-bit
+// content hash, so a collision must not let a second Asset adopt, and later
+// remove, an element another Asset still owns.
+const claimedElements = new WeakSet<Element>();
+
 function attributeName(name: string) {
 	switch (name) {
 		case 'charSet':
@@ -46,20 +51,28 @@ function setAttributes(element: Element, attrs: RouterManagedTag['attrs']) {
 
 function findManagedElement(parent: HTMLElement, key: string) {
 	for (const element of parent.querySelectorAll(`[${MANAGED_KEY_ATTR}]`)) {
-		if (element.getAttribute(MANAGED_KEY_ATTR) === key) {
+		if (element.getAttribute(MANAGED_KEY_ATTR) === key && !claimedElements.has(element)) {
 			return element;
 		}
 	}
 	return undefined;
 }
 
+function claim(element: Element) {
+	claimedElements.add(element);
+	return () => {
+		claimedElements.delete(element);
+		element.remove();
+	};
+}
+
 function mountAsset(props: ManagedAssetProps) {
 	const parent =
 		props.target === 'head' ? document.head : document.body;
 	const managedKey = props.managedKey ?? props.assetKey;
 	const existing = findManagedElement(parent, managedKey);
 	if (existing) {
-		return () => existing.remove();
+		return claim(existing);
 	}
 
 	const element = document.createElement(props.tag);
@@ -69,7 +82,7 @@ function mountAsset(props: ManagedAssetProps) {
 		element.textContent = props.children;
 	}
 	parent.appendChild(element);
-	return () => element.remove();
+	return claim(element);
 }
 
 export function Asset(props: AssetProps) @{
@@ -78,12 +91,16 @@ export function Asset(props: AssetProps) @{
 	const managedKey = (props as ManagedAssetProps).managedKey ?? props.assetKey;
 
 	if (!(isServer ?? router.isServer)) {
+		// Compare attrs by value: a rebuilt tag list allocates new attrs objects on
+		// every navigation, and an identity dependency would remove and re-add
+		// unchanged assets such as the stylesheet.
+		const attrsKey = JSON.stringify(props.attrs ?? null);
 		useLayoutEffect(() => mountAsset(props), [
 			props.assetKey,
 			managedKey,
-			props.attrs,
-			props.children,
 			props.tag,
+			attrsKey,
+			props.children,
 			props.target,
 		]);
 	}

package/src/HeadContent.tsrx

@@ -3,7 +3,7 @@ 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 { getAssetKey, getManagedAssetKey } from './assetKeys.ts';
+import { getAssetKeys } from './assetKeys.ts';
 import { useTags } from './headContentUtils.ts';
 import { useHydrated } from './ClientOnly.tsrx';
 
@@ -27,15 +27,16 @@ export function HeadContent(props: HeadContentProps) @{
 		process.env.NODE_ENV !== 'production' && hydrated
 			? tags.filter((tag) => tag.tag !== 'link' || tag.attrs?.[DEV_STYLES_ATTR] !== true)
 			: tags;
+	const keys = getAssetKeys('head', owner, filteredTags);
 	<>
 		{filteredTags.map((tag, index) => {
-			const assetKey = getAssetKey('head', tag, index);
+			const { assetKey, managedKey } = keys[index]!;
 			// `key` is lifted out of props by createElement (React semantics); the
 			// explicit type argument admits it alongside the AssetProps shape.
 			return createElement<AssetProps & { key?: string; managedKey?: string }>(Asset, {
 				...tag,
 				assetKey,
-				managedKey: getManagedAssetKey('head', owner, index),
+				managedKey,
 				target: 'head',
 				key: assetKey,
 			});

package/src/Match.tsrx

@@ -9,15 +9,15 @@
 // component for it — otherwise `SafeFragment` passes through so suspensions and
 // errors bubble to the nearest ancestor boundary (upstream's
 // ResolvedSuspenseBoundary/ResolvedCatchBoundary/ResolvedNotFoundBoundary).
-// `MatchInner` handles the match STATUS: it suspends (octane `use`, upstream
-// `throw promise`) on pending/redirected/_displayPending/_forcePending, renders
+// `MatchInner` handles the match STATUS: it suspends (a thrown promise, as
+// upstream) on pending/redirected/_displayPending/_forcePending, renders
 // the route's not-found UI for `status === 'notFound'`, throws to the
 // CatchBoundary for `status === 'error'`, and otherwise renders the route
 // component (or `<Outlet/>` for component-less layout routes) keyed by
 // remountDeps. `OnRendered` (rendered by the match directly below the root)
 // emits the router's `onRendered` event after the subtree commits — scroll
 // restoration restores on it.
-import { useRef, useLayoutEffect, use, createElement, Suspense } from 'octane';
+import { useRef, useLayoutEffect, createElement, Suspense } from 'octane';
 import {
 	createControlledPromise,
 	getLocationChangeInfo,
@@ -143,12 +143,17 @@ function MatchInner(props: { matchId: string }) {
 	const getMatchPromise = (key: 'displayPendingPromise' | 'minPendingPromise' | 'loadPromise') =>
 		router.getMatch(match.id)?._nonReactive[key] ?? match._nonReactive[key];
 
+	// Suspend by throwing, like upstream, not with `use()`. Each match state
+	// waits on a different promise, and `use()` is positional: a replay that
+	// finds the match in a new state would get the promise stored for the old
+	// one. Router-core's promises settle to `status: 'resolved'`, which `use()`
+	// reads as still pending, so that stored promise retries forever.
 	if (match._displayPending) {
-		use(getMatchPromise('displayPendingPromise')!);
+		throw getMatchPromise('displayPendingPromise')!;
 	}
 
 	if (match._forcePending) {
-		use(getMatchPromise('minPendingPromise')!);
+		throw getMatchPromise('minPendingPromise')!;
 	}
 
 	if (match.status === 'pending') {
@@ -165,7 +170,7 @@ function MatchInner(props: { matchId: string }) {
 				}, pendingMinMs);
 			}
 		}
-		use(getMatchPromise('loadPromise')!);
+		throw getMatchPromise('loadPromise')!;
 	}
 
 	if (match.status === 'notFound') {
@@ -173,9 +178,12 @@ function MatchInner(props: { matchId: string }) {
 	}
 
 	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')!);
+		// Observed mid-transition while a redirect is in flight — stay suspended so
+		// this stale render is abandoned and the redirect completes.
+		const atom = matchStore as unknown as Partial<MatchAtom>;
+		throw typeof atom.subscribe === 'function'
+			? nextMatchUpdate(atom as MatchAtom, match)
+			: getMatchPromise('loadPromise')!;
 	}
 
 	if (match.status === 'error') {
@@ -199,6 +207,39 @@ function MatchInner(props: { matchId: string }) {
 	return createElement(Outlet, {});
 }
 
+interface MatchAtom {
+	get: () => object;
+	subscribe: (cb: () => void) => { unsubscribe: () => void };
+}
+
+const matchUpdates = new WeakMap<object, Promise<void>>();
+
+// Settles on the first store update after `snapshot`. A redirected match waits
+// on this, not on its loadPromise: router-core resolves that promise when it
+// marks the redirect, and a settled promise retries on a microtask until the
+// redirect target has loaded, starving the timers and network callbacks that
+// load waits on. React's scheduler paces those retries; Octane's retry does
+// not. Server atoms cannot subscribe, so the server keeps upstream's promise:
+// a server redirect is answered before the app renders.
+function nextMatchUpdate(store: MatchAtom, snapshot: object): Promise<void> {
+	let update = matchUpdates.get(snapshot);
+	if (update === undefined) {
+		update = new Promise<void>((resolve) => {
+			const subscription = store.subscribe(() => {
+				subscription.unsubscribe();
+				resolve();
+			});
+			// The store may have moved on between this render and the subscription.
+			if (store.get() !== snapshot) {
+				subscription.unsubscribe();
+				resolve();
+			}
+		});
+		matchUpdates.set(snapshot, update);
+	}
+	return update;
+}
+
 // Emits the router's `onRendered` event once the subtree below the root layout
 // has committed (this component renders as a later sibling of the match content,
 // so its layout effect runs after the subtree's). Tracks the previously-resolved

package/src/Scripts.tsrx

@@ -1,7 +1,7 @@
 import { createElement, useEffect, useId, useState } from 'octane';
 import { isServer } from '@tanstack/router-core/isServer';
 import type { RouterManagedTag } from '@tanstack/router-core';
-import { getAssetKey, getManagedAssetKey } from './assetKeys.ts';
+import { getAssetKeys } from './assetKeys.ts';
 import { useRouter } from './context.ts';
 import { useScripts } from './scriptContentUtils.ts';
 
@@ -29,13 +29,14 @@ export function Scripts() @{
 					...scripts,
 				]
 			: scripts;
+	const keys = getAssetKeys('body', owner, renderScripts);
 	<>
 		{renderScripts.map((script, index) => {
-			const assetKey = getAssetKey('body', script, index);
+			const { assetKey, managedKey } = keys[index]!;
 			return createElement('script', {
 				...script.attrs,
 				key: assetKey,
-				'data-tsr-managed-key': getManagedAssetKey('body', owner, index),
+				'data-tsr-managed-key': managedKey,
 				dangerouslySetInnerHTML: { __html: script.children ?? '' },
 			});
 		})}

package/src/assetKeys.ts

@@ -1,15 +1,45 @@
 import type { RouterManagedTag } from '@tanstack/router-core';
 
-export function getAssetKey(scope: 'head' | 'body', asset: RouterManagedTag, index: number) {
+export type AssetKeys = { assetKey: string; managedKey: string };
+
+function assetContent(asset: RouterManagedTag) {
 	const inlineCss = asset.tag === 'style' && asset.inlineCss;
-	return `${scope}:${index}:${JSON.stringify({
+	return JSON.stringify({
 		tag: asset.tag,
 		attrs: asset.attrs,
 		children: inlineCss ? undefined : asset.children,
 		inlineCss,
-	})}`;
+	});
+}
+
+// FNV-1a, so the managed-key attribute stays short on the SSR element.
+function hashContent(content: string) {
+	let hash = 0x811c9dc5;
+	for (let i = 0; i < content.length; i++) {
+		hash ^= content.charCodeAt(i);
+		hash = Math.imul(hash, 0x01000193);
+	}
+	return (hash >>> 0).toString(36);
 }
 
-export function getManagedAssetKey(scope: 'head' | 'body', owner: string, index: number) {
-	return `${scope}:${owner}:${index.toString(36)}`;
+// Keys derive from each tag's content, never its list position. A navigation
+// that adds or removes a route's preload links shifts every later tag's index;
+// an index-based key remounts the asset, which removes and re-adds the
+// stylesheet link and flashes unstyled content. Identical tags are told apart
+// by occurrence count.
+export function getAssetKeys(
+	scope: 'head' | 'body',
+	owner: string,
+	assets: ReadonlyArray<RouterManagedTag>,
+): Array<AssetKeys> {
+	const seen = new Map<string, number>();
+	return assets.map((asset) => {
+		const content = assetContent(asset);
+		const occurrence = seen.get(content) ?? 0;
+		seen.set(content, occurrence + 1);
+		return {
+			assetKey: `${scope}:${occurrence}:${content}`,
+			managedKey: `${scope}:${owner}:${hashContent(content)}:${occurrence.toString(36)}`,
+		};
+	});
 }

package/src/ssr/RouterClient.tsrx

@@ -22,15 +22,13 @@ function getHydrationPromise(router: AnyRouter) {
 	return promise;
 }
 
-function RouterClientInner(props: { router: AnyRouter }) @{
+// Per react-router's RouterClient, which suspends through <Await> without a
+// fallback: no boundary sits above the router. A root that suspends keeps the
+// server DOM while hydrating and commits the whole tree once hydrate() settles.
+// A boundary here would commit an empty fallback, throttle the hydrated tree's
+// reveal as a Suspense retry, and add a range the server's RouterServer never
+// rendered.
+export function RouterClient(props: { router: AnyRouter }) @{
 	use(toExternalHydrationThenable(getHydrationPromise(props.router)));
 	<RouterProvider router={props.router} />
 }
-
-export function RouterClient(props: { router: AnyRouter }) @{
-	@try {
-		<RouterClientInner router={props.router} />
-	} @pending {
-		<></>
-	}
-}