@octanejs/tanstack-router 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominic Gannaway
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,94 @@
+# @octanejs/tanstack-router
+
+[TanStack Router](https://tanstack.com/router) for the [octane](https://github.com/octanejs/octane) UI framework.
+
+TanStack Router splits a framework-agnostic core (`@tanstack/router-core` — the
+router, route tree, matching, history, and the reactive store) from a thin React
+binding (`@tanstack/react-router`). Mirroring `@octanejs/tanstack-query`, this package
+re-exports the core **verbatim** and reimplements only the binding on octane's hooks.
+The public surface matches `@tanstack/react-router`, so most router code works by
+changing the import.
+
+```tsx
+import {
+  createRouter,
+  createRootRoute,
+  createRoute,
+  RouterProvider,
+  Outlet,
+  Link,
+  useParams,
+} from '@octanejs/tanstack-router';
+import { createRoot } from 'octane';
+
+const rootRoute = createRootRoute({ component: RootLayout });
+const indexRoute = createRoute({ getParentRoute: () => rootRoute, path: '/', component: Home });
+const itemRoute = createRoute({ getParentRoute: () => rootRoute, path: 'item/$id', component: Item });
+
+const router = createRouter({ routeTree: rootRoute.addChildren([indexRoute, itemRoute]) });
+
+createRoot(document.getElementById('app')!).render(() => <RouterProvider router={router} />);
+
+function RootLayout() @{
+  <div>
+    <Link to="/">{'Home'}</Link>
+    <Outlet />
+  </div>
+}
+
+function Item() @{
+  const { id } = useParams({ strict: false });
+  <h1>{('Item ' + id) as string}</h1>
+}
+```
+
+The same code works in React-style `.tsx` too (`className`, `return <jsx>`, `<Link>Home</Link>`) — see `tests/_fixtures/basic-react.tsx`.
+
+## How it works
+
+`@tanstack/router-core` keeps the router state in a reactive store. On the client,
+`createRouter` supplies the store factory (`createAtom`/`batch` from
+`@tanstack/store` — framework-agnostic), whose atoms expose `.subscribe`/`.get`.
+`useStore` binds those to octane's `useSyncExternalStore`, and every read hook
+(`useRouterState`, `useLocation`, `useParams`, …) is a selector over it. The match
+tree renders **pull-based**: `RouterProvider` renders the first match, and each route
+component's `<Outlet/>` looks up the next match via `matchContext` — so navigation
+re-renders only the matches that changed.
+
+## v1 scope
+
+Included: `createRouter`, `createRootRoute`, `createRoute`, `RouterProvider`,
+`Outlet`, `Link`, `Navigate`, `useRouter`, `useRouterState`, `useLocation`,
+`useParams`, `useSearch`, `useLoaderData`, `useMatches`, `useNavigate`,
+**`ScrollRestoration`**, **`Await`/`useAwaited` + `defer` (streaming deferred data)**,
+and **`lazyRouteComponent` (lazy/code-split route components)**, and **not-found
+rendering** (`notFoundComponent`/`defaultNotFoundComponent`/`notFoundMode` — an
+unknown URL or a loader throwing `notFound()` renders the not-found UI inside the
+layout, per TanStack's fuzzy/root boundary rules), plus the full
+`@tanstack/router-core` re-export (`redirect`, `notFound`, history, search helpers,
+types).
+
+```tsx
+// streaming a deferred loader value
+<Await promise={data.slow} fallback={'loading…'}>
+  {(value) => <pre>{JSON.stringify(value) as string}</pre>}
+</Await>
+
+// scroll restoration: either the component or createRouter({ scrollRestoration: true })
+<ScrollRestoration />
+
+// code-split a route's component
+createRoute({ path: 'item/$id', component: lazyRouteComponent(() => import('./Item')) })
+```
+
+Deferred: file-based routing + the codegen plugin, devtools, search-param
+validation/middleware, `useBlocker`, SSR head/scripts.
+
+## Divergences from `@tanstack/react-router`
+
+- **Refs are props** (octane's model) — `createLink`'s `forwardRef` becomes a `ref`
+  prop.
+- **No `flushSync`** in the `Link` click handler (the one hard `react-dom`
+  coupling) — navigation state updates run synchronously in v1.
+- `Link` v1 reflects active state via `data-status="active"` + `aria-current`; the
+  `activeProps`/`inactiveProps` className-merge API is a follow-up.

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@octanejs/tanstack-router",
+  "version": "0.1.2",
+  "license": "MIT",
+  "type": "module",
+  "description": "TanStack Router bindings for the octane renderer — reuses @tanstack/router-core and swaps the React binding for octane's hooks.",
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/tanstack-router"
+  },
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./history": "./src/history.ts"
+  },
+  "dependencies": {
+    "@tanstack/history": "1.162.0",
+    "@tanstack/router-core": "1.171.13",
+    "@tanstack/store": "^0.9.3",
+    "octane": "0.1.3"
+  },
+  "devDependencies": {
+    "@tanstack/react-router": "1.170.16",
+    "@tsrx/react": "^0.2.37",
+    "esbuild": "^0.28.1",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "vitest": "^4.1.9"
+  },
+  "scripts": {
+    "test": "vitest run"
+  }
+}

