@nifrajs/web 2.0.0 → 2.2.0

package/dist/plugins/vite-leak-guard.js

@@ -0,0 +1,67 @@
+/**
+ * `@nifrajs/web/plugins/vite-leak-guard` — nifra's two client-leak guards, for a Vite/Rollup production
+ * build.
+ *
+ * ## Why this exists
+ *
+ * nifra's production default is Bun, and that is not changing: a Vite/Rollup production build inherits
+ * Rollup's build profile and gives up the Bun-native advantage nifra competes on. But some apps depend on
+ * a Vite-only transform that has no Bun equivalent, and for those a Vite production build is the escape
+ * hatch. The moment that hatch exists, the two client-leak guards have to come with it - they are security
+ * guards, not lints: one stops secrets and database access from shipping to a browser. A second production
+ * pipeline arriving WITHOUT them, or with a hastily re-implemented "mostly ported" copy, is the failure the
+ * neutral module-graph seam was built to prevent.
+ *
+ * So this is not a second implementation. The detection logic (`detectNodeBuiltinsInClient`,
+ * `detectServerOnlyInClient`) and the failure MESSAGES (`formatNodeBuiltinLeak`, `formatServerOnlyLeak`)
+ * are the exact same functions the Bun build calls. This plugin only adapts Rollup's bundle shape into the
+ * neutral `ClientModuleGraph` (`fromRollupBundle`) and runs them. A leak reads identically whichever
+ * bundler produced it, and there is one place to change if a guard changes.
+ *
+ * ## How
+ *
+ * In `generateBundle` the whole client graph is available: each output chunk lists its `moduleIds`, and
+ * `this.getModuleInfo(id)` gives each module's resolved import edges. That is exactly what
+ * `fromRollupBundle` needs. Findings fail the build through Rollup's `this.error`, so the message lands in
+ * the build output the same way a Bun-build throw does.
+ *
+ * Add it to the `plugins` of a Vite production build (the LAST plugin, so it sees the final graph):
+ *
+ *   // vite.config.ts (production client build)
+ *   import { viteLeakGuard } from "@nifrajs/web/plugins/vite-leak-guard"
+ *   export default { build: { rollupOptions: { plugins: [viteLeakGuard()] } } }
+ */
+import { detectNodeBuiltinsInClient, detectServerOnlyInClient, formatNodeBuiltinLeak, formatServerOnlyLeak, } from "../build.js";
+import { fromRollupBundle } from "../module-graph.js";
+/**
+ * A Vite/Rollup plugin that fails the build when server-only code or a `node:` builtin reaches the client
+ * bundle - the same two guards, and the same error messages, as nifra's Bun production build.
+ */
+export function viteLeakGuard() {
+    const plugin = {
+        name: "nifra:leak-guard",
+        generateBundle(_options, bundle) {
+            // Resolved import edges per module, straight from Rollup's graph. Dynamic imports count too: a
+            // `node:`/server-only module reached only via `import()` still ships to the browser.
+            const importsOf = (id) => {
+                const info = this.getModuleInfo(id);
+                if (info === null)
+                    return [];
+                return [...(info.importedIds ?? []), ...(info.dynamicallyImportedIds ?? [])];
+            };
+            const graph = fromRollupBundle(bundle, importsOf);
+            // Node-builtin guard first, then server-only - the same order as the Bun build, so the first error a
+            // dev sees is the same across pipelines when a module trips both.
+            const leak = formatNodeBuiltinLeak(detectNodeBuiltinsInClient(graph)) ??
+                formatServerOnlyLeak(detectServerOnlyInClient(graph));
+            if (leak === undefined)
+                return;
+            // Record before throwing: the throw is what fails the build for a standalone user of this plugin,
+            // and the record is what lets a caller that owns the build re-raise the real message (see `leak`).
+            plugin.leak = leak;
+            this.error(new Error(leak));
+        },
+    };
+    return plugin;
+}
+//# sourceMappingURL=vite-leak-guard.js.map

