@nifrajs/web 4.0.2 → 5.0.0

package/src/internal/codegen.ts

@@ -4,6 +4,7 @@ import type { LayoutEntry, Manifest } from "../manifest.ts"
 import {
   ACTION_GLOBAL,
   BOUNDARY_GLOBAL,
+  COMPONENT_GLOBAL,
   DATA_GLOBAL,
   HANDOVER_ID,
   LAYOUT_DATA_GLOBAL,
@@ -11,7 +12,7 @@ import {
   ROUTE_GLOBAL,
 } from "../render-seam.ts"
 import { PRERENDERED_GLOBAL } from "../router.ts"
-import { jsStringLiteral } from "./js-string.ts"
+import { jsStringLiteral, jsValueLiteral } from "./js-string.ts"
 
 /** The globals the page-state handover may set - nothing else in it reaches `window`. */
 const HANDOVER_GLOBALS = [
@@ -20,6 +21,7 @@ const HANDOVER_GLOBALS = [
   ROUTE_GLOBAL,
   ACTION_GLOBAL,
   BOUNDARY_GLOBAL,
+  COMPONENT_GLOBAL,
   PRERENDERED_GLOBAL,
 ]
 export interface GenerateClientEntryOptions {
@@ -36,6 +38,7 @@ export interface GenerateClientEntryOptions {
   readonly clientModule: string
   /** Turn a route/layout source file (relative to the routes dir) into an import specifier. */
   readonly resolve: (file: string) => string
+  readonly serverComponents?: boolean
 }
 
 /**
@@ -81,21 +84,43 @@ export function generateClientEntry(
       files.push(errorFile)
       errorRouteIds.push(route.id)
     }
-    loaderRows.push(`  ${JSON.stringify(route.id)}: ${lazyLoader(files)},`)
+    loaderRows.push(`  ${jsStringLiteral(route.id)}: ${lazyLoader(files)},`)
     if (route.layoutIds.length > 0) layoutIdsOf[route.id] = route.layoutIds
     patternRows.push(
-      `  { routeId: ${JSON.stringify(route.id)}, pattern: ${JSON.stringify(route.pattern)} },`,
+      `  { routeId: ${jsStringLiteral(route.id)}, pattern: ${jsStringLiteral(route.pattern)} },`,
     )
   }
+  // A root status page renders inside the root layout unless it exports `inLayouts = false`, which
+  // only its module says - so the layout loads after the page, and only for a page that does not opt out.
+  const rootLayout = manifest.layouts._layout
+  const statusLoader = (routeId: string, file: string): string =>
+    rootLayout === undefined
+      ? lazyLoader([file])
+      : `() => import(${jsStringLiteral(resolve(file))}).then((page) => withRootLayout(${jsStringLiteral(routeId)}, page))`
   if (manifest.notFound !== undefined) {
-    loaderRows.push(`  "_404": ${lazyLoader([manifest.notFound.file])},`)
+    loaderRows.push(`  "_404": ${statusLoader("_404", manifest.notFound.file)},`)
     statusRoutes[404] = "_404"
   }
   for (const [status, entry] of Object.entries(manifest.statusPages ?? {})) {
     const routeId = `_${status}`
-    loaderRows.push(`  ${JSON.stringify(routeId)}: ${lazyLoader([entry.file])},`)
+    loaderRows.push(`  ${jsStringLiteral(routeId)}: ${statusLoader(routeId, entry.file)},`)
     statusRoutes[Number(status)] = routeId
   }
+  const layoutStatusLines =
+    rootLayout === undefined || Object.keys(statusRoutes).length === 0
+      ? []
+      : [
+          "const layoutStatusRoutes = {}",
+          "const withRootLayout = (id, page) => {",
+          "  if (page.inLayouts === false) return [page]",
+          `  return import(${jsStringLiteral(resolve(rootLayout.file))}).then((layout) => {`,
+          "    layoutStatusRoutes[id] = true",
+          '    layoutIdsOf[id] = ["_layout"]',
+          "    return [layout, page]",
+          "  })",
+          "}",
+        ]
+  const routerStatusOption = layoutStatusLines.length === 0 ? "" : ", layoutStatusRoutes"
   // `_loading` pages. Emitted only when the app has one, so an app without them imports nothing extra.
   // Each is its own lazy chunk; a route row carries its layout ids and the loading pages above it with
   // the number of those layouts each sits under - all the runtime needs to choose one.
@@ -110,14 +135,14 @@ export function generateClientEntry(
       ])
       routeRows.set(
         route.id,
-        `  ${JSON.stringify(route.id)}: ${JSON.stringify([route.layoutIds, above])},`,
+        `  ${jsStringLiteral(route.id)}: ${jsValueLiteral([route.layoutIds, above])},`,
       )
     }
     loadingLines.push(
       "const loadingModules = {",
       ...loadings.map(
         ([id, entry]) =>
-          `  ${JSON.stringify(id)}: () => import(${jsStringLiteral(resolve(entry.file))}),`,
+          `  ${jsStringLiteral(id)}: () => import(${jsStringLiteral(resolve(entry.file))}),`,
       ),
       "}",
       "const loadingRoutes = {",
@@ -129,14 +154,17 @@ export function generateClientEntry(
   return `${[
     // `/client`, never the root: the root's graph carries the server (renderPage, the static-file
     // server), and Vite's dev server evaluates what it is given instead of tree-shaking it.
-    'import { createClientRouter, createMatcher, mergeHeads, resolveMeta } from "@nifrajs/web/client"',
+    'import { createClientRouter, createMatcher, mergeHeads, resolveChainMeta } from "@nifrajs/web/client"',
     'import { applyHead, currentDocumentNonce, installForms, installHistory, signalHydrated, waitForStyles } from "@nifrajs/web/client"',
+    ...(options.serverComponents
+      ? ['import { bindComponentRouter } from "@nifrajs/web/server-components/client"']
+      : []),
     // Namespace import: `errorBoundary` is optional (an adapter may not export it). A namespace member
     // access yields `undefined` if absent - unlike a named import, which would be a link error.
     ...(loadings.length > 0
       ? ['import { withLoading } from "@nifrajs/web/internal/loading-runtime"']
       : []),
-    `import * as __adapter from ${JSON.stringify(clientModule)}`,
+    `import * as __adapter from ${jsStringLiteral(clientModule)}`,
     "const { mountRouter } = __adapter",
     // The assurance hook is optional: ordinary client entries pay only for the namespace lookup, while
     // hydration runners get a runtime identity from the exact adapter module that mounted the page. The
@@ -152,8 +180,8 @@ export function generateClientEntry(
     // names actually exports `mountRouter`. Without this the miss surfaces as
     // "mountRouter is not a function" from inside a bundled chunk, at first paint, naming neither the
     // module nor the requirement - a self-executing entry passes every build and fails only here.
-    `if (typeof mountRouter !== "function") throw new Error(${JSON.stringify(
-      `[nifra/web] clientModule ${JSON.stringify(clientModule)} does not export \`mountRouter\`. ` +
+    `if (typeof mountRouter !== "function") throw new Error(${jsValueLiteral(
+      `[nifra/web] clientModule ${jsStringLiteral(clientModule)} does not export \`mountRouter\`. ` +
         "A client module must export `mountRouter({ router, routes, container })` - it is called by " +
         "the generated bootstrap, so a self-executing entry will not work. Use your adapter's " +
         '`/client` entry (e.g. "@nifrajs/web-react/client"), or re-export mountRouter from it.',
@@ -169,10 +197,11 @@ export function generateClientEntry(
     // to act on. An adapter that knows its framework is in that position says so, and the entry turns
     // the swallowed update into an honest full reload.
     'if (import.meta.hot && __adapter.hotUpdateNeedsReload) import.meta.hot.on("bun:afterUpdate", () => location.reload())',
-    `const errorRouteIds = new Set(${JSON.stringify(errorRouteIds)})`,
+    `const errorRouteIds = new Set(${jsValueLiteral(errorRouteIds)})`,
     // Each route is a lazy loader: dynamic imports → Bun.build (splitting) emits one chunk per
     // route, shared layouts/deps deduped into shared chunks, so a route's code loads only when
     // visited. loadModule caches the [layouts…, page] component chain + the chain's meta list per id.
+    ...layoutStatusLines,
     "const loaders = {",
     ...loaderRows,
     "}",
@@ -191,7 +220,7 @@ export function generateClientEntry(
     // boundary), with the page's `HydrateFallback` - or an empty leaf - where the component goes.
     "const holds = {}",
     // routeId → the ids and `handle` exports `useMatches` reports (layouts, then the page).
-    `const layoutIdsOf = ${JSON.stringify(layoutIdsOf)}`,
+    `const layoutIdsOf = ${jsValueLiteral(layoutIdsOf)}`,
     "const matchChains = {}",
     "const loadModule = async (id) => {",
     "  if (chains[id]) return",
@@ -235,11 +264,11 @@ export function generateClientEntry(
     // router, the deferred mapper and the adapters read, before any of them runs. Only the LAST
     // matching <script> counts, and only known keys: page HTML (sanitized user content) can carry an
     // element with the same id, and arbitrary keys copied onto `window` include `location`.
-    `const handovers = document.querySelectorAll(${JSON.stringify(`script[type="application/json"][id="${HANDOVER_ID}"]`)})`,
+    `const handovers = document.querySelectorAll(${jsValueLiteral(`script[type="application/json"][id="${HANDOVER_ID}"]`)})`,
     "const handover = handovers[handovers.length - 1]",
     "if (handover !== undefined) {",
     '  const state = JSON.parse(handover.textContent || "{}")',
-    `  for (const key of ${JSON.stringify(HANDOVER_GLOBALS)}) {`,
+    `  for (const key of ${jsValueLiteral(HANDOVER_GLOBALS)}) {`,
     "    if (Object.prototype.hasOwnProperty.call(state, key)) Reflect.set(window, key, state[key])",
     "  }",
     "}",
@@ -249,7 +278,7 @@ export function generateClientEntry(
     // Derive the initial route from the URL (correct on refresh/deep-link); fall back to the
     // server-injected route id for non-pattern routes (e.g. _404, which matches nothing).
     "const matched = createMatcher(patterns)(location.pathname)",
-    `const statusRoutes = ${JSON.stringify(statusRoutes)}`,
+    `const statusRoutes = ${jsValueLiteral(statusRoutes)}`,
     `const serverRoute = window.${ROUTE_GLOBAL} ?? ""`,
     // A terminal status page the server rendered (`_404`, `_410`, ...) outranks the URL match: a
     // loader that throws notFound() on `/learn/bad-slug` leaves a URL that still matches
@@ -270,6 +299,7 @@ export function generateClientEntry(
     // Undefined on a page-only app, which is exactly what the router treats as "no layout data".
     `  layoutData: window.${LAYOUT_DATA_GLOBAL} && window.${LAYOUT_DATA_GLOBAL}.map(mapDeferred),`,
     `  boundaries: mapDeferred(window.${BOUNDARY_GLOBAL}),`,
+    `  serverComponents: window.${COMPONENT_GLOBAL},`,
     // actionData (only set after a form POST) is in the initial state so the binding hydrates
     // consistently with the server-rendered markup; mapped through `mapDeferred` too so a deferred
     // action's placeholders become registry markers (a no-op when the action didn't defer).
@@ -280,8 +310,9 @@ export function generateClientEntry(
     // With `_loading` pages the store is wrapped: a slow navigation then names a loading chain (the
     // shared layouts + the `_loading` component) for the mounted view to render in the meantime.
     loadings.length > 0
-      ? "const router = withLoading(createClientRouter({ patterns, initial, loadModule, statusRoutes, searchClientKeys, routeHooks }), { routes: loadingRoutes, modules: loadingModules, chains, searchSchemas, matchChains })"
-      : "const router = createClientRouter({ patterns, initial, loadModule, statusRoutes, searchClientKeys, routeHooks })",
+      ? `const router = withLoading(createClientRouter({ patterns, initial, loadModule, statusRoutes${routerStatusOption}, searchClientKeys, routeHooks }), { routes: loadingRoutes, modules: loadingModules, chains, searchSchemas, matchChains })`
+      : `const router = createClientRouter({ patterns, initial, loadModule, statusRoutes${routerStatusOption}, searchClientKeys, routeHooks })`,
+    ...(options.serverComponents ? ["bindComponentRouter(router)"] : []),
     "installHistory(router)",
     "installForms(router)",
     // The container is found in the DOM, not baked in. `rootId` is a per-render option and this entry
@@ -292,7 +323,7 @@ export function generateClientEntry(
     `const root = document.querySelector("body > div[${ROOT_ATTRIBUTE}]") ?? document.getElementById("root")`,
     // Loud, because there is no recoverable case: this entry ships only in a document `renderPage`
     // opened a container in, so reaching here means the document is not the one it was built for.
-    `if (!root) throw new Error(${JSON.stringify(
+    `if (!root) throw new Error(${jsValueLiteral(
       "[nifra/web] no hydration container found. The generated bootstrap mounts into the element " +
         `renderPage opened the app in - the one marked \`${ROOT_ATTRIBUTE}\` when a custom \`rootId\` ` +
         "is set, `#root` otherwise - and this document has neither. If you emit the document yourself, " +
@@ -351,8 +382,8 @@ export function generateClientEntry(
     // `origin: location.origin` matches the SSR `originOf(req)` (both are `URL.origin` for the same
     // page URL), so a soft-nav re-resolves the SAME absolute canonical/og:url - no head drift.
     "      const nonce = currentDocumentNonce()",
-    "      const args = { data: s.data, params: s.params, origin: location.origin, ...(nonce === undefined ? {} : { nonce }) }",
-    "      applyHead(mergeHeads((metas[s.routeId] ?? [undefined]).map((m) => resolveMeta(m, args))))",
+    "      const args = { data: s.data, pageData: s.data, params: s.params, origin: location.origin, ...(nonce === undefined ? {} : { nonce }) }",
+    "      applyHead(mergeHeads(resolveChainMeta(metas[s.routeId] ?? [undefined], s.layoutData, args)))",
     "    }",
     "  })",
     "}).catch((error) => console.error('[nifra/web] hydration failed:', error))",
@@ -391,13 +422,13 @@ export function generateRouteSearchTypes(
     .sort((a, b) => (a[0] < b[0] ? -1 : 1))
     .map(
       ([pattern, spec]) =>
-        `    ${JSON.stringify(pattern)}: SearchOf<typeof import(${JSON.stringify(spec)})>`,
+        `    ${jsStringLiteral(pattern)}: SearchOf<typeof import(${jsStringLiteral(spec)})>`,
     )
   return `${[
     "// GENERATED by @nifrajs/web generateRouteSearchTypes - typed cross-route navigate({ to, search }).",
     "// Regenerated from the route files; a stale navigate search shape becomes a tsc error. Do not edit.",
     'import type { SearchOf } from "@nifrajs/web"',
-    `declare module ${JSON.stringify(module)} {`,
+    `declare module ${jsStringLiteral(module)} {`,
     "  interface RouteSearch {",
     ...entries,
     "  }",
@@ -504,12 +535,12 @@ export function generateServerManifest(
     "// the same pure logic discoverRoutes feeds, so patterns + layout chains match exactly.",
     'import { buildManifest, type RouteModule } from "@nifrajs/web"',
   ]
-  const clientEntryLine = `export const clientEntry = ${JSON.stringify(clientEntry)}`
+  const clientEntryLine = `export const clientEntry = ${jsStringLiteral(clientEntry)}`
   // Baked stylesheet URLs so the server entry can pass them to createWebApp → <link rel="stylesheet">.
   // Always emitted (default empty) so consumers can `import { styles, routeStyles }` unconditionally.
-  const stylesLine = `export const styles = ${JSON.stringify(styles ?? [])}`
-  const routeStylesLine = `export const routeStyles = ${JSON.stringify(routeStyles ?? {})}`
-  const cssLoadingLine = `export const cssLoading = ${JSON.stringify(cssLoading)}`
+  const stylesLine = `export const styles = ${jsValueLiteral(styles ?? [])}`
+  const routeStylesLine = `export const routeStyles = ${jsValueLiteral(routeStyles ?? {})}`
+  const cssLoadingLine = `export const cssLoading = ${jsStringLiteral(cssLoading)}`
   if (lazy) {
     // Lazy: `() => import("./routes/x")` per route (static specifier → one chunk per route under a
     // code-splitting bundler, loaded on first request). The map keys are the route-relative paths
@@ -533,9 +564,9 @@ export function generateServerManifest(
   // Eager: `import * as` per route (all bundled into the entry, parsed at boot). Index-based
   // identifiers are collision-proof regardless of filename.
   const imports = files.map(
-    (file, i) => `import * as m${i} from ${JSON.stringify(moduleSpecifier(resolve(file)))}`,
+    (file, i) => `import * as m${i} from ${jsStringLiteral(moduleSpecifier(resolve(file)))}`,
   )
-  const entries = files.map((file, i) => `  ${JSON.stringify(file)}: m${i},`)
+  const entries = files.map((file, i) => `  ${jsStringLiteral(file)}: m${i},`)
   return `${[
     ...header,
     ...imports,

package/src/internal/disposable-dir.ts

@@ -0,0 +1,24 @@
+import { existsSync, realpathSync } from "node:fs"
+import { isAbsolute, parse, relative, sep } from "node:path"
+
+/**
+ * Throws unless `dir` is safe to delete recursively: not a filesystem root, and neither equal to nor
+ * an ancestor of any path in `keep` (the sources a build reads, the working directory). Both sides are
+ * compared after resolving symlinks, so a link pointing at the project is refused too. A `dir` that
+ * does not exist yet is always safe.
+ */
+export function assertDisposableDir(option: string, dir: string, keep: readonly string[]): void {
+  if (!existsSync(dir)) return
+  const real = realpathSync.native(dir)
+  if (parse(real).root === real)
+    throw new Error(`[nifra/web] ${option} (${dir}) is a filesystem root; refusing to clear it.`)
+  for (const path of keep) {
+    if (!existsSync(path)) continue
+    const rel = relative(real, realpathSync.native(path))
+    if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) continue
+    throw new Error(
+      `[nifra/web] ${option} (${dir}) ${rel === "" ? "is" : "contains"} ${path}; the build clears ` +
+        `${option} first, which would delete it. Point ${option} at a directory of its own.`,
+    )
+  }
+}

package/src/internal/entry-chunks.ts

@@ -0,0 +1,18 @@
+import { resolve } from "node:path"
+
+/**
+ * Each entry's emitted JS chunk, keyed by the absolute source path the build metafile records for it.
+ * Bun's API does not promise that `outputs` follow `entrypoints` order, so a route's preload is read
+ * from the output that names the route's own source as its entry, never from a position.
+ */
+export function entryChunks(
+  outputs: Readonly<Record<string, { readonly entryPoint?: string }>>,
+  cwd: string,
+): ReadonlyMap<string, string> {
+  const chunks = new Map<string, string>()
+  for (const [path, output] of Object.entries(outputs)) {
+    if (output.entryPoint !== undefined && /\.[cm]?js$/.test(path))
+      chunks.set(resolve(cwd, output.entryPoint), path)
+  }
+  return chunks
+}

package/src/internal/evidence-traversal.ts

@@ -0,0 +1,57 @@
+import type { AsyncLocalStorage } from "node:async_hooks"
+import type { BackendEvidenceProvider } from "@nifrajs/core/mount"
+
+/** The providers composing the current evidence read, outermost first. */
+export type EvidenceAncestry = ReadonlySet<BackendEvidenceProvider>
+
+// Looked up, never imported: a self-contained Worker bundle hoists an import of node:async_hooks,
+// and a Worker on an older compatibility date without nodejs_compat then fails to start. Created
+// on the first evidence read, so serving an app never constructs an AsyncLocalStorage.
+let storage: AsyncLocalStorage<EvidenceAncestry> | undefined
+
+// Without async context, a cycle through a provider that drops the chain reads like concurrent
+// reads. A nested read never settles before its children, so such a cycle piles up in-flight reads
+// of one provider without bound, while real concurrency stays at a handful (llms.txt memoizes).
+const MAX_UNTRACKED_READS = 64
+const untrackedReads = new WeakMap<BackendEvidenceProvider, number>()
+
+function ancestryStorage(): AsyncLocalStorage<EvidenceAncestry> | undefined {
+  const hooks = globalThis.process?.getBuiltinModule?.("node:async_hooks")
+  if (hooks?.AsyncLocalStorage === undefined) return undefined
+  storage ??= new hooks.AsyncLocalStorage()
+  return storage
+}
+
+/**
+ * Run `read` with `provider` joined to the providers already composing this read, refusing a
+ * provider that is its own ancestor. The async context follows a cycle through any provider; the
+ * `passed` chain, which framework providers hand to the providers they compose, is the only record
+ * on a runtime without AsyncLocalStorage, where a cap on in-flight reads of one provider stops a
+ * cycle the chain cannot see.
+ */
+export async function traverseEvidence<T>(
+  provider: BackendEvidenceProvider,
+  passed: unknown,
+  read: (ancestry: EvidenceAncestry) => Promise<T>,
+): Promise<T> {
+  const context = ancestryStorage()
+  const parents = new Set(context?.getStore())
+  if (passed instanceof Set) for (const parent of passed) parents.add(parent)
+  if (parents.has(provider)) {
+    throw new Error("[nifra/web] cyclic composed assurance evidence mount")
+  }
+  const ancestry: EvidenceAncestry = parents.add(provider)
+  if (context !== undefined) return context.run(ancestry, read, ancestry)
+  const reads = untrackedReads.get(provider) ?? 0
+  if (reads >= MAX_UNTRACKED_READS) {
+    throw new Error(
+      `[nifra/web] cyclic composed assurance evidence mount: more than ${MAX_UNTRACKED_READS} reads of one app in flight. This runtime has no AsyncLocalStorage (on Cloudflare, enable nodejs_compat), so a cycle through a custom provider is caught only by this cap.`,
+    )
+  }
+  untrackedReads.set(provider, reads + 1)
+  try {
+    return await read(ancestry)
+  } finally {
+    untrackedReads.set(provider, (untrackedReads.get(provider) ?? 1) - 1)
+  }
+}

package/src/internal/head-merge.ts

@@ -45,6 +45,22 @@ export function resolveMeta(meta: MetaInput | undefined, args: MetaArgs): Meta {
   return meta
 }
 
+/**
+ * Resolve a route's `meta` chain, outermost layout first and the page last. The page's `meta` gets
+ * `args`; a layout's gets its own loader data as `data` (`null` when it has no loader), the value its
+ * component renders. The SSR head and a soft navigation both resolve through this, so they match.
+ */
+export function resolveChainMeta(
+  metas: readonly (MetaInput | undefined)[],
+  layoutData: readonly unknown[] | undefined,
+  args: MetaArgs,
+): Meta[] {
+  const last = metas.length - 1
+  return metas.map((meta, i) =>
+    resolveMeta(meta, i < last ? { ...args, data: layoutData?.[i] ?? null } : args),
+  )
+}
+
 /**
  * Merge a layout chain's heads, outermost first: `title`/`lang`/`dir` are nearest-wins, and
  * `meta`/`link`/`script` concatenate in chain order.

package/src/internal/js-string.ts

@@ -12,7 +12,12 @@ const LINE_SEPARATOR = String.fromCharCode(0x2028)
 const PARAGRAPH_SEPARATOR = String.fromCharCode(0x2029)
 
 export function jsStringLiteral(value: string): string {
-  return JSON.stringify(value)
+  return jsValueLiteral(value)
+}
+
+/** A JSON value embedded in generated source, with the same script-boundary protection. */
+export function jsValueLiteral(value: unknown): string {
+  return (JSON.stringify(value) ?? "undefined")
     .replaceAll("<", "\\u003C")
     .replaceAll(LINE_SEPARATOR, "\\u2028")
     .replaceAll(PARAGRAPH_SEPARATOR, "\\u2029")

package/src/internal/mount-shadow.ts

@@ -83,6 +83,6 @@ export function formatShadowedPages(pages: readonly ShadowedPage[]): string {
   return (
     `${pages.length === 1 ? "1 page route" : `${pages.length} page routes`} can never render: a mount answers every request under its path before page routing, and its 404 is final.\n` +
     `${lines.join("\n")}\n` +
-    'Move each file out of the mounted path, or serve that URL from the mounted app. The backend\'s mount path is `apiPrefix` (default "/api"; export it from framework.ts, or set it to "" to turn the mount off).'
+    "Move each file out of the mounted path, or serve that URL from the mounted app. The backend's mount path is the `apiPrefix` exported from framework.ts; without one the backend is not mounted."
   )
 }

package/src/internal/output-guard.ts

@@ -14,6 +14,7 @@
  * its own `validate` output, as zod and valibot objects do by default.
  */
 import type { StandardResult, StandardSchemaV1 } from "@nifrajs/core/server"
+import { wireDate } from "./wire-date.ts"
 
 // Registry symbols shared with core and `@nifrajs/schema`, so two copies of either still agree.
 const RESPONSE_RESULT = Symbol.for("nifra.response.result")
@@ -23,6 +24,7 @@ const DEFERRED_VALIDATE = Symbol.for("nifra.schema.deferredValidate")
 
 export const DECLASSIFIED_KEY = "x-nifra-declassified"
 const DEFERRED_KEY = "x-nifra-deferred"
+const DATE_KEY = "x-nifra-date"
 
 /** A field name that usually holds a credential or personal identifier. */
 export function isSensitiveFieldName(name: string): boolean {
@@ -80,6 +82,8 @@ interface CompiledGuard {
   /** Undefined when the schema exposes no JSON Schema to project by. */
   readonly project: Project | undefined
   readonly validate: StandardSchemaV1["~standard"]["validate"]
+  /** Dev only: name the keys the guard dropped, so a schema missing a field is not a silent blank. */
+  readonly warnDropped: boolean
 }
 
 interface Deferred {
@@ -101,6 +105,10 @@ const isPlain = (value: object): boolean => {
   return proto === Object.prototype || proto === null
 }
 
+// Read once per schema at route load, never per request.
+const inDevelopment = (): boolean =>
+  typeof process !== "undefined" && process.env?.NODE_ENV === "development"
+
 /** Re-root the issues children pushed since `from` under `key`. Runs only on failure. */
 function prefix(state: RunState, from: number, key: string | number): void {
   for (let i = from; i < state.issues.length; i++) state.issues[i] = `/${key}${state.issues[i]}`
@@ -142,6 +150,20 @@ const UNKNOWN: Project = (value, state) => {
  */
 const LEAF: Project = (value) => (value instanceof Date ? value.toJSON() : value)
 
+const ISO_DATE =
+  /^\d{4}-\d{2}-\d{2}(?:[Tt ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:[Zz]|[+-]\d{2}:?\d{2})?)?$/
+// An invalid Date stays as it is, so the schema's own check refuses it by path.
+const toWireDate = (value: Date): unknown =>
+  Number.isNaN(value.getTime()) ? value : wireDate(value.getTime())
+
+/** A `t.date()` field: a `Date` or an ISO 8601 string becomes a tagged `Date` the browser rebuilds. */
+const DATE: Project = (value) =>
+  value instanceof Date
+    ? toWireDate(value)
+    : typeof value === "string" && ISO_DATE.test(value)
+      ? toWireDate(new Date(value))
+      : value
+
 /** An array whose items are all scalars, passed through whole. */
 const LEAF_ARRAY: Project = (value) => value
 
@@ -151,8 +173,11 @@ const typesOf = (node: Node): readonly unknown[] | undefined =>
 const COMBINATORS = ["anyOf", "oneOf", "allOf"] as const
 
 /** What a schema node (with no `$ref` or combinator) projects as. */
-function shapeOf(node: Node): "deferred" | "object" | "array" | "both" | "leaf" | "unknown" {
+function shapeOf(
+  node: Node,
+): "deferred" | "date" | "object" | "array" | "both" | "leaf" | "unknown" {
   if (node[DEFERRED_KEY] === true) return "deferred"
+  if (node[DATE_KEY] === true) return "date"
   const types = typesOf(node)
   const object =
     types?.includes("object") === true ||
@@ -229,6 +254,8 @@ class Compiler {
     switch (shapeOf(node)) {
       case "deferred":
         return this.deferred(node, where)
+      case "date":
+        return DATE
       case "both":
         return this.dispatch(this.object(node, where), this.array(node, where), undefined)
       case "object":
@@ -411,6 +438,8 @@ class Compiler {
       objects.length === 0 ? undefined : this.object(mergeObjects(objects), where),
       arrays.length === 0 ? undefined : this.array(mergeArrays(arrays), where),
       deferred === undefined ? undefined : this.compile(deferred, where),
+      // A union's string branch makes an ISO string ambiguous, so only a Date becomes a date here.
+      kinds.includes("date"),
     )
   }
 
@@ -418,10 +447,11 @@ class Compiler {
     object: Project | undefined,
     array: Project | undefined,
     deferred: Project | undefined,
+    date = false,
   ): Project {
     return (value, state) => {
       if (typeof value !== "object" || value === null) return value
-      if (value instanceof Date) return value.toJSON()
+      if (value instanceof Date) return date ? toWireDate(value) : value.toJSON()
       if (Array.isArray(value)) return array === undefined ? value : array(value, state)
       if (isDeferred(value)) {
         if (deferred !== undefined) return deferred(value, state)
@@ -442,6 +472,7 @@ class Compiler {
     const inner: CompiledGuard = {
       project: this.compile(node.inner, where),
       validate: validate as CompiledGuard["validate"],
+      warnDropped: inDevelopment(),
     }
     return (value, state) => {
       if (!isDeferred(value)) return value
@@ -526,7 +557,7 @@ function mergeArrays(branches: readonly Node[]): Node {
 }
 
 /** The JSON Schema a schema exposes to project by, if any. */
-function jsonSchemaOf(schema: StandardSchemaV1): Node | undefined {
+export function jsonSchemaOf(schema: StandardSchemaV1): Node | undefined {
   const own = (schema as { readonly jsonSchema?: unknown }).jsonSchema
   if (isNode(own)) return own
   const standard = schema["~standard"] as {
@@ -570,11 +601,52 @@ export function outputGuard(schema: unknown, owner: string, exportName: string):
       )
     }
   }
-  const guard: CompiledGuard = { project, validate: standard["~standard"].validate }
+  const guard: CompiledGuard = {
+    project,
+    validate: standard["~standard"].validate,
+    warnDropped: inDevelopment(),
+  }
   compiled.set(schema, guard)
   return guard
 }
 
+/** Where `before` held a key `after` lacks. Array indices collapse to `*`, so one field reads once. */
+function droppedPaths(before: unknown, after: unknown, path: string, out: Set<string>): void {
+  if (before === after || typeof before !== "object" || before === null) return
+  if (typeof after !== "object" || after === null || before instanceof Date) return
+  if (Array.isArray(before)) {
+    if (!Array.isArray(after)) return
+    const length = Math.min(before.length, after.length)
+    for (let i = 0; i < length; i++) droppedPaths(before[i], after[i], `${path}/*`, out)
+    return
+  }
+  const kept: Readonly<Record<string, unknown>> = Object.fromEntries(Object.entries(after))
+  for (const [key, value] of Object.entries(before)) {
+    // JSON drops an undefined value anyway; the guard dropping it changes nothing the page sees.
+    if (value === undefined) continue
+    if (!Object.hasOwn(kept, key)) out.add(`${path}/${key}`)
+    else droppedPaths(value, kept[key], `${path}/${key}`, out)
+  }
+}
+
+const warnedDrops = new Set<string>()
+
+function warnDropped(label: string, before: unknown, after: unknown): void {
+  const found = new Set<string>()
+  droppedPaths(before, after, "", found)
+  if (found.size === 0) return
+  const paths = [...found]
+  const key = `${label}\n${paths.join("\n")}`
+  if (warnedDrops.has(key)) return
+  if (warnedDrops.size >= 1000) warnedDrops.clear()
+  warnedDrops.add(key)
+  const shown = paths.slice(0, 10).join(", ")
+  const more = paths.length > 10 ? ` and ${paths.length - 10} more` : ""
+  console.warn(
+    `[nifra/web] ${label} returned field(s) its output schema does not declare, so they were dropped before the browser: ${shown}${more}. Declare a field in the schema if the page needs it. (Shown in development only.)`,
+  )
+}
+
 const pathOf = (issue: { readonly path?: ReadonlyArray<unknown> | undefined }): string =>
   (issue.path ?? [])
     .map(
@@ -583,7 +655,12 @@ const pathOf = (issue: { readonly path?: ReadonlyArray<unknown> | undefined }):
     )
     .join("") || "/"
 
-function settle(guard: CompiledGuard, result: StandardResult<unknown>, label: string): unknown {
+function settle(
+  guard: CompiledGuard,
+  result: StandardResult<unknown>,
+  label: string,
+  input: unknown,
+): unknown {
   if (result.issues !== undefined) {
     const paths = [...new Set(result.issues.map(pathOf))]
     throw new OutputGuardError(
@@ -595,6 +672,8 @@ function settle(guard: CompiledGuard, result: StandardResult<unknown>, label: st
     const state: RunState = { label, issues: [] }
     UNKNOWN(result.value, state)
     if (state.issues.length > 0) throw undeclaredDeferred(label, state.issues)
+    // No JSON Schema to project by: the schema's own validate stripped what it does not declare.
+    if (guard.warnDropped) warnDropped(label, input, result.value)
   }
   return result.value
 }
@@ -612,11 +691,13 @@ export function runGuard(guard: CompiledGuard, value: unknown, label: string): u
     const state: RunState = { label, issues: [] }
     projected = guard.project(value, state)
     if (state.issues.length > 0) throw undeclaredDeferred(label, state.issues)
+    // Copy-on-write: the same reference back means nothing was dropped anywhere below.
+    if (guard.warnDropped && projected !== value) warnDropped(label, value, projected)
   }
   const result = guard.validate(projected)
   return result instanceof Promise
-    ? result.then((settled) => settle(guard, settled, label))
-    : settle(guard, result, label)
+    ? result.then((settled) => settle(guard, settled, label, projected))
+    : settle(guard, result, label, projected)
 }
 
 /** What a browser-bound channel sends, and how it is named in errors. */