package/src/Await.tsrx

@@ -0,0 +1,21 @@
+// Suspends on a deferred promise and renders its child — a render-prop
+// `(data) => <jsx/>` — with the resolved value. `AwaitInner` does the `use(promise)`
+// inside a `@try`/`@pending` boundary; the render function is handed to it as a
+// `render` prop (re-passing it as `{children}` would be an identifier, not a literal
+// render-prop, so the consumer's `<Await>{(d) => …}</Await>` stays the public API).
+import { use } from 'octane';
+
+function AwaitInner(props) {
+	const data = use(props.promise);
+	return props.render(data);
+}
+
+export function Await(props) @{
+	@try {
+		<AwaitInner promise={props.promise} render={props.children} />
+	} @pending {
+		<>
+			{props.fallback}
+		</>
+	}
+}

package/src/Await.tsrx.d.ts

@@ -0,0 +1,6 @@
+// Type declaration for the .tsrx component (resolved by relative path).
+export declare const Await: (props: {
+	promise: any;
+	children: (data: any) => unknown;
+	fallback?: unknown;
+}) => unknown;

package/src/CatchBoundary.tsrx

@@ -0,0 +1,91 @@
+// react-router's CatchBoundary + default ErrorComponent, 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:
+//   - renders `children` until a descendant throws during render/effects;
+//   - then renders `errorComponent` with `{ error, reset }`;
+//   - `onCatch(error, errorInfo)` fires once per caught error (componentDidCatch
+//     parity). It runs during the catch-branch render — BEFORE the error UI — so
+//     an onCatch that rethrows (Match forwards `notFound()` errors this way)
+//     propagates to the parent boundary exactly like a throwing componentDidCatch;
+//   - when `getResetKey()` changes while an error is showing, the boundary resets
+//     and re-renders `children` (upstream clears the error in
+//     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';
+
+export function CatchBoundary(props) @{
+	@try {
+		<>
+			{props.children}
+		</>
+	} @catch (error, reset) {
+		<CatchErrorView
+			error={error}
+			reset={reset}
+			getResetKey={props.getResetKey}
+			errorComponent={props.errorComponent}
+			onCatch={props.onCatch}
+		/>
+	}
+}
+
+function CatchErrorView(props) @{
+	// componentDidCatch parity — once per distinct caught error, during render so a
+	// rethrow (the notFound-forwarding path) escapes to the parent boundary.
+	const reported = useRef(null);
+	if (reported.current !== props.error) {
+		reported.current = props.error;
+		if (props.onCatch) props.onCatch(props.error, { componentStack: '' });
+	}
+
+	// Reset when the reset key rolls (navigation). Skip the mount render — the key
+	// captured while catching is the baseline.
+	const resetKey =
+		props.getResetKey ? props.getResetKey() : undefined;
+	const keyRef = useRef(resetKey);
+	useLayoutEffect(() => {
+		if (keyRef.current !== resetKey) {
+			keyRef.current = resetKey;
+			props.reset();
+		}
+	}, [resetKey]);
+
+	const ErrorComp = props.errorComponent ?? ErrorComponent;
+
+	<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) @{
+	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/CatchBoundary.tsrx.d.ts

@@ -0,0 +1,8 @@
+// Type declaration for the .tsrx components (resolved by relative path).
+export declare const CatchBoundary: (props: {
+	getResetKey?: () => number | string;
+	errorComponent?: unknown;
+	onCatch?: (error: any, errorInfo: { componentStack: string }) => void;
+	children?: unknown;
+}) => unknown;
+export declare const ErrorComponent: (props: { error: any; reset?: () => void }) => unknown;

package/src/ClientOnly.tsrx

@@ -0,0 +1,21 @@
+// ClientOnly / useHydrated — port of react-router's ClientOnly.tsx. Renders
+// children only once the client has hydrated: `useHydrated` reads a constant
+// external store whose server snapshot is `false` and client snapshot is
+// `true`, so SSR (and the hydration render) yield the fallback and the first
+// client-only render onward yields the children. Authored in .tsrx so the
+// compiler slots the hook calls (and withSlot-disambiguates useHydrated's
+// call sites).
+import { useSyncExternalStore } from 'octane';
+
+const subscribe = () => () => {};
+
+export function useHydrated() {
+	return useSyncExternalStore(subscribe, () => true, () => false);
+}
+
+export function ClientOnly(props) @{
+	const hydrated = useHydrated();
+	<>
+		{hydrated ? props.children : props.fallback ?? null}
+	</>
+}

package/src/ClientOnly.tsrx.d.ts

@@ -0,0 +1,3 @@
+// Type declaration for the .tsrx module (resolved by relative path).
+export declare const ClientOnly: (props: { children?: unknown; fallback?: unknown }) => unknown;
+export declare const useHydrated: () => boolean;

package/src/Link.tsrx

@@ -0,0 +1,32 @@
+// A navigating anchor — a thin shell over `useLinkProps` (link.ts), which
+// carries ALL of react-router Link's behavior: href building (mask-aware),
+// external-URL + dangerous-protocol handling, active-state detection,
+// preloading (intent/viewport/render), and the navigate click handler with
+// replace/resetScroll/hashScrollIntoView/viewTransition/startTransition/
+// ignoreBlocker forwarded. Children may be a render prop —
+// `{({ isActive, isTransitioning }) => …}` — and `createLink` renders a custom
+// component via the internal `_asChild` prop. Ref is a prop (octane's model —
+// no forwardRef); `disabled` renders without an href + role="link" (upstream
+// drops the anchor's disabled attribute; the aria props carry the state).
+import { isChildrenBlock } from 'octane';
+import { useLinkProps } from './link.ts';
+
+export function Link(props) @{
+	const { _asChild: AsChild, children, ...rest } = props;
+	const linkProps = useLinkProps(rest);
+	const { disabled: _disabled, ...aProps } = linkProps;
+
+	const resolvedChildren =
+		typeof children === 'function' && !isChildrenBlock(children)
+			? children({
+					isActive: linkProps['data-status'] === 'active',
+					isTransitioning: linkProps['data-transitioning'] === 'transitioning',
+				})
+			: children;
+
+	@if (AsChild) {
+		<AsChild {...linkProps}>{resolvedChildren}</AsChild>
+	} @else {
+		<a {...aProps}>{resolvedChildren}</a>
+	}
+}

package/src/Link.tsrx.d.ts

@@ -0,0 +1,4 @@
+// Type declaration for the .tsrx component (resolved by relative path). Props are
+// permissive for v1 (the full type-safe `to`/`params`/`search` surface from
+// react-router's `LinkProps` is a follow-up).
+export declare const Link: (props: Record<string, unknown>) => unknown;

package/src/Match.tsrx

@@ -0,0 +1,204 @@
+// Renders one route match — port of react-router's Match.tsx (MatchView +
+// MatchInner + OnRendered). `Match` subscribes to the match's routeId and the
+// router's `loadedAt` (the error-boundary reset key), resolves the route's
+// boundary components, and composes the pipeline exactly like upstream:
+//
+//   Shell > matchContext > Suspense? > CatchBoundary? > CatchNotFound? > MatchInner
+//
+// Each boundary is only present when the route (or router defaults) configured a
+// 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
+// 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 {
+	createControlledPromise,
+	getLocationChangeInfo,
+	isNotFound,
+	rootRouteId,
+} from '@tanstack/router-core';
+import { useStore } from './useStore.ts';
+import { useRouter, matchContext } from './context.ts';
+import { Outlet } from './Outlet.tsrx';
+import { RouteNotFound } from './RouteNotFound.tsrx';
+import { CatchBoundary, ErrorComponent } from './CatchBoundary.tsrx';
+import { CatchNotFound } from './not-found.tsrx';
+import { SafeFragment } from './SafeFragment.tsrx';
+
+export function Match(props) @{
+	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 PendingComponent = route.options.pendingComponent ?? router.options.defaultPendingComponent;
+	const routeErrorComponent = route.options.errorComponent ?? router.options.defaultErrorComponent;
+	const routeOnCatch = route.options.onCatch ?? router.options.defaultOnCatch;
+	const routeNotFoundComponent = route.isRoot
+		? route.options.notFoundComponent ?? router.options.notFoundRoute?.options.component
+		: route.options.notFoundComponent;
+
+	// Boundary presence, per upstream MatchView. The root route only gets a
+	// Suspense boundary when explicitly opted in via wrapInSuspense.
+	const SuspenseWrap =
+		(!route.isRoot || route.options.wrapInSuspense) &&
+		(route.options.wrapInSuspense ?? PendingComponent ?? routeErrorComponent?.preload)
+			? Suspense
+			: SafeFragment;
+	const CatchWrap = routeErrorComponent ? CatchBoundary : SafeFragment;
+	const NotFoundWrap = routeNotFoundComponent ? CatchNotFound : SafeFragment;
+	const ShellComponent = route.isRoot ? route.options.shellComponent ?? SafeFragment : SafeFragment;
+
+	const pendingElement =
+		PendingComponent ? createElement(PendingComponent, {}) : null;
+	const parentRouteId = route.parentRoute?.id;
+
+	<ShellComponent>
+		<matchContext.Provider value={props.matchId}>
+			<SuspenseWrap fallback={pendingElement}>
+				<CatchWrap
+					getResetKey={() => resetKey}
+					errorComponent={routeErrorComponent || ErrorComponent}
+					onCatch={(error, errorInfo) => {
+						if (isNotFound(error)) {
+							error.routeId ??= routeId;
+							throw error;
+						}
+						if (routeOnCatch) routeOnCatch(error, errorInfo);
+					}}
+				>
+					<NotFoundWrap
+						fallback={(error) => {
+							error.routeId ??= routeId;
+
+							if (
+								!routeNotFoundComponent || error.routeId && error.routeId !== routeId ||
+									!error.routeId && !route.isRoot
+							) {
+								throw error;
+							}
+							return createElement(routeNotFoundComponent, error);
+						}}
+					>
+						<MatchInner matchId={props.matchId} />
+					</NotFoundWrap>
+				</CatchWrap>
+			</SuspenseWrap>
+		</matchContext.Provider>
+		@if (parentRouteId === rootRouteId) {
+			<OnRendered />
+		}
+	</ShellComponent>
+}
+
+function MatchInner(props) {
+	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];
+
+	// 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];
+
+	if (match._displayPending) {
+		use(getMatchPromise('displayPendingPromise'));
+	}
+
+	if (match._forcePending) {
+		use(getMatchPromise('minPendingPromise'));
+	}
+
+	if (match.status === 'pending') {
+		// Once pending UI shows, keep it up for at least pendingMinMs.
+		const pendingMinMs = route.options.pendingMinMs ?? router.options.defaultPendingMinMs;
+		if (pendingMinMs) {
+			const routerMatch = router.getMatch(match.id);
+			if (routerMatch && !routerMatch._nonReactive.minPendingPromise) {
+				const minPendingPromise = createControlledPromise();
+				routerMatch._nonReactive.minPendingPromise = minPendingPromise;
+				setTimeout(() => {
+					minPendingPromise.resolve();
+					routerMatch._nonReactive.minPendingPromise = undefined;
+				}, pendingMinMs);
+			}
+		}
+		use(getMatchPromise('loadPromise'));
+	}
+
+	if (match.status === 'notFound') {
+		return createElement(RouteNotFound, { routeId, error: match.error });
+	}
+
+	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'));
+	}
+
+	if (match.status === 'error') {
+		throw match.error;
+	}
+
+	const Comp = route.options.component ?? router.options.defaultComponent;
+	const remountFn = route.options.remountDeps ?? router.options.defaultRemountDeps;
+	const remountDeps =
+		remountFn
+			? remountFn({
+					routeId,
+					loaderDeps: match.loaderDeps,
+					params: match._strictParams,
+					search: match._strictSearch,
+				})
+			: undefined;
+	const key =
+		remountDeps ? JSON.stringify(remountDeps) : undefined;
+	if (Comp) return createElement(Comp, key !== undefined ? { key } : {});
+	return createElement(Outlet, {});
+}
+
+// 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
+// location in a ref because by effect time Transitioner has already advanced
+// `resolvedLocation` to the new location.
+function OnRendered() @{
+	const router = useRouter();
+	const prevResolvedLocationRef = useRef(undefined);
+	const renderedLocationKey = useStore(
+		router.stores.resolvedLocation,
+		(loc) => loc?.state.__TSR_key,
+	);
+
+	useLayoutEffect(() => {
+		const currentResolvedLocation = router.stores.resolvedLocation.get();
+		const previousResolvedLocation = prevResolvedLocationRef.current;
+
+		if (
+			currentResolvedLocation &&
+				(!previousResolvedLocation ||
+					previousResolvedLocation.href !== currentResolvedLocation.href)
+		) {
+			router.emit({
+				type: 'onRendered',
+				...getLocationChangeInfo(
+					router.stores.location.get(),
+					previousResolvedLocation ?? currentResolvedLocation,
+				),
+			});
+		}
+		prevResolvedLocationRef.current = currentResolvedLocation;
+	}, [renderedLocationKey, router]);
+
+	<></>
+}