package/dist/plugins/vite-leak-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite-leak-guard.js","sourceRoot":"","sources":["../../src/plugins/vite-leak-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,OAAO,EACL,0BAA0B,EAC1B,wBAAwB,EACxB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,gBAAgB,EAAyB,MAAM,oBAAoB,CAAA;AAyC5E;;;GAGG;AACH,MAAM,UAAU,aAAa;IAC3B,MAAM,MAAM,GAAoB;QAC9B,IAAI,EAAE,kBAAkB;QACxB,cAAc,CAAC,QAAQ,EAAE,MAAM;YAC7B,+FAA+F;YAC/F,qFAAqF;YACrF,MAAM,SAAS,GAAG,CAAC,EAAU,EAAqB,EAAE;gBAClD,MAAM,IAAI,GAAG,IAAI,CAAC,aAAa,CAAC,EAAE,CAAC,CAAA;gBACnC,IAAI,IAAI,KAAK,IAAI;oBAAE,OAAO,EAAE,CAAA;gBAC5B,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC,sBAAsB,IAAI,EAAE,CAAC,CAAC,CAAA;YAC9E,CAAC,CAAA;YACD,MAAM,KAAK,GAAG,gBAAgB,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;YACjD,qGAAqG;YACrG,kEAAkE;YAClE,MAAM,IAAI,GACR,qBAAqB,CAAC,0BAA0B,CAAC,KAAK,CAAC,CAAC;gBACxD,oBAAoB,CAAC,wBAAwB,CAAC,KAAK,CAAC,CAAC,CAAA;YACvD,IAAI,IAAI,KAAK,SAAS;gBAAE,OAAM;YAC9B,kGAAkG;YAClG,mGAAmG;YACnG,MAAM,CAAC,IAAI,GAAG,IAAI,CAAA;YAClB,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAA;QAC7B,CAAC;KACF,CAAA;IACD,OAAO,MAAM,CAAA;AACf,CAAC"}

package/dist/public-dir.d.ts

@@ -0,0 +1,36 @@
+/** How long each subtree may be cached. Content-hashed bundle output can be immutable; a
+ * user-authored file keeps its name across deploys, so it gets a day and a revalidation. */
+export interface PublicDirCache {
+    /** `cache-control` for content-hashed assets (default immutable, one year). */
+    readonly hashed?: string;
+    /** `cache-control` for everything else under `public/` (default one day). */
+    readonly assets?: string;
+}
+export interface ServePublicDirOptions {
+    /** Absolute path of the directory to serve. */
+    readonly dir: string;
+    /** URL prefix whose files are content-hashed and may be cached immutably (default `"/assets/"`). */
+    readonly hashedPrefix?: string;
+    readonly cache?: PublicDirCache;
+    /** Optional encoded URL-path allowlist. When present, route misses avoid a filesystem probe. */
+    readonly files?: ReadonlySet<string>;
+}
+/**
+ * Resolve a URL pathname to an absolute path **confined** to `root`, or `undefined` if it escapes.
+ *
+ * This is a user-path-to-filesystem sink, which makes it the one part of this feature with a security
+ * consequence. Decode first (`%2e%2e%2f` is `../`), then normalize, then verify the result is still
+ * under `root` by prefix - checking the *resolved* path rather than scanning the input for `..`,
+ * because a blocklist over encodings is exactly the kind of check that gets bypassed.
+ */
+export declare function resolvePublicPath(root: string, pathname: string): string | undefined;
+/**
+ * Build a static-file handler for `dir`.
+ *
+ * Returns `undefined` on any miss so the caller **falls through to routing** - a static probe must
+ * never shadow a route. That ordering is also why a `routes/robots.txt.tsx` beats a
+ * `public/robots.txt` only if the caller checks routes first; the documented precedence is that the
+ * static probe runs first, so `public/` wins, and an app wanting the route should not ship both.
+ */
+export declare function servePublicDir(options: ServePublicDirOptions): (request: Request) => Promise<Response | undefined>;
+//# sourceMappingURL=public-dir.d.ts.map

package/dist/public-dir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-dir.d.ts","sourceRoot":"","sources":["../src/public-dir.ts"],"names":[],"mappings":"AAiBA;4FAC4F;AAC5F,MAAM,WAAW,cAAc;IAC7B,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,qBAAqB;IACpC,+CAA+C;IAC/C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,oGAAoG;IACpG,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,cAAc,CAAA;IAC/B,gGAAgG;IAChG,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;CACrC;AAKD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAapF;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,qBAAqB,GAC7B,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAmCrD"}

package/dist/public-dir.js

