@octanejs/remix-router 0.1.0

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,90 @@
+# @octanejs/remix-router
+
+[react-router](https://reactrouter.com) for the [octane](https://github.com/octanejs/octane) UI framework.
+
+react-router v7 ships as a single package, so this port **vendors the
+framework-agnostic router core byte-close** (loaders, actions, redirects,
+matching, history — validated by 161 of upstream's own router unit tests
+running against the vendored copy) and transcribes the React layer onto
+octane's hooks. The shipped surface matches react-router 1:1 — existing code
+works by changing the import.
+
+**The port is complete — full export parity.** Data mode, declarative mode
+(`MemoryRouter`, `<Routes>`/`<Route>`, `<Navigate>`), the DOM entry points
+(`BrowserRouter`/`HashRouter`, `createBrowserRouter`/`createHashRouter`,
+`NavLink`, `useSearchParams`), mutations (`Form`, `useSubmit`,
+`useFetcher`/`useFetchers`), guards + scroll (`useBlocker`,
+`unstable_usePrompt`, `ScrollRestoration`, `useBeforeUnload`,
+`useViewTransitionState`), static SSR (`StaticRouter`,
+`StaticRouterProvider`, `createStaticHandler`/`createStaticRouter` on
+`octane/server`), and the cookie/session server runtime (`createCookie`,
+`createSession`, `createCookieSessionStorage`, …). Framework mode
+(`Meta`/`Links`/`Scripts`, `createRequestHandler`) and RSC are permanently out
+of scope — those names exist as throwing stubs so
+`tests/conformance/parity.test.ts` pins the surface at exact parity
+([docs/remix-router-port-plan.md](../../docs/remix-router-port-plan.md) has
+the scope policy).
+
+```tsx
+// before
+import { createBrowserRouter, RouterProvider, Link, useLoaderData } from 'react-router';
+// after
+import { createBrowserRouter, RouterProvider, Link, useLoaderData } from '@octanejs/remix-router';
+
+const router = createBrowserRouter([
+  {
+    path: '/',
+    Component: Layout,
+    children: [
+      { index: true, Component: Home },
+      { path: 'users/:id', loader: fetchUser, Component: User, errorElement: <Oops /> },
+    ],
+  },
+]);
+
+function App() @{
+  <RouterProvider router={router} />
+}
+
+function User() @{
+  const user = useLoaderData();
+  <h1>{user.name as string}</h1>
+}
+```
+
+## Entry points
+
+| import | what you get | notes |
+| --- | --- | --- |
+| `@octanejs/remix-router` | the vendored core surface (matchPath, redirect, data, …) + `createMemoryRouter`, `RouterProvider`, `Outlet`, `Await`, `Link`, `useLinkClickHandler`, the full read-hook family (`useLoaderData`, `useNavigate`, `useNavigation`, `useRouteError`, …), declarative mode (`MemoryRouter`, `Routes`/`Route`, `Navigate`, `createRoutesFromChildren`/`Elements`), the DOM layer (`createBrowserRouter`/`createHashRouter`, `BrowserRouter`/`HashRouter`/`unstable_HistoryRouter`, `NavLink`, `useSearchParams`), mutations (`Form`, `useSubmit`, `useFormAction`, `useFetcher`/`useFetchers`), guards/scroll (`useBlocker`, `ScrollRestoration`, …), static SSR (`StaticRouter`/`StaticRouterProvider`/`createStaticHandler`/`createStaticRouter`), and cookies/sessions (`createCookie`, `createCookieSessionStorage`, …) | full parity |
+| `@octanejs/remix-router/dom` | `RouterProvider` with octane's `flushSync` wired in | mirror of `react-router/dom` |
+
+## How it works
+
+- The router core under `src/lib/router/` is vendored verbatim from
+  react-router 7.18.1 (`scripts/vendor-remix-router.mjs`; two documented
+  type-only deviations; hand-edits prohibited).
+- `RouterProvider` preserves upstream's exact commit paths — `startTransition`
+  wrapping, the `flushSync` option, and the ViewTransition dance (dormant until
+  Phase E) — on octane's `useState`/`useLayoutEffect`/`useOptimistic`/
+  `startTransition`/`flushSync`.
+- `errorElement`/`useRouteError` run on octane's `@try/@catch` (octane has no
+  class components); `<Await>` suspends through octane's `use()` with
+  upstream's TrackedPromise decoration kept verbatim, so `useAsyncValue`/
+  `useAsyncError` are unchanged. Render-prop children work via octane's
+  `isChildrenBlock` guard.
+- `<Routes>` accepts BOTH children forms: descriptor children
+  (`createRoutesFromElements`, `{expr}` arrays) are walked upstream-style,
+  while the natural `.tsrx` block-children authoring goes through a
+  registration collector — each `<Route>` registers its config in a pre-paint
+  layout effect, so the first paint already shows the matched route.
+  Registration order is mount order, which differs from upstream's source
+  order only for `matchRoutes` score ties (pinned + documented).
+- Refs are props (no `forwardRef`); hooks are keyed by octane's
+  compiler-injected per-call-site slots, forwarded through every custom hook.
+
+## Status
+
+Current scope, known divergences, and verification status are tracked in the
+generated [bindings status table](../../docs/bindings-status.md), sourced from
+this package's [`status.json`](./status.json).

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@octanejs/remix-router",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "octane": {
+    "hookSlots": {
+      "manual": [
+        "src"
+      ]
+    }
+  },
+  "description": "react-router for the octane renderer — the framework-agnostic router core vendored byte-close from react-router v7, with the React layer (RouterProvider, hooks, Link, boundaries) transcribed onto octane.",
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/remix-router"
+  },
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./dom": "./src/dom.ts"
+  },
+  "dependencies": {
+    "cookie": "^1.0.1",
+    "octane": "0.1.4"
+  },
+  "devDependencies": {
+    "@tsrx/react": "^0.2.37",
+    "esbuild": "^0.28.1",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "react-router": "7.18.1",
+    "react-router-dom": "7.18.1",
+    "vitest": "^4.1.9"
+  },
+  "scripts": {
+    "test": "vitest run"
+  }
+}

