brustjs 0.1.49-alpha → 0.1.51-alpha

package/runtime/routes.ts

@@ -1,15 +1,8 @@
 import { createContext, createElement, useContext, type ComponentType, type ReactNode } from 'react'
-// React 19 split react-dom/server by runtime: under Bun the bare 'react-dom/server'
-// resolves to the web-streams build (server.bun.js), which only exports
-// renderToReadableStream. renderToPipeableStream (Node streams — what our Writable
-// sink + onAllReady/onShellReady path uses) lives in the .node build. Import it
-// explicitly so SSR works on the react@19 we declare as a peer (React 18 shipped
-// renderToPipeableStream in the bun build, which is why this was silently fine).
-import { renderToPipeableStream } from 'react-dom/server.node'
-import { Writable } from 'node:stream'
 import { Buffer } from 'node:buffer'
 import * as native from './index.js'
 import { renderBranchStreaming } from './render/stream.ts'
+import { renderToAwaitedString } from './render/fragment.ts'
 import { runInStoreContext, collectSnapshot } from './store/server-context.ts'
 import { buildStoreScripts } from './render/inject-store.ts'
 import { getCssHrefsForRoute } from './css.ts'
@@ -98,6 +91,31 @@ export interface BrustRequest {
    * unaborted shared sentinel; signal.aborted === false forever). Real
    * disconnect detection for render/action is a follow-up. */
   signal: AbortSignal
+  /** Matched route params (percent-decoded) — the SAME values the loader ctx
+   * receives. Populated by the TS dispatch layer (`prepReq`) BEFORE the
+   * middleware chain runs, so middleware can authorize against `{id}` without
+   * re-parsing the raw URL. Empty object for routes without params — and for
+   * SSE/WS requests (their envelope carries no params in v1). */
+  params: Record<string, string>
+  /** Request-scoped bag middleware writes and loaders/handlers read. The same
+   * object identity flows through the whole chain (middleware → loader →
+   * component/handler). Locals written before `next()` are visible downstream;
+   * writes AFTER `next()` returns happen after the loader already ran. Reset
+   * to a fresh `{}` per request. */
+  locals: Record<string, unknown>
+}
+
+/** Populate the TS-owned `BrustRequest` fields (`params`, `locals`) on a
+ * request that just arrived in the Rust envelope. Rust knows nothing of these
+ * fields, so every dispatch branch calls this ONCE, before composeChain /
+ * loaders run — the single population point. Mutates and returns `req`. */
+export function prepReq(
+  req: BrustRequest,
+  params: Record<string, string> | undefined,
+): BrustRequest {
+  req.params = params ?? {}
+  req.locals = {}
+  return req
 }
 
 /** Handler module shape — what `() => Promise<WsHandlers>` resolves to.
@@ -235,8 +253,25 @@ export interface NativeVerdict {
   readonly headers?: Record<string, string>
 }
 
-/** Return from a native route loader to render the route's OWN template with
- * HTTP 404. `data` (default `{}`) becomes the template context. */
+/** Signal "not found" from a route loader. ONE helper, two call shapes —
+ * matching how each render path consumes a loader result:
+ *
+ *  - NATIVE route loader: `return notFound(data?)`. The returned verdict is
+ *    inspected by `runNativeChainLoaders` and renders the route's OWN template
+ *    at HTTP 404 (`data` default `{}` becomes the template context).
+ *
+ *  - REACT route loader: `throw notFound()`. A React loader's RETURN value is
+ *    the component's `data` prop (never inspected as a verdict), so the only
+ *    way to signal not-found is to throw. The render dispatch discriminates the
+ *    thrown verdict (it is symbol-tagged — `isNativeVerdict`) BEFORE the generic
+ *    500/errorBoundary handler and renders the NEAREST catch-all (`path: '*'`)
+ *    for the route's prefix at HTTP 404 — NOT the route's own Component, NOT a
+ *    500. If no catch-all is registered for the prefix, a framework default 404
+ *    body is rendered. `data` is ignored on the React throw path (the catch-all
+ *    runs its own loader chain).
+ *
+ * Same value type (`NativeVerdict`) either way — native returns it, React
+ * throws it — so there is a single public `notFound()` API. */
 export function notFound(data?: unknown): NativeVerdict {
   return { [BRUST_VERDICT]: true, status: 404, render: true, data: data ?? {} }
 }
@@ -257,6 +292,115 @@ export function isNativeVerdict(x: unknown): x is NativeVerdict {
   )
 }
 