@@ -0,0 +1,89 @@
+/**
+ * `public/` - user-authored static files, served identically in dev and in production.
+ *
+ * The asymmetry this closes: `nifra dev` served `public/` for free because the HMR path runs on Vite
+ * and Vite serves `public/` by default, while production had no `publicDir` concept at all. So a file
+ * worked all the way through development and 404'd the moment it was deployed. The failure is
+ * inverted - it appears only in production, and only for the assets nobody smoke-tests - and it has
+ * already shipped once as a self-hosted webfont that silently fell back to a system font in prod.
+ *
+ * One owner for both sides is the fix, not a second implementation that happens to agree today.
+ *
+ * Distinct from `publicPath` in `build.ts`, which is the URL prefix for content-hashed bundle chunks.
+ * The names collide and the concepts do not: `publicPath` never covers user-authored files.
+ */
+import { realpath } from "node:fs/promises";
+import { normalize, resolve, sep } from "node:path";
+const IMMUTABLE = "public, max-age=31536000, immutable";
+const ONE_DAY = "public, max-age=86400";
+/**
+ * Resolve a URL pathname to an absolute path **confined** to `root`, or `undefined` if it escapes.
+ *
+ * This is a user-path-to-filesystem sink, which makes it the one part of this feature with a security
+ * consequence. Decode first (`%2e%2e%2f` is `../`), then normalize, then verify the result is still
+ * under `root` by prefix - checking the *resolved* path rather than scanning the input for `..`,
+ * because a blocklist over encodings is exactly the kind of check that gets bypassed.
+ */
+export function resolvePublicPath(root, pathname) {
+    let decoded;
+    try {
+        decoded = decodeURIComponent(pathname);
+    }
+    catch {
+        return undefined; // malformed percent-encoding: not a path we will guess at
+    }
+    // A NUL can truncate a path in a downstream syscall; refuse rather than normalize it away.
+    if (decoded.includes("\0"))
+        return undefined;
+    const rootResolved = resolve(root);
+    const candidate = resolve(rootResolved, `.${normalize(decoded)}`);
+    if (candidate !== rootResolved && !candidate.startsWith(rootResolved + sep))
+        return undefined;
+    return candidate;
+}
+/**
+ * Build a static-file handler for `dir`.
+ *
+ * Returns `undefined` on any miss so the caller **falls through to routing** - a static probe must
+ * never shadow a route. That ordering is also why a `routes/robots.txt.tsx` beats a
+ * `public/robots.txt` only if the caller checks routes first; the documented precedence is that the
+ * static probe runs first, so `public/` wins, and an app wanting the route should not ship both.
+ */
+export function servePublicDir(options) {
+    const root = resolve(options.dir);
+    const rootReal = realpath(root).catch(() => undefined);
+    const hashedPrefix = options.hashedPrefix ?? "/assets/";
+    const hashed = options.cache?.hashed ?? IMMUTABLE;
+    const assets = options.cache?.assets ?? ONE_DAY;
+    return async (request) => {
+        if (request.method !== "GET" && request.method !== "HEAD")
+            return undefined;
+        const { pathname } = new URL(request.url);
+        // A production manifest can reject page routes without touching the filesystem.
+        if (options.files !== undefined && !options.files.has(pathname))
+            return undefined;
+        const abs = resolvePublicPath(root, pathname);
+        if (abs === undefined)
+            return undefined;
+        const [resolvedRoot, resolvedFile] = await Promise.all([
+            rootReal,
+            realpath(abs).catch(() => undefined),
+        ]);
+        if (resolvedRoot === undefined ||
+            resolvedFile === undefined ||
+            (resolvedFile !== resolvedRoot && !resolvedFile.startsWith(resolvedRoot + sep))) {
+            return undefined;
+        }
+        const file = Bun.file(resolvedFile);
+        if (!(await file.exists()))
+            return undefined;
+        const headers = new Headers({
+            "cache-control": pathname.startsWith(hashedPrefix) ? hashed : assets,
+        });
+        // HEAD must not carry a body, but must otherwise match GET's headers.
+        return request.method === "HEAD"
+            ? new Response(null, { headers })
+            : new Response(file, { headers });
+    };
+}
+//# sourceMappingURL=public-dir.js.map

package/dist/public-dir.js.map

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

package/dist/route-manifest.d.ts