package/src/dom.ts

@@ -0,0 +1,16 @@
+// `@octanejs/remix-router/dom` — mirror of upstream `react-router/dom`
+// (dom-export.ts): the RouterProvider variant with flushSync wired in.
+// Upstream needs the react-dom split for this; octane is one package, so
+// this simply binds octane's flushSync.
+import { createElement, flushSync } from 'octane';
+import { RouterProvider as BaseRouterProvider } from './lib/components/RouterProvider.tsrx';
+import type { Router as DataRouter } from './lib/router/router';
+import type { ClientOnErrorFunction } from './lib/context';
+
+export function RouterProvider(props: {
+	router: DataRouter;
+	onError?: ClientOnErrorFunction;
+	useTransitions?: boolean;
+}) {
+	return createElement(BaseRouterProvider as any, { flushSync, ...props });
+}

package/src/index.ts

@@ -0,0 +1,267 @@
+// @octanejs/remix-router — react-router for the octane renderer.
+//
+// react-router v7 ships as a single package whose framework-agnostic core has
+// no runtime subpath, so the core (lib/router/* + framework-free lib helpers)
+// is VENDORED byte-close (see scripts/vendor-remix-router.mjs) and only the
+// React layer is transcribed onto octane's hooks. This entry mirrors upstream
+// packages/react-router/index.ts for everything the port has shipped so far —
+// the phased roadmap lives in docs/remix-router-port-plan.md, and
+// tests/conformance/parity.test.ts pins exactly which upstream exports are
+// still expected-missing per phase.
+//
+// Octane-specific: hooks are keyed by a compiler-injected per-call-site
+// Symbol appended as the LAST argument of every `use*` call; the hooks in
+// lib/hooks.ts forward that slot into their composed base hooks. Refs are
+// props (no forwardRef).
+
+// ── Vendored core (verbatim re-exports, upstream index.ts order) ───────────
+export { createContext, RouterContextProvider } from './lib/router/utils';
+export { Action as NavigationType, createPath, parsePath } from './lib/router/history';
+export type {
+	ServerInstrumentation,
+	ClientInstrumentation,
+	InstrumentRequestHandlerFunction,
+	InstrumentRouterFunction,
+	InstrumentRouteFunction,
+	InstrumentationHandlerResult,
+} from './lib/router/instrumentation';
+export { IDLE_NAVIGATION, IDLE_FETCHER, IDLE_BLOCKER } from './lib/router/router';
+export {
+	data,
+	generatePath,
+	isRouteErrorResponse,
+	matchPath,
+	matchRoutes,
+	redirect,
+	redirectDocument,
+	replace,
+	resolvePath,
+} from './lib/router/utils';
+export type { InitialEntry, Location, Path, To } from './lib/router/history';
+export type {
+	HydrationState,
+	GetScrollPositionFunction,
+	GetScrollRestorationKeyFunction,
+	StaticHandlerContext,
+	Fetcher,
+	Navigation,
+	NavigationStates,
+	RelativeRoutingType,
+	Blocker,
+	BlockerFunction,
+	Router as DataRouter,
+	RouterState,
+	RouterInit,
+	RouterSubscriber,
+	RouterNavigateOptions,
+	RouterFetchOptions,
+	RevalidationState,
+} from './lib/router/router';
+export type {
+	ActionFunction,
+	ActionFunctionArgs,
+	DataRouteMatch,
+	DataRouteObject,
+	DataStrategyFunction,
+	DataStrategyFunctionArgs,
+	DataStrategyMatch,
+	DataStrategyResult,
+	ErrorResponse,
+	FormEncType,
+	FormMethod,
+	IndexRouteObject,
+	LazyRouteFunction,
+	LoaderFunction,
+	LoaderFunctionArgs,
+	MiddlewareFunction,
+	NonIndexRouteObject,
+	ParamParseKey,
+	Params,
+	PathMatch,
+	PathParam,
+	PathPattern,
+	RedirectFunction,
+	RouteMatch,
+	RouteObject,
+	ShouldRevalidateFunction,
+	ShouldRevalidateFunctionArgs,
+	UIMatch,
+} from './lib/router/utils';
+export { href } from './lib/href';
+export { createSearchParams } from './lib/dom/dom';
+export type {
+	FetcherSubmitOptions,
+	ParamKeyValuePair,
+	SubmitOptions,
+	URLSearchParamsInit,
+	SubmitTarget,
+} from './lib/dom/dom';
+
+// ── React layer (Phases A + B) ─────────────────────────────────────────────
+export type { NavigateOptions, Navigator, ClientOnErrorFunction } from './lib/context';
+export { AwaitContextProvider as UNSAFE_AwaitContextProvider } from './lib/context';
+export { Await } from './lib/Await.tsrx';
+export { Router } from './lib/components/Router.tsrx';
+export { RouterProvider, Outlet } from './lib/components/RouterProvider.tsrx';
+export { createMemoryRouter, renderMatches } from './lib/components/utils';
+export type { MemoryRouterOpts } from './lib/components/utils';
+export { MemoryRouter } from './lib/components/MemoryRouter.tsrx';
+export { Navigate } from './lib/components/Navigate';
+export type { NavigateProps } from './lib/components/Navigate';
+export { Routes } from './lib/components/Routes.tsrx';
+export {
+	Route,
+	createRoutesFromChildren,
+	createRoutesFromElements,
+} from './lib/components/routes-collector';
+export type { NavigateFunction } from './lib/hooks';
+export {
+	useActionData,
+	useAsyncError,
+	useAsyncValue,
+	useBlocker,
+	useHref,
+	useInRouterContext,
+	useLoaderData,
+	useLocation,
+	useMatch,
+	useMatches,
+	useNavigate,
+	useNavigation,
+	useNavigationType,
+	useOutlet,
+	useOutletContext,
+	useParams,
+	useResolvedPath,
+	useRevalidator,
+	useRouteError,
+	useRouteLoaderData,
+	useRoutes,
+	useRoute as unstable_useRoute,
+	useRouterState as unstable_useRouterState,
+} from './lib/hooks';
+export type {
+	unstable_RouterState,
+	unstable_RouterStateActiveVariant,
+	unstable_RouterStatePendingVariant,
+	unstable_RouterStateMatch,
+} from './lib/hooks';
+
+// ── DOM layer (Phases A + C + D + E + F) ────────────────────────────────────
+export { Link } from './lib/dom/Link.tsrx';
+export { useLinkClickHandler } from './lib/dom/hooks';
+export { NavLink } from './lib/dom/NavLink.tsrx';
+export type { NavLinkRenderProps } from './lib/dom/NavLink.tsrx';
+export {
+	BrowserRouter,
+	HashRouter,
+	HistoryRouter as unstable_HistoryRouter,
+} from './lib/dom/routers.tsrx';
+export {
+	createBrowserRouter,
+	createHashRouter,
+	useSearchParams,
+	useSubmit,
+	useFormAction,
+	useFetcher,
+	useFetchers,
+	useViewTransitionState,
+	useBeforeUnload,
+	usePrompt as unstable_usePrompt,
+	ScrollRestoration,
+	useScrollRestoration as UNSAFE_useScrollRestoration,
+} from './lib/dom/lib';
+export type {
+	DOMRouterOpts,
+	SetURLSearchParams,
+	SubmitFunction,
+	FetcherSubmitFunction,
+	FetcherWithComponents,
+} from './lib/dom/lib';
+export { Form } from './lib/dom/Form.tsrx';
+export {
+	StaticRouter,
+	StaticRouterProvider,
+	createStaticHandler,
+	createStaticRouter,
+} from './lib/dom/server.tsrx';
+
+// ── UNSAFE_ surface (shipped subset) ────────────────────────────────────────
+export {
+	createMemoryHistory as UNSAFE_createMemoryHistory,
+	createBrowserHistory as UNSAFE_createBrowserHistory,
+	createHashHistory as UNSAFE_createHashHistory,
+	invariant as UNSAFE_invariant,
+} from './lib/router/history';
+export { createRouter as UNSAFE_createRouter } from './lib/router/router';
+export { ErrorResponseImpl as UNSAFE_ErrorResponseImpl } from './lib/router/utils';
+export {
+	DataRouterContext as UNSAFE_DataRouterContext,
+	DataRouterStateContext as UNSAFE_DataRouterStateContext,
+	FetchersContext as UNSAFE_FetchersContext,
+	LocationContext as UNSAFE_LocationContext,
+	NavigationContext as UNSAFE_NavigationContext,
+	RouteContext as UNSAFE_RouteContext,
+	ViewTransitionContext as UNSAFE_ViewTransitionContext,
+} from './lib/context';
+export {
+	hydrationRouteProperties as UNSAFE_hydrationRouteProperties,
+	mapRouteProperties as UNSAFE_mapRouteProperties,
+} from './lib/components/utils';
+export {
+	WithComponentProps as UNSAFE_WithComponentProps,
+	withComponentProps as UNSAFE_withComponentProps,
+	WithHydrateFallbackProps as UNSAFE_WithHydrateFallbackProps,
+	withHydrateFallbackProps as UNSAFE_withHydrateFallbackProps,
+	WithErrorBoundaryProps as UNSAFE_WithErrorBoundaryProps,
+	withErrorBoundaryProps as UNSAFE_withErrorBoundaryProps,
+} from './lib/components/with-props';
+export type { Register } from './lib/types/register';
+export type { MiddlewareEnabled as UNSAFE_MiddlewareEnabled } from './lib/types/future';
+
+// ── Server runtime (vendored cookie/session surface) ────────────────────────
+export { createCookie, isCookie } from './lib/server-runtime/cookies';
+export type {
+	Cookie,
+	CookieOptions,
+	CookieParseOptions,
+	CookieSerializeOptions,
+	CookieSignatureOptions,
+} from './lib/server-runtime/cookies';
+export { createSession, isSession, createSessionStorage } from './lib/server-runtime/sessions';
+export type {
+	Session,
+	SessionData,
+	SessionStorage,
+	SessionIdStorageStrategy,
+	FlashSessionData,
+} from './lib/server-runtime/sessions';
+export { createCookieSessionStorage } from './lib/server-runtime/sessions/cookieStorage';
+export { createMemorySessionStorage } from './lib/server-runtime/sessions/memoryStorage';
+export { ServerMode as UNSAFE_ServerMode } from './lib/server-runtime/mode';
+
+// ── Framework-mode + RSC surface (throwing stubs — see framework-stubs.ts) ──
+export {
+	Meta,
+	Links,
+	Scripts,
+	PrefetchPageLinks,
+	ServerRouter,
+	createRoutesStub,
+	createRequestHandler,
+	unstable_setDevServerHooks,
+	FrameworkContext as UNSAFE_FrameworkContext,
+	RemixErrorBoundary as UNSAFE_RemixErrorBoundary,
+	getPatchRoutesOnNavigationFunction as UNSAFE_getPatchRoutesOnNavigationFunction,
+	useFogOFWarDiscovery as UNSAFE_useFogOFWarDiscovery,
+	getHydrationData as UNSAFE_getHydrationData,
+	createClientRoutes as UNSAFE_createClientRoutes,
+	createClientRoutesWithHMRRevalidationOptOut as UNSAFE_createClientRoutesWithHMRRevalidationOptOut,
+	shouldHydrateRouteLoader as UNSAFE_shouldHydrateRouteLoader,
+	SingleFetchRedirectSymbol as UNSAFE_SingleFetchRedirectSymbol,
+	decodeViaTurboStream as UNSAFE_decodeViaTurboStream,
+	getTurboStreamSingleFetchDataStrategy as UNSAFE_getTurboStreamSingleFetchDataStrategy,
+	routeRSCServerRequest as unstable_routeRSCServerRequest,
+	RSCStaticRouter as unstable_RSCStaticRouter,
+	RSCDefaultRootErrorBoundary as UNSAFE_RSCDefaultRootErrorBoundary,
+} from './lib/framework-stubs';

