@reckona/mreact-router 0.0.202 → 0.0.204

package/README.md

@@ -51,6 +51,8 @@ export default defineConfig({
 
 `allowedSourceDirs` can be omitted for the common route roots: `routesDir: "src/app"` defaults to `["src"]`, and `routesDir: "app"` defaults to `["app"]`. Keep it explicit when shared server/client modules live in additional project-root-relative directories.
 
+Server query data embedded during hydration is visible to the browser. Set `dehydratePolicyModule` to a project-relative server module inside `allowedSourceDirs` when Vite development, prerendering, built Node output, and generated Lambda handlers must share one filter. The module must export a named `dehydrateOptions` object; Mreact bundles it as executable server code and fails closed when the configured module or export is invalid. Programmatic Node and Lambda handlers may instead pass `dehydrateOptions` directly.
+
 `mreact-router build` reads this config. Pass `--target=node` for plain Node/container output, `--target=aws-lambda` for Lambda artifacts with a generated handler and import policy, or `--target=cloudflare` for Workers artifacts with a generated Worker module. Configure `buildTargets: ["aws-lambda"]`, `["cloudflare"]`, or another explicit target list in `mreactRouter()` when one deployment target should be the project default. Without an explicit target, build output includes only the Node-compatible server/client artifacts; Cloudflare and Lambda artifacts are opt-in. The legacy `appDir` shortcut remains available for tests and older direct programmatic usage, but it is deprecated. Use `projectRoot` + `routesDir` for new code. The shortcut is planned for removal after `0.1.0`.
 
 Run `mreact-router boundaries` to inspect every route and its statically traceable rendered server and client components without writing build artifacts. The command loads the same Vite project configuration as `build`; pass an explicit app directory for the legacy direct-directory mode, or add `--json` for a deterministic versioned report with project-relative paths.
@@ -81,6 +83,8 @@ local import:
 
 Internal anchors are intercepted by the app-router client runtime and update the changed route payload instead of forcing a full document reload. The runtime keeps head metadata and route-data scripts synchronized, restores scroll on back/forward navigation, and prefetches client route scripts for likely navigations when the browser is not in reduced-data mode. Client route assets share app-local module instances across development and production route chunks, so app-local modules imported by multiple client routes use the browser's normal single ESM instance across SPA navigation.
 
+Server-only document responses preserve the page's original DOM shape, while client-navigation responses use the `data-mreact-route-id` wrapper required for swapping route content. Route caches, prerender storage, and downstream caches keep those response variants separate. Serialized hydration payloads carry only the request pathname, so shared HTML does not capture visitor-specific origin or query data; routes that read request input restore `props.request.url` from the current document URL immediately before hydration. Read the full URL from the server-side `request` when server route logic needs it, which also makes request dependence visible to the cache tracker.
+
 Use `Link` or `linkProps()` when a route needs explicit navigation behavior:
 
 ```tsx
@@ -120,6 +124,7 @@ client-only code. Navigation observers are available from
 - Imported functions passed to `<form action={...}>` are inferred as server actions, including supported typed registry references such as `actions.save`. Inferred action implementations stay in the server graph and are stripped from production client route bundles. A top-level `"use server"` directive is still supported and marks every exported function in that module as a server action. Production dispatch is fail-closed without a generated or explicit action manifest; direct integrations that intentionally expose every registered action must pass `serverActions: { allowedActions: "any" }`.
 - Browser-enhanced form actions that mutate data, call `revalidatePath()` for the current route, and return normally can use a single-flight mutation response: the action POST response carries fresh navigation HTML marked with `x-mreact-action-single-flight`, so the browser updates the visible route without a second GET. Unsupported action flows still fall back to the existing `x-mreact-revalidate` invalidation and redirect/navigation behavior. This is unrelated to duplicate-submission coalescing or application idempotency keys.
 - Server actions reject `Content-Length` values over `10 MiB` by default. Pass `serverActions: { maxBodyBytes }` to configure the limit.
+- Server action nonces are atomically claimed immediately before application action code runs. Custom `serverActions.replayStore` implementations must provide an atomic `claim()` operation; replay returns `409`, while capacity or store failures fail closed with `503`. An invoked action consumes its nonce even if it later throws because its side effects may already have committed.
 - Route handlers may return or throw standard `Response` objects from method exports such as `GET`, `POST`, or `ALL`. Dynamic route handlers receive decoded params as the second argument: `GET(request, { params })`; catch-all `$...slug` params are arrays of decoded segments. The context also includes `request`, `route`, and adapter `env`; Cloudflare route handlers additionally receive the Worker execution `context`.
 - `redirect(location)` throws router control flow that defaults to HTTP 303 so auth and form flows continue as GET requests after the redirect. Use `redirect(location, { status: 307 })` when preserving the original method and body is required.
 
@@ -131,7 +136,35 @@ Inferred form actions are bound to the rendered form with a hidden token derived
 
 Plain `multipart/form-data` route handlers do not automatically run the server-action CSRF guard. For cookie-authenticated upload forms that post directly to `route.ts`, render a hidden field named `formCsrfFieldName`, set `formCsrfCookie(token)` for the same token, and either call `validateFormCsrf(request, formData)` for small buffered forms or read the CSRF field with `parseMultipartStream()` before consuming a large file part. `request.formData()` buffers multipart file parts in memory; `parseMultipartStream(request, { fields })` keeps file parts as `ReadableStream<Uint8Array>` values with per-part and total byte limits, enforces bounded defaults, and exposes both the raw `filename` and a storage-oriented `safeFilename`. Workers APIs such as R2 require known-length streams, so `part.fixedLengthStream(length).readable` is only valid when the multipart part carries a `Content-Length` header or the handler can pass the exact byte length; otherwise use a bounded `arrayBuffer()` fallback for R2. Put the CSRF field before the file field when you want early rejection without reading the file body.
 
-Use `startDevServer()` and `startServer()` when an app needs to attach HTTP upgrade handling to the same Node server as mreact routes. Both APIs accept `onUpgrade(request, socket, head)`, and `startDevServer()` keeps Vite middleware/HMR wired to the underlying server. Production route artifacts are bundled independently, so mutable custom-server state should live in `getServerRuntimeState(key, create)` rather than in a module-scoped `let` singleton.
+Use `startDevServer()` and `startServer()` when an app needs to attach HTTP upgrade handling to the same Node server as mreact routes. Both APIs accept `onUpgrade(request, socket, head, context)`, and `startDevServer()` keeps Vite middleware/HMR wired to the underlying server. WebSocket handshakes are not protected by the browser same-origin policy or CORS, and browsers send matching cookies with the handshake. mreact therefore rejects missing, opaque, malformed, and cross-origin browser upgrades by default before invoking the application handler. Validate `Origin` before reading a session or other credentials, then explicitly accept or decline every upgrade:
+
+```ts
+import { startServer, validateHttpUpgradeOrigin } from "@reckona/mreact-router";
+import { WebSocketServer } from "ws";
+
+const allowedOrigins = ["https://app.example.com"];
+const wss = new WebSocketServer({ noServer: true });
+
+await startServer({
+  outDir: ".mreact",
+  port: 3000,
+  upgradeOriginPolicy: { allowedOrigins },
+  onUpgrade(request, socket, head, context) {
+    const origin = validateHttpUpgradeOrigin(request, { allowedOrigins });
+    if (!origin.ok || request.url !== "/ws") {
+      return context.decline();
+    }
+
+    context.accept();
+    // Authenticate only after Origin validation, then transfer the socket.
+    wss.handleUpgrade(request, socket, head, (websocket) => {
+      wss.emit("connection", websocket, request);
+    });
+  },
+});
+```
+
+The first three handler arguments remain compatible with synchronous handlers that write a handshake immediately. A handler that delays verification, including `ws` with asynchronous `verifyClient`, must call `context.accept()` synchronously before starting that work; a return with no synchronous socket action is treated as a decline. Thrown errors, rejected handlers, and undecided asynchronous handlers close the socket. Framework-generated structured fields omit request headers and query data, but an application error message is preserved, so handlers must not copy secrets into thrown errors. The default policy compares `Origin` with the validated request authority, so wildcard binds and trusted reverse proxies work when their Host and forwarded-protocol policies are configured correctly. `close()` waits for accepted upgrade sockets up to `upgradeCloseTimeoutMs` and then destroys only those sockets, while ordinary HTTP responses keep their normal drain behavior. Non-browser clients that omit `Origin` require an explicit `{ allowedOrigins, allowMissingOrigin: true }` policy and an alternate authentication boundary; `"unchecked"` is available only as an explicit compatibility escape hatch. Production route artifacts are bundled independently, so mutable custom-server state should live in `getServerRuntimeState(key, create)` rather than in a module-scoped `let` singleton.
 
 Client boundary markers have the same SSR behavior. A plain `Foo.tsx` component runs on the server and does not hydrate by itself. Marking a component boundary with either `Foo.client.tsx` or a top-level `"use client";` directive makes that boundary hydrate on the client; SSR emits a `<template data-mreact-client-boundary="...">` placeholder plus serialized props, and the component JSX appears after hydration. When a client boundary wrapper receives server-renderable JSX children, those children remain visible as SSR DOM between the boundary marker and its props payload so the initial response stays paintable and indexable before hydration. Inferred boundaries from plain imported components can also keep an SSR fallback when every browser-global read is guarded by a `typeof window !== "undefined"` style check: a guarded if/ternary branch, a short-circuited logical expression, or statements after a guarded early exit such as `if (typeof window === "undefined") return;`. A guard on one of `window`, `document`, or `localStorage` covers the others. Unguarded reads, and guards the analyzer cannot follow such as an aliased `const isBrowser = typeof window !== "undefined"` condition, still disable fallback eligibility and produce a placeholder-only boundary. Combining `.client.tsx` with `"use client";` is redundant and does not change the boundary behavior. Route-level `"use client";` is separate: when it appears in a page, layout, or template route module, the whole route is emitted as a hydrated client route. In development, app-local client boundary dependencies are transformed through the mreact client compiler before Vite serves them, and generated mreact runtime imports are resolved by the router plugin, so server-rendered layouts and app shells can import hydrated client controls without adding React or mreact compat runtime aliases.
 
@@ -168,6 +201,8 @@ Route metadata is composed from parent layouts before the matched page. CSP dire
 
 When `metadata.csp.nonce` is set, the CSP serializer appends that nonce to `script-src` and `style-src` only when those directives are present. A nonce on `style-src` disables the browser's implicit allowance for inline styles, so JSX-rendered `<style>` blocks must also carry a matching nonce or move to an external stylesheet. Use `metadata.head` for route-owned inline styles that need the framework nonce, for example `{ tag: "style", nonce: true, content: "body{color:red}" }`. If you only need script hardening, set `script-src` and leave `style-src` unset.
 
+Responses whose enforced or report-only CSP contains a nonce are treated as visitor-dependent: the router marks them `Cache-Control: private, no-store`, excludes them from route caches and prerender manifests, and rejects older persisted entries that contain a nonce. This rule also applies when a final `onResponse` hook adds the CSP header. Hash-based and other nonce-free CSP responses remain eligible for shared caching.
+
 Rendered routes include conservative default response headers: `X-Content-Type-Options: nosniff`, `Referrer-Policy: strict-origin-when-cross-origin`, and `Permissions-Policy: camera=(), microphone=(), geolocation=()`. Use `metadata.security` to opt out of a default, override a policy, add `X-Frame-Options`, or enable HSTS for HTTPS requests. Security header values are validated before they are emitted.
 
 Root app files can define crawler and install metadata without adding route handlers. `robots.ts`, `sitemap.ts`, and `manifest.ts` serve `/robots.txt`, `/sitemap.xml`, and `/manifest.webmanifest`; static `robots.txt`, `sitemap.xml`, `manifest.webmanifest`, `favicon.ico`, `icon.*`, `apple-icon.*`, and `opengraph-image.*` files are copied as public assets during builds. Route-local `opengraph-image.tsx` / `.ts` / `.jsx` / `.js` modules serve `/<route>/opengraph-image`, receive `{ params, request }`, may return a `Response`, string, or bytes, and are used as the default `og:image` when the page does not set one explicitly. Static files take precedence over generated metadata routes for the same URL, and icon files are also used as fallback route metadata when a page does not define its own icon or OpenGraph image.
@@ -206,7 +241,11 @@ export async function loader(context: LoaderContext<{ id: string }>): Promise<Us
 }
 
 export default definePage<typeof loader>(function UserPage(props) {
-  return <h1>{props.params.id}: {props.data.name}</h1>;
+  return (
+    <h1>
+      {props.params.id}: {props.data.name}
+    </h1>
+  );
 });
 ```
 
@@ -257,7 +296,13 @@ Routes that render route-local `<Await>` directly or through app-local server co
 
 ```tsx
 function FeedList(props) {
-  return <ul>{props.items.map((item) => <li>{item}</li>)}</ul>;
+  return (
+    <ul>
+      {props.items.map((item) => (
+        <li>{item}</li>
+      ))}
+    </ul>
+  );
 }
 
 export default function Page() {
@@ -302,9 +347,7 @@ export default function Page() {
           placeholderAs="div"
           placeholder={<StorySkeleton count={batch.size} start={batch.start + 1} />}
         >
-          {(resolved) => (
-            <StoryRows stories={resolved.items} start={resolved.start + 1} />
-          )}
+          {(resolved) => <StoryRows stories={resolved.items} start={resolved.start + 1} />}
         </Await>
       ))}
     </ol>
@@ -344,7 +387,11 @@ Server-only pages get the lightweight navigation runtime automatically — witho
 import { Link } from "@reckona/mreact-router/link";
 
 export default function Page() {
-  return <Link href="/docs" prefetch="viewport">Docs</Link>;
+  return (
+    <Link href="/docs" prefetch="viewport">
+      Docs
+    </Link>
+  );
 }
 ```
 
@@ -360,7 +407,7 @@ The build manifest records this separately from `client: true`, emits a shared n
 
 For Cloudflare Workers, `mreact-router build --target=cloudflare` emits `.mreact/cloudflare/worker.mjs`, `.mreact/cloudflare/route-modules.mjs`, and per-route module chunks for non-prerendered and dynamic App Router pages plus `route.ts` server routes and metadata conventions, so deployments do not need a hand-written Worker entrypoint or Vite-only `import.meta.glob()` transforms. Deploy that output with a Worker config whose `main` is `.mreact/cloudflare/worker.mjs` and whose `ASSETS` binding points at `.mreact/client`.
 
-For Cloudflare Pages advanced mode, run `mreact-router package cloudflare-pages --from .mreact --out .mreact/pages` after `mreact-router build --target=cloudflare`, then deploy with `wrangler pages deploy .mreact/pages`. The package command creates a Pages output directory with bundled `_worker.js`, `_mreact/client/*` static route assets, root public assets, and `mreact-cloudflare-pages-artifact.json`. Pages provides the `ASSETS` binding to `_worker.js`; mreact's generated worker reads that binding and serves only generated client manifest assets, route-linked CSS, and public files. The package step bundles the generated Worker entry, route registry, route chunks, and router adapter code, so application deploy scripts do not need to copy `worker.mjs` manually or decide whether Wrangler should bundle package imports. If your Worker graph includes dependencies that import Node builtins such as `node:util` or bare `util`, configure Cloudflare Pages with the `nodejs_compat` compatibility flag so the packaged Worker can use Cloudflare's Node.js compatibility runtime.
+For Cloudflare Pages advanced mode, run `mreact-router package cloudflare-pages --from .mreact --out .mreact/pages` after `mreact-router build --target=cloudflare`, then deploy with `wrangler pages deploy .mreact/pages`. The package command creates a Pages output directory with bundled `_worker.js`, `_mreact/client/*` static route assets, root public assets, and `mreact-cloudflare-pages-artifact.json`. Pages provides the `ASSETS` binding to `_worker.js`; mreact's generated worker reads that binding and serves only generated client manifest assets, route-linked CSS, and public files. The package step bundles the generated Worker entry, route registry, route chunks, and router adapter code, so application deploy scripts do not need to copy `worker.mjs` manually or decide whether Wrangler should bundle package imports. Configure the `nodejs_compat` compatibility flag so the adapter can use native request-local storage and dependencies can use Cloudflare's Node.js compatibility runtime. Without it, mreact preserves query-client isolation by serializing renders and emits a one-time warning.
 
 User Vite plugins from the project config are forwarded into router bundle builds after the `mreact-router` plugin itself is removed, so MDX-style syntax transforms and custom content loaders can participate in server, client, Cloudflare, and prerender bundles. Vite `define` values are also forwarded into generated Cloudflare server bundles, including `import.meta.env.*` aliases and plain define identifiers used by loaders and route handlers. Client assets, route stylesheet assets imported by pages/layouts/templates or special `error.tsx`/`not-found.tsx` boundaries, and copied public assets are served only when they appear in the generated manifest allow-list. Dynamic routes resolve modules through a build-time registry keyed by `route.file`, not by constructing module ids from request input. Generated Cloudflare route modules preserve app-router layout/template shells and named slots for both string and `stream = true` pages, including route-local `<Await>` boundaries and local server-component imports. Generated Cloudflare server route modules dispatch method exports such as `GET`, `POST`, and `ALL` with decoded dynamic params plus `context.env`, `context.context`, `context.request`, and `context.route`, so handlers can use Worker bindings directly. Cloudflare page rendering installs the per-request query client scope before loader, page, metadata, and document rendering, so server-rendered helpers can call `getQueryClient()` even in runtimes without `AsyncLocalStorage`. The Cloudflare adapter marks streamed HTML with `Cache-Control: no-transform` and `Content-Encoding: identity` so Workers compression does not gzip-buffer the first shell before placeholders can paint. Pass `onResponse` to add cross-cutting response headers to rendered, static, asset, reload, not-found, and error responses. If a generated Cloudflare route module cannot produce the `data-mreact-route-id` marker contract required by client navigation, the adapter returns a reload signal for `x-mreact-navigation: 1` requests so the browser performs a normal document navigation without first buffering the full HTML response.
 
@@ -392,15 +439,15 @@ await warmAwsLambdaRuntime(options);
 export const handler = await createPreloadedAwsLambdaRequestHandler(options);
 ```
 
-Production adapters enforce the app-router import policy when bundling loaders, middleware, route handlers, metadata, and server actions. `mreact-router build` writes `.mreact/server/import-policy.json` from server-side static imports. The built Node server used by `mreact-router start .mreact`, `renderBuiltAppRequest()`, and `createBuiltRequestRuntime()` reads that generated policy automatically and merges its runtime packages with any explicit policy options. Lambda handlers can use `importPolicy: "generated"`. You can still pass an explicit `importPolicy.allowedPackages` list when you need a hand-audited policy.
+Production adapters enforce the app-router import policy when bundling loaders, middleware, route handlers, metadata, and server actions. `mreact-router build` writes `.mreact/server/import-policy.json` from server-side static imports. The public built-output entry points, including `mreact-router start .mreact` and `renderBuiltAppRequest()`, read that generated policy automatically and merge its runtime packages with any explicit policy options. Custom adapters should compose the public render and preload APIs rather than depend on internal runtime constructors. Lambda handlers can use `importPolicy: "generated"`. You can still pass an explicit `importPolicy.allowedPackages` list when you need a hand-audited policy.
 
 For Lambda deployments, build with `mreact-router build --target=aws-lambda` or `buildApp({ targets: ["aws-lambda"] })`. The generated buffered and streaming handlers warm the same middleware policy during module initialization by default and then use request handlers with duplicate preload disabled. The artifact manifest records `mreact-handler.handler` and `mreact-streaming-handler.handler` separately. Select a broader or disabled initialization policy with `--aws-lambda-preload=hot-route-requests|all|none` or `buildApp({ awsLambdaPreload: "all", targets: ["aws-lambda"] })` only after measuring the packaged handler; pair `hot-route-requests` with `--aws-lambda-preload-routes=/,/login` or `awsLambdaPreloadRoutes`. `none` disables generated module preload but still materializes the writable runtime directory during generated handler import. The package command preserves the build-generated policy unless package options explicitly override it. The target writes Node-compatible server/client output, `.mreact/server/import-policy.json`, and generated Lambda entries while skipping `.mreact/cloudflare` route modules, so loaders and server helpers may import Node-only dependencies such as database drivers without being bundled for the Workers runtime.
 
-Package Lambda deployments with `mreact-router package aws-lambda --from .mreact --out .lambda` instead of pointing deployment tooling at the full project checkout. AWS Lambda enforces a 250 MB unzipped deployment package limit, and the runtime only needs `.mreact/`, `mreact-handler.mjs`, `package.json` / lockfiles, and production `node_modules`; `src/`, tests, dev dependencies, build caches, and Vite/Vitest/Playwright tooling are not required. `mreact-router build --target=aws-lambda` keeps compiled server route artifacts in `.mreact/server/server-modules/*.json` instead of embedding them in one large server manifest, writes compiled module bodies as hashed `.mjs` files, and keeps request/control artifacts separate from render artifacts so loader redirects do not read page render bundles. AWS Lambda request/control artifacts bundle the generated import-policy packages they use for loaders, middleware, route handlers, and metadata, reducing first-hit package resolution on sparse Lambda traffic while leaving render-only, server action, custom handler, and adapter dependencies in production `node_modules`. `createAwsLambdaRequestHandler()` treats `outDir` as read-only and materializes generated runtime files under `/tmp/mreact-router/<hash>/runtime` by default, with a `node_modules` symlink back to the deployed package root. Direct `createAwsLambdaRequestHandler()` and `createAwsLambdaStreamingRequestHandler()` handlers start only middleware and shared runtime preload in the background by default, so all-route preload work does not compete with the first user request. If a request arrives before preload finishes, middleware is resolved first, middleware responses or redirects return without loading the matched page artifact, and continuing requests load only the matched route's artifact closure. Static middleware `config.matcher` and `config.id` values are checked before importing the middleware module, so unmatched health checks and route-local middleware skips avoid evaluating heavyweight middleware dependencies. Route request artifacts omit page render exports, and built loader and route metadata artifacts are split, so loader redirects do not evaluate page-only or metadata-only dependencies before render or metadata is needed. Loader redirects settle before page component server transforms and render imports for non-stream routes, stream routes without a loading boundary, and stream loading routes whose loader source contains router control-flow helpers such as `redirect()` or `notFound()`. `createPreloadedAwsLambdaRequestHandler()` validates the first event before it starts full preload. When a deployment intentionally accepts extra Lambda initialization work to reduce first-valid-request latency, call `await warmAwsLambdaRuntime(options)` during controlled initialization before creating the handler. Pass `runtimeDir` only when you need to control that writable cache location. With pnpm, run `pnpm --dir .lambda install --prod --frozen-lockfile --ignore-scripts --config.node-linker=hoisted`. pnpm's default isolated linker is symlink-heavy, so verify the artifact's symlink count with `find .lambda -type l | wc -l` and measure actual file bytes in addition to `du -sh .lambda` before upload. Packages listed in the generated import policy may still be needed by render-only modules, inferred server actions, custom handlers, or adapter code, so keep them installed in that production artifact.
+Package Lambda deployments with `mreact-router package aws-lambda --from .mreact --out .lambda` instead of pointing deployment tooling at the full project checkout. AWS Lambda enforces a 250 MB unzipped deployment package limit, and the runtime only needs `.mreact/`, `mreact-handler.mjs`, `package.json` / lockfiles, and production `node_modules`; `src/`, tests, dev dependencies, build caches, and Vite/Vitest/Playwright tooling are not required. `mreact-router build --target=aws-lambda` keeps compiled server route artifacts in `.mreact/server/server-modules/*.json` instead of embedding them in one large server manifest, writes compiled module bodies as hashed `.mjs` files, and keeps request/control artifacts separate from render artifacts so loader redirects do not read page render bundles. AWS Lambda request/control artifacts bundle the generated import-policy packages they use for loaders, middleware, route handlers, and metadata, reducing first-hit package resolution on sparse Lambda traffic while leaving render-only, server action, custom handler, and adapter dependencies in production `node_modules`. `createAwsLambdaRequestHandler()` treats `outDir` as read-only and materializes generated runtime files under `/tmp/mreact-router/<hash>/runtime` by default, with a `node_modules` symlink back to the deployed package root. Direct `createAwsLambdaRequestHandler()` and `createAwsLambdaStreamingRequestHandler()` handlers start only middleware and shared runtime preload in the background by default, so all-route preload work does not compete with the first user request. If a request arrives before preload finishes, middleware is resolved first, middleware responses or redirects return without loading the matched page artifact, and continuing requests load only the matched route's artifact closure. Static middleware `config.matcher` and `config.id` values are checked before importing the middleware module, so unmatched health checks and route-local middleware skips avoid evaluating heavyweight middleware dependencies. Route request artifacts omit page render exports, and built loader and route metadata artifacts are split, so loader redirects do not evaluate page-only or metadata-only dependencies before render or metadata is needed. Every loader's outer result settles before page component transforms or render imports for non-stream routes and stream routes, including stream routes with a loading boundary and controls reached through imported helpers. Return non-critical promises through `defer()` and render them with `<Await>` when they should continue behind the loading boundary. `createPreloadedAwsLambdaRequestHandler()` validates the first event before it starts full preload. When a deployment intentionally accepts extra Lambda initialization work to reduce first-valid-request latency, call `await warmAwsLambdaRuntime(options)` during controlled initialization before creating the handler. Pass `runtimeDir` only when you need to control that writable cache location. With pnpm, run `pnpm --dir .lambda install --prod --frozen-lockfile --ignore-scripts --config.node-linker=hoisted`. pnpm's default isolated linker is symlink-heavy, so verify the artifact's symlink count with `find .lambda -type l | wc -l` and measure actual file bytes in addition to `du -sh .lambda` before upload. Packages listed in the generated import policy may still be needed by render-only modules, inferred server actions, custom handlers, or adapter code, so keep them installed in that production artifact.
 
 When a deployment needs custom adapter options such as `serverActions.authorize`, `onResponse`, `errorHandler`, or `allowedHosts`, create an app handler and package it with `mreact-router package aws-lambda --from .mreact --out .lambda --handler src/lambda.ts`. The package command bundles that handler into `.lambda/mreact-handler.mjs`, resolves app-local TypeScript imports with Vite-style extensionless paths, and keeps package imports external so production `node_modules` remains the runtime dependency boundary. If the handler imports the same app server modules that routes also import, those modules are compiled into the handler bundle separately from the mreact route artifacts; use `getServerRuntimeState()` for state that must be shared through the router runtime instead of relying on module singletons.
 
-Configure `allowedHosts` for production Lambda deployments so absolute URLs, redirects, cache keys, and metadata cannot be derived from attacker-controlled Host input. The Lambda adapter uses `Host` by default and only reads `x-forwarded-host` when `hostPolicy: "trusted-proxy"` is set. It also ignores `x-forwarded-proto` unless `trustForwardedProto: true` is configured, deriving the request scheme from the Lambda event protocol when available and otherwise defaulting to HTTPS.
+Configure `allowedHosts` for production Lambda deployments so absolute URLs, redirects, cache keys, and metadata cannot be derived from attacker-controlled Host input. The Lambda adapter uses `Host` by default and only reads `x-forwarded-host` when `hostPolicy: "trusted-proxy"` is set. API Gateway HTTP API v2 and Lambda Function URL requests default to HTTPS because `requestContext.http.protocol` is an HTTP version such as `HTTP/1.1`, not a URL scheme. The adapter ignores `x-forwarded-proto` unless `trustForwardedProto: true` is configured; enable that option only behind a proxy that overwrites the header.
 
 Use the Lambda `preload` option to tune that trade-off. Direct handlers default to `"middleware"` so cold starts do not kick off all route module imports in parallel with the first request. `createPreloadedAwsLambdaRequestHandler()` and `createPreloadedAwsLambdaStreamingRequestHandler()` default to `"all"` after event validation. Call `warmAwsLambdaRuntime()` explicitly when initialization-time full preload is an intentional deployment choice. Set `preload: "none"` to disable background preload, `preload: "all"` only when you have measured that all-route background preload helps the deployed function, `preload: { mode: "hot-routes", routes: ["/", "/dashboard"] }` with `warmAwsLambdaRuntime()` to warm selected route closures including render modules before valid traffic, or `preload: { mode: "hot-route-requests", routes: ["/", "/login"] }` to warm only middleware plus selected route loader/server-route request modules without evaluating page/layout render modules. For direct handlers that cannot use top-level async initialization, add `wait: "before-render"` to an object preload strategy to let page-rendering invocations wait for the already-started preload after loader redirects have had a chance to return; add `wait: "first-request"` only when the first invocation can pay the full preload cost. Lambda request timing reports `first-request` waits as `preloadWaitMs`, and render timing reports `before-render` waits as `preloadWaitMs`.
 

package/dist/actions.d.ts

@@ -1,4 +1,4 @@
-import { type ServerActionHandlerOptions, type ServerActionReplayStore, type ServerActionRequestReference } from "@reckona/mreact-server";
+import { type ServerActionHandlerOptions, type ServerActionReplayClaim, type ServerActionReplayStore, type ServerActionRequestReference } from "@reckona/mreact-server";
 import { type AppRouterCache } from "./cache.js";
 import { type AppRouterImportPolicy } from "./import-policy.js";
 import { type RequestCookies } from "./navigation.js";
@@ -19,10 +19,15 @@ declare class BoundedReplayStore {
     private readonly ttlMs;
     private readonly maxEntries;
     private readonly entries;
+    private capacityWarningActive;
+    private warnedLeaseReclamation;
+    private readonly minimumRetentionMs;
     constructor(ttlMs: number, maxEntries: number);
-    has(value: string): boolean;
-    add(value: string): void;
+    claim(value: string): ServerActionReplayClaim;
+    clear(): void;
     size(): number;
+    private warnCapacity;
+    private warnLeaseReclamation;
 }
 export declare function __clearDefaultReplayStore(): void;
 export declare function __readDefaultReplayStore(): BoundedReplayStore;

package/dist/actions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"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"}

package/dist/actions.js

@@ -3,12 +3,12 @@ import { access, readdir, readFile } from "node:fs/promises";
 import { dirname, join, relative, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { collectFormActionExpressionReferences, hasModuleDirective, } from "@reckona/mreact-compiler";
-import { createServerActionHandler, } from "@reckona/mreact-server";
+import { createServerActionHandler, ensureServerActionReplayStoreContract, } from "@reckona/mreact-server";
 import { bundleRouterModule } from "./bundle-pipeline.js";
 import { withRouteCacheContext } from "./cache.js";
 import { fileImportMetaUrlPlugin, importAppRouterSourceModule } from "./module-runner.js";
 import { createAppRouterImportPolicyPlugin } from "./import-policy.js";
-import { cookies } from "./navigation.js";
+import { cookies, isSafeInternalRedirect } from "./navigation.js";
 export { createFormCsrfToken, formCsrfCookie, formCsrfFieldName, serverActionCookie, validateFormCsrf, } from "./csrf.js";
 import { formCsrfFieldName, readExistingFormCsrfToken, serverActionCookieName, validateFormCsrf, } from "./csrf.js";
 import { collectRuntimeInferredServerActions, } from "./server-action-inference.js";
@@ -45,6 +45,7 @@ const actionTokenSecret = configuredActionTokenSecret(process.env.MREACT_SERVER_
 // traffic does not trip false-positive 409s.
 const DEFAULT_REPLAY_TTL_MS = 10 * 60 * 1000;
 const DEFAULT_REPLAY_MAX_ENTRIES = 50_000;
+const DEFAULT_REPLAY_MINIMUM_RETENTION_MS = 60_000;
 const DEFAULT_ACTION_BODY_MAX_BYTES = 10 * 1024 * 1024;
 const DEFAULT_ACTION_FORM_MAX_FIELDS = 1_000;
 let warnedUnrestrictedServerActions = false;
@@ -67,51 +68,107 @@ class BoundedReplayStore {
     ttlMs;
     maxEntries;
     entries = new Map();
+    capacityWarningActive = false;
+    warnedLeaseReclamation = false;
+    minimumRetentionMs;
     constructor(ttlMs, maxEntries) {
         this.ttlMs = ttlMs;
         this.maxEntries = maxEntries;
+        this.minimumRetentionMs = Math.min(ttlMs, DEFAULT_REPLAY_MINIMUM_RETENTION_MS);
     }
-    has(value) {
-        const expiresAt = this.entries.get(value);
-        if (expiresAt === undefined)
-            return false;
-        if (expiresAt < Date.now()) {
+    claim(value) {
+        const now = Date.now();
+        if (this.entries.size < this.maxEntries) {
+            this.capacityWarningActive = false;
+        }
+        const existing = this.entries.get(value);
+        if (existing?.state === "completed" && existing.expiresAt <= now) {
             this.entries.delete(value);
-            return false;
         }
-        return true;
-    }
-    add(value) {
-        const now = Date.now();
+        else if (existing?.state === "in-flight" && existing.leaseExpiresAt <= now) {
+            this.entries.delete(value);
+            this.warnLeaseReclamation();
+        }
+        if (this.entries.has(value))
+            return { status: "replay" };
         if (this.entries.size >= this.maxEntries) {
-            const oldest = this.entries.entries().next().value;
-            if (oldest !== undefined) {
-                const [key, expiresAt] = oldest;
-                this.entries.delete(key);
-                if (expiresAt < now) {
-                    while (this.entries.size >= this.maxEntries) {
-                        const nextOldest = this.entries.entries().next().value;
-                        if (nextOldest === undefined || nextOldest[1] >= now) {
-                            break;
-                        }
-                        this.entries.delete(nextOldest[0]);
-                    }
+            this.warnCapacity();
+            let reclaimableCompletedKey;
+            for (const [key, entry] of this.entries) {
+                if ((entry.state === "completed" && entry.expiresAt <= now) ||
+                    (entry.state === "in-flight" && entry.leaseExpiresAt <= now)) {
+                    this.entries.delete(key);
+                }
+                else if (reclaimableCompletedKey === undefined &&
+                    entry.state === "completed" &&
+                    entry.protectedUntil <= now) {
+                    reclaimableCompletedKey = key;
                 }
             }
+            if (this.entries.size >= this.maxEntries && reclaimableCompletedKey !== undefined) {
+                this.entries.delete(reclaimableCompletedKey);
+            }
+            if (this.entries.size >= this.maxEntries)
+                return { status: "capacity-exceeded" };
         }
-        this.entries.set(value, now + this.ttlMs);
+        const entry = { state: "in-flight", leaseExpiresAt: now + this.ttlMs };
+        this.entries.set(value, entry);
+        let finalized = false;
+        return {
+            status: "claimed",
+            finalize: () => {
+                if (finalized)
+                    return;
+                finalized = true;
+                if (this.entries.get(value) === entry) {
+                    const completedAt = Date.now();
+                    this.entries.delete(value);
+                    this.entries.set(value, {
+                        state: "completed",
+                        expiresAt: completedAt + this.ttlMs,
+                        protectedUntil: completedAt + this.minimumRetentionMs,
+                    });
+                }
+            },
+        };
+    }
+    // Exposed for tests; not part of the ServerActionReplayStore interface.
+    clear() {
+        this.entries.clear();
+        this.capacityWarningActive = false;
+        this.warnedLeaseReclamation = false;
     }
     // Exposed for tests; not part of the ServerActionReplayStore interface.
     size() {
         return this.entries.size;
     }
+    warnCapacity() {
+        if (this.capacityWarningActive)
+            return;
+        this.capacityWarningActive = true;
+        let completed = 0;
+        let inFlight = 0;
+        for (const entry of this.entries.values()) {
+            if (entry.state === "completed")
+                completed += 1;
+            else
+                inFlight += 1;
+        }
+        console.error(`mreact-router: default server action replay store reached capacity (size=${this.entries.size}, maxEntries=${this.maxEntries}, completed=${completed}, inFlight=${inFlight}, minimumRetentionMs=${this.minimumRetentionMs}). Completed claims remain exact through minimumRetentionMs and may be reclaimed under pressure afterward; expired in-flight leases may also be reclaimed. Applications requiring exact protection for the full action lifetime and retention window must use a shared replay store.`);
+    }
+    warnLeaseReclamation() {
+        if (this.warnedLeaseReclamation)
+            return;
+        this.warnedLeaseReclamation = true;
+        console.error(`mreact-router: default server action replay store reclaimed an expired in-flight claim after leaseMs=${this.ttlMs}; exact duplicate-execution protection no longer applies to that abandoned claim.`);
+    }
 }
 const usedFormActionNonces = new BoundedReplayStore(DEFAULT_REPLAY_TTL_MS, DEFAULT_REPLAY_MAX_ENTRIES);
 // Test helpers: drop all entries between cases / expose the bounded store
 // so tests can drive its eviction semantics directly. Not part of the
 // public surface (prefixed with `__`).
 export function __clearDefaultReplayStore() {
-    usedFormActionNonces.entries.clear();
+    usedFormActionNonces.clear();
 }
 export function __readDefaultReplayStore() {
     return usedFormActionNonces;
@@ -272,7 +329,7 @@ async function dispatchServerActionRequestWithoutCacheContext(options) {
                 : { allowedActions: jsonAllowedServerActions(options.serverActions.allowedActions) }),
             csrf: { cookieName: serverActionCookieName() },
             maxBodyBytes: options.serverActions?.maxBodyBytes ?? DEFAULT_ACTION_BODY_MAX_BYTES,
-            replayProtection: { seen: replayStore },
+            replayProtection: { store: replayStore },
         });
         return handle(options.request);
     }
@@ -321,10 +378,6 @@ async function dispatchServerActionRequestWithoutCacheContext(options) {
         })) {
         return jsonResponse({ ok: false, error: "Unknown server action." }, 404);
     }
-    const nonceResponse = validateFormNonce(formData, options.serverActions?.replayStore ?? usedFormActionNonces);
-    if (nonceResponse !== undefined) {
-        return nonceResponse;
-    }
     let registry;
     try {
         registry = await loadServerActionRegistry({
@@ -351,19 +404,35 @@ async function dispatchServerActionRequestWithoutCacheContext(options) {
     if (authorizationResponse !== undefined) {
         return authorizationResponse;
     }
+    const replayClaim = await claimFormNonce(nonce, options.serverActions?.replayStore ?? usedFormActionNonces);
+    if (replayClaim instanceof Response)
+        return replayClaim;
+    let actionResponse;
+    let actionError;
     try {
         const value = await action(actionFormData, createServerActionContext(options.request));
         if (value instanceof Response) {
-            return value;
+            actionResponse = value;
+        }
+        else if (value === undefined || value === null) {
+            actionResponse = redirectToFormReferer(options.request);
         }
-        if (value === undefined || value === null) {
-            return redirectToFormReferer(options.request);
+        else {
+            actionResponse = jsonResponse({ ok: true, value }, 200);
         }
-        return jsonResponse({ ok: true, value }, 200);
     }
     catch (error) {
-        return jsonResponse({ ok: false, error: error instanceof Error ? error.message : String(error) }, 500);
+        actionError = error;
+    }
+    try {
+        await replayClaim.finalize();
+    }
+    catch {
+        return replayStoreUnavailableResponse();
     }
+    return actionError === undefined
+        ? actionResponse
+        : jsonResponse({ ok: false, error: actionError instanceof Error ? actionError.message : String(actionError) }, 500);
 }
 function createServerActionContext(request) {
     const clientIp = clientIpFromRequest(request);
@@ -509,8 +578,9 @@ function sameOriginRefererPath(request) {
     try {
         const requestUrl = new URL(request.url);
         const refererUrl = new URL(referer, requestUrl);
-        return refererUrl.origin === requestUrl.origin
-            ? `${refererUrl.pathname}${refererUrl.search}`
+        const location = `${refererUrl.pathname}${refererUrl.search}`;
+        return refererUrl.origin === requestUrl.origin && isSafeInternalRedirect(location)
+            ? location
             : undefined;
     }
     catch {
@@ -986,16 +1056,26 @@ function validateServerActionRequestOrigin(request) {
         return jsonResponse({ ok: false, error: "Origin not allowed." }, 403);
     }
 }
-function validateFormNonce(formData, replayStore) {
-    const nonce = stringFormValue(formData.get(formFieldNonce));
-    if (nonce === undefined || nonce.length === 0) {
-        return jsonResponse({ ok: false, error: "Missing server action nonce." }, 400);
+async function claimFormNonce(nonce, replayStore) {
+    let claim;
+    if (!ensureServerActionReplayStoreContract(replayStore)) {
+        return replayStoreUnavailableResponse();
+    }
+    try {
+        claim = await replayStore.claim(nonce);
     }
-    if (replayStore.has(nonce)) {
+    catch {
+        return replayStoreUnavailableResponse();
+    }
+    if (claim.status === "replay") {
         return jsonResponse({ ok: false, error: "Server action nonce was already used." }, 409);
     }
-    replayStore.add(nonce);
-    return undefined;
+    if (claim.status === "capacity-exceeded")
+        return replayStoreUnavailableResponse();
+    return claim;
+}
+function replayStoreUnavailableResponse() {
+    return new Response(JSON.stringify({ ok: false, error: "Server action replay protection is unavailable." }), { status: 503, headers: { "content-type": "application/json", "retry-after": "1" } });
 }
 function cleanActionFormData(formData) {
     const cleaned = new FormData();