@@ -0,0 +1,91 @@
+/**
+ * `@nifrajs/web/route-manifest` — what each route actually DOES, as one artifact.
+ *
+ * The facts are already in the route modules: `prerender`, `getStaticPaths`, `revalidate`, `hydrate`.
+ * What has never existed is anywhere to read them together. To answer "which pages are static?", "which
+ * ones revalidate, and how often?", "which ship no JS?", you open every route file and hold the answer in
+ * your head - and the answer changes on the target you deploy to, which is nowhere near the route file.
+ *
+ * That gap is not just inconvenient. The interesting cases are the ones where a route's declaration and
+ * its deploy target disagree, and there is currently nothing that can notice: an ISR route on a target
+ * with no revalidation story regenerates on every request; a `static` build containing a route that was
+ * never prerenderable ships a page that 404s. Both are silent, and both are decided at build time by
+ * information no single place holds.
+ *
+ * So this derives one record per route - render mode, hydration, cache policy - resolves it against the
+ * target, and reports what the target cannot honour. Pure and fs-free: it takes an already-built
+ * `Manifest` so it runs at build time, in `nifra routes`, and in a test with a hand-built manifest.
+ */
+import type { Manifest, RouteModule } from "./manifest.js";
+/**
+ * How a route produces its HTML.
+ *
+ * - `static`  - prerendered at build; served as a file, no server render at request time.
+ * - `isr`     - server-rendered, then cached and revalidated on a timer (`export const revalidate`).
+ * - `ssr`     - server-rendered per request. The default, and the only mode that needs a live server.
+ */
+export type RenderMode = "static" | "isr" | "ssr";
+/** What a route needs from its host in order to behave as declared. */
+export type RouteCapability = "server" | "revalidation";
+/** One route's resolved behaviour. */
+export interface RouteManifestEntry {
+    /** The route's id (its key in the build manifest and in `routes`). */
+    readonly id: string;
+    /** The matching pattern, e.g. `/blog/:slug`. */
+    readonly pattern: string;
+    readonly mode: RenderMode;
+    /** Whether the full-document client is shipped. `false` means the page loads no framework JS. */
+    readonly hydrate: boolean;
+    /** Revalidation window in seconds. Present only for `isr`. */
+    readonly revalidate?: number;
+    /**
+     * Concrete paths prerendered at build. Present for `static` routes: a single path for a static route,
+     * one per `getStaticPaths` entry for a dynamic one. Absent means "no path was enumerated", which for a
+     * dynamic route is exactly the condition that makes it unprerenderable.
+     */
+    readonly prerenderedPaths?: readonly string[];
+    /** What this route needs from the host to behave as declared. */
+    readonly requires: readonly RouteCapability[];
+}
+/** A route whose declaration the chosen target cannot honour, and what actually happens if it ships. */
+export interface RouteManifestConflict {
+    readonly id: string;
+    readonly pattern: string;
+    readonly capability: RouteCapability;
+    /** What goes wrong on this target - the consequence, not the rule that was broken. */
+    readonly consequence: string;
+}
+/** The whole artifact: every route's behaviour, plus anything the target cannot honour. */
+export interface RouteManifest {
+    /** The deploy target this was resolved against, when one was given. */
+    readonly target?: string;
+    readonly routes: readonly RouteManifestEntry[];
+    readonly conflicts: readonly RouteManifestConflict[];
+    /** Route counts by mode - the summary a report leads with. */
+    readonly totals: Readonly<Record<RenderMode, number>>;
+}
+/**
+ * Derive one route's behaviour from its module exports.
+ *
+ * `prerender`/`getStaticPaths` win over `revalidate`: a page rendered at build time is not revalidated at
+ * runtime, so if a route declares both, the build-time answer is the one that describes what ships. That
+ * combination is worth surfacing rather than silently resolving, which is what `conflicts` is for once a
+ * target is known.
+ */
+export declare function deriveRouteEntry(id: string, pattern: string, module: Pick<RouteModule, "prerender" | "getStaticPaths" | "revalidate" | "hydrate">, prerenderedPaths?: readonly string[]): RouteManifestEntry;
+/**
+ * Build the route manifest for a discovered app, optionally resolved against a deploy target.
+ *
+ * `prerendered` maps a route id to the concrete paths the build actually emitted for it - pass what
+ * `prerenderRoutes` produced. Without it, dynamic routes are reported by their declaration alone, which
+ * is the right answer before a build has run and the wrong one after.
+ */
+export declare function buildRouteManifest(manifest: Manifest, options?: {
+    readonly target?: string;
+    readonly prerendered?: Readonly<Record<string, readonly string[]>>;
+    /** Runtime capabilities supplied outside generated entries (for example an explicit `withISR`). */
+    readonly capabilities?: readonly RouteCapability[];
+}): Promise<RouteManifest>;
+/** Render the manifest as a readable report - the `nifra routes --modes` output. */
+export declare function renderRouteManifest(manifest: RouteManifest): string;
+//# sourceMappingURL=route-manifest.d.ts.map