package/src/internal.ts

@@ -0,0 +1,37 @@
+// Slot mechanics shared by the binding's plain-`.ts` hooks (same helper as
+// @octanejs/tanstack-query). The octane compiler injects a per-call-site Symbol slot into
+// every hook call in compiled files; these binding files are NOT compiled, so a
+// hook here receives the caller's slot as its trailing argument and derives a
+// distinct sub-slot for each base hook it composes.
+
+// Memoized: subSlot runs on EVERY hook call every render; the cache returns the
+// identical Symbol.for-interned value without the concat + registry lookup.
+const subSlotCache = new Map<symbol, Map<string, symbol>>();
+// Tag-only symbols for the slotless-caller case (see below).
+const bareTagCache = new Map<string, symbol>();
+
+export function subSlot(slot: symbol | undefined, tag: string): symbol {
+	// No inherited slot (the caller was NOT compiled — e.g. a vendored wrapper
+	// hook): return a stable TAG-ONLY symbol rather than undefined. The runtime
+	// combines it with the ambient withSlot path, so sibling base hooks inside
+	// one composed hook stay DISTINCT per tag. Returning undefined here made
+	// them all resolve to the bare path — one shared slot, state collision.
+	if (slot === undefined) {
+		let bare = bareTagCache.get(tag);
+		if (bare === undefined) bareTagCache.set(tag, (bare = Symbol.for(':' + tag)));
+		return bare;
+	}
+	let byTag = subSlotCache.get(slot);
+	if (byTag === undefined) subSlotCache.set(slot, (byTag = new Map()));
+	let sym = byTag.get(tag);
+	if (sym === undefined) byTag.set(tag, (sym = Symbol.for((slot.description ?? '') + ':' + tag)));
+	return sym;
+}
+
+// Split the compiler-injected trailing slot off a hook's runtime args, returning
+// the user args (everything before it) and the slot.
+export function splitSlot(args: any[]): [any[], symbol | undefined] {
+	const tail = args[args.length - 1];
+	const slot = typeof tail === 'symbol' ? (tail as symbol) : undefined;
+	return [slot !== undefined ? args.slice(0, -1) : args, slot];
+}