+const HTTP_ERROR: unique symbol = Symbol.for('brust.httpError')
+
+export interface HttpErrorOpts {
+  /** Override the Content-Type. Defaults: string body → `text/plain;
+   * charset=utf-8`, object body → `application/json; charset=utf-8`. */
+  contentType?: string
+  /** Extra response headers (e.g. `WWW-Authenticate`). */
+  headers?: Record<string, string>
+}
+
+/** The symbol-keyed value `httpError()` throws. Body/contentType are resolved
+ * at construction so every catch site emits the same wire shape. Mirrors the
+ * NativeVerdict / ActionError branding (Symbol.for survives the trigger being
+ * duplicated across bundles). */
+export interface HttpErrorTrigger {
+  readonly [HTTP_ERROR]: true
+  readonly status: number
+  readonly body: string
+  readonly contentType: string
+  readonly headers?: Record<string, string>
+}
+
+/** Throw from a route loader (React or native) to short-circuit the response
+ * with an arbitrary error status — the loader-side analogue of a middleware
+ * short-circuit:
+ *
+ * ```ts
+ * loader: async ({ req }) => {
+ *   if (!req.locals.user) throw httpError(403, 'no entry')
+ *   …
+ * }
+ * ```
+ *
+ * THROW-only (it never returns) — one usage form on both render paths, unlike
+ * `notFound()` which native loaders RETURN. `body`: string → text/plain (or
+ * `opts.contentType`), object → JSON, omitted → empty. Status must be an
+ * integer in 400-599: 3xx is `redirect()`'s job, a 404 that renders a page is
+ * `notFound()`'s. The response is a plain short-circuit — it never reaches the
+ * errorBoundary and never logs as a 500. */
+export function httpError(status: number, body?: string | object, opts?: HttpErrorOpts): never {
+  if (!Number.isInteger(status) || status < 400 || status > 599) {
+    throw new Error(
+      `httpError(status) must be an integer in 400-599, got ${status} — use redirect() for 3xx and notFound() for a rendered 404`,
+    )
+  }
+  let bodyStr: string
+  let contentType: string
+  if (body === undefined || typeof body === 'string') {
+    bodyStr = body ?? ''
+    contentType = opts?.contentType ?? 'text/plain; charset=utf-8'
+  } else {
+    bodyStr = JSON.stringify(body)
+    contentType = opts?.contentType ?? 'application/json; charset=utf-8'
+  }
+  const trigger: HttpErrorTrigger = {
+    [HTTP_ERROR]: true,
+    status,
+    body: bodyStr,
+    contentType,
+    headers: opts?.headers,
+  }
+  throw trigger
+}
+
+/** True when a thrown value is the `httpError()` trigger (symbol-keyed — a
+ * plain object with a `status` property is NOT mistaken for one). */
+export function isHttpErrorTrigger(x: unknown): x is HttpErrorTrigger {
+  return typeof x === 'object' && x !== null && (x as Record<symbol, unknown>)[HTTP_ERROR] === true
+}
+
+/** Framework default 404 body, served when a React `notFound()` fires but no
+ * catch-all (`path: '*'`) is registered for the route's prefix — so the response
+ * is still HTTP 404 with a body (never a 500, never a crash). */
+const DEFAULT_NOT_FOUND_BODY =
+  '<!doctype html><html lang="en"><head><meta charset="utf-8"><title>404 Not Found</title></head><body><main><h1>404</h1><p>Not found.</p></main></body></html>'
+
+/** True when a thrown value is the React `notFound()` trigger: a NativeVerdict
+ * that renders at HTTP 404 (vs a thrown `redirect()`, which is `render: false`).
+ * Distinct from ActionError (a different Symbol) and from real Errors, so the
+ * render-dispatch catch can re-render the catch-all ONLY for this case and let
+ * everything else fall through to the 500/errorBoundary path. */
+function isNotFoundTrigger(x: unknown): x is NativeVerdict {
+  return isNativeVerdict(x) && x.render === true && x.status === 404
+}
+
+/** Select the nearest catch-all (`path: '*'`) FlatRoute for an unmatched path —
+ * the JS-side mirror of Rust's `select_not_found` (routing/routes.rs). Returns
+ * the catch-all's route_id (array index) or `undefined` if none covers the path.
+ *
+ * Longest segment-prefix wins: a `notFoundPrefix` of `/docs` covers `/docs` and
+ * `/docs/...` but NOT `/docsearch`; the root catch-all (`''`) covers everything
+ * as the last resort. Identical precedence to the Rust unmatched-path tier, so a
+ * React `notFound()` selects the SAME catch-all a genuinely-unmatched path would. */
+function selectNotFound(routes: FlatRoute[], path: string): number | undefined {
+  let bestId: number | undefined
+  let bestLen = -1
+  for (let i = 0; i < routes.length; i++) {
+    const r = routes[i]
+    if (r.notFound !== true) continue
+    const p = r.notFoundPrefix ?? ''
+    const covers = p === '' || path === p || path.startsWith(`${p}/`)
+    if (covers && p.length > bestLen) {
+      bestLen = p.length
+      bestId = i
+    }
+  }
+  return bestId
+}
+
 /** Loader context passed to native chain loaders. */
 export interface NativeLoaderCtx {
   params: Record<string, string>
@@ -264,10 +408,15 @@ export interface NativeLoaderCtx {
   req: BrustRequest
 }
 
-/** Result of running a native route's chain loaders top-down: either a merged
- * flat context object (all loader results shallow-merged, child keys win), or
- * the first verdict encountered (top-down) which short-circuits the chain. */
-export type NativeChainResult = { data: Record<string, unknown> } | { verdict: NativeVerdict }
+/** Result of running a native route's chain loaders top-down: a merged flat
+ * context object (all loader results shallow-merged, child keys win), the
+ * first verdict encountered (top-down) which short-circuits the chain, or an
+ * `httpError()` trigger THROWN by a loader (intercepted per-loader so it never
+ * reaches the caller's generic 500 catch). */
+export type NativeChainResult =
+  | { data: Record<string, unknown> }
+  | { verdict: NativeVerdict }
+  | { httpError: HttpErrorTrigger }
 
 /** Run a native route's `flat.chain` loaders top-down (parent → leaf) and merge
  * their results into ONE flat context object.
@@ -294,7 +443,16 @@ export async function runNativeChainLoaders(
     if (!node.loader) continue
     // `as never` bypasses per-route Params narrowing — NativeLoaderCtx is the
     // default-instantiated loader ctx shape ({ params, path, req }).
-    const result = await node.loader(ctx as never)
+    let result: unknown
+    try {
+      result = await node.loader(ctx as never)
+    } catch (err) {
+      // httpError() short-circuit — intercept PER-LOADER so the trigger never
+      // reaches the caller's generic loader catch (which logs + 500s). Any
+      // other throw keeps the existing 500 contract.
+      if (isHttpErrorTrigger(err)) return { httpError: err }
+      throw err
+    }
     if (isNativeVerdict(result)) {
       return { verdict: result }
     }
@@ -409,6 +567,22 @@ export interface FlatRoute {
   /** Sub-project J — Component.name when leaf had `native: true`. Captured
    * at flatten time (build-time AST identifier), so minifier-safe. */
   nativeTemplate?: string
+  /** Catch-all (`{ path: '*' }`) marker. When true this FlatRoute is a
+   * "not found" fallback: it stays in the array at its natural index (route_id
+   * stable) but install SKIPS the matchit insert for it — it only renders when
+   * matchit returns NoMatch under `notFoundPrefix`. NEVER remove a flagged
+   * entry from the flat array (that would shift every later route_id).
+   *
+   * A catch-all render is stamped HTTP 404 UNCONDITIONALLY (spec invariant 4:
+   * "never 200"). A `redirect()` from the catch-all's OWN loader still wins —
+   * redirect verdicts short-circuit and return before the 404 stamp on every
+   * path. A non-redirect verdict status, however, is overridden by 404 (a 404
+   * page is a 404, by definition). */
+  notFound?: boolean
+  /** Parent layout's path prefix this catch-all covers. Root catch-all → `''`
+   * (matches everything as last resort). Longest segment-prefix wins at match
+   * time. Never contains `*` (it's the parent prefix, not the catch-all path). */
+  notFoundPrefix?: string
 }
 
 /** Compose a child's relative path onto a parent's base path.
@@ -530,7 +704,10 @@ function assertNativeSubtree(children: Route[], where: string): void {
  * the design spec (S3). */
 export function flattenRoutes(routes: Route[]): FlatRoute[] {
   const out: FlatRoute[] = []
-  walkRoutes(routes, [], '', out)
+  // Tracks `notFoundPrefix` values already claimed by a catch-all so a second
+  // catch-all under the same prefix throws instead of silently shadowing.
+  const seenNotFoundPrefixes = new Set<string>()
+  walkRoutes(routes, [], '', out, seenNotFoundPrefixes)
   return out
 }
 
