@nifrajs/web 3.5.0 → 4.0.0

package/src/pwa-manifest.ts

@@ -0,0 +1,226 @@
+/**
+ * `@nifrajs/web/pwa-manifest` - a Web App Manifest builder, the declarative half of PWA next to
+ * `@nifrajs/web/service-worker`'s generated worker. Pure + runtime-agnostic: describe the app and
+ * get the `manifest.json` bytes to serve (typically `app.get("/manifest.webmanifest", ...)` with
+ * `content-type: application/manifest+json`), plus the `<link rel="manifest">` tag for the
+ * document head. Follows the [Web App Manifest spec](https://www.w3.org/TR/appmanifest/) field
+ * names exactly, so MDN is the reference for anything not documented here.
+ *
+ * Invalid input throws loudly at build/startup time (a missing install name, a malformed icon
+ * size, an unknown display mode) - a manifest the browser silently ignores is worse than no
+ * manifest, and these are all developer mistakes, never request input.
+ */
+
+export type ManifestDisplay = "fullscreen" | "standalone" | "minimal-ui" | "browser"
+export type ManifestDir = "ltr" | "rtl" | "auto"
+export type ManifestPurpose = "any" | "maskable" | "monochrome"
+
+export interface ManifestIcon {
+  /** Icon URL, resolved relative to `start_url` by the browser when relative. */
+  readonly src: string
+  /** Space-separated sizes, e.g. `"192x192 512x512"`, or `"any"`. Default `"any"`. */
+  readonly sizes?: string
+  /** MIME type, e.g. `"image/png"`. */
+  readonly type?: string
+  /** Space-separated purposes. Default `"any"`. */
+  readonly purpose?: string
+}
+
+export interface ManifestScreenshot {
+  readonly src: string
+  readonly sizes?: string
+  readonly type?: string
+}
+
+export interface ManifestShortcut {
+  readonly name: string
+  readonly url: string
+  readonly short_name?: string
+  readonly description?: string
+  readonly icons?: readonly ManifestIcon[]
+}
+
+export interface PwaManifestOptions {
+  /** Full install name (`"Nifra News"`). One of `name` / `short_name` is required. */
+  readonly name?: string
+  /** Short install name for launchers (`"News"`). One of `name` / `short_name` is required. */
+  readonly short_name?: string
+  readonly description?: string
+  /** Navigation scope root. Default `"/"`. */
+  readonly start_url?: string
+  /** URL scope the manifest (and its service worker) controls. Default `start_url`'s directory. */
+  readonly scope?: string
+  /** Preferred display mode. Default `"standalone"` (the installable PWA shape). */
+  readonly display?: ManifestDisplay
+  readonly orientation?: string
+  readonly background_color?: string
+  readonly theme_color?: string
+  readonly lang?: string
+  readonly dir?: ManifestDir
+  /** Opaque id distinguishing this install (defaults to `start_url` per spec). */
+  readonly id?: string
+  readonly categories?: readonly string[]
+  readonly icons?: readonly ManifestIcon[]
+  readonly screenshots?: readonly ManifestScreenshot[]
+  readonly shortcuts?: readonly ManifestShortcut[]
+}
+
+const SIZE_LIST = /^(?:any|\d+x\d+)(?:\s+(?:any|\d+x\d+))*$/
+const PURPOSE_TOKENS: ReadonlySet<string> = new Set(["any", "maskable", "monochrome"])
+
+/** The start URL's directory, origin-preserving for absolute URLs. Query strings and hashes
+ * never belong to a scope - it is a URL prefix the browser matches against. */
+function defaultScope(start_url: string): string {
+  if (start_url.startsWith("/")) {
+    const bare = start_url.split(/[?#]/)[0] as string
+    return bare.endsWith("/") ? bare : bare.slice(0, bare.lastIndexOf("/") + 1)
+  }
+  let url: URL
+  try {
+    url = new URL(start_url)
+  } catch {
+    throw new Error(`pwaManifest: start_url ${JSON.stringify(start_url)} is not a path or URL`)
+  }
+  if (url.origin === "null" || (url.protocol !== "http:" && url.protocol !== "https:")) {
+    throw new Error(`pwaManifest: start_url ${JSON.stringify(start_url)} is not a path or URL`)
+  }
+  const dir = url.pathname.endsWith("/")
+    ? url.pathname
+    : url.pathname.slice(0, url.pathname.lastIndexOf("/") + 1)
+  return `${url.origin}${dir}`
+}
+
+function purposeOf(purpose: string | undefined, what: string): string | undefined {
+  if (purpose === undefined) return undefined
+  const tokens = purpose.split(/\s+/).filter((t) => t !== "")
+  if (tokens.length === 0) throw new Error(`pwaManifest: ${what} purpose must not be empty`)
+  for (const token of tokens) {
+    if (!PURPOSE_TOKENS.has(token)) {
+      throw new Error(
+        `pwaManifest: ${what} purpose ${JSON.stringify(token)} must be any/maskable/monochrome`,
+      )
+    }
+  }
+  return tokens.join(" ")
+}
+
+/** Build the manifest document object (pass through `JSON.stringify` to serve it). */
+export function pwaManifest(options: PwaManifestOptions): Record<string, unknown> {
+  const { name, short_name } = options
+  if (name === undefined && short_name === undefined) {
+    throw new Error("pwaManifest: one of name / short_name is required")
+  }
+  if (name !== undefined && name.trim() === "") {
+    throw new Error("pwaManifest: name must not be empty")
+  }
+  if (short_name !== undefined && short_name.trim() === "") {
+    throw new Error("pwaManifest: short_name must not be empty")
+  }
+  const display = options.display ?? "standalone"
+  if (
+    display !== "fullscreen" &&
+    display !== "minimal-ui" &&
+    display !== "browser" &&
+    display !== "standalone"
+  ) {
+    throw new Error(`pwaManifest: unknown display ${JSON.stringify(display)}`)
+  }
+  if (
+    options.dir !== undefined &&
+    options.dir !== "ltr" &&
+    options.dir !== "rtl" &&
+    options.dir !== "auto"
+  ) {
+    throw new Error(`pwaManifest: unknown dir ${JSON.stringify(options.dir)}`)
+  }
+  const start_url = options.start_url ?? "/"
+  if (start_url === "" || start_url.startsWith("//")) {
+    throw new Error("pwaManifest: start_url must be a relative path or absolute URL")
+  }
+  const manifest: Record<string, unknown> = {}
+  if (name !== undefined) manifest.name = name
+  if (short_name !== undefined) manifest.short_name = short_name
+  if (options.description !== undefined) manifest.description = options.description
+  manifest.start_url = start_url
+  // The default scope is the start URL's directory ("https://x.com/app/home" → "…/app/"),
+  // query/hash excluded; a same-origin absolute URL keeps its origin, a relative one stays
+  // relative. Anything unparseable is a developer mistake, and fails loud.
+  manifest.scope = options.scope ?? defaultScope(start_url)
+  manifest.display = display
+  if (options.orientation !== undefined) manifest.orientation = options.orientation
+  if (options.background_color !== undefined) manifest.background_color = options.background_color
+  if (options.theme_color !== undefined) manifest.theme_color = options.theme_color
+  if (options.lang !== undefined) manifest.lang = options.lang
+  if (options.dir !== undefined) manifest.dir = options.dir
+  if (options.id !== undefined) manifest.id = options.id
+  if (options.categories !== undefined) manifest.categories = [...options.categories]
+  if (options.icons !== undefined) {
+    manifest.icons = options.icons.map((icon, i) => {
+      if (icon.src === "") throw new Error(`pwaManifest: icons[${i}].src must not be empty`)
+      const sizes = icon.sizes ?? "any"
+      if (!SIZE_LIST.test(sizes)) {
+        throw new Error(
+          `pwaManifest: icons[${i}].sizes ${JSON.stringify(icon.sizes)} must be "any" or space-separated WxH`,
+        )
+      }
+      const entry: Record<string, unknown> = { src: icon.src, sizes }
+      if (icon.type !== undefined) entry.type = icon.type
+      const purpose = purposeOf(icon.purpose, `icons[${i}]`)
+      if (purpose !== undefined) entry.purpose = purpose
+      return entry
+    })
+  }
+  if (options.screenshots !== undefined) {
+    manifest.screenshots = options.screenshots.map((shot, i) => {
+      if (shot.src === "") throw new Error(`pwaManifest: screenshots[${i}].src must not be empty`)
+      const entry: Record<string, unknown> = { src: shot.src }
+      if (shot.sizes !== undefined) {
+        if (!SIZE_LIST.test(shot.sizes)) {
+          throw new Error(
+            `pwaManifest: screenshots[${i}].sizes ${JSON.stringify(shot.sizes)} must be "any" or space-separated WxH`,
+          )
+        }
+        entry.sizes = shot.sizes
+      }
+      if (shot.type !== undefined) entry.type = shot.type
+      return entry
+    })
+  }
+  if (options.shortcuts !== undefined) {
+    manifest.shortcuts = options.shortcuts.map((cut, i) => {
+      if (cut.name === "") throw new Error(`pwaManifest: shortcuts[${i}].name must not be empty`)
+      if (cut.url === "") throw new Error(`pwaManifest: shortcuts[${i}].url must not be empty`)
+      const entry: Record<string, unknown> = { name: cut.name, url: cut.url }
+      if (cut.short_name !== undefined) entry.short_name = cut.short_name
+      if (cut.description !== undefined) entry.description = cut.description
+      if (cut.icons !== undefined) {
+        entry.icons = cut.icons.map((icon, j) => {
+          if (icon.src === "") {
+            throw new Error(`pwaManifest: shortcuts[${i}].icons[${j}].src must not be empty`)
+          }
+          const sizes = icon.sizes ?? "any"
+          if (!SIZE_LIST.test(sizes)) {
+            throw new Error(
+              `pwaManifest: shortcuts[${i}].icons[${j}].sizes must be "any" or space-separated WxH`,
+            )
+          }
+          return { src: icon.src, sizes }
+        })
+      }
+      return entry
+    })
+  }
+  return manifest
+}
+
+/** Serialize a manifest document to servable JSON (stable key order, no whitespace). */
+export function serializeManifest(manifest: Record<string, unknown>): string {
+  return JSON.stringify(manifest)
+}
+
+/** The `<link rel="manifest">` tag for the document head. */
+export function manifestLink(href = "/manifest.webmanifest"): string {
+  if (href === "") throw new Error("manifestLink: href must not be empty")
+  const quoted = href.replace(/"/g, "&quot;")
+  return `<link rel="manifest" href="${quoted}">`
+}

package/src/query.ts

@@ -642,7 +642,7 @@ export function createMutation<TData, TVariables>(
   let mutationFn = fn
   let cbs = callbacks
   let state = IDLE_MUTATION as MutationState<TData, TVariables>
-  let token = 0
+  let latest = 0
   const listeners = new Set<() => void>()
   const emit = (): void => {
     for (const l of listeners) l()
@@ -665,19 +665,19 @@ export function createMutation<TData, TVariables>(
     },
     reset: () => setState(IDLE_MUTATION as MutationState<TData, TVariables>),
     mutate: async (variables) => {
-      const mine = ++token
+      const mine = ++latest
       setState({ status: "pending", data: undefined, error: undefined, variables })
       // Only await a callback when one is actually supplied - an `await undefined` would insert a
       // needless microtask before the mutationFn runs (and complicates single-flight timing).
       if (cbs.onMutate !== undefined) await cbs.onMutate(variables)
       try {
         const data = await mutationFn(variables)
-        if (mine === token) setState({ status: "success", data, error: undefined, variables })
+        if (mine === latest) setState({ status: "success", data, error: undefined, variables })
         if (cbs.onSuccess !== undefined) await cbs.onSuccess(data, variables)
         if (cbs.onSettled !== undefined) await cbs.onSettled(data, undefined, variables)
         return data
       } catch (error) {
-        if (mine === token) setState({ status: "error", data: undefined, error, variables })
+        if (mine === latest) setState({ status: "error", data: undefined, error, variables })
         if (cbs.onError !== undefined) await cbs.onError(error, variables)
         if (cbs.onSettled !== undefined) await cbs.onSettled(undefined, error, variables)
         throw error

package/src/render-seam.ts

@@ -30,6 +30,41 @@ export interface RenderProps {
   readonly search?: Record<string, unknown>
   /** Neutral named-boundary states; adapters choose how each boundary's `render` UI is mounted. */
   readonly boundaries?: BoundaryStates
+  /** The rendered chain's module ids and `handle` exports, for the adapter's `useMatches`. */
+  readonly matchChain?: MatchChain
+}
+
+/**
+ * The modules a render stacks, as `useMatches` needs them: each one's id and `handle` export,
+ * outermost layout first and the page (or status page) last. Built by the server for SSR and by the
+ * generated client entry per route, from the same manifest, so both sides report the same matches.
+ */
+export interface MatchChain {
+  /** Layout ids (`orgs/[org]/_layout`), then the page's route id. */
+  readonly ids: readonly string[]
+  /** Each module's `handle` export, index-aligned with {@link ids}. */
+  readonly handles: readonly unknown[]
+}
+
+/** One module of the rendered chain, as `useMatches` returns it. */
+export interface UIMatch {
+  /** The module's id: a layout's (`orgs/[org]/_layout`), or the page's route id last. */
+  readonly id: string
+  /** The part of the URL path this module wraps: a layout's directory prefix, the whole path for the
+   * page. Raw, as it appears in the URL. */
+  readonly pathname: string
+  /** The params this module's loader receives: a layout's own, every route param for the page. */
+  readonly params: Readonly<Record<string, string>>
+  /** This module's loader data: `null` for a layout without a loader. */
+  readonly data: unknown
+  /** The module's `handle` export - any value, commonly a breadcrumb label or a render function. */
+  readonly handle: unknown
+}
+
+/** Per-document options for {@link RenderAdapter.renderToStream}. */
+export interface RenderStreamOptions {
+  /** The document's CSP nonce, for every executable `<script>` the framework streams. */
+  readonly nonce?: string
 }
 
 /**
@@ -39,11 +74,14 @@ export interface RenderProps {
 export interface RenderAdapter {
   /**
    * Render a route's layout `chain` (outermost layout → page) to a Web stream of HTML bytes,
-   * including the framework's hydration markers.
+   * including the framework's hydration markers. When `options.nonce` is set, every executable
+   * `<script>` the framework streams (out-of-order Suspense runtimes, serialized resources) must
+   * carry it, or a nonce-based Content-Security-Policy blocks it and the boundary never resolves.
    */
   renderToStream(
     chain: readonly unknown[],
     props: RenderProps,
+    options?: RenderStreamOptions,
   ): ReadableStream<Uint8Array> | Promise<ReadableStream<Uint8Array>>
   /** Render the chain to a complete HTML string when no content is deferred. */
   renderToString?(chain: readonly unknown[], props: RenderProps): string | Promise<string>
@@ -67,6 +105,13 @@ export function ssrModuleLoader(): SsrModuleLoader | undefined {
   return loaderSlot[SSR_MODULE_LOADER_SLOT]
 }
 
+/**
+ * `id` of the inert `<script type="application/json">` a hydrating document hands its page state over
+ * in: one JSON object keyed by the `*_GLOBAL` names below, which the client entry assigns onto
+ * `window` before anything reads them. Data the browser never executes needs no CSP nonce or hash.
+ */
+export const HANDOVER_ID = "__nifra-handover"
+
 /** Global the server serializes loader data into; the client reads it to hydrate. */
 export const DATA_GLOBAL = "__NIFRA_DATA__"
 /** Per-layout loader data for hydration. */

package/src/route-manifest.ts

@@ -16,8 +16,19 @@
  * target, and reports what the target cannot honour. Pure and fs-free: it takes an already-built
  * `Manifest` so it runs at build time, in `nifra routes`, and in a test with a hand-built manifest.
  */
+
+import { codeUnitOrder } from "./internal/code-unit-order.ts"
 import type { Manifest, RouteModule } from "./manifest.ts"
 
+export {
+  formatShadowedPages,
+  normalizeMountPath,
+  type ShadowedPage,
+  shadowedPages,
+} from "./internal/mount-shadow.ts"
+/** Which half of a route each export belongs in: the frontend file or its `x.backend.ts`. */
+export { BACKEND_ROUTE_EXPORTS, FRONTEND_ROUTE_EXPORTS } from "./manifest.ts"
+
 /**
  * How a route produces its HTML.
  *
@@ -115,7 +126,8 @@ export function deriveRouteEntry(
     requires: readonly RouteCapability[]
   } = { id, pattern, mode, hydrate: module.hydrate !== false, requires }
   if (mode === "isr" && module.revalidate !== undefined) entry.revalidate = module.revalidate
-  if (mode === "isr" && module.revalidateTags !== undefined) {
+  // A function's tags exist per request; the manifest records only a fixed list.
+  if (mode === "isr" && Array.isArray(module.revalidateTags)) {
     entry.revalidateTags = module.revalidateTags
   }
   if (prerenderedPaths !== undefined) entry.prerenderedPaths = prerenderedPaths
@@ -134,7 +146,7 @@ const TARGET_CAPABILITIES: Readonly<Record<string, readonly RouteCapability[]>>
   bun: ["server"],
   node: ["server"],
   deno: ["server"],
-  "cf-pages": ["server"],
+  cloudflare: ["server"],
   vercel: ["server"],
   static: [],
 }
@@ -169,7 +181,7 @@ export async function buildRouteManifest(
     const module = (await route.load()) as RouteModule
     entries.push(deriveRouteEntry(route.id, route.pattern, module, options.prerendered?.[route.id]))
   }
-  entries.sort((a, b) => a.pattern.localeCompare(b.pattern))
+  entries.sort((a, b) => codeUnitOrder(a.pattern, b.pattern))
 
   const conflicts: RouteManifestConflict[] = []
   const capabilities =

package/src/route-types.ts

@@ -0,0 +1,264 @@
+/**
+ * `@nifrajs/web/route-types` - the generated `./+types/<route>` modules.
+ *
+ * Every route file gets `.nifra/types/<routes>/<dir>/+types/<name>.d.ts`, declaring a `Route`
+ * namespace: the route's `Params`, the `LoaderData` and `ActionData` its output schemas let through,
+ * the `LoaderArgs` its backend half receives, and its component's props. With
+ * `"rootDirs": [".", "./.nifra/types"]` in tsconfig, both halves of a route import it as
+ * `./+types/<name>`:
+ *
+ *     // routes/blog/[slug].tsx
+ *     import type { Route } from "./+types/[slug]"
+ *     export default function Post({ data }: Route.ComponentProps) { ... }
+ *
+ *     // routes/blog/[slug].backend.ts
+ *     export async function loader({ api, params }: Route.LoaderArgs) { ... }
+ *
+ * `LoaderData` is the output type of `loaderOutput`, not the loader's return type: the data guard
+ * projects the loader's value through that schema, so the schema is what the component receives.
+ * `.nifra/types/register.d.ts` registers `backend/app.ts`'s `backend` with `@nifrajs/client`, so `api`
+ * is typed without a route importing the backend.
+ */
+import {
+  type Dirent,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs"
+import { dirname, join, relative } from "node:path"
+import { codeUnitOrder } from "./internal/code-unit-order.ts"
+import {
+  buildManifest,
+  isMiddlewareFile,
+  isRouteBackendFile,
+  type LayoutEntry,
+  type Manifest,
+} from "./manifest.ts"
+
+/** Where the generated types live, relative to the app root. */
+export const ROUTE_TYPES_DIR = ".nifra/types"
+
+const BACKEND_APP = "backend/app"
+const SCRIPT_EXTS = [".ts", ".tsx", ".js", ".jsx"] as const
+
+export interface RouteTypesOptions {
+  /** The app root: where `.nifra/` and `backend/app.ts` live. */
+  readonly appRoot: string
+  /** The routes directory. Defaults to `<appRoot>/routes`. */
+  readonly routesDir?: string
+}
+
+type Kind = "page" | "layout"
+
+interface RouteFile {
+  readonly file: string
+  readonly backend: string | undefined
+  readonly kind: Kind
+}
+
+const posix = (path: string): string => path.replaceAll("\\", "/")
+
+/** Every route file the router serves, once each: pages, layouts and the special pages. */
+function routeFiles(manifest: Manifest): readonly RouteFile[] {
+  const files = new Map<string, RouteFile>()
+  const add = (entry: Pick<LayoutEntry, "file" | "backend">, kind: Kind): void => {
+    if (!files.has(entry.file))
+      files.set(entry.file, { file: entry.file, backend: entry.backend, kind })
+  }
+  for (const route of manifest.routes) add(route, "page")
+  for (const layout of Object.values(manifest.layouts)) add(layout, "layout")
+  for (const group of [
+    manifest.errors,
+    manifest.notFounds,
+    manifest.statusPages,
+    manifest.loadings,
+  ]) {
+    for (const entry of Object.values(group ?? {})) add(entry, "page")
+  }
+  if (manifest.notFound !== undefined) add(manifest.notFound, "page")
+  return [...files.values()].sort((a, b) => codeUnitOrder(a.file, b.file))
+}
+
+const PARAM = /^\[([A-Za-z_][A-Za-z0-9_]*)\]$/
+const OPTIONAL = /^\[\[([A-Za-z_][A-Za-z0-9_]*)\]\]$/
+const CATCH_ALL = /^\[\.\.\.([A-Za-z_][A-Za-z0-9_]*)\]$/
+
+/** The params a route file's URL carries: its directories', plus its own name's for a page. */
+function paramsType(file: string, kind: Kind): string {
+  const segments = file.replace(/\.[^./]+$/, "").split("/")
+  const own =
+    kind === "page" && !segments.at(-1)?.startsWith("_") ? segments : segments.slice(0, -1)
+  const fields: string[] = []
+  for (const segment of own) {
+    const optional = OPTIONAL.exec(segment)
+    const name = optional?.[1] ?? PARAM.exec(segment)?.[1] ?? CATCH_ALL.exec(segment)?.[1]
+    if (name !== undefined) fields.push(`readonly ${name}${optional === null ? "" : "?"}: string`)
+  }
+  return fields.length === 0 ? "Record<string, never>" : `{ ${fields.join("; ")} }`
+}
+
+/** A module specifier for `target` from a file in `fromDir`, without a script extension. */
+function specifier(fromDir: string, target: string): string {
+  let path = posix(relative(fromDir, target))
+  for (const ext of SCRIPT_EXTS) if (path.endsWith(ext)) path = path.slice(0, -ext.length)
+  return path.startsWith(".") ? path : `./${path}`
+}
+
+const backendAppOf = (appRoot: string): string | undefined =>
+  SCRIPT_EXTS.map((ext) => join(appRoot, `${BACKEND_APP}${ext}`)).find((path) => existsSync(path))
+
+function routeTypesModule(
+  route: RouteFile,
+  out: string,
+  routesDir: string,
+  label: string,
+  register: string | undefined,
+): string {
+  const dir = dirname(out)
+  const backend = route.backend === undefined ? undefined : join(routesDir, route.backend)
+  // Only a script module's exports are visible to TypeScript; a .svelte/.vue/.mdx one is an ambient shim.
+  const frontend = /\.[jt]sx?$/.test(route.file) ? join(routesDir, route.file) : undefined
+  const lines = [`// Generated by nifra from ${label}. Do not edit: \`nifra types\` rewrites it.`]
+  if (register !== undefined)
+    lines.push(`/// <reference path="${posix(relative(dir, register))}" />`)
+  lines.push('import type { OutputOf, RouteLoaderArgs, SearchSchemaOf } from "@nifrajs/client"')
+  if (route.kind === "page") lines.push('import type { RenderProps } from "@nifrajs/web"')
+  lines.push("")
+  if (backend !== undefined)
+    lines.push(`type Backend = typeof import("${specifier(dir, backend)}")`)
+  if (frontend !== undefined)
+    lines.push(`type Frontend = typeof import("${specifier(dir, frontend)}")`)
+  if (backend !== undefined || frontend !== undefined) lines.push("")
+  const output = (name: string) => (backend === undefined ? "null" : `OutputOf<Backend, "${name}">`)
+  lines.push(
+    "export namespace Route {",
+    "  /** The URL params this route's path carries. */",
+    `  export type Params = ${paramsType(route.file, route.kind)}`,
+    "  /** What the loader sends to the browser: the output type of `loaderOutput`. */",
+    `  export type LoaderData = ${output("loaderOutput")}`,
+    "  /** What the action sends back: the output type of `actionOutput`. */",
+    `  export type ActionData = ${output("actionOutput")}`,
+    "  /** The context the backend half's loader receives. */",
+    `  export type LoaderArgs = RouteLoaderArgs<Params${frontend === undefined ? "" : ", SearchSchemaOf<Frontend>"}>`,
+    "  /** The context the backend half's action receives. */",
+    "  export type ActionArgs = LoaderArgs",
+  )
+  if (route.kind === "page") {
+    lines.push(
+      "  /** The page component's props. */",
+      '  export type ComponentProps = Omit<RenderProps, "data" | "actionData" | "params"> & {',
+      "    readonly data: LoaderData",
+      "    readonly actionData?: ActionData",
+      "    readonly params: Params",
+      "  }",
+    )
+  } else {
+    lines.push(
+      "  /** The layout component's props; `Children` is the adapter's children type. */",
+      "  export type ComponentProps<Children = unknown> = {",
+      "    readonly data: LoaderData",
+      "    readonly children?: Children",
+      "  }",
+    )
+  }
+  lines.push("}", "")
+  return lines.join("\n")
+}
+
+function registerModule(out: string, backendApp: string, label: string): string {
+  return [
+    `// Generated by nifra from ${label}. Do not edit: \`nifra types\` rewrites it.`,
+    `import type { backend } from "${specifier(dirname(out), backendApp)}"`,
+    "",
+    'declare module "@nifrajs/client" {',
+    "  interface Register {",
+    "    readonly backend: typeof backend",
+    "  }",
+    "}",
+    "",
+  ].join("\n")
+}
+
+/** Every generated types file for the app, by absolute path. */
+export function routeTypeFiles(options: RouteTypesOptions): ReadonlyMap<string, string> {
+  const appRoot = options.appRoot
+  const routesDir = options.routesDir ?? join(appRoot, "routes")
+  const typesRoot = join(appRoot, ROUTE_TYPES_DIR)
+  const files = new Map<string, string>()
+  const backendApp = backendAppOf(appRoot)
+  const register = backendApp === undefined ? undefined : join(typesRoot, "register.d.ts")
+  if (backendApp !== undefined && register !== undefined) {
+    files.set(register, registerModule(register, backendApp, posix(relative(appRoot, backendApp))))
+  }
+  if (!existsSync(routesDir)) return files
+  const listed = (readdirSync(routesDir, { recursive: true }) as string[])
+    .map(posix)
+    .filter(
+      (file) =>
+        /\.(?:tsx|jsx|svelte|vue|mdx)$/.test(file) ||
+        isRouteBackendFile(file) ||
+        isMiddlewareFile(file),
+    )
+  // Discovery only: the importer is never called.
+  const manifest = buildManifest(listed, () => () => Promise.reject(new Error("not loaded")))
+  const routesRel = posix(relative(appRoot, routesDir))
+  for (const route of routeFiles(manifest)) {
+    const dir = dirname(route.file)
+    const name = route.file.slice(dir === "." ? 0 : dir.length + 1).replace(/\.[^.]+$/, "")
+    const out = join(typesRoot, routesRel, dir === "." ? "" : dir, "+types", `${name}.d.ts`)
+    files.set(out, routeTypesModule(route, out, routesDir, `${routesRel}/${route.file}`, register))
+  }
+  return files
+}
+
+/** Generated files missing or different on disk, and files on disk the app no longer generates. */
+export function staleRouteTypes(options: RouteTypesOptions): readonly string[] {
+  const files = routeTypeFiles(options)
+  const stale: string[] = []
+  for (const [path, content] of files) {
+    if (!existsSync(path) || readFileSync(path, "utf8") !== content) stale.push(path)
+  }
+  for (const path of onDisk(join(options.appRoot, ROUTE_TYPES_DIR))) {
+    if (!files.has(path)) stale.push(path)
+  }
+  return stale.sort()
+}
+
+function onDisk(dir: string): readonly string[] {
+  if (!existsSync(dir)) return []
+  return (readdirSync(dir, { recursive: true, withFileTypes: true }) as Dirent[])
+    .filter((entry) => entry.isFile())
+    .map((entry) => join(entry.parentPath, entry.name))
+}
+
+export interface RouteTypesResult {
+  /** Files written because they were missing or out of date. */
+  readonly written: readonly string[]
+  /** Files removed because no route generates them any more. */
+  readonly removed: readonly string[]
+}
+
+/**
+ * Bring `.nifra/types` up to date with the app's routes. Unchanged files are left alone, so an
+ * editor watching them sees only real changes. Owns the directory: anything else in it is removed.
+ */
+export function writeRouteTypes(options: RouteTypesOptions): RouteTypesResult {
+  const files = routeTypeFiles(options)
+  const written: string[] = []
+  const removed: string[] = []
+  for (const [path, content] of files) {
+    if (existsSync(path) && readFileSync(path, "utf8") === content) continue
+    mkdirSync(dirname(path), { recursive: true })
+    writeFileSync(path, content)
+    written.push(path)
+  }
+  for (const path of onDisk(join(options.appRoot, ROUTE_TYPES_DIR))) {
+    if (files.has(path)) continue
+    rmSync(path)
+    removed.push(path)
+  }
+  return { written: written.sort(), removed: removed.sort() }
+}