@nifrajs/web 4.0.2 → 5.1.0

package/src/plugins/zone-guard.ts

@@ -10,11 +10,14 @@
 import { statSync } from "node:fs"
 import { dirname, isAbsolute, relative, resolve } from "node:path"
 import type { BunPlugin } from "bun"
+import { installedManifest } from "../internal/package-entries.ts"
 import { privateEnvDenial } from "../internal/private-env.ts"
+import { withoutQuery } from "../internal/without-query.ts"
 import {
   BACKEND_ONLY_MARKER,
   browserDenial,
   createZoneClassifier,
+  specifierPackage,
   type ZoneClassifier,
 } from "../zones.ts"
 
@@ -58,6 +61,40 @@ export interface ZoneGuardOptions {
 /** Zones whose code runs in a browser, so may read only public environment variables. */
 const BROWSER_CODE = new Set<string>(["route-frontend", "frontend", "shared"])
 
+const loaderFor = (file: string): "ts" | "tsx" | "js" | "jsx" | undefined => {
+  const extension = /\.[cm]?([jt]sx?)$/.exec(file)?.[1]
+  return extension === "ts" || extension === "tsx" || extension === "js" || extension === "jsx"
+    ? extension
+    : undefined
+}
+
+/**
+ * Why browser code at `file` may not make one of its package imports: one naming an entry its package
+ * declares backend-only, or one its per-entry map leaves out. A path cannot tell two entries that share
+ * a file apart, so the dev server judges the specifier here, where it is written.
+ */
+function entryDenial(classifier: ZoneClassifier, file: string, source: string): string | undefined {
+  const loader = loaderFor(file)
+  if (loader === undefined) return undefined
+  let imports: ReadonlyArray<{ readonly path: string }>
+  try {
+    imports = new Bun.Transpiler({ loader }).scanImports(source)
+  } catch {
+    // Source Bun cannot read fails its own load with the parse error.
+    return undefined
+  }
+  for (const { path } of imports) {
+    const name = specifierPackage(path)
+    const manifest = name === undefined ? undefined : installedManifest(dirname(file), name)
+    if (manifest === undefined) continue
+    const classification = classifier.classify(manifest, path)
+    if (classification.entry === undefined) continue
+    const reason = browserDenial(classification, path)
+    if (reason !== undefined) return `it imports "${path}": ${reason}`
+  }
+  return undefined
+}
+
 export function zoneGuardPlugin(options: ZoneGuardOptions): BunPlugin {
   const classifier = options.classifier ?? createZoneClassifier(options)
   const display = (file: string): string => {
@@ -86,14 +123,16 @@ export function zoneGuardPlugin(options: ZoneGuardOptions): BunPlugin {
           BROWSER_CODE.has(classification.zone)
         ) {
           const source = await Bun.file(args.path).text()
-          reason = privateEnvDenial(args.path, source, options.publicEnvPrefix ?? "PUBLIC_")
+          reason =
+            privateEnvDenial(args.path, source, options.publicEnvPrefix ?? "PUBLIC_") ??
+            entryDenial(classifier, args.path, source)
         }
         return reason === undefined ? undefined : refuse(args.path, reason)
       })
       build.onResolve({ filter: NON_SOURCE_PATH }, (args) => {
         // An entry point (a dev server's HTML page) is the build's own choice, not an import.
         if (args.importer === "") return undefined
-        const file = resolve(dirname(args.importer), args.path.replace(/[?#].*$/, ""))
+        const file = resolve(dirname(args.importer), withoutQuery(args.path))
         // No such file means an extensionless import of a dotted source name (`./date.utils`): Bun resolves
         // it to the source file, which onLoad judges. Judging the bare path would refuse a file never loaded.
         if (!isFile(file)) return undefined

package/src/prerender.ts

@@ -9,7 +9,7 @@
  * routes are not supported.
  */
 import { mkdirSync, writeFileSync } from "node:fs"
-import { dirname, resolve, sep } from "node:path"
+import { dirname, join, resolve, sep } from "node:path"
 import { assertNoSecrets, buildEnvironment, type SecretExemption } from "./internal/secret-scan.ts"
 import { fillRoutePattern, type RouteEntry } from "./manifest.ts"
 import { DATA_HEADER, PRERENDERED_GLOBAL, PRERENDERED_LIST_PATH } from "./router.ts"
@@ -70,10 +70,32 @@ function trimTrailingSlashes(path: string): string {
   return path.slice(0, end)
 }
 
-/** Map a route path to its output file: `/` → `index.html`, `/a/b` → `a/b/index.html`. */
+/**
+ * One request-path segment as the file name a static host looks up, which is the segment decoded, or
+ * `undefined` when no file name maps back to it: malformed percent-encoding, `.` or `..`, or a decoded
+ * `/`, `\` or NUL.
+ */
+function fileSegment(segment: string): string | undefined {
+  let decoded: string
+  try {
+    decoded = decodeURIComponent(segment)
+  } catch {
+    return undefined
+  }
+  if (decoded === "." || decoded === ".." || /[/\\\0]/.test(decoded)) return undefined
+  return decoded
+}
+
+/**
+ * Map a route path to its output file: `/` → `index.html`, `/a/b` → `a/b/index.html`. Segments are
+ * written decoded (`/caf%C3%A9` → `café/index.html`) because a static host decodes the request path
+ * before it looks for a file; a segment with no such file name stays as written.
+ */
 export function htmlFileFor(pattern: string): string {
   const trimmed = trimTrailingSlashes(pattern.replace(/^\/+/, ""))
-  return trimmed === "" ? "index.html" : `${trimmed}/index.html`
+  if (trimmed === "") return "index.html"
+  const segments = trimmed.split("/").map((segment) => fileSegment(segment) ?? segment)
+  return `${segments.join("/")}/index.html`
 }
 
 // The handover of a page whose prerendered set is served as a list rather than inlined.
@@ -119,6 +141,16 @@ export async function prerenderRoutes(options: PrerenderOptions): Promise<Preren
   // static (one path) and dynamic (one path per getStaticPaths entry) routes. A failed render is a skip;
   // a credential in the output fails the whole prerender.
   const renderPath = async (path: string): Promise<void> => {
+    // Refused before rendering: a segment no file name maps back to, or a file outside `outDir`.
+    const file = htmlFileFor(path)
+    const segments = trimTrailingSlashes(path.replace(/^\/+/, "")).split("/")
+    const abs = segments.every((s) => s === "" || fileSegment(s) !== undefined)
+      ? outputPath(outRoot, file)
+      : undefined
+    if (abs === undefined) {
+      skipped.push({ path, reason: "unsafe output path" })
+      return
+    }
     const res = await options.app.fetch(new Request(`${origin}${path}`))
     if (!res.ok) {
       // A failed render is a per-route skip, not a build failure - surfaced for the caller to log.
@@ -127,12 +159,6 @@ export async function prerenderRoutes(options: PrerenderOptions): Promise<Preren
     }
     const html = await res.text()
     listUrl ??= PRERENDERED_LIST_URL.exec(html)?.[1]
-    const file = htmlFileFor(path)
-    const abs = outputPath(outRoot, file)
-    if (abs === undefined) {
-      skipped.push({ path, reason: "unsafe output path" })
-      return
-    }
     assertClean(file, html)
     mkdirSync(dirname(abs), { recursive: true })
     writeFileSync(abs, html)
@@ -150,15 +176,10 @@ export async function prerenderRoutes(options: PrerenderOptions): Promise<Preren
       !(dataRes.headers.get("content-type") ?? "").includes("application/x-ndjson")
     ) {
       dataFile = dataFileFor(path)
-      const dataAbs = outputPath(outRoot, dataFile)
-      if (dataAbs === undefined) {
-        await dataRes.body?.cancel()
-        dataFile = undefined
-      } else {
-        const data = await dataRes.text()
-        assertClean(dataFile, data)
-        writeFileSync(dataAbs, data)
-      }
+      const data = await dataRes.text()
+      assertClean(dataFile, data)
+      // Beside `index.html`, so inside `outDir` whenever it is.
+      writeFileSync(join(dirname(abs), "_data.json"), data)
     } else {
       await dataRes.body?.cancel() // not emitting (non-OK or NDJSON) - release the stream
     }

package/src/public-dir.ts

@@ -12,12 +12,12 @@
  * Distinct from `publicPath` in `build.ts`, which is the URL prefix for content-hashed bundle chunks.
  * The names collide and the concepts do not: `publicPath` never covers user-authored files.
  */
-import { constants as FS } from "node:fs"
-import { open, realpath } from "node:fs/promises"
+import { realpath } from "node:fs/promises"
 import { extname, normalize, resolve, sep } from "node:path"
 import { Readable } from "node:stream"
 import { parseByteRange } from "@nifrajs/core/range"
 import { pathnameOf } from "@nifrajs/core/server"
+import { openResolved } from "./open-resolved.ts"
 
 /** How long each subtree may be cached. Content-hashed bundle output can be immutable; a
  * user-authored file keeps its name across deploys, so it gets a day and a revalidation. */
@@ -31,8 +31,15 @@ export interface PublicDirCache {
 export interface ServePublicDirOptions {
   /** Absolute path of the directory to serve. */
   readonly dir: string
-  /** URL prefix whose files are content-hashed and may be cached immutably (default `"/assets/"`). */
+  /** URL prefix whose files are content-hashed and may be cached immutably (default `"/assets/"`).
+   * Ignored when `hashedFiles` is set. */
   readonly hashedPrefix?: string
+  /**
+   * Encoded URL paths of the content-hashed files, such as a build manifest's `assets`. When set, only
+   * these are cached immutably and every other file gets the `assets` policy, so a user-authored file
+   * that happens to sit under the hashed prefix still revalidates.
+   */
+  readonly hashedFiles?: ReadonlySet<string>
   readonly cache?: PublicDirCache
   /** Optional encoded URL-path allowlist. When present, route misses avoid a filesystem probe. */
   readonly files?: ReadonlySet<string>
@@ -166,6 +173,7 @@ export function servePublicDir(
   const root = resolve(options.dir)
   const rootReal = realpath(root).catch(() => undefined)
   const hashedPrefix = options.hashedPrefix ?? "/assets/"
+  const hashedFiles = options.hashedFiles
   const hashed = options.cache?.hashed ?? IMMUTABLE
   const assets = options.cache?.assets ?? ONE_DAY
 
@@ -192,16 +200,27 @@ export function servePublicDir(
     }
     // Open the canonical path once and stream from that descriptor. Reopening the pathname after
     // realpath containment checks would let a writable public tree swap a symlink between validation
-    // and the actual read. O_NOFOLLOW also rejects a final-component symlink if one appears before
-    // the open; the descriptor then pins the bytes for the lifetime of the response.
-    let handle: Awaited<ReturnType<typeof open>> | undefined
+    // and the actual read. openResolved also refuses the name once any component of it became a
+    // symlink; the descriptor then pins the bytes for the lifetime of the response.
+    let handle: Awaited<ReturnType<typeof openResolved>> | undefined
     try {
-      handle = await open(resolvedFile, FS.O_RDONLY | FS.O_NOFOLLOW)
+      try {
+        handle = await openResolved(resolvedFile)
+      } catch {
+        // A name refused or gone since realpath falls through, as a failed realpath does.
+        return undefined
+      }
       const stat = await handle.stat()
       if (!stat.isFile()) return undefined
       const size = stat.size
       const headers = new Headers({
-        "cache-control": pathname.startsWith(hashedPrefix) ? hashed : assets,
+        "cache-control": (
+          hashedFiles === undefined
+            ? pathname.startsWith(hashedPrefix)
+            : hashedFiles.has(pathname)
+        )
+          ? hashed
+          : assets,
         // Advertised unconditionally: a client that never sees `accept-ranges` will not attempt a seek,
         // so a video or audio file under `public/` is scrubbable only once this header is present.
         "accept-ranges": "bytes",

package/src/query.ts

@@ -111,6 +111,12 @@ export interface DehydratedState {
     readonly data: unknown
     readonly updatedAt: number
   }>
+  /** The successful infinite queries, pages and page params. */
+  readonly infiniteQueries?: ReadonlyArray<{
+    readonly key: unknown
+    readonly data: InfiniteData<unknown, unknown>
+    readonly updatedAt: number
+  }>
 }
 
 /** The keyed query cache. One per app (a binding registers it like the router). */
@@ -125,8 +131,9 @@ export interface QueryClient {
     fn: (pageParam: P) => Promise<T>,
     options: InfiniteQueryOptions<T, P>,
   ) => InfiniteQueryHandle<T, P>
-  /** Mark matching cached queries stale and refetch the **mounted** ones (subscribers > 0). Array
-   * keys match by **prefix** (`["todo"]` ⇒ every `["todo", …]`); other keys match exactly. */
+  /** Mark matching cached queries, infinite ones included, stale and refetch the **mounted** ones
+   * (subscribers > 0). Array keys match by **prefix** (`["todo"]` ⇒ every `["todo", …]`); other keys
+   * match exactly. */
   invalidateQueries: (keyOrPrefix: unknown) => void
   /** Read a cached query's data (`undefined` if absent or not yet successful). Synchronous, no fetch. */
   getQueryData: <T>(key: unknown) => T | undefined
@@ -218,17 +225,24 @@ export function createQueryClient(options: QueryClientOptions): QueryClient {
 
   // Lazily evict entries whose GC timer has elapsed (no subscribers), then enforce the hard cap by
   // dropping the oldest-inserted unsubscribed entries. Called on every `query()` - no background timer.
-  const sweep = (): void => {
-    const t = now()
-    for (const [h, e] of cache) {
-      if (e.subscribers === 0 && e.gcAt !== undefined && t >= e.gcAt) cache.delete(h)
+  const sweepEntries = (
+    entries: Map<string, { readonly subscribers: number; readonly gcAt: number | undefined }>,
+    t: number,
+  ): void => {
+    for (const [h, e] of entries) {
+      if (e.subscribers === 0 && e.gcAt !== undefined && t >= e.gcAt) entries.delete(h)
     }
-    if (cache.size <= max) return
-    for (const [h, e] of cache) {
-      if (cache.size <= max) break
-      if (e.subscribers === 0) cache.delete(h) // oldest-inserted unsubscribed first (Map order)
+    if (entries.size <= max) return
+    for (const [h, e] of entries) {
+      if (entries.size <= max) break
+      if (e.subscribers === 0) entries.delete(h) // oldest-inserted unsubscribed first (Map order)
     }
   }
+  const sweep = (): void => {
+    const t = now()
+    sweepEntries(cache, t)
+    sweepEntries(infinite, t)
+  }
 
   // Build a cache entry + its handle. `fn`/`staleTime` are mutated in place on re-bind (closures change
   // between renders). All the fetch/dedup/generation machinery lives here so query(), prefetchQuery(),
@@ -348,6 +362,9 @@ export function createQueryClient(options: QueryClientOptions): QueryClient {
       entry.generation++
       if (entry.subscribers > 0) void entry.handle.refetch().catch(() => {}) // refresh mounted now (best-effort)
     }
+    for (const entry of infinite.values()) {
+      if (keyMatchesPrefix(entry.key, keyOrPrefix)) entry.invalidate()
+    }
   }
 
   const getQueryData = <T>(key: unknown): T | undefined => {
@@ -392,7 +409,17 @@ export function createQueryClient(options: QueryClientOptions): QueryClient {
       if (entry.state.status === "success")
         queries.push({ key: entry.key, data: entry.state.data, updatedAt: entry.state.updatedAt })
     }
-    return { queries }
+    const infiniteQueries: Array<{
+      key: unknown
+      data: InfiniteData<unknown, unknown>
+      updatedAt: number
+    }> = []
+    for (const entry of infinite.values()) {
+      const { status, data, updatedAt } = entry.handle.snapshot()
+      if (status === "success" && data !== undefined)
+        infiniteQueries.push({ key: entry.key, data, updatedAt })
+    }
+    return { queries, infiniteQueries }
   }
 
   const hydrate = (state: DehydratedState): void => {
@@ -409,6 +436,14 @@ export function createQueryClient(options: QueryClientOptions): QueryClient {
       if (entry.state.status !== "success" || q.updatedAt > entry.state.updatedAt)
         entry.setState(successState(q.data, q.updatedAt))
     }
+    // An infinite entry needs its page options before it can exist, so a snapshot for a key not yet
+    // queried waits here until `infiniteQuery` creates it.
+    for (const q of state.infiniteQueries ?? []) {
+      const h = hashQueryKey(q.key)
+      const existing = infinite.get(h)
+      if (existing === undefined) seeded.set(h, q)
+      else existing.seed(q.data, q.updatedAt)
+    }
   }
 
   // --- Infinite (paged) queries -----------------------------------------------------------------
@@ -427,19 +462,33 @@ export function createQueryClient(options: QueryClientOptions): QueryClient {
       )
       return existing.handle as InfiniteQueryHandle<T, P>
     }
-    const created = makeInfinite<T, P>(fn, opts)
+    const created = makeInfinite<T, P>(key, fn, opts)
     infinite.set(h, created as InfiniteEntry<unknown, unknown>)
+    const snapshot = seeded.get(h)
+    if (snapshot !== undefined) {
+      seeded.delete(h)
+      created.seed(snapshot.data, snapshot.updatedAt)
+    }
     return created.handle
   }
 
   // Infinite entries live in their own map (their data shape + fetch model differ from plain queries).
   interface InfiniteEntry<T, P> {
+    readonly key: unknown
     handle: InfiniteQueryHandle<T, P>
     rebind: (fn: (p: P) => Promise<T>, opts: InfiniteQueryOptions<T, P>) => void
+    /** Mark stale, drop an in-flight fetch's result, and refetch when mounted. */
+    invalidate: () => void
+    /** Take a dehydrated snapshot unless the entry already holds fresher data. */
+    seed: (data: InfiniteData<unknown, unknown>, updatedAt: number) => void
+    subscribers: number
+    gcAt: number | undefined
   }
   const infinite = new Map<string, InfiniteEntry<unknown, unknown>>()
+  const seeded = new Map<string, NonNullable<DehydratedState["infiniteQueries"]>[number]>()
 
   const makeInfinite = <T, P>(
+    key: unknown,
     fetchPage: (pageParam: P) => Promise<T>,
     initialOpts: InfiniteQueryOptions<T, P>,
   ): InfiniteEntry<T, P> => {
@@ -447,6 +496,7 @@ export function createQueryClient(options: QueryClientOptions): QueryClient {
     let opts = initialOpts
     let state: QueryState<InfiniteData<T, P>> = PENDING as QueryState<InfiniteData<T, P>>
     let generation = 0
+    let invalidated = false
     let promise: Promise<InfiniteData<T, P>> | undefined
     const listeners = new Set<() => void>()
     const emit = (): void => {
@@ -475,7 +525,8 @@ export function createQueryClient(options: QueryClientOptions): QueryClient {
         data.pageParams,
       )
     }
-    const isStale = (): boolean => now() - state.updatedAt >= (opts.staleTime ?? defaultStaleTime)
+    const isStale = (): boolean =>
+      invalidated || now() - state.updatedAt >= (opts.staleTime ?? defaultStaleTime)
 
     // Run a paged operation under a fresh generation, guarding against a superseding op (like `run`).
     const runPaged = (build: () => Promise<InfiniteData<T, P>>): Promise<InfiniteData<T, P>> => {
@@ -486,6 +537,7 @@ export function createQueryClient(options: QueryClientOptions): QueryClient {
         try {
           const data = await build()
           if (gen !== generation) return data
+          invalidated = false
           setState(successState(data, now()))
           return data
         } catch (error) {
@@ -511,9 +563,13 @@ export function createQueryClient(options: QueryClientOptions): QueryClient {
     const handle: InfiniteQueryHandle<T, P> = {
       snapshot: () => state,
       subscribe: (listener) => {
+        entry.subscribers++
+        entry.gcAt = undefined
         listeners.add(listener)
         return () => {
           listeners.delete(listener)
+          entry.subscribers--
+          if (entry.subscribers === 0) entry.gcAt = now() + gcTime
         }
       },
       fetch: () => fetchFirst(false),
@@ -558,13 +614,30 @@ export function createQueryClient(options: QueryClientOptions): QueryClient {
         return p !== undefined && p !== null
       },
     }
-    return {
-      handle: handle as InfiniteQueryHandle<unknown, unknown>,
+    const entry: InfiniteEntry<T, P> = {
+      key,
+      handle,
       rebind: (nextFn, nextOpts) => {
         fn = nextFn
         opts = nextOpts
       },
-    } as InfiniteEntry<T, P>
+      invalidate: () => {
+        invalidated = true
+        // A fetch begun before this point read pre-mutation data: it may not publish, and a new fetch
+        // must not join it.
+        generation++
+        promise = undefined
+        if (entry.subscribers > 0) void handle.refetch().catch(() => {})
+      },
+      seed: (data, updatedAt) => {
+        if (state.status === "success" && state.updatedAt >= updatedAt) return
+        // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: the snapshot was dehydrated from an entry under this key, whose pages and params are T and P
+        setState(successState(data as InfiniteData<T, P>, updatedAt))
+      },
+      subscribers: 0,
+      gcAt: undefined,
+    }
+    return entry
   }
 
   return {
@@ -609,8 +682,10 @@ export interface MutationCallbacks<TData, TVariables> {
 export interface MutationHandle<TData, TVariables> {
   snapshot: () => MutationState<TData, TVariables>
   subscribe: (listener: () => void) => () => void
-  /** Run the mutation. Resolves to the data (and runs onSuccess/onSettled) or rejects (onError/onSettled).
-   * The latest concurrent call wins the published state (older results are dropped). */
+  /** Run the mutation. Resolves to the data (and runs onSuccess/onSettled) or rejects (onError/onSettled);
+   * a throwing `onMutate` fails it the same way. A throwing `onSuccess` or `onSettled` after the write
+   * rejects the call but leaves the state `success` and never calls `onError`. The latest concurrent
+   * call wins the published state (older results are dropped). */
   mutate: (variables: TVariables) => Promise<TData>
   /** Rebind the latest `fn`/callbacks (closures change between renders) without losing state. */
   rebind: (
@@ -667,21 +742,27 @@ export function createMutation<TData, TVariables>(
     mutate: async (variables) => {
       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)
+      let data: TData
       try {
-        const data = await mutationFn(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
+        // 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)
+        data = await mutationFn(variables)
       } catch (error) {
         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
       }
+      if (mine === latest) setState({ status: "success", data, error: undefined, variables })
+      // The write happened: a success callback that throws rejects the call, but is no failure of the
+      // write, so it never reaches onError (which would roll back what the server kept).
+      try {
+        if (cbs.onSuccess !== undefined) await cbs.onSuccess(data, variables)
+      } finally {
+        if (cbs.onSettled !== undefined) await cbs.onSettled(data, undefined, variables)
+      }
+      return data
     },
   }
 }

package/src/render-seam.ts

@@ -12,6 +12,7 @@ import type { Submission } from "./router.ts"
 
 /** The data handed to a route component. */
 export interface RenderProps {
+  readonly serverComponents?: import("./server-components/types.ts").ComponentState
   readonly data: unknown
   /** Per-layout loader data, aligned index-for-index with the layout prefix of `chain`. */
   readonly layoutData?: readonly unknown[]
@@ -61,10 +62,24 @@ export interface UIMatch {
   readonly handle: unknown
 }
 
+/**
+ * Markup a render produced for outside the app root, which an adapter that sets
+ * {@link RenderAdapter.documentParts} appends to. Each part must be complete before the render
+ * settles: `renderToString` resolving, or `renderToStream` returning its stream.
+ */
+export interface DocumentParts {
+  /** Placed at the end of `<head>`. Svelte's `<svelte:head>` lands here. */
+  head: string
+  /** Placed first in `<body>`, before the app root. Vue's `<Teleport to="body">` lands here. */
+  body: string
+}
+
 /** 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
+  /** Present only for an adapter that sets {@link RenderAdapter.documentParts}. */
+  readonly parts?: DocumentParts
 }
 
 /**
@@ -83,10 +98,22 @@ export interface RenderAdapter {
     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>
+  /**
+   * Render the chain to a complete HTML string when no content is deferred. `options.nonce` is the
+   * document's CSP nonce, for any inline script the renderer emits (Solid's hydration data).
+   */
+  renderToString?(
+    chain: readonly unknown[],
+    props: RenderProps,
+    options?: RenderStreamOptions,
+  ): string | Promise<string>
   /** Per-document bootstrap markup injected into `<head>` for client hydration. */
   hydrationHead(nonce?: string): string
+  /**
+   * Set when a render can produce markup that belongs outside the app root. Every render is then
+   * passed `options.parts` to fill; an adapter without it never is, and pays nothing for the seam.
+   */
+  readonly documentParts?: boolean
 }
 
 /** Loads a module through the dev server's module graph rather than the runtime's resolver. */
@@ -123,5 +150,6 @@ export const ROUTE_GLOBAL = "__NIFRA_ROUTE__"
 export const ACTION_GLOBAL = "__NIFRA_ACTION__"
 /** Dynamic-boundary states for hydration; absent when a route declares no boundaries. */
 export const BOUNDARY_GLOBAL = "__NIFRA_BOUNDARIES__"
+export const COMPONENT_GLOBAL = "__NIFRA_COMPONENTS__"
 /** Marker attribute used to find a non-default hydration container. */
 export const ROOT_ATTRIBUTE = "data-nifra-root"

package/src/route-types.ts

@@ -30,6 +30,7 @@ import {
 } from "node:fs"
 import { dirname, join, relative } from "node:path"
 import { codeUnitOrder } from "./internal/code-unit-order.ts"
+import { jsStringLiteral } from "./internal/js-string.ts"
 import {
   buildManifest,
   isMiddlewareFile,
@@ -85,6 +86,8 @@ function routeFiles(manifest: Manifest): readonly RouteFile[] {
 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_]*)\]$/
+// A `[name]` inside a part-literal segment such as `post-[id]` or `[lang]-feed.xml`.
+const EMBEDDED_PARAM = /\[([A-Za-z_][A-Za-z0-9_]*)\]/g
 
 /** 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 {
@@ -96,10 +99,20 @@ function paramsType(file: string, kind: Kind): string {
     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`)
+    else
+      for (const embedded of segment.matchAll(EMBEDDED_PARAM))
+        fields.push(`readonly ${embedded[1]}: string`)
   }
   return fields.length === 0 ? "Record<string, never>" : `{ ${fields.join("; ")} }`
 }
 
+// A file name may hold a line terminator, which would end the `//` header comment it is quoted in.
+const commentSafe = (text: string): string =>
+  text.replace(
+    /[\n\r\u2028\u2029]/g,
+    (char) => `\\u${char.charCodeAt(0).toString(16).padStart(4, "0")}`,
+  )
+
 /** 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))
@@ -121,16 +134,24 @@ function routeTypesModule(
   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.`]
+  const lines = [
+    `// Generated by nifra from ${commentSafe(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(
+    'import type { OutputOf, RouteActionReturn, RouteLoaderArgs, RouteLoaderReturn, SearchSchemaOf } from "@nifrajs/client"',
+  )
+  lines.push(
+    route.kind === "page"
+      ? 'import type { MetaArgs as WebMetaArgs, RenderProps } from "@nifrajs/web"'
+      : 'import type { MetaArgs as WebMetaArgs } from "@nifrajs/web"',
+  )
   lines.push("")
   if (backend !== undefined)
-    lines.push(`type Backend = typeof import("${specifier(dir, backend)}")`)
+    lines.push(`type Backend = typeof import(${jsStringLiteral(specifier(dir, backend))})`)
   if (frontend !== undefined)
-    lines.push(`type Frontend = typeof import("${specifier(dir, frontend)}")`)
+    lines.push(`type Frontend = typeof import(${jsStringLiteral(specifier(dir, frontend))})`)
   if (backend !== undefined || frontend !== undefined) lines.push("")
   const output = (name: string) => (backend === undefined ? "null" : `OutputOf<Backend, "${name}">`)
   lines.push(
@@ -145,6 +166,12 @@ function routeTypesModule(
     `  export type LoaderArgs = RouteLoaderArgs<Params${frontend === undefined ? "" : ", SearchSchemaOf<Frontend>"}>`,
     "  /** The context the backend half's action receives. */",
     "  export type ActionArgs = LoaderArgs",
+    "  /** The backend half's loader. Annotate it, `export const loader: Route.Loader = ...`, and what it returns is checked against `loaderOutput`. */",
+    `  export type Loader = (args: LoaderArgs) => RouteLoaderReturn<${backend === undefined ? "null" : "Backend"}>`,
+    "  /** The backend half's action. Annotate it, `export const action: Route.Action = ...`, and what it returns is checked against `actionOutput`. */",
+    `  export type Action = (args: ActionArgs) => RouteActionReturn<${backend === undefined ? "null" : "Backend"}>`,
+    "  /** What this module's `meta` function receives: its own loader data as `data`. */",
+    "  export type MetaArgs = WebMetaArgs<LoaderData>",
   )
   if (route.kind === "page") {
     lines.push(
@@ -170,8 +197,8 @@ function routeTypesModule(
 
 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)}"`,
+    `// Generated by nifra from ${commentSafe(label)}. Do not edit: \`nifra types\` rewrites it.`,
+    `import type { backend } from ${jsStringLiteral(specifier(dirname(out), backendApp))}`,
     "",
     'declare module "@nifrajs/client" {',
     "  interface Register {",