package/dist/route-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-manifest.d.ts","sourceRoot":"","sources":["../src/route-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAE1D;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,KAAK,GAAG,KAAK,CAAA;AAEjD,uEAAuE;AACvE,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,cAAc,CAAA;AAEvD,sCAAsC;AACtC,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,gDAAgD;IAChD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,iGAAiG;IACjG,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,8DAA8D;IAC9D,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC7C,iEAAiE;IACjE,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAA;CAC9C;AAED,wGAAwG;AACxG,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAA;IACpC,sFAAsF;IACtF,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAC7B;AAED,2FAA2F;AAC3F,MAAM,WAAW,aAAa;IAC5B,uEAAuE;IACvE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,MAAM,EAAE,SAAS,kBAAkB,EAAE,CAAA;IAC9C,QAAQ,CAAC,SAAS,EAAE,SAAS,qBAAqB,EAAE,CAAA;IACpD,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAA;CACtD;AAKD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,WAAW,GAAG,gBAAgB,GAAG,YAAY,GAAG,SAAS,CAAC,EACpF,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,GACnC,kBAAkB,CAyBpB;AA0BD;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,QAAQ,EAClB,OAAO,GAAE;IACP,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAA;IAClE,mGAAmG;IACnG,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,eAAe,EAAE,CAAA;CAC9C,GACL,OAAO,CAAC,aAAa,CAAC,CAuCxB;AAED,oFAAoF;AACpF,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,CA2CnE"}

package/dist/route-manifest.js

