@real-router/react 0.24.1 → 0.25.0

package/dist/esm/useRouteEnter-CxjYofFa.d.mts

@@ -0,0 +1,279 @@
+import { ReactElement, ReactNode } from "react";
+import { State } from "@real-router/core";
+
+//#region src/components/modern/RouteView/types.d.ts
+interface RouteViewProps {
+  /** Route tree node name to subscribe to. "" for root. */
+  readonly nodeName: string;
+  /** <RouteView.Match>, <RouteView.Self>, and <RouteView.NotFound> elements. */
+  readonly children: ReactNode;
+}
+interface MatchProps {
+  /** Route segment to match against. */
+  readonly segment: string;
+  /** Exact match only (no descendants). Defaults to false. */
+  readonly exact?: boolean;
+  /** Preserve component state when deactivated (React Activity). Defaults to false. */
+  readonly keepAlive?: boolean;
+  /** Fallback content to show while children are suspended. */
+  readonly fallback?: ReactNode;
+  /** Content to render when matched. */
+  readonly children: ReactNode;
+}
+interface SelfProps {
+  /**
+   * Fallback content to show while children are suspended.
+   *
+   * Symmetric with `<RouteView.Match fallback>` — wraps children in
+   * `<Suspense>` when defined.
+   */
+  readonly fallback?: ReactNode;
+  /** Content to render when the active route name equals the parent RouteView's nodeName. */
+  readonly children: ReactNode;
+}
+interface NotFoundProps {
+  /** Content to render on UNKNOWN_ROUTE. */
+  readonly children: ReactNode;
+}
+//#endregion
+//#region src/components/modern/RouteView/components.d.ts
+declare function Match(_props: MatchProps): null;
+declare namespace Match {
+  var displayName: string;
+}
+declare function Self(_props: SelfProps): null;
+declare namespace Self {
+  var displayName: string;
+}
+declare function NotFound(_props: NotFoundProps): null;
+declare namespace NotFound {
+  var displayName: string;
+}
+//#endregion
+//#region src/components/modern/RouteView/RouteView.d.ts
+declare function RouteViewRoot({
+  nodeName,
+  children
+}: Readonly<RouteViewProps>): ReactElement | null;
+declare namespace RouteViewRoot {
+  var displayName: string;
+}
+declare const RouteView: typeof RouteViewRoot & {
+  Match: typeof Match;
+  Self: typeof Self;
+  NotFound: typeof NotFound;
+};
+//#endregion
+//#region src/hooks/useRouteExit.d.ts
+interface RouteExitContext {
+  /** The route being left. */
+  route: State;
+  /** The route being navigated to. */
+  nextRoute: State;
+  /**
+   * AbortSignal that fires when this navigation is superseded by a later
+   * one (rapid clicks). Already filtered: when the handler runs,
+   * `signal.aborted` is guaranteed to be `false`. Use
+   * `signal.addEventListener("abort", cleanup, { once: true })` for
+   * cleanup that must run on cancellation.
+   */
+  signal: AbortSignal;
+}
+interface UseRouteExitOptions {
+  /**
+   * Skip the handler when `route.name === nextRoute.name`
+   * (sort/filter/query-only navigations on the same route). Default:
+   * `true`.
+   */
+  skipSameRoute?: boolean;
+}
+type RouteExitHandler = (context: RouteExitContext) => void | Promise<void>;
+/**
+ * Subscribe to the router's leave-window with the universal guards baked
+ * in. Wraps `router.subscribeLeave` so consumers don't repeat the same
+ * boilerplate every time:
+ *
+ *   - **Reentrant abort pre-check**: if `signal.aborted` is already `true`
+ *     when the handler would run (rapid navigation superseded a slower
+ *     one), the handler is skipped entirely. `signal.addEventListener(
+ *     "abort", ...)` does not fire retroactively, so without this guard
+ *     downstream cleanup would never trigger.
+ *   - **Same-route skip**: by default, `route.name === nextRoute.name`
+ *     short-circuits the handler — query-only navigations (sort, filter,
+ *     pagination) skip the work. Opt out with `skipSameRoute: false`.
+ *   - **Stable handler reference**: the handler can change identity on
+ *     every render without causing resubscription — internal ref keeps
+ *     the latest handler accessible to the long-lived subscription.
+ *
+ * Returns nothing — the subscription's lifecycle is bound to the
+ * component's mount.
+ *
+ * If the handler returns a Promise, the router blocks on it. If the
+ * Promise resolves, navigation proceeds. If it rejects, the router emits
+ * `TRANSITION_CANCELLED` (existing core behavior, no change here).
+ *
+ * @example Animation
+ * ```tsx
+ * const ref = useRef<HTMLDivElement>(null);
+ *
+ * useRouteExit(async ({ signal }) => {
+ *   const el = ref.current;
+ *   if (!el) return;
+ *   el.classList.add("fade-out");
+ *   const cleanup = () => el.classList.remove("fade-out");
+ *   signal.addEventListener("abort", cleanup, { once: true });
+ *   try {
+ *     el.getBoundingClientRect();   // style flush
+ *     await Promise.allSettled(el.getAnimations().map((a) => a.finished));
+ *   } finally {
+ *     cleanup();
+ *   }
+ * });
+ * ```
+ *
+ * @example Auto-save form draft
+ * ```tsx
+ * useRouteExit(async ({ signal }) => {
+ *   if (formState.dirty) await api.saveDraft(formState, { signal });
+ * });
+ * ```
+ *
+ * @example Cancel inflight requests
+ * ```tsx
+ * useRouteExit(() => {
+ *   inflightController.abort();
+ * });
+ * ```
+ *
+ * @example Library-coordinated exit (motion / framer-motion)
+ * ```tsx
+ * const exitResolverRef = useRef<(() => void) | null>(null);
+ *
+ * useRouteExit(({ signal }) => {
+ *   return new Promise<void>((resolve) => {
+ *     exitResolverRef.current = resolve;
+ *     signal.addEventListener("abort", () => resolve(), { once: true });
+ *   });
+ * });
+ *
+ * const onExitComplete = () => exitResolverRef.current?.();
+ * // pass onExitComplete to <AnimatePresence>
+ * ```
+ *
+ * @example Reading rich transition metadata via `nextRoute.transition`
+ * ```tsx
+ * useRouteExit(({ route, nextRoute }) => {
+ *   // nextRoute.transition: TransitionMeta — preview of the upcoming nav
+ *   if (nextRoute.transition.segments.deactivated.includes("products")) {
+ *     // leaving the products subtree entirely — flush product-related caches
+ *     productCache.clear();
+ *   }
+ *   if (nextRoute.transition.redirected) {
+ *     // skip animation when navigation arrived via redirect
+ *     return;
+ *   }
+ * });
+ * ```
+ */
+declare function useRouteExit(handler: RouteExitHandler, options?: UseRouteExitOptions): void;
+//#endregion
+//#region src/hooks/useRouteEnter.d.ts
+interface RouteEnterContext {
+  /** The route that was just activated. */
+  route: State;
+  /** The route that was active immediately before this navigation. */
+  previousRoute: State;
+}
+type RouteEnterHandler = (context: RouteEnterContext) => void;
+interface UseRouteEnterOptions {
+  /**
+   * Skip the handler when `route.name === previousRoute.name`
+   * (sort/filter/query-only navigations on the same route). Default:
+   * `true`. Symmetric with `useRouteExit`'s same-name option.
+   */
+  skipSameRoute?: boolean;
+}
+/**
+ * Fire `handler` once when the component mounts as a result of a
+ * navigation. Mirror of `useRouteExit` for the entry side.
+ *
+ * What this hook covers that ad-hoc `useEffect` + `useRoute()` doesn't:
+ *
+ *   - **Skip-initial**: handler is skipped when there is no
+ *     `previousRoute` (i.e. first-load mount). Most consumers want to
+ *     fire side effects only on real navigations, not on hydration.
+ *   - **Same-route skip** (default): handler is skipped when
+ *     `route.name === previousRoute.name`. Sort/filter/query-only
+ *     navigations re-run the effect (because `route` reference changes
+ *     in `useRoute`'s snapshot), but they are not "entries" in the
+ *     animation / analytics sense — the component instance has stayed
+ *     mounted throughout. Opt out with `skipSameRoute: false` when
+ *     the handler legitimately needs to fire on every navigation
+ *     (e.g. analytics tracking each query-param flip).
+ *   - **StrictMode double-mount immunity**: in dev, React's StrictMode
+ *     runs every effect twice to surface bugs. Without a guard,
+ *     analytics fire twice, animations restart, focus jumps. The hook
+ *     tracks the last-handled `route` reference and short-circuits the
+ *     second pass.
+ *   - **Latest-handler ref**: the handler can change identity on every
+ *     render without re-running the effect — the registered wrapper
+ *     dispatches to whatever `handlerRef.current` points to.
+ *   - **Mount-time `route` / `previousRoute` snapshot**: the handler
+ *     receives the values that were live at the moment of mount, not
+ *     the latest ones (which may have moved on if the user navigated
+ *     again before the effect drained).
+ *
+ * Race-safety: `useRoute()` is wired through `useSyncExternalStore` from
+ * `@real-router/sources`, so by the time the new component's effect
+ * runs, the snapshot is the post-commit one. This is the reason we can
+ * read mount-time context from `useRoute()` instead of subscribing to
+ * `router.subscribe` directly (which fires before React schedules a
+ * re-render — the well-known race in distributed components).
+ *
+ * @example Direction-aware entry animation
+ * ```tsx
+ * useRouteEnter(({ route }) => {
+ *   const direction = route.context.browser?.direction;
+ *   ref.current?.classList.add(
+ *     direction === "back" ? "slide-from-left" : "slide-from-right",
+ *   );
+ * });
+ * ```
+ *
+ * @example Source-aware focus management
+ * ```tsx
+ * useRouteEnter(({ route }) => {
+ *   if (route.context.browser?.source === "navigate") {
+ *     headingRef.current?.focus();
+ *   }
+ * });
+ * ```
+ *
+ * @example Analytics page-enter event (skip-initial built-in)
+ * ```tsx
+ * useRouteEnter(({ route, previousRoute }) => {
+ *   analytics.track("page_enter", {
+ *     route: route.name,
+ *     from: previousRoute.name,
+ *   });
+ * });
+ * ```
+ *
+ * @example Reading rich transition metadata via `route.transition`
+ * ```tsx
+ * useRouteEnter(({ route }) => {
+ *   // route.transition: TransitionMeta — populated by core for every state
+ *   if (route.transition.redirected) {
+ *     showToast(`Redirected from ${route.transition.from}`);
+ *   }
+ *   if (route.transition.segments.activated.includes("products")) {
+ *     // products subtree just became active (could be products or
+ *     // products.detail). Useful for subtree-scoped side effects.
+ *   }
+ * });
+ * ```
+ */
+declare function useRouteEnter(handler: RouteEnterHandler, options?: UseRouteEnterOptions): void;
+//#endregion
+export { RouteExitContext as a, useRouteExit as c, NotFoundProps as d, RouteViewProps as f, useRouteEnter as i, RouteView as l, RouteEnterHandler as n, RouteExitHandler as o, SelfProps as p, UseRouteEnterOptions as r, UseRouteExitOptions as s, RouteEnterContext as t, MatchProps as u };
+//# sourceMappingURL=useRouteEnter-CxjYofFa.d.mts.map