@@ -539,6 +716,7 @@ function walkRoutes(
   parentChain: Route[],
   basePath: string,
   out: FlatRoute[],
+  seenNotFoundPrefixes: Set<string>,
 ): void {
   for (const r of routes) {
     validateRoute(r, basePath)
@@ -549,11 +727,36 @@ function walkRoutes(
       continue
     }
 
+    // Catch-all (`{ path: '*' }`) — a "not found" fallback for the `basePath`
+    // subtree. It is a LEAF (no children/index) and is KEPT in the flat array
+    // at its natural index (route_id stable) flagged `notFound`. Its fullPath
+    // is set to the parent prefix (never a `*` matchit pattern) so a later
+    // install step can skip the matchit insert and rely on the flag.
+    if (r.path === '*') {
+      if (r.children && r.children.length > 0) {
+        throw new Error(`catch-all route "*" must be a leaf (no children) under "${basePath}"`)
+      }
+      // (index is already mutually exclusive with path via validateRoute.)
+      const prefix = basePath
+      if (seenNotFoundPrefixes.has(prefix)) {
+        throw new Error(
+          `duplicate catch-all route "*": only one catch-all allowed per prefix "${prefix}"`,
+        )
+      }
+      seenNotFoundPrefixes.add(prefix)
+      // Construct atomically (no post-hoc mutation) so the flag + prefix are
+      // never observable half-set. `fullPath === notFoundPrefix` by design; the
+      // install step gates the matchit-insert skip on the `notFound` flag, not
+      // on fullPath (see runtime/index.ts registerRoutes).
+      out.push({ ...makeFlat(chain, prefix), notFound: true, notFoundPrefix: prefix })
+      continue
+    }
+
     const ownPath = r.path ?? ''
     const myPath = joinPath(basePath, ownPath)
 
     if (r.children && r.children.length > 0) {
-      walkRoutes(r.children, chain, myPath, out)
+      walkRoutes(r.children, chain, myPath, out, seenNotFoundPrefixes)
     } else {
       // Leaf with a path (validated above).
       out.push(makeFlat(chain, myPath))
@@ -815,6 +1018,9 @@ export function makeRenderer(
       // have a per-conn AbortController. Middleware/loaders/components
       // can still read req.signal.aborted (always false).
       call.req.signal = NEVER_ABORTS
+      // Populate the TS-owned req fields (matched params + a fresh locals bag)
+      // BEFORE the middleware chain runs.
+      prepReq(call.req, call.params)
 
       // Run the middleware chain against a streaming-marker terminal.
       // Middleware that short-circuits (returns without calling next())
@@ -835,6 +1041,16 @@ export function makeRenderer(
       try {
         verdict = (await chain()) as StreamMarkerResponse
       } catch (err) {
+        // `throw httpError(...)` belongs in loaders, but a middleware that
+        // throws it still deserves the intended status, not a 500 + log dump.
+        if (isHttpErrorTrigger(err)) {
+          return packSingleChunkResponse(slotView, encoder, {
+            status: err.status,
+            contentType: err.contentType,
+            body: err.body,
+            headers: err.headers,
+          })
+        }
         console.error(`[brust] middleware/render uncaught:`, err)
         // FAST LANE: single-chunk error. Works for both React (big dispatch
         // reads the SAB via its fast-lane arm) and native routes (which take
@@ -972,6 +1188,18 @@ export function makeRenderer(
             body: 'internal error',
           })
         }
+        if ('httpError' in chainResult) {
+          // A native loader threw httpError() — short-circuit with the
+          // trigger's response (same fast-lane mechanism as a middleware
+          // short-circuit, which already carries arbitrary statuses).
+          const he = chainResult.httpError
+          return packSingleChunkResponse(slotView, encoder, {
+            status: he.status,
+            contentType: he.contentType,
+            body: he.body,
+            headers: he.headers,
+          })
+        }
         let renderStatus: number | undefined
         if ('verdict' in chainResult) {
           // First verdict wins (top-down). Remaining loaders already skipped.
@@ -991,6 +1219,12 @@ export function makeRenderer(
         } else {
           data = chainResult.data
         }
+        // Catch-all (`path: '*'`) leaf rendered on an unmatched path: stamp HTTP
+        // 404 unconditionally, regardless of any verdict status. The loader does
+        // NOT need to call notFound() — being a catch-all IS the 404 signal.
+        if (flat.notFound === true) {
+          renderStatus = 404
+        }
         // B7 — native store-snapshot SSR. Fill the framework-owned
         // `{{ __brust_store__ | safe }}` slot (emitted into every native
         // full-document <head>) with the defineStore SSR snapshot collected
@@ -1127,32 +1361,107 @@ export function makeRenderer(
       return await runInRequestContext(call.req?.cookies ?? {}, async () => {
         // Computed ONCE and shared by buildRenderElement (leaf swap) and
         // renderBranchStreaming (forceIslands) so the two can never diverge.
-        const shellMode = wantsSsgFallbackShell(flat, call)
-        let element: ReactNode
-        let errorBoundary: ComponentType<{ error: Error }>
+        let shellMode = wantsSsgFallbackShell(flat, call)
+        let element: ReactNode = null
+        // The route actually rendered + its HTTP status. Normally the matched
+        // `flat` at the verdict status (404 when the matched route IS a
+        // catch-all). A React loader that `throw`s `notFound()` swaps both to
+        // the nearest catch-all at 404 below.
+        let renderFlat = flat
+        let renderStatus = flat.notFound === true ? 404 : verdict.status
         try {
           element = await buildRenderElement(call, flat, opts.getWorkerId, shellMode)
-          errorBoundary =
-            flat.errorBoundary ??
-            (({ error }) => createElement('div', null, `Internal Server Error: ${error.message}`))
         } catch (err) {
-          // Setup failure BEFORE renderToPipeableStream — loader throw, params
-          // bind throw. Shape matches the legacy "internal error" path so
-          // existing integration tests stay green.
-          console.error(`[brust] render setup failed:`, err)
-          return await emitSingleChunkResponse(
-            slotView,
-            napi,
-            workerId,
-            encoder,
-            {
-              status: 500,
-              contentType: 'text/html; charset=utf-8',
-              body: 'internal error',
-            },
-            slot,
-          )
+          if (isHttpErrorTrigger(err)) {
+            // React loader threw httpError() — short-circuit with the trigger's
+            // response. NOT the errorBoundary, NOT the 500 path below: this is
+            // a deliberate response, like a middleware short-circuit.
+            return await emitSingleChunkResponse(
+              slotView,
+              napi,
+              workerId,
+              encoder,
+              {
+                status: err.status,
+                contentType: err.contentType,
+                body: err.body,
+                headers: err.headers,
+              },
+              slot,
+            )
+          }
+          if (isNotFoundTrigger(err)) {
+            // React `notFound()` trigger: abandon the matched route and render
+            // the NEAREST catch-all (same selection as a Rust-unmatched path)
+            // at HTTP 404 — NOT the route's own Component, NOT a 500. Reuse the
+            // existing 404-render machinery by re-running buildRenderElement
+            // against the catch-all's chain.
+            // nfId is the array index, which IS the route_id (catch-alls keep
+            // their natural slot — see FlatRoute.notFound), so byRouteId resolves
+            // the same flat route the Rust tier picks for an unmatched path.
+            const nfId = selectNotFound(routes, call.path)
+            const nfFlat = nfId !== undefined ? byRouteId.get(nfId) : undefined
+            renderStatus = 404
+            if (nfFlat) {
+              renderFlat = nfFlat
+              shellMode = wantsSsgFallbackShell(nfFlat, call)
+              try {
+                element = await buildRenderElement(call, nfFlat, opts.getWorkerId, shellMode)
+              } catch (nfErr) {
+                // The catch-all's OWN loader/render setup failed — don't loop;
+                // fall back to the framework default 404 body at 404.
+                console.error(`[brust] catch-all render setup failed:`, nfErr)
+                return await emitSingleChunkResponse(
+                  slotView,
+                  napi,
+                  workerId,
+                  encoder,
+                  {
+                    status: 404,
+                    contentType: 'text/html; charset=utf-8',
+                    body: DEFAULT_NOT_FOUND_BODY,
+                  },
+                  slot,
+                )
+              }
+            } else {
+              // No catch-all registered for this prefix → framework default 404
+              // body at status 404 (don't crash, don't 500).
+              return await emitSingleChunkResponse(
+                slotView,
+                napi,
+                workerId,
+                encoder,
+                {
+                  status: 404,
+                  contentType: 'text/html; charset=utf-8',
+                  body: DEFAULT_NOT_FOUND_BODY,
+                },
+                slot,
+              )
+            }
+          } else {
+            // Setup failure BEFORE renderToPipeableStream — loader throw, params
+            // bind throw. Shape matches the legacy "internal error" path so
+            // existing integration tests stay green.
+            console.error(`[brust] render setup failed:`, err)
+            return await emitSingleChunkResponse(
+              slotView,
+              napi,
+              workerId,
+              encoder,
+              {
+                status: 500,
+                contentType: 'text/html; charset=utf-8',
+                body: 'internal error',
+              },
+              slot,
+            )
+          }
         }
+        const errorBoundary: ComponentType<{ error: Error }> =
+          renderFlat.errorBoundary ??
+          (({ error }) => createElement('div', null, `Internal Server Error: ${error.message}`))
         const storeSnapshot = collectSnapshot()
         await renderBranchStreaming({
           element,
@@ -1161,9 +1470,11 @@ export function makeRenderer(
           workerId,
           napi,
           errorBoundary,
-          status: verdict.status,
+          // Catch-all (`path: '*'`) leaf rendered on an unmatched path OR a
+          // React `notFound()` swap: stamp HTTP 404 (mirrors the native path).
+          status: renderStatus,
           headers: flushSetCookie(verdict.headers),
-          routePath: flat.fullPath,
+          routePath: renderFlat.fullPath,
           storeSnapshot,
           // SSG fallback shells have zero islands on the page but the
           // client-loader runtime still needs the importmap + bootstrap.
@@ -1174,7 +1485,7 @@ export function makeRenderer(
       })
     }
     if (call.kind === 'navigation') {
-      await navigationBranch(call, byRouteId, slotView, encoder, opts.getWorkerId, slot)
+      await navigationBranch(call, byRouteId, routes, slotView, encoder, opts.getWorkerId, slot)
       return 0
     }
     if (call.kind === 'action') {
@@ -1229,45 +1540,13 @@ export function makeRenderer(
   }
 }
 
-/** Render a React element to a single HTML string, awaiting all Suspense
- * boundaries via onAllReady. Used by navigationBranch — renderToString
- * would only capture the shell + fallbacks, while renderBranchStreaming
- * is for the streaming render path. */
-function renderToAwaitedString(element: ReactNode): Promise<string> {
-  return new Promise<string>((resolve, reject) => {
-    const chunks: Buffer[] = []
-    const sink = new Writable({
-      write(chunk, _enc, cb) {
-        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk))
-        cb()
-      },
-    })
-    sink.on('finish', () => resolve(Buffer.concat(chunks).toString('utf8')))
-    sink.on('error', reject)
-
-    let stream: ReturnType<typeof renderToPipeableStream>
-    stream = renderToPipeableStream(element, {
-      onAllReady() {
-        try {
-          stream.pipe(sink)
-        } catch (e) {
-          reject(e)
-        }
-      },
-      onShellError(err) {
-        reject(err)
-      },
-      onError(err) {
-        // Logged at the navigationBranch level; let onAllReady drive completion.
-        console.error('[brust] navigation render onError:', err)
-      },
-    })
-  })
-}
+// renderToAwaitedString moved to render/fragment.ts (shared with the public
+// renderFragment API) — imported above; navigationBranch behavior unchanged.
 
 async function navigationBranch(
   call: Extract<RouteCall, { kind: 'navigation' }>,
   byRouteId: Map<number, FlatRoute>,
+  routes: FlatRoute[],
   view: Uint8Array,
   encoder: TextEncoder,
   getWorkerId: (() => number | null) | undefined,
@@ -1317,6 +1596,10 @@ async function navigationBranch(
     _brustStream: NAV_MARKER,
   })
 
+  // Populate the TS-owned req fields (matched params + a fresh locals bag)
+  // BEFORE the middleware chain runs — mirrors the render branch.
+  prepReq(call.req, call.params)
+
   // navigationBranch receives a 'navigation' call, but composeChain only
   // needs req + middleware — cast to satisfy the type.
   const navChain = composeChain(
@@ -1329,6 +1612,17 @@ async function navigationBranch(
   try {
     navVerdict = (await navChain()) as NavMarkerResponse
   } catch (err) {
+    // Same guard as the render path: an httpError thrown from middleware gets
+    // its intended status (non-2xx nav → client full-reload contract).
+    if (isHttpErrorTrigger(err)) {
+      await emitSingleChunkResponse(view, napi, workerId, encoder, {
+        status: err.status,
+        contentType: err.contentType,
+        body: err.body,
+        headers: err.headers,
+      })
+      return
+    }
     console.error('[brust] navigation middleware threw:', err)
     await emitSingleChunkResponse(
       view,
@@ -1384,6 +1678,14 @@ async function navigationBranch(
     // with no headers param, so staged cookies are dropped there (same as the
     // full-document native render path).
     let navHeaders: Record<string, string> | undefined
+    // The nav-payload HTTP status. Normally 200, or 404 when the matched route
+    // IS a catch-all (rendered on a genuinely-unmatched `/_brust/page/*` path).
+    // A React loader `throw notFound()` (caught below) swaps the rendered route
+    // to the nearest catch-all and forces this to 404 — mirroring the
+    // full-document render path. NOTE: in the trigger case `flat` is the MATCHED
+    // route (notFound === false), so the status must be forced to 404 explicitly,
+    // not derived from `flat.notFound`.
+    let navStatus = flat.notFound === true ? 404 : 200
     if (flat.nativeTemplate !== undefined) {
       fullHtml = await renderNativeRouteToHtml(call, flat, view, encoder, workerId, slot)
     } else {
@@ -1393,23 +1695,54 @@ async function navigationBranch(
       // injection is needed in a NAV payload: the payload is swapped into a
       // document that already booted the bootstrap (the navigator IS the
       // bootstrap), and the takeover runtime imports its chunk itself.
-      fullHtml = await runInRequestContext(call.req?.cookies ?? {}, async () => {
-        const element = await buildRenderElement(
-          call as any,
-          flat,
-          getWorkerId,
-          wantsSsgFallbackShell(flat, call as any),
-        )
-        if (!element) throw new Error('render setup failed')
-        // Use renderToPipeableStream + onAllReady so pages with <Suspense> emit
-        // their RESOLVED markup, not the fallback. renderToString would only
-        // capture the shell — navigating SPA-style to a Suspense-using route
-        // would otherwise ship "loading…" and never recover.
-        const html = await renderToAwaitedString(element)
-        store = collectSnapshot()
-        navHeaders = flushSetCookie(undefined)
-        return html
-      })
+      const renderFlatToHtml = (target: FlatRoute): Promise<string> =>
+        runInRequestContext(call.req?.cookies ?? {}, async () => {
+          const element = await buildRenderElement(
+            call as any,
+            target,
+            getWorkerId,
+            wantsSsgFallbackShell(target, call as any),
+          )
+          if (!element) throw new Error('render setup failed')
+          // Use renderToPipeableStream + onAllReady so pages with <Suspense> emit
+          // their RESOLVED markup, not the fallback. renderToString would only
+          // capture the shell — navigating SPA-style to a Suspense-using route
+          // would otherwise ship "loading…" and never recover.
+          const html = await renderToAwaitedString(element)
+          store = collectSnapshot()
+          navHeaders = flushSetCookie(undefined)
+          return html
+        })
+      try {
+        fullHtml = await renderFlatToHtml(flat)
+      } catch (err) {
+        if (!isNotFoundTrigger(err)) throw err
+        // React `notFound()` trigger on the SPA-nav path: abandon the matched
+        // route and render the NEAREST catch-all (same selection as a
+        // Rust-unmatched path) as the nav payload at HTTP 404 — NOT a 500
+        // `{"error":"render failed"}`. Mirrors the full-document render path.
+        navStatus = 404
+        // nfId is the array index == route_id (catch-alls keep their slot).
+        const nfId = selectNotFound(routes, call.path)
+        const nfFlat = nfId !== undefined ? byRouteId.get(nfId) : undefined
+        if (nfFlat) {
+          try {
+            fullHtml = await renderFlatToHtml(nfFlat)
+          } catch (nfErr) {
+            // The catch-all's OWN loader/render threw (notFound or a real error):
+            // ship the framework default 404 body — don't recurse into another
+            // catch-all selection.
+            console.error('[brust] catch-all nav render failed:', nfErr)
+            fullHtml = DEFAULT_NOT_FOUND_BODY
+            store = null
+          }
+        } else {
+          // No catch-all registered for this prefix → framework default 404 body
+          // shipped as a nav payload (so the client swaps it in), at 404.
+          fullHtml = DEFAULT_NOT_FOUND_BODY
+          store = null
+        }
+      }
     }
 
     // Extract <main> inner content. If the page didn't render a <main>,
@@ -1436,7 +1769,11 @@ async function navigationBranch(
       workerId,
       encoder,
       {
-        status: 200,
+        // Catch-all (`path: '*'`) leaf rendered as a SPA-nav payload on an
+        // unmatched path — OR a React `throw notFound()` swapped to the nearest
+        // catch-all — stamps HTTP 404 while still shipping the rendered body so
+        // the client swaps it in (vs the bare `{"error":"not found"}`).
+        status: navStatus,
         contentType: 'application/json; charset=utf-8',
         body,
         headers: navHeaders,
@@ -1444,6 +1781,28 @@ async function navigationBranch(
       slot,
     )
   } catch (err) {
+    if (isHttpErrorTrigger(err)) {
+      // A loader threw httpError() on the SPA-nav path (React render or the
+      // native re-throw below). Mirror the existing non-2xx middleware
+      // short-circuit semantics: emit the trigger's response as-is — the
+      // client treats any non-2xx nav response as a fallback trigger (full
+      // reload), so the user lands on the authoritative document response.
+      // No new JSON error shape.
+      await emitSingleChunkResponse(
+        view,
+        napi,
+        workerId,
+        encoder,
+        {
+          status: err.status,
+          contentType: err.contentType,
+          body: err.body,
+          headers: err.headers,
+        },
+        slot,
+      )
+      return
+    }
     console.error('[brust] navigation render failed:', err)
     await emitSingleChunkResponse(
       view,
@@ -1493,6 +1852,12 @@ async function renderNativeRouteToHtml(
     }),
   )
 
+  if ('httpError' in chainResult) {
+    // Re-throw the trigger — navigationBranch's catch emits it as the nav
+    // response (non-2xx → client full-reload, mirroring a middleware
+    // short-circuit).
+    throw chainResult.httpError
+  }
   if ('verdict' in chainResult) {
     // SPA nav can't emit a redirect/404 in-place; force the client's full-reload
     // fallback so the document path produces the authoritative status.
@@ -1860,6 +2225,10 @@ export async function dispatchAction(
     }
   }
   call.req.signal = NEVER_ABORTS
+  // Populate the TS-owned req fields (matched params + a fresh locals bag)
+  // BEFORE the middleware chain runs. ctx.req === call.req, so handler locals
+  // reads see middleware writes with zero threading.
+  prepReq(call.req, call.params)
 
   // Body decode — dispatch by content-type (JSON / urlencoded / multipart).
   let rawBody: unknown
@@ -1948,6 +2317,15 @@ export async function dispatchAction(
     } catch (err) {
       if (isActionError(err)) {
         response = actionErrorResponse(err)
+      } else if (isHttpErrorTrigger(err)) {
+        // ActionError is the idiomatic action-status tool, but an httpError
+        // escaping a shared middleware/handler still gets its intended status.
+        response = {
+          status: err.status,
+          body: err.body,
+          contentType: err.contentType,
+          headers: err.headers,
+        }
       } else {
         console.error('[brust] action middleware uncaught:', err)
         response = {
@@ -1981,6 +2359,9 @@ async function mcpBranchToResponse(
   // reading req.signal.aborted always sees false; the SSE branch is where
   // real disconnect lives.
   call.req.signal = NEVER_ABORTS
+  // No params in the MCP envelope and no middleware chain — but the
+  // BrustRequest contract declares params/locals non-optional, so populate.
+  prepReq(call.req, undefined)
   const responseJson = await mcp.handleRequest(call.body_text, call.req)
   if (responseJson === '') {
     // Notification — no response body. Return 204 No Content.
@@ -2054,6 +2435,9 @@ async function sseBranch(
   // Inject NEVER_ABORTS into req for the middleware run. handleSseStream
   // will overwrite with a per-conn AbortController.signal afterward.
   call.req.signal = NEVER_ABORTS
+  // The SSE envelope carries NO params — middleware sees empty params in v1
+  // (widening the Rust envelope is a separate change). Fresh locals bag.
+  prepReq(call.req, undefined)
 
   // Run middleware chain with a 200 placeholder terminal. The terminal
   // does NOT invoke leaf.sse — handleSseStream does that after middleware
@@ -2160,6 +2544,9 @@ async function wsBranch(
   // lifecycle is via registered onMessage/onClose callbacks rather than
   // awaiting on a request signal.
   call.req.signal = NEVER_ABORTS
+  // The WS envelope carries NO params — middleware sees empty params in v1
+  // (same contract as SSE above). Fresh locals bag.
+  prepReq(call.req, undefined)
 
   // Run middleware chain with a 101 placeholder terminal that signals
   // "ready to upgrade". The terminal does NOT call route.websocket —