@nifrajs/web 2.1.0 → 2.3.0

package/src/llms-txt.ts

@@ -91,11 +91,19 @@ export async function generateLlmsTxt(
   // 1. Project Guidelines
   let agentsMd = ""
   try {
-    if (typeof Bun !== "undefined") {
-      agentsMd = await Bun.file("AGENTS.md").text()
-    } else {
-      const fs = await import("node:fs/promises")
-      agentsMd = await fs.readFile("AGENTS.md", "utf-8")
+    // Edge bundles define this flag and dead-code-eliminate the filesystem branch. Keeping the import
+    // behind a runtime-only `typeof Bun` check is insufficient: Rollup must still emit an unresolved
+    // `node:` dependency, which workerd cannot load.
+    const edgeRuntime = (
+      globalThis as typeof globalThis & { readonly __NIFRA_EDGE_RUNTIME__?: boolean }
+    ).__NIFRA_EDGE_RUNTIME__
+    if (edgeRuntime !== true) {
+      if (typeof Bun !== "undefined") {
+        agentsMd = await Bun.file("AGENTS.md").text()
+      } else {
+        const fs = await import("node:fs/promises")
+        agentsMd = await fs.readFile("AGENTS.md", "utf-8")
+      }
     }
   } catch {
     // ignore

package/src/manifest.ts

@@ -1,16 +1,17 @@
 /**
- * Route manifest — the fs-free heart of file-based routing. Maps route file paths to nifra
+ * Route manifest - the fs-free heart of file-based routing. Maps route file paths to nifra
  * router patterns + their nested layout chain. `discoverRoutes` (in `@nifrajs/web/fs`) scans
  * the filesystem and feeds `buildManifest`; everything here is pure logic, so it stays
  * portable (no fs, no DOM) and fully unit-testable. Edge deploys pre-build the manifest.
  */
+import type { StandardSchemaV1 } from "@nifrajs/core/server"
 
 /** Context passed to a route `loader`. The `api` + `env` are injected by `createWebApp` and typed
  * per-route via `@nifrajs/client`'s `LoaderArgs<Api, Env>` (here they are opaque to the agnostic core). */
 export interface LoaderContext {
   readonly params: Record<string, string>
   readonly request: Request
-  /** Alias of {@link request} — mirrors a route handler's `c.req` so the same name works in both. */
+  /** Alias of {@link request} - mirrors a route handler's `c.req` so the same name works in both. */
   readonly req: Request
   readonly api: unknown
   /** Platform bindings forwarded from the request `c.env` (Workers env/KV/D1). Opaque here. */
@@ -18,6 +19,10 @@ export interface LoaderContext {
   /** `true` when the request carries a valid draft/preview cookie (only when `createWebApp` is given a
    * `draftSecret`; otherwise always `false`). Branch on it to load unpublished content for editors. */
   readonly draft: boolean
+  /** The URL search params, validated against the route's `searchSchema` (a Standard Schema) when it
+   * declares one - failing closed to the schema's defaults - else the raw parsed query. Typed per-route
+   * via `@nifrajs/client`'s `LoaderArgs<Api, Env, Search>`. */
+  readonly search: Record<string, unknown>
 }
 
 /** A route's optional data loader: params/request in, data out. */
@@ -25,20 +30,20 @@ export type Loader = (ctx: LoaderContext) => unknown | Promise<unknown>
 
 /**
  * A route's optional mutation, run on POST. Shares the loader context (params/request/api);
- * read the form/JSON body off `request`. Returns either a `Response` (e.g. a redirect —
+ * read the form/JSON body off `request`. Returns either a `Response` (e.g. a redirect -
  * passed straight through) or data, surfaced to the page component as `actionData`.
  */
 export type Action = (ctx: LoaderContext) => unknown | Promise<unknown>
 
 /**
  * One `<link>` tag's attributes for a route/layout's `meta.link`. The common HTML `<link>` attributes
- * are spelled out and **optional** so a typed partial like `{ rel, href, hreflang }` is assignable —
+ * are spelled out and **optional** so a typed partial like `{ rel, href, hreflang }` is assignable -
  * the previous `Record<string, string>` required *every* value to be a present string, which rejected
- * exactly that idiomatic shape (the bug this fixes). The index signature keeps custom/`data-*` attrs
- * (and any future standard attr) passing without a cast; `boolean` covers boolean attributes like
- * `disabled` (rendered as a bare attribute when `true`, omitted when `false`), and `undefined` lets a
- * caller spread in a conditionally-absent attribute. Attribute *names* are still shape-validated and
- * values HTML-escaped at render — a widened type never widens the injection surface.
+ * exactly that idiomatic shape (the bug this fixes). Standard attributes are explicit and the template
+ * index signature admits inert `data-*` metadata without opening executable `on*` attributes. `boolean`
+ * covers `disabled` (rendered bare when `true`, omitted when `false`), and `undefined` lets a caller
+ * spread in a conditionally absent attribute. SSR and soft navigation apply one runtime allowlist too,
+ * so a cast or untyped route cannot widen the injection surface.
  */
 export interface LinkDescriptor {
   readonly rel?: string
@@ -46,6 +51,7 @@ export interface LinkDescriptor {
   readonly hreflang?: string
   readonly crossorigin?: string
   readonly media?: string
+  readonly nonce?: string
   readonly sizes?: string
   readonly type?: string
   readonly as?: string
@@ -57,43 +63,85 @@ export interface LinkDescriptor {
   readonly imagesizes?: string
   readonly color?: string
   readonly disabled?: boolean
-  readonly [attr: string]: string | boolean | undefined
+  readonly [attr: `data-${string}`]: string | undefined
 }
 
-/** One `<script>` element a route contributes to `<head>` — for structured data (JSON-LD) and other
+/** One managed `<meta>` tag. Standard attributes and inert `data-*` metadata only. */
+export interface MetaDescriptor {
+  readonly charset?: string
+  readonly content?: string
+  readonly "http-equiv"?: string
+  readonly itemprop?: string
+  readonly media?: string
+  readonly name?: string
+  readonly property?: string
+  readonly scheme?: string
+  readonly [attr: `data-${string}`]: string | undefined
+}
+
+/** One `<script>` element a route contributes to `<head>` - for structured data (JSON-LD) and other
  * inert, non-executable head scripts. The `content` is the script body; `type` defaults to
  * `"application/ld+json"` (the common case). The renderer escapes `content` against an HTML breakout
- * (`</`, `<!--`, `]]>`) — see `escapeScriptContent` — so a JSON-LD payload can never close the
+ * (`</`, `<!--`, `]]>`) - see `escapeScriptContent` - so a JSON-LD payload can never close the
  * `<script>` element early. `content` is **JSON/text, never raw HTML**: this slot is not an XSS escape
  * hatch for arbitrary markup. */
+export type InertScriptType = "application/ld+json" | "application/json"
+
 export interface ScriptDescriptor {
   /** The script's `type` attribute. Default `"application/ld+json"`. */
-  readonly type?: string
+  readonly type?: InertScriptType
   /** The script body (e.g. a `JSON.stringify`'d JSON-LD object). Escaped for safe `<script>` embedding. */
   readonly content: string
 }
 
+/** Explicit escape hatch for executable inline code. A CSP nonce is mandatory. */
+export interface UnsafeScriptDescriptor {
+  readonly unsafe: true
+  readonly type: "module" | "text/javascript"
+  readonly nonce: string
+  readonly content: string
+}
+
 /**
- * The document head a route contributes — title + `<meta>`/`<link>`/`<script>` tag sets. Returned by a
+ * The document head a route contributes - title + `<meta>`/`<link>`/`<script>` tag sets. Returned by a
  * route/layout `meta` (statically, or from a {@link MetaArgs} function). Every value is serialized into
- * managed (`data-nifra`) head tags: attribute *names* are shape-validated and *values* HTML-escaped at
- * render (see `tagAttrs`/`headTags` in `@nifrajs/web`), and `script[].content` is breakout-escaped — so
- * loader-derived strings (LLM-authored `og:*`, user content) are XSS-safe in the head by construction.
+ * managed (`data-nifra`) head tags: tag-specific attribute allowlists reject event handlers and active
+ * URL/refresh contexts, values are HTML-escaped at render, and `script[].content` is breakout-escaped -
+ * so loader-derived strings (LLM-authored `og:*`, user content) are XSS-safe by construction.
  * Layout-chain heads merge with the page's via `mergeHeads` (arrays concat outermost→page; `title` is
  * nearest-wins). Build `og:*`/`twitter:*` with `openGraph(...)`, canonical with `canonical(...)`, and
  * JSON-LD with `jsonLd(...)` (all from `@nifrajs/web`) rather than hand-writing the records.
  */
 export interface Meta {
   readonly title?: string
-  readonly meta?: ReadonlyArray<Record<string, string>>
+  readonly meta?: readonly MetaDescriptor[]
   readonly link?: readonly LinkDescriptor[]
   /** Inert head `<script>`s (JSON-LD structured data, etc.). See {@link ScriptDescriptor}. */
   readonly script?: readonly ScriptDescriptor[]
+  /** Executable inline scripts. Prefer external modules; construct only with `unsafeInlineScript()`. */
+  readonly unsafeScript?: readonly UnsafeScriptDescriptor[]
+  /**
+   * The document language - `<html lang="...">`. Nearest-wins like `title`, so a localized route can
+   * override a layout's default. Defaults to `"en"` when no head in the chain sets it.
+   *
+   * This is the ONLY way to set it: the shell's `<html>` is framework-owned, so a multilingual app
+   * otherwise serves every URL as `lang="en"` - which tells a screen reader to pronounce every locale
+   * with an English voice, and suppresses the browser's translation offer.
+   */
+  readonly lang?: string
+  /**
+   * The document writing direction - `<html dir="...">`. Nearest-wins like `title`. Omitted from the
+   * shell when unset, which is HTML's `ltr` default, so an LTR app's output is byte-identical.
+   *
+   * Required for Arabic/Hebrew/Urdu/Persian: without it the browser lays the page out left-to-right
+   * and mis-orders trailing punctuation, so the text renders wrong rather than merely unstyled.
+   */
+  readonly dir?: "ltr" | "rtl" | "auto"
 }
 
 /**
  * Args for a route's `meta` function: the loader's `data` + the route `params` + the request `origin`.
- * `meta()` runs in BOTH SSR and client navigation, so it has **no `request`/`process.env`/server access** —
+ * `meta()` runs in BOTH SSR and client navigation, so it has **no `request`/`process.env`/server access** -
  * `origin` is the only server-resolved fact it gets (so you needn't thread `siteUrl` through loader data
  * for absolute `og:url`/`canonical`/`og:image` URLs). See {@link origin}.
  */
@@ -101,10 +149,10 @@ export interface MetaArgs<Data = unknown> {
   readonly data: Data
   readonly params: Record<string, string>
   /**
-   * The site origin — scheme + host (+ port), e.g. `"https://news.example.com"`, **with no trailing
+   * The site origin - scheme + host (+ port), e.g. `"https://news.example.com"`, **with no trailing
    * slash**. The single piece of server/env knowledge `meta()` otherwise can't see: it runs in BOTH
    * SSR and client navigation, so it has no `request`/`process.env`. The framework resolves it from the
-   * request URL during SSR and from `location.origin` on client nav — and they match, so an absolute
+   * request URL during SSR and from `location.origin` on client nav - and they match, so an absolute
    * `og:url`/`canonical`/`og:image` built from it never drifts between the server-rendered `<head>` and
    * a soft-nav. Use it for absolute URLs (`origin + "/posts/" + slug`) instead of threading `siteUrl`
    * through loader data. Empty string (`""`) when the origin is unknown (e.g. a hand-built test render
@@ -114,7 +162,7 @@ export interface MetaArgs<Data = unknown> {
 }
 
 /** A route's `meta`: a static {@link Meta}, or a function of the loader data + params + the request
- * origin ({@link MetaArgs}). Use the `origin` arg for absolute `canonical`/`og:url`/`og:image` URLs —
+ * origin ({@link MetaArgs}). Use the `origin` arg for absolute `canonical`/`og:url`/`og:image` URLs -
  * it's resolved server-side from the request and matches the client's `location.origin`. */
 export type MetaInput = Meta | ((args: MetaArgs) => Meta)
 
@@ -129,7 +177,7 @@ export interface StaticPaths {
   readonly paths: readonly StaticPath[]
   /**
    * How a path NOT in `paths` is handled. `"ssr"` (default) → rendered on-demand by the worker
-   * (the natural hybrid behavior — an unlisted path simply isn't a static file); `"404"` → only the
+   * (the natural hybrid behavior - an unlisted path simply isn't a static file); `"404"` → only the
    * listed paths exist. Recorded by `prerenderRoutes` for the deploy layer.
    */
   readonly fallback?: "ssr" | "404"
@@ -138,11 +186,21 @@ export interface StaticPaths {
 /** A dynamic route's build-time param enumeration (the SSG equivalent of "which pages exist"). */
 export type GetStaticPaths = () => StaticPaths | Promise<StaticPaths>
 
-/** A route module — the default component + optional loader / action / meta. */
+/** A route module - the default component + optional loader / action / meta. */
 export interface RouteModule {
   readonly default: unknown
   readonly loader?: Loader
   readonly action?: Action
+  /** A Standard Schema validating this route's URL search params. When present, `ctx.search` is parsed +
+   * validated against it (failing closed to the schema's defaults on invalid input); type it into the
+   * loader with `LoaderArgs<Api, Env, typeof searchSchema>`. */
+  readonly searchSchema?: StandardSchemaV1<unknown, Record<string, unknown>>
+  /** Search keys that are purely client-side UI (`"tab"`, a client-side `"sort"`, `"modal"`) and do NOT
+   * affect this route's loader. When a client navigation stays on the same route + pathname and changes
+   * ONLY these keys, the router updates the URL (so `useSearch` re-renders) WITHOUT re-running the loader.
+   * Any other key change revalidates as usual - so omitting a data-affecting key here can never serve
+   * stale data, it only forgoes the optimization. Client-only: the server always renders fresh. */
+  readonly searchClientKeys?: readonly string[]
   readonly meta?: MetaInput
   /**
    * Opt this route out of nifra's full-document client hydration. The server still renders the full
@@ -154,12 +212,12 @@ export interface RouteModule {
   /**
    * Opt a **static** route (no `:param`/`*`) into build-time prerendering (SSG): `prerenderRoutes`
    * (from `@nifrajs/web/build`) renders it to a static `index.html` at build. The loader runs at build
-   * with the in-process `api` (build-safe data only — no per-request cookies/secrets); `defer()` on a
+   * with the in-process `api` (build-safe data only - no per-request cookies/secrets); `defer()` on a
    * prerendered route resolves at build. For **dynamic** routes use {@link getStaticPaths} instead.
    */
   readonly prerender?: boolean
   /**
-   * Enumerate the concrete params to prerender for a **dynamic** (`:param`) route — the SSG path list
+   * Enumerate the concrete params to prerender for a **dynamic** (`:param`) route - the SSG path list
    * (blogs/docs/etc.). Runs at build; `prerenderRoutes` renders one `index.html` per returned path.
    */
   readonly getStaticPaths?: GetStaticPaths
@@ -171,7 +229,7 @@ export interface RouteModule {
   readonly revalidate?: number
   /**
    * No-framework island bundles (`@nifrajs/web/islands`) to load on this route, as `<script
-   * type="module">` in the document tail. Loaded **regardless of `hydrate`** — pair with
+   * type="module">` in the document tail. Loaded **regardless of `hydrate`** - pair with
    * `export const hydrate = false` for a static page that ships zero framework JS and mounts
    * interactivity through `<Island>` markers + `mountIslands` enhancers instead.
    */
@@ -181,7 +239,7 @@ export interface RouteModule {
 /** A layout (or `_404`/`_error`) entry: its source file (for client codegen) + a lazy loader.
  *
  * A `_layout.tsx` may export `meta` (static {@link Meta} or a function of the loader data + params,
- * same shape as a route's) to contribute sitewide `<head>` tags — `hreflang`/`preconnect`/etc. that
+ * same shape as a route's) to contribute sitewide `<head>` tags - `hreflang`/`preconnect`/etc. that
  * belong on every page under the layout. The layout chain's heads merge with the page's: arrays
  * (`meta`/`link`) concatenate outermost→innermost→page; scalars (`title`) are nearest-wins (the page
  * overrides an inner layout, which overrides an outer one). See `mergeHeads` in `@nifrajs/web`. */
@@ -195,6 +253,16 @@ export interface RouteEntry {
   readonly id: string
   readonly pattern: string
   readonly layoutIds: readonly string[]
+  /**
+   * Param names each layout in {@link layoutIds} owns, aligned by index.
+   *
+   * A layout wraps a URL prefix, so these are the params it may read and the ones whose change should
+   * re-run its loader - everything deeper belongs to routes beneath it. Derived per (route, layout)
+   * pair rather than per layout, because one layout can own different params on different expanded
+   * patterns: `[[lang]]/docs/_layout` owns nothing on `/docs/:slug` and `{lang}` on `/:lang/docs/:slug`.
+   * Optional only so hand-built test manifests may omit it.
+   */
+  readonly layoutParams?: ReadonlyArray<readonly string[]>
   /** `_error` boundary ids in this route's ancestor chain (outermost → innermost). The last is the
    * **nearest** boundary, rendered when the route's loader throws. Always set by `buildManifest`
    * (optional only so hand-built test manifests may omit it); absent/empty ⇒ no boundary (error 500s). */
@@ -211,11 +279,16 @@ export interface Manifest {
    * `buildManifest` (optional only so hand-built test manifests may omit it). */
   readonly errors?: Readonly<Record<string, LayoutEntry>>
   readonly notFound?: LayoutEntry
+  /** Per-status terminal pages from `_<status>.tsx` at the routes root (`_410`, `_451`, …), keyed by
+   * the status as a string. Rendered by a loader's `gone()` / `statusPage(n)`; a status with no page
+   * falls back to `_404`, and then to plain text. `_404` itself stays on {@link notFound} - it is
+   * reached by unmatched paths too, which these are not. */
+  readonly statusPages?: Readonly<Record<string, LayoutEntry>>
 }
 
 // `.svelte` and `.vue` routes are supported too: their `default` export is the component and
 // `loader`/`action`/`meta` come from a module-level script block (Svelte `<script module>`, Vue's plain
-// `<script>`) as named ESM exports — the same RouteModule shape as `.tsx`. Both compile via their
+// `<script>`) as named ESM exports - the same RouteModule shape as `.tsx`. Both compile via their
 // package's Bun plugin (`@nifrajs/web-svelte/plugin`, `@nifrajs/web-vue/plugin`).
 const ROUTE_EXT = /\.(tsx|jsx|svelte|vue|mdx)$/
 const PARAM = /^\[([A-Za-z_][A-Za-z0-9_]*)\]$/
@@ -224,8 +297,12 @@ const CATCH_ALL = /^\[\.\.\.([A-Za-z_][A-Za-z0-9_]*)\]$/
 // two patterns (`:lang` present / absent), so `[[lang]]/about` serves both `/about` and `/en/about`.
 const OPTIONAL = /^\[\[([A-Za-z_][A-Za-z0-9_]*)\]\]$/
 // A route group: a `(name)` folder organizes routes (and can hold its own `_layout`) without
-// contributing a URL segment — mirrors Next/Remix. Requires content between the parens.
+// contributing a URL segment - mirrors Next/Remix. Requires content between the parens.
 const GROUP = /^\(.+\)$/
+// A terminal status page: `_410.tsx`, `_451.tsx`. `_404` is matched before this and stays its own
+// thing. Restricted to 3 digits so `_401k` or `_4` is treated as an ordinary underscore-prefixed
+// file (ignored) rather than silently becoming a status page.
+const STATUS_PAGE = /^_[1-5][0-9][0-9]$/
 
 const stripExt = (file: string): string => file.replace(ROUTE_EXT, "")
 const baseName = (file: string): string => file.slice(file.lastIndexOf("/") + 1)
@@ -238,18 +315,116 @@ const errorIdFor = (dir: string): string => (dir === "" ? "_error" : `${dir}/_er
  * Derive **every** nifra router pattern a route file maps to (relative to the routes dir):
  * `index` → the parent path, `[id]` → `:id`, `[...slug]` → `*slug` (catch-all, captures the rest of
  * the path into one param), `(group)` folders are dropped from the URL (organization only), and an
- * optional `[[lang]]` expands the set — once with the segment present (`:lang`) and once absent. A file
+ * optional `[[lang]]` expands the set - once with the segment present (`:lang`) and once absent. A file
  * with no optionals yields exactly one pattern. Throws on an invalid param or a catch-all that isn't
  * the last segment.
  */
+/** Every `[…]` marker in a file segment, so a part-literal segment can be spliced into a pattern. */
+const FILE_MARKER = /\[([^\]]*)\]/g
+const FILE_PARAM_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/
+
+/**
+ * Translate a part-literal-part-`[param]` file segment into its route pattern, or `undefined` when
+ * the segment is wholly literal or wholly a marker (both already handled by the caller).
+ *
+ * `[inKey].txt` becomes `:inKey.txt`. Needed because IndexNow-style verification files, per-locale
+ * sitemaps, and static-site URL parity (`post-[id].html`) all put a variable INSIDE a filename, and
+ * `stripExt` already reduces `[inKey].txt.tsx` to `[inKey].txt` - `robots.txt.tsx` proves literal
+ * dots survive into a segment, so this was only ever a parser gap.
+ *
+ * `[[optional]]` and `[...catchAll]` are **rejected** inside a mixed segment rather than given a
+ * meaning. There is no sensible absent form for `/[[locale]]-feed.xml` - `/-feed.xml` and dropping
+ * the segment are both surprising - and a catch-all captures the remaining path verbatim, which
+ * conflicts with a trailing literal. A clear rejection beats semantics nobody can predict.
+ */
+function mixedFileSegment(seg: string, file: string): string | undefined {
+  // A segment that is ENTIRELY one of the existing whole-segment forms belongs to the caller, not
+  // here. Checked against the real patterns rather than by comparing the first marker to the
+  // segment: `[[lang]]` does not equal its own first `[…]` match, so a naive comparison sends every
+  // optional segment down the mixed path and rejects it.
+  if (PARAM.test(seg) || OPTIONAL.test(seg) || CATCH_ALL.test(seg)) return undefined
+  const markers = [...seg.matchAll(FILE_MARKER)]
+  if (markers.length === 0) return undefined
+
+  let pattern = ""
+  let cursor = 0
+  for (const marker of markers) {
+    const inner = marker[1] ?? ""
+    if (inner.startsWith("...")) {
+      throw new Error(
+        `[nifra/web] catch-all "[${inner}]" cannot be combined with literal text in "${file}" (segment "${seg}") - a catch-all captures the rest of the path, so a trailing literal can never match. Give it its own segment.`,
+      )
+    }
+    if (inner.startsWith("[")) {
+      throw new Error(
+        `[nifra/web] optional "[${inner}]]" cannot be combined with literal text in "${file}" (segment "${seg}") - there is no sensible form for the segment when it is absent. Use a required [name], or give the optional its own segment.`,
+      )
+    }
+    if (!FILE_PARAM_NAME.test(inner)) {
+      throw new Error(
+        `[nifra/web] invalid route param in "${file}": "[${inner}]" must be [name], [[name]], [...name], or a (group) folder`,
+      )
+    }
+    pattern += `${seg.slice(cursor, marker.index)}:${inner}`
+    cursor = (marker.index ?? 0) + marker[0].length
+  }
+  return pattern + seg.slice(cursor)
+}
+
 export function filePathToPatterns(file: string): string[] {
-  // Each combo is a list of URL segments built so far; an optional segment doubles the set.
-  let combos: string[][] = [[]]
+  return filePathToRoutes(file).map((route) => route.pattern)
+}
+
+/** One URL pattern a route file expands to, plus the scope information layouts need. */
+export interface FileRoutePattern {
+  readonly pattern: string
+  /**
+   * URL segments contributed by the first *k* path parts of the file, indexed by *k*.
+   *
+   * This is what makes a layout's scope derivable without turning layouts into router nodes. A layout
+   * lives at a directory; the segments that directory contributes are exactly the prefix of the URL it
+   * wraps, so `depths[partsIn(layoutDir)]` is how many leading pattern segments it owns - and the
+   * params inside that prefix are the ones it may read.
+   *
+   * Per EXPANDED pattern, not per file, because the two diverge: `[[lang]]/docs/_layout` owns nothing
+   * on `/docs/:slug` and `{lang}` on `/:lang/docs/:slug`. A route group contributes no segment, so
+   * `(marketing)/_layout` owns nothing at all.
+   */
+  readonly depths: readonly number[]
+}
+
+/** Expand a route file into its URL patterns, each carrying per-directory segment counts. */
+export function filePathToRoutes(file: string): FileRoutePattern[] {
+  // Each combo is the URL segments built so far, plus the running per-path-part segment count.
+  let combos: Array<{ segs: string[]; depths: number[] }> = [{ segs: [], depths: [0] }]
   const segments = stripExt(file).split("/")
+  // Record the running segment count after each path part, on every combo. Called once per part so
+  // `depths` stays index-aligned with the file's path parts even for parts that emit nothing.
+  const mark = (): void => {
+    for (const combo of combos) combo.depths.push(combo.segs.length)
+  }
+  const push = (segment: string): void => {
+    for (const combo of combos) combo.segs.push(segment)
+  }
   for (let i = 0; i < segments.length; i++) {
     const seg = segments[i]!
-    if (seg === "index") continue
-    if (GROUP.test(seg)) continue // route group — no URL segment (its `_layout` still applies, keyed by dir)
+    if (seg === "index") {
+      mark()
+      continue
+    }
+    if (GROUP.test(seg)) {
+      // Route group - no URL segment (its `_layout` still applies, keyed by dir).
+      mark()
+      continue
+    }
+    // A segment that is part literal, part `[param]` - `[inKey].txt`, `post-[id].html`. Checked
+    // before the whole-segment forms below, which only handle a marker spanning the entire segment.
+    const mixed = mixedFileSegment(seg, file)
+    if (mixed !== undefined) {
+      push(mixed)
+      mark()
+      continue
+    }
     if (seg.startsWith("[")) {
       const catchAll = CATCH_ALL.exec(seg)
       if (catchAll !== null) {
@@ -261,13 +436,18 @@ export function filePathToPatterns(file: string): string[] {
             `[nifra/web] catch-all "${seg}" must be the last segment in "${file}" (found "${after.join("/")}" after it)`,
           )
         }
-        combos = combos.map((c) => [...c, `*${catchAll[1]}`])
+        push(`*${catchAll[1]}`)
+        mark()
         continue
       }
       const optional = OPTIONAL.exec(seg)
       if (optional !== null) {
         // Optional segment: keep each existing combo (absent) AND a copy with `:name` appended (present).
-        combos = combos.flatMap((c) => [c, [...c, `:${optional[1]}`]])
+        combos = combos.flatMap((c) => [
+          { segs: c.segs, depths: c.depths },
+          { segs: [...c.segs, `:${optional[1]}`], depths: [...c.depths] },
+        ])
+        mark()
         continue
       }
       const match = PARAM.exec(seg)
@@ -276,16 +456,17 @@ export function filePathToPatterns(file: string): string[] {
           `[nifra/web] invalid route param in "${file}": "${seg}" must be [name], [[name]], [...name], or a (group) folder`,
         )
       }
-      combos = combos.map((c) => [...c, `:${match[1]}`])
+      push(`:${match[1]}`)
     } else {
-      combos = combos.map((c) => [...c, seg])
+      push(seg)
     }
+    mark()
   }
-  return combos.map((c) => `/${c.join("/")}`)
+  return combos.map((c) => ({ pattern: `/${c.segs.join("/")}`, depths: c.depths }))
 }
 
 /**
- * The **canonical** single pattern for a route file — all optional segments present. A file with no
+ * The **canonical** single pattern for a route file - all optional segments present. A file with no
  * optionals yields its one pattern. Use {@link filePathToPatterns} to get every pattern (optionals
  * expand the set).
  */
@@ -295,6 +476,26 @@ export function filePathToPattern(file: string): string {
 }
 
 /** The dir chain from root → the file's own dir, e.g. "a/b/p.tsx" → ["", "a", "a/b"]. */
+/**
+ * Param names in the first `count` segments of a pattern - the params a layout at that depth owns.
+ *
+ * This is the whole scoping mechanism: a layout wraps a URL prefix, so the params inside that prefix
+ * are the ones it may read, and the ones whose change should re-run its loader. Everything deeper
+ * belongs to routes below it and must not invalidate it.
+ */
+function paramsInPrefix(pattern: string, count: number): string[] {
+  if (count === 0) return []
+  const names: string[] = []
+  const segments = pattern === "/" ? [] : pattern.slice(1).split("/")
+  for (const segment of segments.slice(0, count)) {
+    // Mirrors the router's own grammar: `:name`, `*name`, and a mixed segment's embedded `:name`s.
+    for (const match of segment.matchAll(/[:*]([A-Za-z_][A-Za-z0-9_]*)/g)) {
+      names.push(match[1] as string)
+    }
+  }
+  return names
+}
+
 const ancestorDirs = (file: string): string[] => {
   const dirs = [""]
   const dir = dirOf(file)
@@ -309,7 +510,7 @@ const ancestorDirs = (file: string): string[] => {
 
 /**
  * Build a manifest from route file paths (relative to the routes dir) + an `importer` that
- * turns a path into a lazy module loader. Pure — no fs. Throws at boot (the loud-and-early
+ * turns a path into a lazy module loader. Pure - no fs. Throws at boot (the loud-and-early
  * RouteConfigError ethos) on duplicate patterns. `_layout`/`_404`/`_error` files are special; other
  * `_`-prefixed files are ignored (private/colocated, never routed).
  */
@@ -322,6 +523,7 @@ export function buildManifest(
   const errorDirs = new Set<string>()
   const errors: Record<string, LayoutEntry> = {}
   let notFound: LayoutEntry | undefined
+  const statusPages: Record<string, LayoutEntry> = {}
   const routeFiles: string[] = []
 
   for (const file of files) {
@@ -336,6 +538,11 @@ export function buildManifest(
       errors[errorIdFor(dir)] = { file, load: importer(file) }
     } else if (stem === "_404") {
       notFound = { file, load: importer(file) }
+    } else if (STATUS_PAGE.test(stem) && dirOf(file) === "") {
+      // `_410.tsx`, `_451.tsx`, … at the routes root. Root-only: unlike `_error`, these are not
+      // resolved per segment - a terminal status is a property of the outcome, not of where in the
+      // tree the route lives, and a per-segment variant would need a precedence rule nobody asked for.
+      statusPages[stem.slice(1)] = { file, load: importer(file) }
     } else if (!stem.startsWith("_")) {
       routeFiles.push(file)
     }
@@ -345,13 +552,14 @@ export function buildManifest(
   const routes: RouteEntry[] = []
   for (const file of routeFiles) {
     const dirs = ancestorDirs(file)
-    const layoutIds = dirs.filter((dir) => layoutDirs.has(dir)).map(layoutIdFor)
+    const layoutDirsForFile = dirs.filter((dir) => layoutDirs.has(dir))
+    const layoutIds = layoutDirsForFile.map(layoutIdFor)
     const errorIds = dirs.filter((dir) => errorDirs.has(dir)).map(errorIdFor)
     const id = stripExt(file)
     const load = importer(file) // one lazy loader per file, shared by its (possibly expanded) patterns
     // An optional `[[x]]` segment expands a file into multiple patterns, all pointing at the same
     // module (same id/load/layout chain). Distinct patterns ⇒ no match ambiguity (different lengths).
-    for (const pattern of filePathToPatterns(file)) {
+    for (const { pattern, depths } of filePathToRoutes(file)) {
       const existing = byPattern.get(pattern)
       if (existing !== undefined) {
         throw new Error(
@@ -359,11 +567,19 @@ export function buildManifest(
         )
       }
       byPattern.set(pattern, file)
-      routes.push({ id, pattern, layoutIds, errorIds, file, load })
+      const layoutParams = layoutDirsForFile.map((dir) =>
+        paramsInPrefix(pattern, depths[dir === "" ? 0 : dir.split("/").length] ?? 0),
+      )
+      routes.push({ id, pattern, layoutIds, layoutParams, errorIds, file, load })
     }
   }
 
-  const base: Manifest = { routes, layouts, errors }
+  const base: Manifest = {
+    routes,
+    layouts,
+    errors,
+    ...(Object.keys(statusPages).length > 0 ? { statusPages } : {}),
+  }
   return notFound === undefined ? base : { ...base, notFound }
 }
 
@@ -402,7 +618,7 @@ export function fillRoutePattern(
 /** The static-routing facts a server needs from the route modules: which concrete paths are
  * prerendered, plus each dynamic route's `getStaticPaths` fallback policy. */
 export interface StaticRoutes {
-  /** Concrete prerendered paths — static `prerender` routes + each `getStaticPaths` entry. */
+  /** Concrete prerendered paths - static `prerender` routes + each `getStaticPaths` entry. */
   readonly paths: string[]
   /** Per dynamic route pattern, its `getStaticPaths` `fallback` (`"ssr"` default). `createWebApp` uses
    * `"404"` to reject an unlisted path under that route at runtime (the path simply doesn't exist). */
@@ -410,7 +626,7 @@ export interface StaticRoutes {
 }
 
 /**
- * Enumerate the static-routing facts `prerenderRoutes` would produce — static routes opted in via
+ * Enumerate the static-routing facts `prerenderRoutes` would produce - static routes opted in via
  * `export const prerender = true`, each `getStaticPaths` entry of a dynamic route, and each dynamic
  * route's `fallback` policy. Pure (no rendering), so a server can compute what to hand `createWebApp`
  * (the prerendered set for the client's static-`_data.json` soft-nav + the fallback map for