package/dist/esm/useRouteEnter-CxjYofFa.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRouteEnter-CxjYofFa.d.mts","names":[],"sources":["../../src/components/modern/RouteView/types.ts","../../src/components/modern/RouteView/components.tsx","../../src/components/modern/RouteView/RouteView.tsx","../../src/hooks/useRouteExit.tsx","../../src/hooks/useRouteEnter.tsx"],"mappings":";;;;UAEiB,cAAA;;WAEN,QAAA;EAFM;EAAA,SAIN,QAAA,EAAU,SAAA;AAAA;AAAA,UAGJ,UAAA;EALN;EAAA,SAOA,OAAA;EALU;EAAA,SAOV,KAAA;EAPmB;EAAA,SASnB,SAAA;EANgB;EAAA,SAQhB,QAAA,GAAW,SAAA;EAEQ;EAAA,SAAnB,QAAA,EAAU,SAAA;AAAA;AAAA,UAGJ,SAAA;EALN;;;;;;EAAA,SAYA,QAAA,GAAW,SAAA;EAPI;EAAA,SASf,QAAA,EAAU,SAAA;AAAA;AAAA,UAGJ,aAAA;EALK;EAAA,SAOX,QAAA,EAAU,SAAA;AAAA;;;iBClCL,KAAA,CAAM,MAAA,EAAQ,UAAA;AAAA,kBAAd,KAAA;EAAA,IAAK,WAAA;AAAA;AAAA,iBAML,IAAA,CAAK,MAAA,EAAQ,SAAA;AAAA,kBAAb,IAAA;EAAA,IAAI,WAAA;AAAA;AAAA,iBAMJ,QAAA,CAAS,MAAA,EAAQ,aAAA;AAAA,kBAAjB,QAAA;EAAA,IAAQ,WAAA;AAAA;;;iBCLf,aAAA,CAAA;EACP,QAAA;EACA;AAAA,GACC,QAAA,CAAS,cAAA,IAAkB,YAAA;AAAA,kBAHrB,aAAA;EAAA,IAAa,WAAA;AAAA;AAAA,cAgDT,SAAA,SAAS,aAAA;;;;;;;UCnDL,gBAAA;;EAEf,KAAA,EAAO,KAAA;EHNQ;EGQf,SAAA,EAAW,KAAA;;;;;;;;EAQX,MAAA,EAAQ,WAAA;AAAA;AAAA,UAGO,mBAAA;EHFa;;;;;EGQ5B,aAAA;AAAA;AAAA,KAGU,gBAAA,IACV,OAAA,EAAS,gBAAA,YACC,OAAA;;;AHVZ;;;;;;;;;;AAYA;;;;;;;;AChCA;;;;;;;;;;AAMA;;;;;;;;;;AAMA;;;;;;;;;;;;;ACP0C;;;;;;;;;;;;;;;;;;;AAKA;;;;;AA6C1C;;;;;;;;;;iBCgEgB,YAAA,CACd,OAAA,EAAS,gBAAA,EACT,OAAA,GAAU,mBAAA;;;UCrHK,iBAAA;;EAEf,KAAA,EAAO,KAAA;EJNQ;EIQf,aAAA,EAAe,KAAA;AAAA;AAAA,KAGL,iBAAA,IAAqB,OAAA,EAAS,iBAAA;AAAA,UAEzB,oBAAA;EJTN;;;;AAGX;EIYE,aAAA;AAAA;;;;;;;;;;;AJCF;;;;;;;;;;AAYA;;;;;;;;AChCA;;;;;;;;;;AAMA;;;;;;;;;;AAMA;;;;;;;;;;;;;ACP0C;;;;;;;;;;;;;;;;;;;iBEiG1B,aAAA,CACd,OAAA,EAAS,iBAAA,EACT,OAAA,GAAU,oBAAA"}