@@ -0,0 +1,128 @@
+/** A route is dynamic when its pattern carries a param or wildcard segment. */
+const isDynamic = (pattern) => /[:*]/.test(pattern);
+/**
+ * Derive one route's behaviour from its module exports.
+ *
+ * `prerender`/`getStaticPaths` win over `revalidate`: a page rendered at build time is not revalidated at
+ * runtime, so if a route declares both, the build-time answer is the one that describes what ships. That
+ * combination is worth surfacing rather than silently resolving, which is what `conflicts` is for once a
+ * target is known.
+ */
+export function deriveRouteEntry(id, pattern, module, prerenderedPaths) {
+    const wantsPrerender = module.prerender === true || module.getStaticPaths !== undefined;
+    // A dynamic route is only really static if concrete paths were enumerated for it. `getStaticPaths`
+    // declares the intent; the paths are the evidence, and without them there is nothing prerendered to
+    // serve. Treating intent as sufficient is how a "static" build ships a page that 404s.
+    const enumerated = prerenderedPaths !== undefined && prerenderedPaths.length > 0;
+    const isStatic = wantsPrerender && (!isDynamic(pattern) || enumerated);
+    const mode = isStatic ? "static" : module.revalidate !== undefined ? "isr" : "ssr";
+    const requires = [];
+    if (mode !== "static")
+        requires.push("server");
+    if (mode === "isr")
+        requires.push("revalidation");
+    const entry = { id, pattern, mode, hydrate: module.hydrate !== false, requires };
+    if (mode === "isr" && module.revalidate !== undefined)
+        entry.revalidate = module.revalidate;
+    if (prerenderedPaths !== undefined)
+        entry.prerenderedPaths = prerenderedPaths;
+    return entry;
+}
+/**
+ * What each deploy target can actually do.
+ *
+ * `static` is the one that matters: it has no server at all, so every non-prerendered route is a page
+ * that will 404 in production while working perfectly in dev. The rest all run a server; they differ in
+ * how revalidation is wired, not in whether it exists, so this deliberately does not invent finer
+ * distinctions it cannot verify.
+ */
+const TARGET_CAPABILITIES = {
+    bun: ["server"],
+    node: ["server"],
+    deno: ["server"],
+    "cf-pages": ["server"],
+    vercel: ["server"],
+    static: [],
+};
+const CONSEQUENCE = {
+    server: "this target ships no server, so the route is never rendered - the URL 404s in production while working in dev. Add `export const prerender = true` (or `getStaticPaths` for a dynamic route), or build for a target that runs a server.",
+    revalidation: "this target cannot revalidate a cached page, so `revalidate` has no effect and the route renders on every request.",
+};
+/**
+ * Build the route manifest for a discovered app, optionally resolved against a deploy target.
+ *
+ * `prerendered` maps a route id to the concrete paths the build actually emitted for it - pass what
+ * `prerenderRoutes` produced. Without it, dynamic routes are reported by their declaration alone, which
+ * is the right answer before a build has run and the wrong one after.
+ */
+export async function buildRouteManifest(manifest, options = {}) {
+    const entries = [];
+    for (const route of manifest.routes) {
+        // Loading the module is what makes this authoritative rather than a guess from the filename: the
+        // render mode lives in the module's exports and nowhere else.
+        const module = (await route.load());
+        entries.push(deriveRouteEntry(route.id, route.pattern, module, options.prerendered?.[route.id]));
+    }
+    entries.sort((a, b) => a.pattern.localeCompare(b.pattern));
+    const conflicts = [];
+    const capabilities = options.capabilities ??
+        (options.target === undefined ? undefined : TARGET_CAPABILITIES[options.target]);
+    if (capabilities !== undefined) {
+        for (const entry of entries) {
+            for (const capability of entry.requires) {
+                if (capabilities.includes(capability))
+                    continue;
+                conflicts.push({
+                    id: entry.id,
+                    pattern: entry.pattern,
+                    capability,
+                    consequence: CONSEQUENCE[capability],
+                });
+            }
+        }
+    }
+    const totals = { static: 0, isr: 0, ssr: 0 };
+    for (const entry of entries)
+        totals[entry.mode] += 1;
+    const result = { routes: entries, conflicts, totals };
+    if (options.target !== undefined)
+        result.target = options.target;
+    return result;
+}
+/** Render the manifest as a readable report - the `nifra routes --modes` output. */
+export function renderRouteManifest(manifest) {
+    const lines = [];
+    lines.push(manifest.target === undefined
+        ? "nifra route manifest"
+        : `nifra route manifest — target: ${manifest.target}`);
+    lines.push("");
+    if (manifest.routes.length === 0) {
+        lines.push("no routes found.");
+        return lines.join("\n");
+    }
+    const width = Math.max(10, ...manifest.routes.map((r) => r.pattern.length)) + 2;
+    lines.push(`${"route".padEnd(width)}${"mode".padEnd(9)}${"hydrate".padEnd(9)}cache`);
+    lines.push("-".repeat(width + 18 + 24));
+    for (const route of manifest.routes) {
+        const cache = route.mode === "isr"
+            ? `revalidate ${route.revalidate}s`
+            : route.mode === "static"
+                ? `prerendered${route.prerenderedPaths ? ` (${route.prerenderedPaths.length})` : ""}`
+                : "per request";
+        lines.push(route.pattern.padEnd(width) +
+            route.mode.padEnd(9) +
+            (route.hydrate ? "yes" : "no").padEnd(9) +
+            cache);
+    }
+    lines.push("");
+    lines.push(`${manifest.totals.static} static · ${manifest.totals.isr} isr · ${manifest.totals.ssr} ssr`);
+    if (manifest.conflicts.length > 0) {
+        lines.push("");
+        lines.push(`✗ ${manifest.conflicts.length} route(s) the target cannot honour:`);
+        for (const conflict of manifest.conflicts) {
+            lines.push(`  ✗ ${conflict.pattern} — ${conflict.consequence}`);
+        }
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=route-manifest.js.map

package/dist/route-manifest.js.map

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

package/dist/router.d.ts

@@ -22,6 +22,60 @@ export declare const REDIRECT_HEADER = "x-nifra-redirect";
  * the active one. The client validates each path against the manifest matcher before acting on it.
  */
 export declare const REVALIDATE_HEADER = "x-nifra-revalidate";
+/**
+ * Response header carrying a **terminal status** a loader signalled with `notFound()` / `gone()` /
+ * `statusPage(n)` during a client-side navigation's data fetch.
+ *
+ * A soft-nav fetches data, not a document, so the server cannot answer by rendering the `_404` page -
+ * it has only JSON to return. Without this channel the two halves disagree: a crawler doing a hard
+ * navigation gets a correct 404 page while a user who clicked a link gets an error or a blank screen.
+ * The client reads it and renders the same boundary the server would have.
+ *
+ * Carried in a header rather than the body so it survives the NDJSON deferred-data path unchanged,
+ * exactly like {@link REDIRECT_HEADER}.
+ */
+export declare const STATUS_HEADER = "x-nifra-status";
+/**
+ * Layout indices a client navigation is asking the server NOT to re-run, comma separated.
+ *
+ * The client owns the decision because it holds both the old and new match plus each layout's scoped
+ * params. The server treats it as a hint and refuses to skip a `gate` regardless - a guard that runs
+ * only when the client says so is not a guard.
+ */
+export declare const RETAIN_HEADER = "x-nifra-retain";
+/**
+ * The path a client navigation is coming FROM, sent on the data-mode GET.
+ *
+ * Lets the SERVER decide which layout loaders to skip: it already knows each layout's scoped params
+ * (derived at build time), so given both paths it can tell whether a layout's own prefix changed.
+ * Doing it server-side means the client never needs the scope table, and the decision lives next to
+ * the data it is about.
+ *
+ * Sent only when the client actually holds layout data to retain, so a request without it is simply
+ * the full-chain case.
+ */
+export declare const NAV_FROM_HEADER = "x-nifra-from";
+/**
+ * The data-mode payload once a chain can carry layout data.
+ *
+ * Versioned because a prerendered `_data.json` is a static file on a CDN and outlives the deploy that
+ * wrote it: a browser running new client code can be handed an envelope written by the previous
+ * build. The reader therefore accepts BOTH the bare pre-envelope value and this shape, and decides by
+ * structure rather than by assuming the deploy was atomic.
+ */
+export interface RouteDataEnvelope {
+    readonly v: 1;
+    readonly data: unknown;
+    readonly layoutData?: readonly unknown[];
+    /** Indices whose loader was SKIPPED because the layout's own params did not change. The client
+     * keeps its existing value at each of these, so an unchanged layout is neither refetched nor lost. */
+    readonly retained?: readonly number[];
+    /** Terminal status signalled by a loader. Added by the browser transport after reading
+     * `X-Nifra-Status`; old servers and static data files simply omit it. */
+    readonly status?: number;
+}
+/** Recognise the envelope without mistaking a plain loader object that happens to have a `data` key. */
+export declare function isRouteDataEnvelope(value: unknown): value is RouteDataEnvelope;
 /** A URL matched against the manifest patterns: which route + its extracted params. */
 export interface RouteMatch {
     readonly routeId: string;
@@ -41,6 +95,9 @@ export interface RouterState {
     /** The current URL path (used to revalidate the active loader after an action). */
     readonly path: string;
     readonly data: unknown;
+    /** Per-layout loader data, aligned with the matched chain's leading layout prefix. Absent when no
+     * layout in that chain has a loader. */
+    readonly layoutData?: readonly unknown[] | undefined;
     /** An action's data return after a client-side submit (cleared on navigation). */
     readonly actionData?: unknown;
     /** True while a navigation or submit is in flight (drives loading UI). */
@@ -64,7 +121,10 @@ export interface RoutePattern {
 export declare function createMatcher(patterns: readonly RoutePattern[]): (path: string) => RouteMatch | null;
 /** How a router fetches a route's loader data on navigation. `signal` aborts a superseded fetch
  * (and its deferred stream). */
-export type FetchRouteData = (path: string, match: RouteMatch, signal?: AbortSignal) => Promise<unknown>;
+export type FetchRouteData = (path: string, match: RouteMatch, signal?: AbortSignal, navigation?: {
+    readonly from: string;
+    readonly retain: readonly number[];
+}) => Promise<unknown>;
 /** Per-submit options. `revalidate: false` opts out of the post-action loader re-fetch. */
 export interface SubmitOptions {
     /** Re-run the active route's loader after the action settles (default `true`). Set `false` to
@@ -154,6 +214,9 @@ export interface ClientRouterOptions {
     /** Ensure a route's code chunk is loaded before rendering (code-splitting). Awaited in parallel
      * with the loader data, so `pending` covers both. Omit when the bundle isn't split. */
     readonly loadModule?: (routeId: string) => Promise<void>;
+    /** Terminal status → client route id. Generated entries populate this from `_404` and
+     * `_<status>` files so soft navigation renders the same boundary as a hard request. */
+    readonly statusRoutes?: Readonly<Record<number, string>>;
 }
 /** Options for a per-adapter `mountRouter` (the Router binding that hydrates + re-renders). */
 export interface MountRouterOptions {

package/dist/router.d.ts.map

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