@nifrajs/web 0.1.0-alpha.1 → 0.1.0-alpha.2

package/src/index.ts

@@ -7,7 +7,7 @@
  * the adapter interprets them. That keeps this package both framework-agnostic and free
  * of DOM types: it is pure server orchestration + string building.
  */
-import { type Server, server } from "@nifrajs/core"
+import { server } from "@nifrajs/core"
 import {
   DEFERRED_ERROR_CODE,
   DEFERRED_RUNTIME,
@@ -19,7 +19,17 @@ import {
 } from "./deferred.ts"
 import { isDraftEnabled } from "./draft.ts"
 import { ISR_REVALIDATE_HEADER } from "./isr.ts"
-import type { LayoutEntry, Manifest, Meta, MetaArgs, MetaInput, RouteEntry } from "./manifest.ts"
+import type {
+  LayoutEntry,
+  LinkDescriptor,
+  Manifest,
+  Meta,
+  MetaArgs,
+  MetaInput,
+  RouteEntry,
+  RouteModule,
+  ScriptDescriptor,
+} from "./manifest.ts"
 import {
   DATA_HEADER,
   PRERENDERED_GLOBAL,
@@ -76,6 +86,7 @@ export {
   filePathToPatterns,
   type GetStaticPaths,
   type LayoutEntry,
+  type LinkDescriptor,
   type Loader,
   type LoaderContext,
   type Manifest,
@@ -84,6 +95,7 @@ export {
   type MetaInput,
   type RouteEntry,
   type RouteModule,
+  type ScriptDescriptor,
   type StaticPath,
   type StaticPaths,
   type StaticRoutes,
@@ -122,6 +134,35 @@ export {
 // Deferred loader data (`defer()` + the `Deferred<T>` type) — consumed by the adapter's `<Await>`.
 export { type Deferred, defer }
 
+/** Phantom brand key for {@link ServerOnly}. A unique symbol so the brand can't be forged by a plain
+ * object literal; `unique symbol` keys never appear in the emitted JS, so the brand is purely
+ * type-level (zero runtime cost). The property is optional + `never`-typed, so a `ServerOnly<T>`
+ * stays assignment-compatible with `T` — it documents intent without obstructing real use. */
+declare const SERVER_ONLY_BRAND: unique symbol
+
+/**
+ * Type-level intent marker for a value that must only exist on the server — a secret, a DB handle, a
+ * server-only client. `ServerOnly<T>` is structurally `T` (the brand is an optional phantom field, so
+ * existing code keeps type-checking), but it advertises to readers + the compiler that the value is
+ * not meant to cross to the browser. It is **purely type-level** and erases at build — it does NOT,
+ * by itself, keep the value out of the client bundle.
+ *
+ * The enforcement is two runtime conventions:
+ *  - add the side-effect import `import "@nifrajs/web/server-only"` at the top of the module — the
+ *    client build ({@link buildClient}) fails loud, with the import chain, if it reaches a browser
+ *    chunk (the poison-import marker);
+ *  - or name the file `*.server.ts` — the `.server` convention empties it in the client build.
+ *
+ * Use this brand to express the intent in the types; pair it with one of those runtime markers so a
+ * leak is caught at build time rather than shipping a secret to the client.
+ *
+ * @example
+ * import "@nifrajs/web/server-only"
+ * import type { ServerOnly } from "@nifrajs/web"
+ * export const apiKey: ServerOnly<string> = process.env.SECRET_API_KEY!
+ */
+export type ServerOnly<T> = T & { readonly [SERVER_ONLY_BRAND]?: never }
+
 /** The data handed to a route component. Opaque to the core. `actionData` is the return of a
  * route `action` after a POST (absent on plain GETs). `pending` + `submission` are client-only
  * (absent on SSR): they drive **optimistic UI** — render from `submission.formData` while `pending`. */
@@ -178,6 +219,14 @@ export const ROUTE_GLOBAL = "__NIFRA_ROUTE__"
  * reads it so hydration after a native form POST matches the server-rendered markup. */
 export const ACTION_GLOBAL = "__NIFRA_ACTION__"
 
+/**
+ * The single default port for the dev server (`@nifrajs/web/dev`, `@nifrajs/web/vite`) **and**
+ * `nifra start`. Deliberately uncommon: `3000`/`5173`/`8080` collide with whatever else is running
+ * (Next, Vite, a stray Node API). `4321` rarely is — and being the *same* constant across `nifra dev`
+ * and `nifra start` means a project's URL doesn't change between commands. Override per-run with
+ * `--port <n>` or the `PORT` env var. */
+export const DEFAULT_DEV_PORT = 4321
+
 // Shared, stateless — allocated once at module load, not per render/stream.
 const TEXT_ENCODER = new TextEncoder()
 
@@ -241,7 +290,17 @@ export interface RenderPageOptions {
   /** Document title (fallback when `head.title` is unset). */
   readonly title?: string
   /** Resolved route head — `title` overrides `title` above; `meta`/`link` render as managed
-   * (`data-nifra`) tags the client updates on navigation. */
+   * (`data-nifra`) tags the client updates on navigation.
+   *
+   * **Head contract (the layout chain contributes).** `createWebApp` resolves this via
+   * {@link mergeHeads}: a route's head is its **layout chain's** `meta`/`head` exports merged with the
+   * page's. A `_layout.tsx` may `export const meta` (or `export function meta(args)`) — its tags land
+   * on every page below it (the home for `hreflang`, `preconnect`, a section-default `<title>`). The
+   * merge is **nearest-wins for scalars** (the page's `title` overrides an inner layout's, which
+   * overrides an outer one; an undefined page title keeps the layout's) and **concatenated for the
+   * `meta`/`link` arrays** (outermost layout first, page last). `<link>` attributes are name-validated
+   * (any letter/digit/hyphen name — covers `rel`/`href`/`hreflang`/`crossorigin`/`media`/`sizes`/`as`/
+   * `integrity`/`fetchpriority`/…) and value-escaped against XSS. */
   readonly head?: Meta
   /** Id of the container wrapping the app markup (default `"root"`). */
   readonly rootId?: string
@@ -612,6 +671,23 @@ function escapeHtml(value: string): string {
   return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;")
 }
 
+/**
+ * Escape a `<script>` element's text content so it cannot break out of the element. Per the HTML spec,
+ * a script's text may contain any character EXCEPT the sequences that the parser treats as element
+ * boundaries: `</` (which would begin the end tag — `</script>` is the obvious XSS vector, but ANY `</`
+ * starts script-data-end-tag parsing), and the comment/CDATA edges `<!--` / `]]>`. We escape the `<`
+ * (and the `>` of `]]>`) to its JS unicode escape: inside a JS/JSON string literal `<` is the
+ * identical character, so a JSON-LD payload is byte-equivalent after parsing — but the raw `<`/`>` the
+ * HTML tokenizer scans for is gone. This is the JSON-LD-in-HTML rule (content is JSON, never raw HTML),
+ * mirroring {@link serializeData}'s posture for the data-global script. Idempotent on already-safe text.
+ */
+function escapeScriptContent(content: string): string {
+  // Order matters: rewrite `]]>` first (its `>` becomes `>`), then every `<` (covers `</` and
+  // `<!--` in one pass). `<` → `<`; the lone `>` of `]]>` → `>`. A bare `>` elsewhere is
+  // harmless in script data, so only the `]]>` close is targeted for `>`.
+  return content.replaceAll("]]>", "]]\\u003e").replaceAll("<", "\\u003c")
+}
+
 function escapeAttr(value: string): string {
   return value
     .replaceAll("&", "&amp;")
@@ -620,15 +696,31 @@ function escapeAttr(value: string): string {
     .replaceAll(">", "&gt;")
 }
 
+// Attribute-NAME guard for emitted `<meta>`/`<link>` tags. Intentionally a *name-shape* allowlist, not
+// a hardcoded per-attribute one: any letter/digit/hyphen name beginning with a letter is permitted, so
+// every standard `<link>` attribute flows through — `rel`, `href`, `hreflang`, `crossorigin`, `media`,
+// `sizes`, `type`, `as`, `title`, `integrity`, `referrerpolicy`, `imagesrcset`, `imagesizes`,
+// `disabled`, `color`, `fetchpriority` — alongside `<meta>`'s `name`/`property`/`content` and custom
+// `data-*`. A hardcoded list would silently drop valid attrs (the bug this guards against: `hreflang`
+// /`crossorigin` getting filtered out). What it rejects is name-shape abuse only — a name with a space,
+// `=`, `>`, quote, or a leading digit can't break out of the tag. Attribute VALUES are escaped
+// separately (they may carry loader data → XSS), so a widened name set never widens the injection
+// surface. Names that fail the shape check are dropped.
 const SAFE_ATTR_NAME = /^[a-zA-Z][a-zA-Z0-9-]*$/
 
-/** Serialize a meta/link tag's attributes: validate the name (dev-authored) + escape the value
- * (may carry loader data → XSS). Invalid attribute names are dropped. */
-function tagAttrs(attrs: Record<string, string>): string {
-  return Object.entries(attrs)
-    .filter(([name]) => SAFE_ATTR_NAME.test(name))
-    .map(([name, value]) => `${name}="${escapeAttr(value)}"`)
-    .join(" ")
+/** Serialize a meta/link tag's attributes: validate the name shape (see {@link SAFE_ATTR_NAME}) +
+ * escape the value against XSS. Invalid attribute names are dropped. Values follow the HTML attribute
+ * conventions {@link LinkDescriptor} types: a string renders `name="escaped"`; `true` renders the bare
+ * boolean attribute (`disabled`); `false` and `undefined` are skipped (a conditionally-absent attr). */
+function tagAttrs(attrs: Record<string, string | boolean | undefined>): string {
+  let out = ""
+  for (const [name, value] of Object.entries(attrs)) {
+    if (value === undefined || value === false) continue // omitted / absent boolean attribute
+    if (!SAFE_ATTR_NAME.test(name)) continue // name-shape abuse — dropped (see SAFE_ATTR_NAME)
+    if (out !== "") out += " "
+    out += value === true ? name : `${name}="${escapeAttr(value)}"`
+  }
+  return out
 }
 
 // Memoize the serialized head-tag string by the resolved `Meta` object's identity. A STATIC route
@@ -638,10 +730,13 @@ function tagAttrs(attrs: Record<string, string>): string {
 // content can vary). WeakMap so a route module that's GC'd takes its entry with it.
 const headTagsCache = new WeakMap<Meta, string>()
 
-/** Render a route's `meta`/`link` as managed (`data-nifra`) head tags. Title is set separately.
- * String concatenation (no intermediate `.map()` arrays + spread) — parity with the already
- * concat-based preloadLinks/styleLinks/islandPreloads loops; byte-identical output.
- * Result is memoized per resolved-`Meta` identity (static meta → serialized once per route). */
+/** Render a route's `meta`/`link`/`script` as managed (`data-nifra`) head tags. Title is set
+ * separately. XSS-safe by construction: every attribute flows through {@link tagAttrs} (name shape-
+ * validated, value HTML-escaped), and each `script[].content` through `escapeScriptContent`
+ * (breakout-escaped) — so loader-derived strings (LLM-authored `og:*`, user content) can't inject markup
+ * or close the tag early. String concatenation (no intermediate `.map()` arrays + spread) — parity with
+ * the already concat-based preloadLinks/styleLinks/islandPreloads loops; byte-identical output. Result
+ * is memoized per resolved-`Meta` identity (static meta → serialized once per route). */
 function headTags(head: Meta | undefined): string {
   if (head === undefined) return ""
   const cached = headTagsCache.get(head)
@@ -649,6 +744,12 @@ function headTags(head: Meta | undefined): string {
   let out = ""
   if (head.meta !== undefined) for (const m of head.meta) out += `<meta ${tagAttrs(m)} data-nifra>`
   if (head.link !== undefined) for (const l of head.link) out += `<link ${tagAttrs(l)} data-nifra>`
+  // `<script>` slot — JSON-LD + other inert head scripts. `type` is attribute-escaped; `content` is
+  // breakout-escaped (`escapeScriptContent`) so a `</script>` (or `<!--`/`]]>`) payload can't close the
+  // element early. Managed (`data-nifra`) so a soft-nav's `applyHead` cleanly replaces it.
+  if (head.script !== undefined)
+    for (const s of head.script)
+      out += `<script type="${escapeAttr(s.type ?? "application/ld+json")}" data-nifra>${escapeScriptContent(s.content)}</script>`
   headTagsCache.set(head, out)
   return out
 }
@@ -659,6 +760,118 @@ export function resolveMeta(meta: MetaInput | undefined, args: MetaArgs): Meta {
   return typeof meta === "function" ? meta(args) : meta
 }
 
+/**
+ * A `<link rel="canonical">` descriptor for a route's `meta.link`. The canonical URL tells search
+ * engines which URL is authoritative for a page (deduping query-string / tracking variants).
+ *
+ * ```ts
+ * export const meta = (a) => ({ link: [canonical(`https://site.com/posts/${a.params.slug}`)] })
+ * ```
+ */
+export function canonical(href: string): LinkDescriptor {
+  return { rel: "canonical", href }
+}
+
+/** Inputs for {@link openGraph} — the common Open Graph properties. All optional; only the provided
+ * ones become tags. `type` defaults to `"website"`. */
+export interface OpenGraphInput {
+  readonly title?: string
+  readonly description?: string
+  /** Absolute URL of the share image (`og:image`). */
+  readonly image?: string
+  /** Canonical URL of the page (`og:url`). */
+  readonly url?: string
+  /** Object type (`og:type`) — `"website"`, `"article"`, … Default `"website"`. */
+  readonly type?: string
+}
+
+/**
+ * Build the Open Graph `<meta property="og:*">` entries for a route's `meta.meta`. Returns only the
+ * properties you supplied (plus `og:type`, defaulting to `"website"`), so it composes with other meta.
+ *
+ * ```ts
+ * export const meta = { meta: [...openGraph({ title: "Nifra", image: "https://site.com/og.png" })] }
+ * ```
+ */
+export function openGraph(input: OpenGraphInput): Array<Record<string, string>> {
+  const tags: Array<Record<string, string>> = []
+  const add = (property: string, content: string | undefined): void => {
+    if (content !== undefined) tags.push({ property, content })
+  }
+  add("og:title", input.title)
+  add("og:description", input.description)
+  add("og:image", input.image)
+  add("og:url", input.url)
+  // `og:type` always present (the spec's required property) — default "website" when unset.
+  tags.push({ property: "og:type", content: input.type ?? "website" })
+  return tags
+}
+
+/**
+ * Build a JSON-LD `<script type="application/ld+json">` entry for a route's `meta.script` from a plain
+ * object. `JSON.stringify` produces the body; the head renderer breakout-escapes it (see
+ * `escapeScriptContent`), so a string field containing `</script>` is embedded safely.
+ *
+ * ```ts
+ * export const meta = {
+ *   script: [jsonLd({ "@context": "https://schema.org", "@type": "Article", headline: "Hi" })],
+ * }
+ * ```
+ */
+export function jsonLd(data: Record<string, unknown>): ScriptDescriptor {
+  return { type: "application/ld+json", content: JSON.stringify(data) }
+}
+
+/**
+ * Merge a route's `<head>` contributions from its layout chain + the page into one {@link Meta}.
+ *
+ * The head contract (see {@link CreateWebAppOptions} and `LayoutEntry`): a `_layout.tsx` may export
+ * `meta` to put sitewide tags (`hreflang`, `preconnect`, a default `<title>`, …) on every page below
+ * it. `heads` is passed **outermost layout → … → innermost layout → page** (the same order as the
+ * render chain), and merges:
+ *  - **`title`** — *nearest-wins*: the last defined value across the list, so the page overrides an
+ *    inner layout, which overrides an outer one. A layout `title` is the section default; an undefined
+ *    page `title` keeps it.
+ *  - **`meta` / `link`** — *concatenated* in list order (outermost first, page last). Duplicate-tag
+ *    de-duplication is the caller's concern; the framework emits exactly what's declared so a layout
+ *    can ship N `<link rel="alternate" hreflang>` tags and a page can add its own canonical.
+ *
+ * Returns a fresh object whose identity is stable per `heads` *content* only when every entry is a
+ * static (by-reference) `Meta` and there is exactly one — otherwise a new object each call. That is
+ * fine: {@link headTags}'s memo is keyed on identity, so a per-request merge simply recomputes (its
+ * content can vary with loader data anyway).
+ */
+export function mergeHeads(heads: readonly Meta[]): Meta {
+  // Single-head fast path (a route with no layout `meta`, by far the common case) — return the
+  // resolved object by reference so headTags' identity-keyed memo hits across requests for static meta.
+  if (heads.length === 1) return heads[0] as Meta
+  let title: string | undefined
+  const meta: Array<Record<string, string>> = []
+  const link: LinkDescriptor[] = []
+  const script: ScriptDescriptor[] = []
+  for (const h of heads) {
+    if (h.title !== undefined) title = h.title // nearest-wins: later (more specific) overrides
+    if (h.meta !== undefined) meta.push(...h.meta)
+    if (h.link !== undefined) link.push(...h.link)
+    if (h.script !== undefined) script.push(...h.script) // concatenated like meta/link (outermost first)
+  }
+  // Build the result with only the fields that were actually contributed — an empty `meta`/`link`/
+  // `script` array would otherwise be a spurious (if harmless) key. A mutable local; the cast to `Meta`
+  // is sound because a key is assigned only when defined (so `exactOptionalPropertyTypes` never sees
+  // `undefined`).
+  const merged: {
+    title?: string
+    meta?: Meta["meta"]
+    link?: Meta["link"]
+    script?: Meta["script"]
+  } = {}
+  if (title !== undefined) merged.title = title
+  if (meta.length > 0) merged.meta = meta
+  if (link.length > 0) merged.link = link
+  if (script.length > 0) merged.script = script
+  return merged as Meta
+}
+
 export interface CreateWebAppOptions {
   readonly adapter: RenderAdapter
   readonly manifest: Manifest
@@ -667,8 +880,24 @@ export interface CreateWebAppOptions {
   /** Default document title for all pages. */
   readonly title?: string
   /** Injected into each loader's `ctx.api` — typically an `inProcessClient(app)` (typed
-   * per-route via `@nifrajs/client`'s `createRoutes`). Opaque to the core. */
+   * per-route via `@nifrajs/client`'s `createRoutes`). Opaque to the core.
+   *
+   * **Auto-mount.** When `api` exposes a callable `.fetch(url, init)` (every `inProcessClient(backend)`
+   * does — see {@link isMountableApi}), `createWebApp` also serves that backend over HTTP at
+   * {@link apiPrefix} (default `/api`): a request whose pathname starts with the prefix is dispatched
+   * straight to `api.fetch(req.url, req)` before page routing, and the backend's `Response` is returned
+   * untouched. This closes the reported gap where `POST /api/sync` / `/api/auth/*` 404/405'd against the
+   * page router until the app author hand-wrote an `if (pathname.startsWith("/api/")) …` branch in
+   * `server-bun.ts`. The mount runs in `nifra dev` too (the Vite dev server dispatches every request
+   * through this same app). Pass `apiPrefix: ""` to disable it (pages-only). */
   readonly api?: unknown
+  /** HTTP path prefix the {@link api} backend is auto-mounted at (default `"/api"`). A request whose
+   * pathname is exactly the prefix or starts with `prefix + "/"` is dispatched to the backend before
+   * page routing; the backend therefore defines its routes at the **full** path (`server().post("/api/
+   * sync", …)`), matching the in-process `inProcessClient` call sites. Set to `""` to disable the
+   * auto-mount entirely (the app serves pages only and `api` stays a loader-only `ctx.api`). Mounting
+   * is also a no-op when `api` has no callable `.fetch` (e.g. a plain object passed as `ctx.api`). */
+  readonly apiPrefix?: string
   /** Secret for **draft / preview mode** (see `enableDraft`). When set, a request carrying a valid
    * signed `__nifra_draft` cookie gets `ctx.draft === true` in loaders/actions (else always `false`).
    * Pair with `withISR({ draftSecret })` so editors bypass the cache. Omit to disable draft mode. */
@@ -719,13 +948,48 @@ interface RouteContext {
   readonly env: unknown
 }
 
+/** The minimal shape the `/api/*` auto-mount needs: a `fetch(url, init)` that yields a `Response`.
+ * `inProcessClient(backend)` exposes exactly this (its in-process bridge); a raw `@nifrajs/core`
+ * `Server` does not match (its `fetch` takes a `Request`, not `(url, init)`) — which is intended,
+ * since the documented `api` is the `inProcessClient` proxy, not the bare server. */
+interface MountableApi {
+  readonly fetch: (url: string, init?: RequestInit) => Response | Promise<Response>
+}
+
+/**
+ * Narrow an opaque `api` to a {@link MountableApi}. Guards the `/api/*` auto-mount: an `api` set to a
+ * plain loader-only value (no `.fetch`) leaves the app pages-only rather than crashing. Kept a
+ * structural shape check (not an `instanceof`) so any in-process bridge — `inProcessClient`, a test
+ * stub, a custom agent — is mountable without `@nifrajs/web` depending on `@nifrajs/client`.
+ */
+function isMountableApi(api: unknown): api is MountableApi {
+  // inProcessClient(backend) is a CALLABLE Eden proxy — `typeof` is "function", not "object" — so the
+  // guard must accept both; it only needs a callable `.fetch` (the in-process bridge the outer proxy
+  // exposes for the mount). An object-only check silently disabled the whole /api/* auto-mount.
+  return (
+    (typeof api === "object" || typeof api === "function") &&
+    api !== null &&
+    typeof (api as { fetch?: unknown }).fetch === "function"
+  )
+}
+
 /**
  * Build a nifra app from a route manifest: every route SSRs its layout chain via `renderPage`,
  * and a wildcard catch-all renders `_404` (or a plain 404). Reuses @nifrajs/core's router +
  * lifecycle, so matching, params, and precedence are battle-tested. fs-free — feed it a
  * manifest from `discoverRoutes` (`@nifrajs/web/fs`) at startup, so the served app stays portable.
+ *
+ * **Typed platform bindings.** Pass `Env` — `createWebApp<Env>({ … })` — to declare the app's Workers
+ * bindings ONCE. It seeds the returned `Server`'s context with `{ env: Env }` (exactly as the backend's
+ * `server<Env>()` does), so `app.fetch(req, { env })` / `toFetchHandler(app)` type-check the `env`
+ * argument against the declared shape — no per-binding cast at the edge entry. Per-route loaders/actions
+ * stay typed independently of this call: annotate them with `@nifrajs/client`'s `LoaderArgs<Api, Env>`
+ * (same `Env`) so `ctx.env.MY_KV` is typed there too. Omit the parameter and `Env` is `unknown` — the
+ * secure default; validate at the trust boundary before use.
  */
-export function createWebApp(options: CreateWebAppOptions): Server {
+export function createWebApp<Env = unknown>(
+  options: CreateWebAppOptions,
+): ReturnType<typeof server<Env>> {
   const { adapter, manifest, clientEntry, title, api } = options
   const titleOption = title === undefined ? {} : { title }
   // Draft/preview: when a `draftSecret` is configured, each request's signed `__nifra_draft` cookie is
@@ -747,26 +1011,87 @@ export function createWebApp(options: CreateWebAppOptions): Server {
     if (perRoute !== undefined) return { styles: perRoute }
     return options.styles && options.styles.length > 0 ? { styles: options.styles } : {}
   }
-  const app = server()
+  // Seed the context with the declared `Env` so `app.fetch(req, { env })` / `toFetchHandler(app)` type
+  // the platform bindings (see the `createWebApp` doc). The runtime `env` still arrives per-request via
+  // `app.fetch(req, { env })`; this is a compile-time-only seed (`server<Env>()` casts, doesn't store).
+  const app = server<Env>()
+  // Auto-mount the in-process backend over HTTP at `apiPrefix` (default `/api`), BEFORE page routing.
+  // `onRequest` runs on the raw request ahead of the router, so this wins over the page wildcard `/*`
+  // for every method (POST/GET/PUT/…) — not just the GET page routes — and a backend 404 (`/api/none`)
+  // surfaces as the backend's own response, never the page 404. We dispatch the SAME `Request` object
+  // (its body unread) so streamed/large bodies pass through untouched; the backend defines its routes
+  // at the full prefixed path (`server().post("/api/sync", …)`), matching the `inProcessClient` call
+  // sites. `apiPrefix: ""` opts out; a non-mountable `api` (no `.fetch`) is left pages-only. The hook
+  // is registered ONLY when both hold, so a pages-only app keeps core's synchronous no-hook fast path.
+  //
+  // Backward-compat: an app that still hand-dispatches `/api/*` in its server entry (the old
+  // `if (pathname.startsWith("/api/")) return backend.fetch(req)`) intercepts BEFORE `app.fetch` is
+  // ever called, so that branch returns first and this hook never sees the request — no double
+  // handling. Apps that drop the hand-dispatch now rely on this mount instead (dev + prod alike).
+  const apiPrefix = options.apiPrefix ?? "/api"
+  if (apiPrefix !== "" && isMountableApi(api)) {
+    const mountedApi = api
+    app.onRequest((req) => {
+      const { pathname } = new URL(req.url)
+      // Exactly the prefix (`/api`) or a sub-path (`/api/…`) — NOT a sibling like `/apixyz` that merely
+      // shares the prefix as a string head. Dispatch the original `req` (body intact) to the backend.
+      if (pathname === apiPrefix || pathname.startsWith(`${apiPrefix}/`)) {
+        return mountedApi.fetch(req.url, req)
+      }
+      return undefined // not an API path → continue to page routing
+    })
+  }
   // SSG `fallback: "404"`: the set of concrete paths that actually exist for those routes. An unlisted
   // path under a `"404"` route is rejected (it isn't a static file, and the route declared it shouldn't
   // SSR on demand). O(1) membership via a Set.
   const prerenderedSet = new Set(options.prerenderedPaths ?? [])
 
-  // Resolve a route's layout chain (outermost layout → page). Loaded lazily — the data-only and
-  // 405 branches return before any layout is needed.
-  const loadLayouts = (route: RouteEntry): Promise<unknown[]> =>
+  // Load a route's layout modules (outermost layout → innermost), keeping each module whole so the
+  // render path can take both its `default` (the component chain) AND its `meta` (the sitewide head it
+  // contributes). Loaded lazily — the data-only and 405 branches return before any layout is needed.
+  const loadLayoutModules = (
+    route: RouteEntry,
+  ): Promise<ReadonlyArray<{ default: unknown; meta?: MetaInput }>> =>
     Promise.all(
       // layoutIds only reference layouts present in the manifest (buildManifest invariant).
-      route.layoutIds.map((id) =>
-        (manifest.layouts[id] as LayoutEntry).load().then((m) => m.default),
-      ),
+      route.layoutIds.map((id) => (manifest.layouts[id] as LayoutEntry).load()),
     )
 
+  // Build a route's render chain + its merged `<head>` from the already-loaded layout modules + the
+  // page module. The chain is `[…layout components, page]`; the head merges each layout's `meta`
+  // export (outermost→innermost) with the page's (last), so a `head`/`meta` on `_layout.tsx`
+  // contributes sitewide tags. `metaArgs` (loader data + params) feed function-form `meta`s.
+  const resolveChainAndHead = (
+    layoutModules: ReadonlyArray<{ default: unknown; meta?: MetaInput }>,
+    page: RouteModule,
+    metaArgs: MetaArgs,
+  ): { chain: unknown[]; head: Meta } => {
+    const chain = [...layoutModules.map((m) => m.default), page.default]
+    const heads = [
+      ...layoutModules.map((m) => resolveMeta(m.meta, metaArgs)),
+      resolveMeta(page.meta, metaArgs),
+    ]
+    return { chain, head: mergeHeads(heads) }
+  }
+
   // Dir a special-file id lives in: `_error`→"" , `a/b/_error`→"a/b" (and likewise for `_layout`).
   const dirOfId = (id: string, suffix: string): string =>
     id === suffix ? "" : id.slice(0, id.length - suffix.length - 1)
 
+  // The request's origin (scheme + host + port, NO trailing slash) — the one server fact `meta()` needs
+  // for absolute `canonical`/`og:url`/`og:image` but can't otherwise see (it also runs on the client).
+  // `URL.origin` is exactly that shape; it matches the browser's `location.origin` for the same URL, so
+  // a soft-nav's `applyHead` resolves an identical `<head>` (no hydration drift). A malformed `req.url`
+  // (shouldn't happen on a real request) degrades to `""` — the documented unknown-origin default —
+  // rather than throwing during render.
+  const originOf = (req: Request): string => {
+    try {
+      return new URL(req.url).origin
+    } catch {
+      return ""
+    }
+  }
+
   /**
    * Render the **nearest `_error` boundary** when a route's loader throws (the agnostic, server-side
    * half of error UI — works on every adapter, no client takeover). The boundary renders in place of
@@ -883,8 +1208,11 @@ export function createWebApp(options: CreateWebAppOptions): Server {
           headers: { "content-type": "application/x-ndjson; charset=utf-8" },
         })
       }
-      const chain = [...(await loadLayouts(route)), mod.default]
-      const head = resolveMeta(mod.meta, { data, params: c.params })
+      const { chain, head } = resolveChainAndHead(await loadLayoutModules(route), mod, {
+        data,
+        params: c.params,
+        origin: originOf(c.req),
+      })
       const hydrateRoute = mod.hydrate !== false
       try {
         // `await` so a shell-render throw (renderToStream rejects before any byte) is caught here and
@@ -968,8 +1296,11 @@ export function createWebApp(options: CreateWebAppOptions): Server {
       const data = mod.loader
         ? await mod.loader({ params: c.params, request: c.req, api, env: c.env, draft })
         : null
-      const chain = [...(await loadLayouts(route)), mod.default]
-      const head = resolveMeta(mod.meta, { data, params: c.params })
+      const { chain, head } = resolveChainAndHead(await loadLayoutModules(route), mod, {
+        data,
+        params: c.params,
+        origin: originOf(c.req),
+      })
       const hydrateRoute = mod.hydrate !== false
       // A full-page POST streams the action's `defer()`'d parts mid-document behind `<Await>` too —
       // `renderPage` splits `actionData` like loader data (works with JS off; hydrates after).
@@ -1054,7 +1385,7 @@ export function generateClientEntry(
   }
 
   return `${[
-    'import { createClientRouter, createMatcher, resolveMeta } from "@nifrajs/web"',
+    'import { createClientRouter, createMatcher, mergeHeads, resolveMeta } from "@nifrajs/web"',
     'import { applyHead, installForms, installHistory } from "@nifrajs/web/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.
@@ -1064,7 +1395,7 @@ export function generateClientEntry(
     `const errorRouteIds = new Set(${JSON.stringify(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 page's meta per id.
+    // visited. loadModule caches the [layouts…, page] component chain + the chain's meta list per id.
     "const loaders = {",
     ...loaderRows,
     "}",
@@ -1077,15 +1408,19 @@ export function generateClientEntry(
     // the adapter's boundary so a client render error renders the `_error` UI. DOM-transparent, so the
     // hydrated tree matches the SSR markup (which has no boundary). Falls back to the plain chain when
     // the adapter has no `errorBoundary`.
+    // `metas[id]` is the chain's `meta` exports in head order (outermost layout → … → page), so a
+    // soft-nav merges the layout chain's head with the page's — matching the SSR `<head>` (sitewide
+    // layout tags persist across client navigation, no flash of page-only head). `_error` carries no
+    // head (a terminal boundary), so it's excluded from the meta list for error routes.
     "  if (errorBoundary && errorRouteIds.has(id)) {",
     "    const fallback = mods[mods.length - 1].default",
     "    const page = mods[mods.length - 2].default",
     "    const layouts = mods.slice(0, mods.length - 2).map((m) => m.default)",
     "    chains[id] = [...layouts, errorBoundary(fallback), page]",
-    "    metas[id] = mods[mods.length - 2].meta",
+    "    metas[id] = mods.slice(0, mods.length - 1).map((m) => m.meta)",
     "  } else {",
     "    chains[id] = mods.map((m) => m.default)",
-    "    metas[id] = mods[mods.length - 1].meta",
+    "    metas[id] = mods.map((m) => m.meta)",
     "  }",
     "}",
     "const patterns = [",
@@ -1118,7 +1453,13 @@ export function generateClientEntry(
     "  mountRouter({ router, routes: chains, container: root })",
     "  router.subscribe(() => {",
     "    const s = router.snapshot()",
-    "    if (!s.pending) applyHead(resolveMeta(metas[s.routeId], { data: s.data, params: s.params }))",
+    // Merge the matched route's chain meta (layouts→page) into one head — same contract as SSR.
+    "    if (!s.pending) {",
+    // `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 args = { data: s.data, params: s.params, origin: location.origin }",
+    "      applyHead(mergeHeads((metas[s.routeId] ?? [undefined]).map((m) => resolveMeta(m, args))))",
+    "    }",
     "  })",
     "})",
   ].join("\n")}\n`