package/dist/esm/useRouterTransition-CI1P95ZQ.d.mts

@@ -0,0 +1,56 @@
+import { i as RouteContext } from "./RouterErrorBoundary-C-MH_yrP.mjs";
+import { Navigator, Params, Router, State } from "@real-router/core";
+import { RouteUtils } from "@real-router/route-utils";
+import { RouterTransitionSnapshot } from "@real-router/sources";
+
+//#region src/hooks/useRouter.d.ts
+declare const useRouter: () => Router;
+//#endregion
+//#region src/hooks/useNavigator.d.ts
+declare const useNavigator: () => Navigator;
+//#endregion
+//#region src/hooks/useRouteUtils.d.ts
+/**
+ * Returns a pre-computed {@link RouteUtils} instance for the current router.
+ *
+ * `getRouteUtils` is WeakMap-cached per `RouteTreeNode` inside
+ * `@real-router/route-utils`, so the same router always returns the same
+ * `RouteUtils` instance across renders — no local cache needed in the adapter.
+ *
+ * @returns RouteUtils instance with pre-computed chains and siblings
+ *
+ * @example
+ * ```tsx
+ * const utils = useRouteUtils();
+ *
+ * utils.getChain("users.profile");
+ * // → ["users", "users.profile"]
+ *
+ * utils.getSiblings("users");
+ * // → ["admin"]
+ *
+ * utils.isDescendantOf("users.profile", "users");
+ * // → true
+ * ```
+ */
+declare const useRouteUtils: () => RouteUtils;
+//#endregion
+//#region src/hooks/useRoute.d.ts
+/**
+ * Return shape of `useRoute<P>()` — the context with `route` narrowed to
+ * `State<P>` (non-nullable). Promoting the intersection to a named alias
+ * keeps the function signature and the cast site in sync.
+ */
+type RouteHookResult<P extends Params = Params> = Omit<RouteContext<P>, "route"> & {
+  route: State<P>;
+};
+declare const useRoute: <P extends Params = Params>() => RouteHookResult<P>;
+//#endregion
+//#region src/hooks/useRouteNode.d.ts
+declare function useRouteNode(nodeName: string): RouteContext;
+//#endregion
+//#region src/hooks/useRouterTransition.d.ts
+declare function useRouterTransition(): RouterTransitionSnapshot;
+//#endregion
+export { useNavigator as a, useRouteUtils as i, useRouteNode as n, useRouter as o, useRoute as r, useRouterTransition as t };
+//# sourceMappingURL=useRouterTransition-CI1P95ZQ.d.mts.map

