@nifrajs/web 3.3.0 → 4.0.0

package/dist/internal/web-app.d.ts

@@ -1,6 +1,11 @@
+import type { MountableApp } from "@nifrajs/core/server";
 import { type ServerOptions, server } from "@nifrajs/core/server";
+import { type CspPolicy } from "../csp.js";
+import type { CssLoadingMode } from "../css-contract.js";
 import type { Manifest } from "../manifest.js";
 import type { RenderAdapter } from "../render-seam.js";
+import { type NonceResolver } from "./page-execution.js";
+export type { NonceResolver } from "./page-execution.js";
 export interface CreateWebAppOptions<Env = unknown> {
     readonly adapter: RenderAdapter;
     readonly manifest: Manifest;
@@ -8,6 +13,21 @@ export interface CreateWebAppOptions<Env = unknown> {
     readonly clientEntry: string;
     /** Default document title for all pages. */
     readonly title?: string;
+    /**
+     * Resolve a fresh CSP nonce for each document request. The value is applied to every
+     * framework-owned executable script; return `undefined` to keep the default nonce-free output.
+     * Nonce-bearing documents are marked `private, no-store` so the request-specific value is not
+     * replayed by browser, CDN, or ISR caches. The resolver does not declare a CSP header because the
+     * policy's allowed sources are app-specific.
+     */
+    readonly nonce?: NonceResolver<Env>;
+    /**
+     * A hash-based Content-Security-Policy from `createCspPolicy`, instead of `nonce`. A document then
+     * carries a nonce only when it needs one (it `defer()`s a value, or `meta` names the nonce in
+     * `unsafeInlineScript`); every other page is nonce-free, gets the same CSP header on every request,
+     * and stays cacheable by `withISR` or a CDN. `meta` still receives a nonce to name.
+     */
+    readonly csp?: CspPolicy;
     /**
      * Options for the underlying `server()` - `requestTimeoutMs`, `admission`, `gracefulSignals`, and
      * the rest of {@link ServerOptions}.
@@ -69,14 +89,26 @@ export interface CreateWebAppOptions<Env = unknown> {
      * mount interface from `@nifrajs/core/mount`; `createWebApp` also serves that backend over HTTP at
      * {@link apiPrefix} (default `/api`): a request whose pathname starts with the prefix is dispatched
      * before page routing with the same `env`/`waitUntil` platform context, and the backend's `Response`
-     * is returned untouched. The mount runs in `nifra dev` too. Pass `apiPrefix: ""` to disable it. */
+     * is returned untouched. The mount runs in `nifra dev` too. Pass `apiPrefix: ""` to disable it.
+     *
+     * **Request-scoped loader calls.** While a page renders, its loaders, actions and boundaries get a
+     * `ctx.api` bound to that request's platform identity: a backend handler reached through it sees the
+     * visitor's `c.clientIp` (derived under this app's `server.clientIp` trust declaration), `c.env` and
+     * `c.waitUntil`, so a per-caller rate limit or audit field keys on the real visitor. `c.clientIp` is
+     * the supported way to read the caller - identity travels in the platform, so rebuilding a `Request`
+     * does not lose it. Headers do NOT travel: the page request's `cookie` and `authorization` are never
+     * copied, so a loader call is anonymous unless the loader passes headers on the call itself. */
     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` does not expose the symbol mount. */
+     * is also a no-op when `api` does not expose the symbol mount.
+     *
+     * A page file under the prefix (`routes/api/report.tsx`) could never render - the backend answers
+     * first and its 404 is final - so `createWebApp` throws, naming the file. The same holds for every
+     * other pre-route mount. */
     readonly apiPrefix?: string;
     /**
      * Strip {@link apiPrefix} from the pathname before dispatching to `api` (default `false`).
@@ -98,14 +130,16 @@ export interface CreateWebAppOptions<Env = unknown> {
      *
      * Tried longest-path-first and BEFORE the `api` mount, so a mount at `/api/auth` wins over a backend
      * at `/api` no matter which was declared first. `stripPrefix` is the per-mount form of {@link apiStrip}:
-     * leave it off to pass the full path through.
+     * leave it off to pass the full path through. `opaque` states why a mount whose routes nifra cannot
+     * read (better-auth's handler) is outside assurance; it is then listed as a known gap.
      */
     readonly mounts?: ReadonlyArray<{
         readonly path: string;
-        readonly app: {
-            fetch(request: Request): Response | Promise<Response>;
-        };
+        readonly app: MountableApp<Env>;
         readonly stripPrefix?: boolean;
+        readonly priority?: number;
+        readonly fallbackOn?: 404;
+        readonly opaque?: 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`).
@@ -124,15 +158,27 @@ export interface CreateWebAppOptions<Env = unknown> {
      * of the aggregate `styles`, so a page ships only the CSS it uses. An empty array ⇒ no `<link>` (the
      * page imports no CSS). Routes absent here fall back to `styles`. Omit ⇒ always use `styles`. */
     readonly routeStyles?: Readonly<Record<string, readonly string[]>>;
+    /**
+     * Activation policy for framework-owned stylesheet links (default `"blocking"`). `"deferred"`
+     * emits `media="print"` links; the generated client waits for them and switches them to `all` before
+     * mounting. Pair with an aggregate Vite stylesheet (`cssCodeSplit: false`) to prevent lazy-prefetch
+     * CSS insertion. Non-hydrated pages always keep their stylesheet links blocking.
+     */
+    readonly cssLoading?: CssLoadingMode;
     /** SSG: the prerendered-path set (e.g. `enumerateStaticRoutes(routes).paths` or the build's
-     * `prerendered.json`). Injected as `window.__NIFRA_PRERENDERED__` on every page so a client soft-nav
-     * into a prerendered route fetches its static `_data.json` instead of hitting the worker. */
+     * `prerendered.json`). Handed over as `window.__NIFRA_PRERENDERED__` on every page so a client soft-nav
+     * into a prerendered route fetches its static `_data.json` instead of hitting the worker. A set over
+     * 4 KB of JSON is served once from `/__nifra/prerendered.json?v=<version>`, cacheable for good, and
+     * pages hand over only that URL; `prerenderRoutes` writes the file into a static output. */
     readonly prerenderedPaths?: readonly string[];
     /** Publish the project's `AGENTS.md` inside `/llms.txt` and `/llms-full.txt`. **Off by default**:
      * those endpoints are public and unauthenticated, while `AGENTS.md` is a repo file written for the
      * team - unreleased feature names, internal hostnames, and "don't touch X yet" notes live there
      * routinely. Turn it on only for a repo whose guidelines you would publish as a page. */
     readonly publishLocalGuidelines?: boolean;
+    /** Serve `/llms.txt` and `/llms-full.txt` (default `true`): the page routes, and the backend routes
+     * when the backend is mounted over HTTP at {@link apiPrefix}. `false` registers neither path. */
+    readonly llmsTxt?: boolean;
     /** SSG: per dynamic route pattern, its `getStaticPaths` `fallback` (from `enumerateStaticRoutes` or
      * the build's `prerendered.json`). A route mapped to `"404"` rejects any path NOT in
      * `prerenderedPaths` with the 404 page - the unlisted path simply doesn't exist. `"ssr"` (the
@@ -168,4 +214,6 @@ export interface CreateWebAppOptions<Env = unknown> {
  * secure default; validate at the trust boundary before use.
  */
 export declare function createWebApp<Env = unknown>(options: CreateWebAppOptions<Env>): ReturnType<typeof server<Env>>;
+/** Resolve one composed, token-only evidence snapshot for a web app and its mounted surfaces. */
+export declare function webProjectEvidence(source: unknown): Promise<import("@nifrajs/core/evidence").ProjectEvidenceSnapshot>;
 //# sourceMappingURL=web-app.d.ts.map

package/dist/internal/web-app.d.ts.map

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