react-bun-ssr 0.3.2 → 0.4.1

package/README.md

@@ -38,11 +38,6 @@ Prerequisites:
 - Bun `>= 1.3.10`
 - `rbssr` available on PATH in the workflow you use to start a new app
 
-Try in browser:
-
-- StackBlitz (primary): https://stackblitz.com/github/react-formation/react-bun-ssr/tree/main/examples/sandbox-starter
-- CodeSandbox (fallback): https://codesandbox.io/s/github/react-formation/react-bun-ssr/tree/main/examples/sandbox-starter
-
 Minimal setup:
 
 ```bash
@@ -114,11 +109,50 @@ Read more:
 
 For a page request, the framework resolves the matching route, runs global and nested middleware, executes the matched loader or action, and then renders an HTML response or returns a direct `Response` when the route short-circuits. API routes use the same route tree and middleware model, but return handler responses instead of page HTML.
 
+Under the hood, page HTML, API, internal action, and internal transition requests now share the same runtime request boundary, which keeps middleware, redirects, and response finalization behavior aligned across request kinds.
+
 Read more:
 
 - https://react-bun-ssr.dev/docs/routing/middleware
 - https://react-bun-ssr.dev/docs/data/loaders
 
+### Actions with React `useActionState`
+
+Page mutations use React 19 form actions (`useActionState`) with an explicit route stub:
+
+```tsx
+// app/routes/login.tsx
+import { useActionState } from "react";
+import { createRouteAction } from "react-bun-ssr/route";
+
+type LoginState = { error?: string };
+export const action = createRouteAction<LoginState>();
+
+export default function LoginPage() {
+  const [state, formAction, pending] = useActionState(action, {});
+  return (
+    <form action={formAction}>
+      {state.error ? <p>{state.error}</p> : null}
+      <button disabled={pending}>Sign in</button>
+    </form>
+  );
+}
+```
+
+```tsx
+// app/routes/login.server.tsx
+import { redirect } from "react-bun-ssr";
+import type { Action } from "react-bun-ssr/route";
+
+export const action: Action = async (ctx) => {
+  const email = String(ctx.formData?.get("email") ?? "").trim();
+  if (!email) return { error: "Email is required" };
+  return redirect("/dashboard");
+};
+```
+
+`createRouteAction` is the preferred pattern. `useRouteAction` remains available for backward compatibility.
+
 ### Rendering model
 
 SSR is the default model. HTML responses stream, deferred loader data is supported, and soft client transitions are handled through `Link` and `useRouter`. The docs site in this repository uses the same routing, rendering, markdown, and transition model that framework users get.

package/framework/cli/dev-runtime.ts

@@ -26,13 +26,20 @@ function isConfigFileName(fileName: string): boolean {
 }
 
 function isTopLevelAppRuntimeFile(relativePath: string): boolean {
-  return /^root\.(tsx|jsx|ts|js)$/.test(relativePath) || /^middleware\.(tsx|jsx|ts|js)$/.test(relativePath);
+  return /^root(?:\.server)?\.(tsx|jsx|ts|js)$/.test(relativePath)
+    || /^middleware(?:\.server)?\.(tsx|jsx|ts|js)$/.test(relativePath);
 }
 
 function isMarkdownRouteFile(relativePath: string): boolean {
   return /^routes\/.+\.md$/.test(relativePath);
 }
 
+function isServerOnlyRuntimeFile(relativePath: string): boolean {
+  return /^root\.server\.(tsx|jsx|ts|js)$/.test(relativePath)
+    || /^middleware\.server\.(tsx|jsx|ts|js)$/.test(relativePath)
+    || /^routes\/.+\.server\.(tsx|jsx|ts|js)$/.test(relativePath);
+}
+
 function isStructuralAppPath(relativePath: string): boolean {
   return relativePath === "routes"
     || relativePath.startsWith("routes/")
@@ -265,11 +272,21 @@ export async function runHotDevChild(options: {
       return;
     }
 
+    if (eventType === "rename" && isServerOnlyRuntimeFile(relativePath)) {
+      publishReload("server-runtime");
+      return;
+    }
+
     if (eventType === "rename" && isStructuralAppPath(relativePath)) {
       scheduleStructuralSync();
       return;
     }
 
+    if (eventType === "change" && isServerOnlyRuntimeFile(relativePath)) {
+      publishReload("server-runtime");
+      return;
+    }
+
     if (eventType !== "change" || !isMarkdownRouteFile(relativePath)) {
       return;
     }

package/framework/runtime/action-stub.ts

@@ -0,0 +1,26 @@
+export type RouteActionStateHandler<TState = unknown> = (
+  previousState: TState,
+  formData: FormData,
+) => Promise<TState>;
+
+const ROUTE_ACTION_STUB_MARKER = Symbol.for("react-bun-ssr.route-action-stub");
+
+export function markRouteActionStub<TState>(
+  handler: RouteActionStateHandler<TState>,
+): RouteActionStateHandler<TState> {
+  Object.defineProperty(handler, ROUTE_ACTION_STUB_MARKER, {
+    value: true,
+    enumerable: false,
+    configurable: false,
+    writable: false,
+  });
+  return handler;
+}
+
+export function isRouteActionStub(value: unknown): value is RouteActionStateHandler<unknown> {
+  if (typeof value !== "function") {
+    return false;
+  }
+
+  return (value as unknown as Record<PropertyKey, unknown>)[ROUTE_ACTION_STUB_MARKER] === true;
+}

package/framework/runtime/client-runtime.tsx

@@ -1,15 +1,10 @@
 import { hydrateRoot, type Root } from "react-dom/client";
 import {
-  consumeTransitionChunkText,
-  createTransitionChunkParserState,
-  flushTransitionChunkText,
   isStaleNavigationToken,
   matchClientPageRoute,
   sanitizePrefetchCache,
-  shouldHardNavigateForRedirectDepth,
   shouldSkipSoftNavigation,
 } from "./client-transition-core";
-import { isDeferredToken } from "./deferred";
 import {
   addNavigationNavigateListener,
   canNavigationNavigateWithIntercept,
@@ -21,6 +16,12 @@ import {
   RBSSR_ROUTER_SCRIPT_ID,
 } from "./runtime-constants";
 import { replaceManagedHead } from "./head-reconcile";
+import {
+  applyRouteWireDeferredChunk,
+  completeRouteWireTransition,
+  createRouteWireProtocol,
+  reviveRouteWirePayload,
+} from "./route-wire-protocol";
 import {
   createCatchAppTree,
   createErrorAppTree,
@@ -34,7 +35,6 @@ import type {
   RenderPayload,
   RouteModule,
   RouteModuleBundle,
-  TransitionDeferredChunk,
   TransitionDocumentChunk,
   TransitionInitialChunk,
   TransitionRedirectChunk,
@@ -73,16 +73,6 @@ interface PrefetchEntry {
   donePromise: Promise<void>;
 }
 
-interface TransitionRequestOptions {
-  onDeferredChunk?: (chunk: TransitionDeferredChunk) => void;
-  signal?: AbortSignal;
-}
-
-interface TransitionRequestHandle {
-  initialPromise: Promise<TransitionInitialChunk | TransitionRedirectChunk | TransitionDocumentChunk | null>;
-  donePromise: Promise<void>;
-}
-
 interface FrameworkNavigationInfo {
   __rbssrTransition: true;
   id: string;
@@ -173,6 +163,28 @@ function getClientRuntimeSingleton(): ClientRuntimeSingleton {
 
 const clientRuntimeSingleton = getClientRuntimeSingleton();
 
+function readCurrentWindowUrl(): URL | null {
+  if (typeof window === "undefined") {
+    return null;
+  }
+
+  return new URL(window.location.href);
+}
+
+function getClientRouteWireProtocol() {
+  return createRouteWireProtocol({
+    getCurrentUrl: readCurrentWindowUrl,
+  });
+}
+
+function getDeferredRuntime(): DeferredClientRuntime | undefined {
+  if (typeof window === "undefined") {
+    return undefined;
+  }
+
+  return window.__RBSSR_DEFERRED__;
+}
+
 function emitNavigation(info: NavigateResult): void {
   for (const listener of clientRuntimeSingleton.navigationListeners) {
     try {
@@ -373,31 +385,6 @@ function findPendingTransitionForEvent(event: NavigateEventLike): PendingNavigat
   return bestMatch;
 }
 
-function reviveDeferredPayload(payload: RenderPayload): RenderPayload {
-  const sourceData = payload.data;
-  if (!sourceData || Array.isArray(sourceData) || typeof sourceData !== "object") {
-    return payload;
-  }
-
-  const runtime = window.__RBSSR_DEFERRED__;
-  if (!runtime) {
-    return payload;
-  }
-
-  const revivedData = { ...(sourceData as Record<string, unknown>) };
-  for (const [key, value] of Object.entries(revivedData)) {
-    if (!isDeferredToken(value)) {
-      continue;
-    }
-    revivedData[key] = runtime.get(value.__rbssrDeferred);
-  }
-
-  return {
-    ...payload,
-    data: revivedData,
-  };
-}
-
 function ensureRuntimeState(): RuntimeState {
   if (!clientRuntimeSingleton.runtimeState) {
     throw new Error("Client runtime is not initialized. Ensure hydrateInitialRoute() ran first.");
@@ -406,106 +393,6 @@ function ensureRuntimeState(): RuntimeState {
   return clientRuntimeSingleton.runtimeState;
 }
 
-function createTransitionUrl(toUrl: URL): URL {
-  const transitionUrl = new URL("/__rbssr/transition", window.location.origin);
-  transitionUrl.searchParams.set("to", toUrl.pathname + toUrl.search + toUrl.hash);
-  return transitionUrl;
-}
-
-function startTransitionRequest(
-  toUrl: URL,
-  options: TransitionRequestOptions = {},
-): TransitionRequestHandle {
-  let resolveInitial: (
-    value: TransitionInitialChunk | TransitionRedirectChunk | TransitionDocumentChunk | null,
-  ) => void = () => undefined;
-  let rejectInitial: (reason?: unknown) => void = () => undefined;
-  const initialPromise = new Promise<
-    TransitionInitialChunk | TransitionRedirectChunk | TransitionDocumentChunk | null
-  >((resolve, reject) => {
-    resolveInitial = resolve;
-    rejectInitial = reject;
-  });
-
-  const donePromise = (async () => {
-    const endpoint = createTransitionUrl(toUrl);
-    const response = await fetch(endpoint.toString(), {
-      method: "GET",
-      credentials: "same-origin",
-      signal: options.signal,
-    });
-
-    if (!response.ok || !response.body) {
-      throw new Error(`Transition request failed with status ${response.status}`);
-    }
-
-    const reader = response.body.getReader();
-    const decoder = new TextDecoder();
-    let parserState = createTransitionChunkParserState();
-
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done) {
-        break;
-      }
-
-      const previousInitialChunk = parserState.initialChunk;
-      const previousDeferredCount = parserState.deferredChunks.length;
-      parserState = consumeTransitionChunkText(
-        parserState,
-        decoder.decode(value, { stream: true }),
-      );
-
-      if (!previousInitialChunk && parserState.initialChunk) {
-        resolveInitial(parserState.initialChunk);
-      }
-
-      for (const chunk of parserState.deferredChunks.slice(previousDeferredCount)) {
-        options.onDeferredChunk?.(chunk);
-      }
-    }
-
-    const previousInitialChunk = parserState.initialChunk;
-    const previousDeferredCount = parserState.deferredChunks.length;
-    parserState = flushTransitionChunkText(parserState);
-
-    if (!previousInitialChunk && parserState.initialChunk) {
-      resolveInitial(parserState.initialChunk);
-    }
-
-    for (const chunk of parserState.deferredChunks.slice(previousDeferredCount)) {
-      options.onDeferredChunk?.(chunk);
-    }
-
-    if (!parserState.initialChunk) {
-      resolveInitial(null);
-    }
-  })();
-
-  donePromise.catch(error => {
-    rejectInitial(error);
-  });
-
-  return {
-    initialPromise,
-    donePromise,
-  };
-}
-
-function applyDeferredChunk(chunk: TransitionDeferredChunk): void {
-  const runtime = window.__RBSSR_DEFERRED__;
-  if (!runtime) {
-    return;
-  }
-
-  if (chunk.ok) {
-    runtime.resolve(chunk.id, chunk.value);
-    return;
-  }
-
-  runtime.reject(chunk.id, chunk.error ?? "Deferred value rejected");
-}
-
 async function ensureRouteModuleLoaded(routeId: string, snapshot: ClientRouterSnapshot): Promise<void> {
   if (clientRuntimeSingleton.moduleRegistry.has(routeId)) {
     return;
@@ -538,8 +425,11 @@ function getOrCreatePrefetchEntry(
     ? ensureRouteModuleLoaded(routeId, snapshot).catch(() => undefined)
     : Promise.resolve();
 
-  const transitionRequest = startTransitionRequest(toUrl, {
-    onDeferredChunk: applyDeferredChunk,
+  const transitionRequest = getClientRouteWireProtocol().startTransition({
+    to: toUrl,
+    onDeferredChunk: chunk => {
+      applyRouteWireDeferredChunk(chunk, getDeferredRuntime());
+    },
     signal,
   });
   const initialPromise = transitionRequest.initialPromise.catch(() => {
@@ -574,7 +464,7 @@ async function renderTransitionInitial(
   options: NavigateOptions & { prefetched: boolean; fromPath: string },
 ): Promise<NavigateResult> {
   const state = ensureRuntimeState();
-  const revivedPayload = reviveDeferredPayload(chunk.payload);
+  const revivedPayload = reviveRouteWirePayload(chunk.payload, getDeferredRuntime());
   let modules: RouteModuleBundle | null = null;
   let tree = null as ReturnType<typeof createPageAppTree> | ReturnType<typeof createNotFoundAppTree>;
 
@@ -713,7 +603,7 @@ async function navigateToInternal(
           matchedModules,
           {
             routeId: matched.route.id,
-            data: null,
+            loaderData: null,
             params: matched.params,
             url: toUrl.toString(),
           },
@@ -733,43 +623,34 @@ async function navigateToInternal(
       throw new Error("Transition response did not include an initial payload.");
     }
 
-    if (initialChunk.type === "document") {
-      hardNavigate(new URL(initialChunk.location, window.location.origin));
-      return null;
-    }
-
-    if (initialChunk.type === "redirect") {
-      const redirectUrl = new URL(initialChunk.location, window.location.origin);
-      if (!isInternalUrl(redirectUrl)) {
-        hardNavigate(redirectUrl);
-        return null;
-      }
-
-      const depth = (options.redirectDepth ?? 0) + 1;
-      if (shouldHardNavigateForRedirectDepth(depth)) {
-        hardNavigate(redirectUrl);
-        return null;
-      }
-
-      return navigateToInternal(redirectUrl, {
-        ...options,
-        replace: true,
-        redirected: true,
-        redirectDepth: depth,
-        // The intercepted navigation has already committed the source URL.
-        // The redirected target must update history explicitly.
-        historyManagedByNavigationApi: false,
-      });
-    }
-
-    const result = await renderTransitionInitial(initialChunk, toUrl, {
-      ...options,
-      prefetched: usedPrefetch,
-      fromPath: currentPath,
+    return completeRouteWireTransition(initialChunk, {
+      currentUrl: new URL(window.location.href),
+      redirectDepth: options.redirectDepth,
+      render: async chunk => {
+        const result = await renderTransitionInitial(chunk, toUrl, {
+          ...options,
+          prefetched: usedPrefetch,
+          fromPath: currentPath,
+        });
+        options.onNavigate?.(result);
+        emitNavigation(result);
+        return result;
+      },
+      softNavigate: async (location, redirectInfo) => {
+        return navigateToInternal(new URL(location, window.location.href), {
+          ...options,
+          replace: redirectInfo.replace,
+          redirected: redirectInfo.redirected,
+          redirectDepth: redirectInfo.redirectDepth,
+          // The intercepted navigation has already committed the source URL.
+          // The redirected target must update history explicitly.
+          historyManagedByNavigationApi: false,
+        });
+      },
+      hardNavigate: location => {
+        hardNavigate(new URL(location, window.location.href));
+      },
     });
-    options.onNavigate?.(result);
-    emitNavigation(result);
-    return result;
   } catch {
     hardNavigate(toUrl);
     return null;
@@ -1060,7 +941,10 @@ export function hydrateInitialRoute(routeId: string): void {
     return;
   }
 
-  const payload = reviveDeferredPayload(getScriptJson<RenderPayload>(RBSSR_PAYLOAD_SCRIPT_ID));
+  const payload = reviveRouteWirePayload(
+    getScriptJson<RenderPayload>(RBSSR_PAYLOAD_SCRIPT_ID),
+    getDeferredRuntime(),
+  );
   const routerSnapshot = getScriptJson<ClientRouterSnapshot>(RBSSR_ROUTER_SCRIPT_ID);
   const modules = clientRuntimeSingleton.moduleRegistry.get(routeId);
   if (!modules) {

package/framework/runtime/helpers.ts

@@ -1,5 +1,6 @@
-import type { FrameworkConfig, RedirectResult } from "./types";
+import type { FrameworkConfig, RedirectResult, RequestContext } from "./types";
 import { defer as deferValue } from "./deferred";
+import { routeError } from "./route-errors";
 
 export function json(data: unknown, init: ResponseInit = {}): Response {
   const headers = new Headers(init.headers);
@@ -30,6 +31,79 @@ export function defineConfig(config: FrameworkConfig): FrameworkConfig {
 
 export const defer = deferValue;
 
+function toNormalizedFallback(value: string): string {
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return "/";
+  }
+  if (trimmed.startsWith("/")) {
+    return trimmed.startsWith("//") ? "/" : trimmed;
+  }
+  if (trimmed.startsWith("?") || trimmed.startsWith("#")) {
+    return `/${trimmed}`;
+  }
+  if (/^[a-zA-Z][a-zA-Z\d+\-.]*:/.test(trimmed)) {
+    return "/";
+  }
+  return `/${trimmed.replace(/^\/+/, "")}`;
+}
+
+export function sanitizeRedirectTarget(value: string | null | undefined, fallback = "/"): string {
+  const normalizedFallback = toNormalizedFallback(fallback);
+  if (typeof value !== "string") {
+    return normalizedFallback;
+  }
+
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return normalizedFallback;
+  }
+
+  if (trimmed.startsWith("//") || trimmed.startsWith("\\\\")) {
+    return normalizedFallback;
+  }
+
+  let parsed: URL;
+  try {
+    parsed = new URL(trimmed, "http://rbssr.local");
+  } catch {
+    return normalizedFallback;
+  }
+
+  if (parsed.origin !== "http://rbssr.local") {
+    return normalizedFallback;
+  }
+
+  const normalizedTarget = `${parsed.pathname}${parsed.search}${parsed.hash}`;
+  if (!normalizedTarget.startsWith("/")) {
+    return normalizedFallback;
+  }
+
+  return normalizedTarget;
+}
+
+export function assertSameOriginAction(ctx: Pick<RequestContext, "request" | "url">): void {
+  if (ctx.request.method.toUpperCase() === "GET" || ctx.request.method.toUpperCase() === "HEAD") {
+    return;
+  }
+
+  const originHeader = ctx.request.headers.get("origin");
+  if (!originHeader) {
+    return;
+  }
+
+  let origin: URL;
+  try {
+    origin = new URL(originHeader);
+  } catch {
+    throw routeError(403, { message: "Invalid Origin header." });
+  }
+
+  if (origin.origin !== ctx.url.origin) {
+    throw routeError(403, { message: "Cross-origin form submissions are not allowed." });
+  }
+}
+
 export function isRedirectResult(value: unknown): value is RedirectResult {
   return Boolean(
     value &&

package/framework/runtime/index.ts

@@ -1,29 +1,59 @@
-export type {
-  Action,
-  ActionContext,
-  ActionResult,
-  ApiRouteModule,
-  BuildManifest,
-  BuildRouteAsset,
-  DeferredLoaderResult,
-  DeferredToken,
-  FrameworkConfig,
-  Loader,
-  LoaderContext,
-  LoaderResult,
-  Middleware,
-  Params,
-  RedirectResult,
-  ResponseHeaderRule,
-  RequestContext,
-  RouteCatchContext,
-  RouteErrorContext,
-  RouteErrorResponse,
-  RouteModule,
+import type {
+  Action as RuntimeAction,
+  ActionContext as RuntimeActionContext,
+  ActionResult as RuntimeActionResult,
+  ApiRouteModule as RuntimeApiRouteModule,
+  BuildManifest as RuntimeBuildManifest,
+  BuildRouteAsset as RuntimeBuildRouteAsset,
+  DeferredLoaderResult as RuntimeDeferredLoaderResult,
+  DeferredToken as RuntimeDeferredToken,
+  FrameworkConfig as RuntimeFrameworkConfig,
+  Loader as RuntimeLoader,
+  LoaderContext as RuntimeLoaderContext,
+  LoaderResult as RuntimeLoaderResult,
+  Middleware as RuntimeMiddleware,
+  Params as RuntimeParams,
+  RedirectResult as RuntimeRedirectResult,
+  RequestContext as RuntimeRequestContext,
+  ResponseContext as RuntimeResponseContext,
+  ResponseCookies as RuntimeResponseCookies,
+  ResponseCookieOptions as RuntimeResponseCookieOptions,
+  ResponseHeaderRule as RuntimeResponseHeaderRule,
+  RouteCatchContext as RuntimeRouteCatchContext,
+  RouteErrorContext as RuntimeRouteErrorContext,
+  RouteErrorResponse as RuntimeRouteErrorResponse,
+  RouteModule as RuntimeRouteModule,
 } from "./types";
 
+export interface AppRouteLocals extends Record<string, unknown> {}
+
+export type Action = RuntimeAction<AppRouteLocals>;
+export type ActionContext = RuntimeActionContext<AppRouteLocals>;
+export type ActionResult = RuntimeActionResult;
+export type ApiRouteModule = RuntimeApiRouteModule;
+export type BuildManifest = RuntimeBuildManifest;
+export type BuildRouteAsset = RuntimeBuildRouteAsset;
+export type DeferredLoaderResult = RuntimeDeferredLoaderResult;
+export type DeferredToken = RuntimeDeferredToken;
+export type FrameworkConfig = RuntimeFrameworkConfig;
+export type Loader = RuntimeLoader<AppRouteLocals>;
+export type LoaderContext = RuntimeLoaderContext<AppRouteLocals>;
+export type LoaderResult = RuntimeLoaderResult;
+export type Middleware = RuntimeMiddleware<AppRouteLocals>;
+export type Params = RuntimeParams;
+export type RedirectResult = RuntimeRedirectResult;
+export type RequestContext = RuntimeRequestContext<AppRouteLocals>;
+export type ResponseContext = RuntimeResponseContext;
+export type ResponseCookies = RuntimeResponseCookies;
+export type ResponseCookieOptions = RuntimeResponseCookieOptions;
+export type ResponseHeaderRule = RuntimeResponseHeaderRule;
+export type RouteCatchContext = RuntimeRouteCatchContext;
+export type RouteErrorContext = RuntimeRouteErrorContext;
+export type RouteErrorResponse = RuntimeRouteErrorResponse;
+export type RouteModule = RuntimeRouteModule;
+
 export { createServer, startHttpServer } from "./server";
-export { defer, json, redirect, defineConfig } from "./helpers";
+export { assertSameOriginAction, defer, defineConfig, json, redirect, sanitizeRedirectTarget } from "./helpers";
 export { isRouteErrorResponse, notFound, routeError } from "./route-errors";
 export { Link, type LinkProps } from "./link";
 export { useRouter, type Router, type RouterNavigateInfo, type RouterNavigateListener, type RouterNavigateOptions } from "./router";