package/src/Match.tsrx.d.ts

@@ -0,0 +1,2 @@
+// Type declaration for the .tsrx component (resolved by relative path).
+export declare const Match: (props: { matchId: string }) => unknown;

package/src/MatchRoute.tsrx

@@ -0,0 +1,32 @@
+// useMatchRoute / MatchRoute — port of react-router's Matches.tsx matcher pair.
+// The hook subscribes to `matchRouteDeps` (location href + resolved href +
+// status) so the matcher re-evaluates per navigation, and returns
+// `matchRoute(opts)` → 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';
+
+export function useMatchRoute() {
+	const router = useRouter();
+	useStore(router.stores.matchRouteDeps, (d) => d);
+	return useCallback((opts) => {
+		const { pending, caseSensitive, fuzzy, includeSearch, ...rest } = opts;
+		return router.matchRoute(rest, { pending, caseSensitive, fuzzy, includeSearch });
+	}, [router]);
+}
+
+export function MatchRoute(props) @{
+	const matchRoute = useMatchRoute();
+	const params = matchRoute(props);
+	const out =
+		typeof props.children === 'function' && !isChildrenBlock(props.children)
+			? props.children(params)
+			: params
+				? props.children
+				: null;
+	<>
+		{out}
+	</>
+}

package/src/MatchRoute.tsrx.d.ts