package/dist/esm/useRouterTransition-CI1P95ZQ.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRouterTransition-CI1P95ZQ.d.mts","names":[],"sources":["../../src/hooks/useRouter.tsx","../../src/hooks/useNavigator.tsx","../../src/hooks/useRouteUtils.tsx","../../src/hooks/useRoute.tsx","../../src/hooks/useRouteNode.tsx","../../src/hooks/useRouterTransition.tsx"],"mappings":";;;;;;cAMa,SAAA,QAAgB,MAAA;;;cCAhB,YAAA,QAAmB,SAAA;;;;;;;;ADAhC;;;;;;;;ACAA;;;;;;;;ACwBA;;cAAa,aAAA,QAAoB,UAAA;;;;;;;AFxBjC;KGMK,eAAA,WAA0B,MAAA,GAAS,MAAA,IAAU,IAAA,CAChD,YAAA,CAAiB,CAAA;EAEb,KAAA,EAAO,KAAA,CAAM,CAAA;AAAA;AAAA,cAEN,QAAA,aAAsB,MAAA,GAAS,MAAA,OAAW,eAAA,CAAgB,CAAA;;;iBCTvD,YAAA,CAAa,QAAA,WAAmB,YAAA;;;iBCDhC,mBAAA,CAAA,GAAuB,wBAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/react",
-  "version": "0.24.1",
+  "version": "0.25.0",
   "type": "commonjs",
   "description": "React integration for Real-Router",
   "main": "./dist/cjs/index.js",
