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

package/dist/index.d.ts

@@ -7,17 +7,46 @@
  * 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 } from "@nifrajs/core";
+import { server } from "@nifrajs/core";
 import { type Deferred, defer } from "./deferred.js";
-import type { Manifest, Meta, MetaArgs, MetaInput } from "./manifest.js";
+import type { LinkDescriptor, Manifest, Meta, MetaArgs, MetaInput, ScriptDescriptor } from "./manifest.js";
 import { type Submission } from "./router.js";
 export { DRAFT_COOKIE, type DraftCookieControls, disableDraft, type EnableDraftOptions, enableDraft, isDraftEnabled, } from "./draft.js";
 export { type FontDisplay, type FontFace, type FontPreloadInput, type FontSource, fontFace, fontPreload, } from "./fonts.js";
 export { type CachedResponse, type CacheStore, ISR_REVALIDATE_HEADER, ISR_STATUS_HEADER, type ISRApp, type ISROptions, type ISRPlatform, KVCacheStore, type KVCacheStoreOptions, type KVNamespaceLike, MemoryCacheStore, type MemoryCacheStoreOptions, type RevalidateEndpointOptions, revalidateEndpoint, withISR, } from "./isr.js";
-export { type Action, buildManifest, enumeratePrerenderedPaths, enumerateStaticRoutes, filePathToPattern, filePathToPatterns, type GetStaticPaths, type LayoutEntry, type Loader, type LoaderContext, type Manifest, type Meta, type MetaArgs, type MetaInput, type RouteEntry, type RouteModule, type StaticPath, type StaticPaths, type StaticRoutes, } from "./manifest.js";
+export { type Action, buildManifest, enumeratePrerenderedPaths, enumerateStaticRoutes, filePathToPattern, filePathToPatterns, type GetStaticPaths, type LayoutEntry, type LinkDescriptor, type Loader, type LoaderContext, type Manifest, type Meta, type MetaArgs, type MetaInput, type RouteEntry, type RouteModule, type ScriptDescriptor, type StaticPath, type StaticPaths, type StaticRoutes, } from "./manifest.js";
 export { createQueryClient, hashQueryKey, type QueryClient, type QueryClientOptions, type QueryHandle, type QueryState, type QueryStatus, } from "./query.js";
 export { type ClientRouter, type ClientRouterOptions, createClientRouter, createMatcher, DATA_HEADER, type Fetcher, type FetcherState, type FetchRouteData, type MountRouterOptions, REDIRECT_HEADER, REVALIDATE_HEADER, type RouteMatch, type RoutePattern, type RouterState, type Submission, type SubmitOptions, } from "./router.js";
 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`. */
@@ -66,6 +95,13 @@ export declare const ROUTE_GLOBAL = "__NIFRA_ROUTE__";
 /** Global the server serializes an action's data return into (absent on GETs); the client
  * reads it so hydration after a native form POST matches the server-rendered markup. */
 export declare 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 declare const DEFAULT_DEV_PORT = 4321;
 type MaybePromise<T> = T | Promise<T>;
 declare const RESPONSE_RESULT: unique symbol;
 export interface RenderedPage {
@@ -109,7 +145,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;
@@ -179,6 +225,68 @@ export declare function revalidate<T>(paths: readonly string[], data: T): Revali
 export declare function serializeData(data: unknown): string;
 /** Resolve a route's `meta` (static or a function of the loader data + params) to a {@link Meta}. */
 export declare function resolveMeta(meta: MetaInput | undefined, args: MetaArgs): 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 declare function canonical(href: string): LinkDescriptor;
+/** 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 declare function openGraph(input: OpenGraphInput): Array<Record<string, string>>;
+/**
+ * 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 declare function jsonLd(data: Record<string, unknown>): ScriptDescriptor;
+/**
+ * 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 declare function mergeHeads(heads: readonly Meta[]): Meta;
 export interface CreateWebAppOptions {
     readonly adapter: RenderAdapter;
     readonly manifest: Manifest;
@@ -187,8 +295,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. */
@@ -232,8 +356,16 @@ export interface CreateWebAppOptions {
  * 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 declare function createWebApp(options: CreateWebAppOptions): Server;
+export declare function createWebApp<Env = unknown>(options: CreateWebAppOptions): ReturnType<typeof server<Env>>;
 export interface GenerateClientEntryOptions {
     /** Module specifier for the adapter's client runtime (exports `mountRouter`), e.g.
      * `"@nifrajs/web-solid/client"`. */

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -36,6 +36,13 @@ export const ROUTE_GLOBAL = "__NIFRA_ROUTE__";
 /** Global the server serializes an action's data return into (absent on GETs); the client
  * 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();
 // XSS-safe `<script>` JSON escaping in a SINGLE pass: `<`/`>` would break out of the
@@ -302,6 +309,22 @@ export function serializeData(data) {
 function escapeHtml(value) {
     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) {
+    // 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) {
     return value
         .replaceAll("&", "&amp;")
@@ -309,14 +332,33 @@ function escapeAttr(value) {
         .replaceAll("<", "&lt;")
         .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. */
+/** 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) {
-    return Object.entries(attrs)
-        .filter(([name]) => SAFE_ATTR_NAME.test(name))
-        .map(([name, value]) => `${name}="${escapeAttr(value)}"`)
-        .join(" ");
+    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
 // `meta` is returned by-reference from resolveMeta, so the same object recurs every request → cache
@@ -324,10 +366,13 @@ function tagAttrs(attrs) {
 // builds a fresh object each request (new identity) → miss → recompute, exactly as needed (its
 // content can vary). WeakMap so a route module that's GC'd takes its entry with it.
 const headTagsCache = new WeakMap();
-/** 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) {
     if (head === undefined)
         return "";
@@ -341,6 +386,12 @@ function headTags(head) {
     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;
 }
@@ -350,11 +401,133 @@ export function resolveMeta(meta, args) {
         return {};
     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) {
+    return { rel: "canonical", href };
+}
+/**
+ * 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) {
+    const tags = [];
+    const add = (property, content) => {
+        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) {
+    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) {
+    // 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];
+    let title;
+    const meta = [];
+    const link = [];
+    const script = [];
+    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 = {};
+    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;
+}
+/**
+ * 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) {
+    // 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.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) {
     const { adapter, manifest, clientEntry, title, api } = options;
@@ -378,18 +551,74 @@ export function createWebApp(options) {
             return { styles: perRoute };
         return options.styles && options.styles.length > 0 ? { styles: options.styles } : {};
     };
+    // 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();
+    // 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) => Promise.all(
+    // 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) => Promise.all(
     // layoutIds only reference layouts present in the manifest (buildManifest invariant).
-    route.layoutIds.map((id) => manifest.layouts[id].load().then((m) => m.default)));
+    route.layoutIds.map((id) => manifest.layouts[id].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, page, metaArgs) => {
+        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, suffix) => 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) => {
+        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
@@ -501,8 +730,11 @@ export function createWebApp(options) {
                     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
@@ -588,8 +820,11 @@ export function createWebApp(options) {
             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).
@@ -655,7 +890,7 @@ export function generateClientEntry(manifest, options) {
         loaderRows.push(`  "_404": ${lazyLoader([manifest.notFound.file])},`);
     }
     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.
@@ -665,7 +900,7 @@ export function generateClientEntry(manifest, options) {
         `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,
         "}",
@@ -678,15 +913,19 @@ export function generateClientEntry(manifest, options) {
         // 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 = [",
@@ -719,7 +958,13 @@ export function generateClientEntry(manifest, options) {
         "  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`;