package/src/lib/Await.tsrx

@@ -0,0 +1,145 @@
+// Await — port of react-router@7.18.1 lib/components.tsx's Await +
+// AwaitErrorBoundary + ResolveAwait onto octane. The class boundary becomes an
+// octane @try/@catch; the "throw to the suspense boundary" becomes use(promise)
+// (octane's suspend primitive); the TrackedPromise decoration (_tracked/_data/
+// _error defineProperty) is kept verbatim so useAsyncValue/useAsyncError and
+// AwaitContext consumers stay upstream-identical.
+//
+// Boundary layering (upstream parity): a class boundary does NOT catch its own
+// render throws, so the no-errorElement rethrow (bubble to the ROUTE boundary)
+// and the pending suspension live in AwaitBody, OUTSIDE Await's render-error
+// catch; the @try/@catch wraps only the CHILDREN render (what upstream's
+// componentDidCatch actually sees).
+import { use, useCallback, useContext, useRef, isChildrenBlock } from 'octane';
+import { AwaitContext, DataRouterContext, DataRouterStateContext } from './context.ts';
+import { getRoutePattern } from './router/utils.ts';
+
+// NOTE: children are forwarded in PROP position (children={...}) through the
+// internal layers — a JSX `{props.children}` child would be re-wrapped into an
+// octane children BLOCK at each hop, destroying the render-prop identity the
+// isChildrenBlock guard in ResolveAwait relies on.
+export function Await(props) @{
+	const dataRouterContext = useContext(DataRouterContext);
+	const dataRouterStateContext = useContext(DataRouterStateContext);
+
+	const onError = useCallback((error, errorInfo) => {
+		if (dataRouterContext && dataRouterContext.onError && dataRouterStateContext) {
+			dataRouterContext.onError(error, {
+				location: dataRouterStateContext.location,
+				params: dataRouterStateContext.matches[0]?.params || {},
+				pattern: getRoutePattern(dataRouterStateContext.matches),
+				errorInfo,
+			});
+		}
+	}, [dataRouterContext, dataRouterStateContext]);
+
+	<AwaitBody
+		resolve={props.resolve}
+		errorElement={props.errorElement}
+		onError={onError}
+		children={props.children}
+	/>
+}
+
+function AwaitBody(props) @{
+	// Upstream AwaitErrorBoundary.render() tracking logic, verbatim.
+	let promise;
+	let status = 'pending';
+
+	if (!(props.resolve instanceof Promise)) {
+		// Didn't get a promise - provide as a resolved promise
+		status = 'success';
+		promise = Promise.resolve();
+		Object.defineProperty(promise, '_tracked', { get: () => true });
+		Object.defineProperty(promise, '_data', { get: () => props.resolve });
+	} else if (props.resolve._tracked) {
+		// Already tracked promise - check contents
+		promise = props.resolve;
+		status = '_error' in promise ? 'error' : '_data' in promise ? 'success' : 'pending';
+	} else {
+		// Raw (untracked) promise - track it
+		status = 'pending';
+		const resolve = props.resolve;
+		Object.defineProperty(resolve, '_tracked', { get: () => true });
+		promise = resolve.then((data) => Object.defineProperty(resolve, '_data', { get: () => data }), (
+			error,
+		) => {
+			// Log promise rejections
+			props.onError?.(error);
+			Object.defineProperty(resolve, '_error', { get: () => error });
+		});
+	}
+
+	if (status === 'error' && !props.errorElement) {
+		// No errorElement, throw to the nearest route-level error boundary.
+		// (Outside the children @try below — a boundary never catches its own
+		// render throw, upstream parity.)
+		throw props.resolve._error;
+	}
+
+	if (status === 'pending') {
+		// Suspend to the nearest boundary; the replay re-enters with
+		// _data/_error defined. use() is octane's suspend primitive (upstream
+		// throws the promise).
+		use(promise);
+	}
+
+	@if (status === 'error') {
+		<AwaitContext.Provider value={promise}>{props.errorElement}</AwaitContext.Provider>
+	} @else {
+		@try {
+			<AwaitContext.Provider value={promise}>
+				<ResolveAwait children={props.children} />
+			</AwaitContext.Provider>
+		} @catch (caught, reset) {
+			<AwaitCaught caught={caught} errorElement={props.errorElement} onError={props.onError} />
+		}
+	}
+}
+
+// A render error from the children — upstream's getDerivedStateFromError turns
+// it into a rejected tracked promise rendered through errorElement (or
+// rethrown when there is none).
+function AwaitCaught(props) @{
+	// componentDidCatch parity — once per distinct caught error, during render.
+	const reported = useRef(null);
+	if (reported.current !== props.caught) {
+		reported.current = props.caught;
+		if (props.onError) {
+			props.onError(props.caught, { componentStack: '' });
+		} else {
+			console.error('<Await> caught the following error during render', props.caught, {
+				componentStack: '',
+			});
+		}
+	}
+
+	if (!props.errorElement) {
+		// Rethrow from the catch branch → propagates to the parent boundary.
+		throw props.caught;
+	}
+
+	const renderError = props.caught;
+	const promise = Promise.reject().catch(() => {}); // Avoid unhandled rejection warnings
+	Object.defineProperty(promise, '_tracked', { get: () => true });
+	Object.defineProperty(promise, '_error', { get: () => renderError });
+
+	<AwaitContext.Provider value={promise}>{props.errorElement}</AwaitContext.Provider>
+}
+
+// Indirection to leverage useAsyncValue for a render-prop API on `<Await>`.
+// (useAsyncValue inlined via AwaitContext to keep this file free of a hooks.ts
+// dependency; identical semantics.)
+function ResolveAwait(props) @{
+	const value = useContext(AwaitContext);
+	const data = value?._data;
+	// Render-prop guard: octane children BLOCKS are functions too — only a real
+	// user render-prop gets called (isChildrenBlock idiom).
+	const toRender =
+		typeof props.children === 'function' && !isChildrenBlock(props.children)
+			? props.children(data)
+			: props.children;
+	<>
+		{toRender}
+	</>
+}

package/src/lib/Await.tsrx.d.ts

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