@@ -13,11 +13,26 @@
       ],
       "ink": [
         "./dist/cjs/ink.d.ts"
+      ],
+      "ssr": [
+        "./dist/cjs/ssr.d.ts"
+      ],
+      "legacy/ssr": [
+        "./dist/cjs/legacy.ssr.d.ts"
       ]
     }
   },
   "exports": {
     ".": {
+      "react-server": {
+        "@real-router/internal-source": "./src/index.react-server.ts",
+        "types": {
+          "import": "./dist/esm/index.react-server.d.mts",
+          "require": "./dist/cjs/index.react-server.d.ts"
+        },
+        "import": "./dist/esm/index.react-server.mjs",
+        "require": "./dist/cjs/index.react-server.js"
+      },
       "@real-router/internal-source": "./src/index.ts",
       "types": {
         "import": "./dist/esm/index.d.mts",
@@ -43,6 +58,33 @@
       },
       "import": "./dist/esm/ink.mjs",
       "require": "./dist/cjs/ink.js"
+    },
+    "./ssr": {
+      "react-server": {
+        "@real-router/internal-source": "./src/ssr.react-server.ts",
+        "types": {
+          "import": "./dist/esm/ssr.react-server.d.mts",
+          "require": "./dist/cjs/ssr.react-server.d.ts"
+        },
+        "import": "./dist/esm/ssr.react-server.mjs",
+        "require": "./dist/cjs/ssr.react-server.js"
+      },
+      "@real-router/internal-source": "./src/ssr.ts",
+      "types": {
+        "import": "./dist/esm/ssr.d.mts",
+        "require": "./dist/cjs/ssr.d.ts"
+      },
+      "import": "./dist/esm/ssr.mjs",
+      "require": "./dist/cjs/ssr.js"
+    },
+    "./legacy/ssr": {
+      "@real-router/internal-source": "./src/legacy.ssr.ts",
+      "types": {
+        "import": "./dist/esm/legacy.ssr.d.mts",
+        "require": "./dist/cjs/legacy.ssr.d.ts"
+      },
+      "import": "./dist/esm/legacy.ssr.mjs",
+      "require": "./dist/cjs/legacy.ssr.js"
     }
   },
   "files": [
@@ -76,9 +118,9 @@
   "license": "MIT",
   "sideEffects": false,
   "dependencies": {
-    "@real-router/core": "^0.52.0",
+    "@real-router/core": "^0.53.0",
     "@real-router/route-utils": "^0.2.2",
-    "@real-router/sources": "^0.8.1"
+    "@real-router/sources": "^0.8.2"
   },
   "devDependencies": {
     "@testing-library/dom": "10.4.1",
@@ -88,7 +130,7 @@
     "ink": "7.0.1",
     "ink-testing-library": "4.0.0",
     "vitest-react-profiler": "1.12.0",
-    "@real-router/browser-plugin": "^0.17.1"
+    "@real-router/browser-plugin": "^0.17.2"
   },
   "peerDependencies": {
     "@types/react": ">=18.0.0",

package/src/components/Await.tsx

@@ -0,0 +1,46 @@
+import { use } from "react";
+
+import { useDeferred } from "../hooks/useDeferred";
+
+import type { ReactNode } from "react";
+
+export interface AwaitProps<T> {
+  /** Deferred key declared in the loader's `defer({ deferred: { <name>: ... } })`. */
+  readonly name: string;
+  /** Render the resolved value. Suspends while pending; throws inside the
+   * nearest Error Boundary on rejection. */
+  readonly children: (value: T) => ReactNode;
+}
+
+/**
+ * Ergonomic wrapper around `useDeferred(name)` + React 19's `use(promise)`.
+ *
+ * ```tsx
+ * <Suspense fallback={<Spinner />}>
+ *   <Await<Review[]> name="reviews">
+ *     {(reviews) => <ReviewList items={reviews} />}
+ *   </Await>
+ * </Suspense>
+ * ```
+ *
+ * Equivalent to:
+ *
+ * ```tsx
+ * function Inner() {
+ *   const reviews = use(useDeferred<Review[]>("reviews"));
+ *   return <ReviewList items={reviews} />;
+ * }
+ * ```
+ *
+ * Pick `<Await>` for cross-adapter consistency with the SvelteKit
+ * `{#await}` / Solid `<Await/>` shape; pick the inline `use(useDeferred(...))`
+ * form if you prefer one fewer abstraction.
+ */
+export function Await<T = unknown>({
+  name,
+  children,
+}: AwaitProps<T>): ReactNode {
+  const value = use(useDeferred<T>(name));
+
+  return children(value);
+}

package/src/components/ClientOnly.tsx

@@ -0,0 +1,25 @@
+import { useEffect, useState } from "react";
+
+import type { ReactNode } from "react";
+
+export interface ClientOnlyProps {
+  readonly children: ReactNode;
+  readonly fallback?: ReactNode;
+}
+
+export function ClientOnly({
+  children,
+  fallback = null,
+}: ClientOnlyProps): ReactNode {
+  const [mounted, setMounted] = useState(false);
+
+  useEffect(() => {
+    // SSR/hydration boundary: server emits the fallback branch, client matches
+    // it on first paint, then this effect flips state to swap in the children.
+    // The intentional re-render is what makes the markup match across renders.
+    // eslint-disable-next-line @eslint-react/set-state-in-effect -- intentional post-hydration swap
+    setMounted(true);
+  }, []);
+
+  return mounted ? children : fallback;
+}

package/src/components/HttpStatusCode.tsx

@@ -0,0 +1,66 @@
+import { useContext } from "react";
+
+import { HttpStatusContext } from "./HttpStatusProvider";
+
+import type { ReactNode } from "react";
+
+export interface HttpStatusCodeProps {
+  /** HTTP status to apply to the response. Common values: 404, 410, 451, 503. */
+  readonly code: number;
+}
+
+/**
+ * Render-time HTTP status declaration. Mount inside a route component (typical
+ * use case: a glob `*` route's NotFound page) when the status is decided by
+ * the rendered tree rather than a loader.
+ *
+ * Writes `code` to the nearest `<HttpStatusProvider>`'s sink during render and
+ * returns `null`. With no provider mounted (the standard client-side case)
+ * the component is a silent no-op — same component tree hydrates without
+ * touching the DOM or warning about mismatches.
+ *
+ * Loader-driven errors (`LoaderNotFound` → 404, `LoaderRedirect` → 30x) keep
+ * working as before; this component covers render-time decisions only.
+ *
+ * Last write wins when several `<HttpStatusCode />` instances mount in the
+ * same render pass — sink reflects the last component that ran.
+ *
+ * ```tsx
+ * // entry-server.tsx
+ * import { renderToString } from "react-dom/server";
+ * import { createHttpStatusSink, HttpStatusProvider } from "@real-router/react/ssr";
+ *
+ * const sink = createHttpStatusSink();
+ * const html = renderToString(
+ *   <HttpStatusProvider sink={sink}>
+ *     <RouterProvider router={router}>
+ *       <App />
+ *     </RouterProvider>
+ *   </HttpStatusProvider>,
+ * );
+ * response.status(sink.code ?? 200).send(html);
+ * ```
+ *
+ * **Streaming SSR (`renderToReadableStream`):** the response status MUST be
+ * sent before the first body byte flushes. If `<HttpStatusCode />` is mounted
+ * inside a late-resolving `<Suspense>` boundary, the sink write may happen
+ * AFTER the headers are already on the wire — the override is then lost.
+ * Either mount the component in the shell (above every `<Suspense>` that
+ * could delay it) or `await stream.allReady` before reading `sink.code`
+ * (which forfeits streaming benefits). For non-streaming SSR
+ * (`renderToString`) there is no such ordering concern.
+ *
+ * **Valid `code` range:** Node's `res.end()` throws `Invalid status code` on
+ * `NaN`, `0`, negative values, or values `> 999` — this surfaces as a 5xx /
+ * dropped connection, not silent corruption. Pass a real HTTP status integer
+ * (commonly 4xx/5xx; 100-999 is what Node accepts).
+ */
+export function HttpStatusCode({ code }: HttpStatusCodeProps): ReactNode {
+  const sink = useContext(HttpStatusContext);
+
+  if (sink) {
+    sink.code = code;
+  }
+
+  return null;
+}

package/src/components/HttpStatusProvider.tsx

@@ -0,0 +1,26 @@
+import { createContext } from "react";
+
+import type { HttpStatusSink } from "../utils/createHttpStatusSink";
+import type { ReactNode } from "react";
+
+export const HttpStatusContext = createContext<HttpStatusSink | null>(null);
+
+export interface HttpStatusProviderProps {
+  readonly sink: HttpStatusSink;
+  readonly children: ReactNode;
+}
+
+export function HttpStatusProvider({
+  sink,
+  children,
+}: HttpStatusProviderProps): ReactNode {
+  // `<HttpStatusContext.Provider value>` (not the React 19 `<HttpStatusContext value>`
+  // shorthand) — same component file is exported via `/legacy/ssr` for React 18
+  // consumers, where the shorthand throws "Element type is invalid: expected
+  // a string but got: object".
+  return (
+    <HttpStatusContext.Provider value={sink}>
+      {children}
+    </HttpStatusContext.Provider>
+  );
+}