@@ -0,0 +1,3 @@
+// Type declaration for the .tsrx module (resolved by relative path).
+export declare const MatchRoute: (props: Record<string, unknown>) => unknown;
+export declare const useMatchRoute: () => (opts: Record<string, unknown>) => unknown;

package/src/Matches.tsrx

@@ -0,0 +1,58 @@
+// Renders the navigation engine + the match tree root — port of react-router's
+// Matches.tsx. Structure mirrors upstream:
+//
+//   InnerWrap? > Suspense(root pending) > Transitioner + MatchesInner
+//   MatchesInner: matchContext(firstId) > global CatchBoundary? > Match(firstId)
+//
+// The root Suspense is ALWAYS present on the client (fallback is the root
+// route's pendingComponent ?? defaultPendingComponent ?? null) — it's the
+// already-revealed boundary that lets a navigation transition hold the current
+// page when the next route suspends without a boundary of its own. The global
+// CatchBoundary (opt out: `disableGlobalCatchBoundary`) renders the generic
+// 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 } from './context.ts';
+import { Transitioner } 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 PendingComponent =
+		rootRoute.options.pendingComponent ?? router.options.defaultPendingComponent;
+	const pendingElement =
+		PendingComponent ? createElement(PendingComponent, {}) : null;
+	const InnerWrap = router.options.InnerWrap ?? SafeFragment;
+
+	// `createRouter({ scrollRestoration: true })` wires scroll save/restore here, so
+	// it works without the (deprecated) <ScrollRestoration/> component.
+	useLayoutEffect(() => {
+		if (router.options.scrollRestoration) setupScrollRestoration(router);
+	}, [router]);
+
+	<InnerWrap>
+		<Suspense fallback={pendingElement}>
+			<Transitioner />
+			<MatchesInner />
+		</Suspense>
+	</InnerWrap>
+}
+
+function MatchesInner() @{
+	const router = useRouter();
+	const matchId = useStore(router.stores.firstId, (id) => id);
+	const resetKey = useStore(router.stores.loadedAt, (l) => l);
+	const CatchWrap = router.options.disableGlobalCatchBoundary ? SafeFragment : CatchBoundary;
+
+	<matchContext.Provider value={matchId}>
+		<CatchWrap getResetKey={() => resetKey} errorComponent={ErrorComponent}>
+			@if (matchId) {
+				<Match matchId={matchId} />
+			}
+		</CatchWrap>
+	</matchContext.Provider>
+}

package/src/Matches.tsrx.d.ts

@@ -0,0 +1,2 @@
+// Type declaration for the .tsrx component (resolved by relative path).
+export declare const Matches: () => unknown;