@nifrajs/web 3.1.0 → 3.2.0

package/dist/index.d.ts

@@ -7,618 +7,15 @@
  * 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 ResponseResult, type ServerOptions, server } from "@nifrajs/core/server";
-import { type BoundaryStates } from "./boundary.js";
-import { type Deferred, defer } from "./deferred.js";
-import { mergeHeads, resolveMeta } from "./internal/head-merge.js";
-import type { LinkDescriptor, Manifest, Meta, MetaDescriptor, ScriptDescriptor, UnsafeScriptDescriptor } from "./manifest.js";
-import type { RenderAdapter } from "./render-seam.js";
 export { assertStaticBoundaryImports, type Boundary, type BoundaryDescriptor, type BoundaryError, type BoundaryMode, type BoundaryRegistration, type BoundaryRequestCtx, type BoundaryState, type BoundaryStates, type BoundaryStatus, boundaryDescriptors, boundaryModeKey, type DynamicBoundary, type DynamicBoundaryBatch, type InterceptBoundary, MemoryStaticBoundaryCache, type PendingBoundary, resolveDynamicBoundaries, resolveStaticBoundaries, type StaticBoundary, type StaticBoundaryCache, type StaticBoundaryImportEdge, type StaticBoundaryRoot, type StaticCtx, startDynamicBoundaries, } from "./boundary.js";
+export { assertRenderAdapterConformance, RenderAdapterConformanceError, type RenderAdapterConformanceFixture, } from "./conformance.js";
+export { type Deferred, defer } from "./deferred.js";
 export { DRAFT_COOKIE, type DraftCookieControls, disableDraft, type EnableDraftOptions, enableDraft, isDraftEnabled, type PreviewEndpointOptions, previewEndpoint, } 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_REVALIDATE_TAGS_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, type ClientAction, type ClientActionArgs, type ClientActionResult, type ClientLoader, type ClientLoaderArgs, type ClientRequestBody, type ClientRouteHooks, enumerateStaticRoutes, filePathToPattern, filePathToPatterns, type GetStaticPaths, type InertScriptType, type LayoutEntry, type LinkDescriptor, type Loader, type LoaderContext, type Manifest, type Meta, type MetaArgs, type MetaDescriptor, type MetaInput, type RouteEntry, type RouteModule, type ScriptDescriptor, type StaticPath, type StaticPaths, type StaticRoutes, type UnsafeScriptDescriptor, } from "./manifest.js";
-export { type Blocker, type BlockerController, type BlockerFunction, type BlockerLocation, type BlockerState, type BrowserNavigate, getBrowserNavigate, IDLE_BLOCKER, type NavigateFunction, type NavigateOptions, type NavigateSearchOf, type NavigateTargetInput, type RouteSearch, registerBlocker, resolveNavigate, setBlockerController, setBrowserNavigate, } from "./navigation.js";
-export { type PublicDirCache, resolvePublicPath, type ServePublicDirOptions, servePublicDir, } from "./public-dir.js";
-export { createMutation, createQueryClient, type DehydratedState, hashQueryKey, type InfiniteData, type InfiniteQueryHandle, type InfiniteQueryOptions, type MutationCallbacks, type MutationHandle, type MutationState, type MutationStatus, type QueryClient, type QueryClientOptions, type QueryHandle, type QueryOptions, type QueryState, type QueryStatus, } from "./query.js";
-export { type ClientRouter, type ClientRouterOptions, createClientRouter, createMatcher, DATA_HEADER, type Fetcher, type FetcherState, type FetchRouteData, type MountRouterOptions, NAV_FROM_HEADER, REDIRECT_HEADER, RETAIN_HEADER, REVALIDATE_HEADER, type RouteMatch, type RoutePattern, type RouterState, STATUS_HEADER, type Submission, type SubmitOptions, } from "./router.js";
-export { type Deferred, defer, mergeHeads, resolveMeta };
-/** 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;
-};
-export { assertRenderAdapterConformance, RenderAdapterConformanceError, type RenderAdapterConformanceFixture, } from "./conformance.js";
-export { ACTION_GLOBAL, BOUNDARY_GLOBAL, DATA_GLOBAL, LAYOUT_DATA_GLOBAL, type RenderAdapter, type RenderProps, ROOT_ATTRIBUTE, ROUTE_GLOBAL, type SsrModuleLoader, setSsrModuleLoader, ssrModuleLoader, } from "./render-seam.js";
-export { type SearchOf, searchOf, searchOfChain, serializeSearch } from "./search.js";
-/**
- * Pre-hydration form guard - a tiny inline script flushed in `<head>` (it runs in the window between
- * first paint and the island bundle taking over). It neutralizes the one real hydration footgun: a
- * JS-only form (a hand-wired `onSubmit` with no native fallback) submitting *natively* before its
- * handler is attached, which navigates the browser to a broken `?field=…` GET of the current page.
- *
- * It blocks ONLY that shape - an effective-GET form whose action targets the current document - and
- * only until hydration commits (`data-nifra-hydrated`, set by the client entry). Method-`post` forms
- * (progressive enhancement: the native POST hits the route `action`) and GET forms with a real action
- * (a search box → `/search`) pass through untouched. Opt out per-form with `data-native`. Static text
- * (no interpolation), so it can't carry injected markup. See the Hydration guide.
- */
-export declare const PRE_HYDRATION_GUARD: string;
-/**
- * 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 {
-    readonly [RESPONSE_RESULT]: true;
-    toResponse(): Response;
-    toNodeBody?(): {
-        readonly status: number;
-        readonly headers: Readonly<Record<string, string | readonly string[]>> | undefined;
-        readonly body: string | Uint8Array;
-    };
-}
-export interface RenderPageOptions {
-    readonly adapter: RenderAdapter;
-    /** The layout chain to render - outermost layout → page (opaque; the adapter renders it). */
-    readonly chain: readonly unknown[];
-    /** The loader output for this request. */
-    readonly data: unknown;
-    /** An action's data return (POST only) - surfaced to the page as `actionData` + serialized
-     * for the client so post-POST hydration matches. Omit on GETs. */
-    readonly actionData?: unknown;
-    /**
-     * URL of the built client entry (loaded as a module script).
-     *
-     * Optional ONLY on a `hydrate: false` page, where there is no client takeover to feed and this value
-     * reaches no output at all. The union below is what enforces that: omitting it on a hydrating page
-     * stays a compile error rather than rendering `src=""`.
-     */
-    readonly clientEntry?: string;
-    /** Chunk URLs for the **matched** route (its layout chain + own chunk) to `modulepreload` in the
-     * shell - so the route code downloads in parallel with the entry instead of after it
-     * (`buildClient`'s per-route map). Empty/omitted ⇒ only the entry is preloaded (unchanged). */
-    readonly preload?: readonly string[];
-    /** Stylesheet URLs for the **matched** route (its layout chain + own CSS, from `buildClient`'s
-     * `BuildManifest.css`) - injected as `<link rel="stylesheet">` in `<head>` so styles arrive with the
-     * first paint (no FOUC). Rendered even on non-hydrated pages. Empty/omitted ⇒ none (unchanged). */
-    readonly styles?: readonly string[];
-    /** SSG: the prerendered-path set, serialized to `window.__NIFRA_PRERENDERED__` so the client fetches
-     * a static `_data.json` on soft-nav into a prerendered route. Empty/omitted ⇒ not injected. */
-    readonly prerenderedPaths?: readonly string[];
-    /** ISR: route freshness in seconds, emitted as the `x-nifra-isr-revalidate` header for a `withISR`
-     * wrapper to read. Omit ⇒ no header (the wrapper's default TTL applies). */
-    readonly revalidate?: number;
-    /** ISR invalidation tags emitted as a bounded `x-nifra-isr-tags` header. */
-    readonly revalidateTags?: readonly string[];
-    /** Matched route id; written to `window.__NIFRA_ROUTE__` so the client hydrates this chain. */
-    readonly routeId?: string;
-    /** The matched route's decoded path params - surfaced to the page as `params` (via {@link RenderProps})
-     * so an adapter's `useParams` is SSR-correct. Omit ⇒ `{}` (a route with no dynamic segments, or an
-     * error/404 render). */
-    readonly params?: Readonly<Record<string, string>>;
-    /** The request's `pathname + search` - surfaced as `path` (via {@link RenderProps}) so an adapter's
-     * `useLocation`/`useSearchParams` render the right URL server-side and hydrate without drift. Omit ⇒
-     * `""`. */
-    readonly path?: string;
-    /** The route's validated search (`searchOf(mod.searchSchema, url.search)`, the same value handed to
-     * the loader as `ctx.search`), surfaced as `search` (via {@link RenderProps}) so an adapter's
-     * `useSearch` is SSR-correct. Omit ⇒ `{}` (a render with no search context). */
-    readonly search?: Record<string, unknown>;
-    /** Per-layout loader data, forwarded to the adapter as `RenderProps.layoutData`. Aligned with the
-     * chain's layout prefix; omitted when no layout in the chain has a loader. */
-    readonly layoutData?: readonly unknown[];
-    /** Dynamic-boundary states, forwarded to the adapter and serialized for hydration when present. */
-    readonly boundaries?: BoundaryStates;
-    /** HTTP status for the response (default 200; e.g. 404 for a not-found page). */
-    readonly status?: number;
-    /** Extra response headers - e.g. the `cache-control` a terminal status page wants. `content-type`
-     * is ignored (the document is always HTML) and the ISR freshness header is applied after these,
-     * so neither can be overridden from here. */
-    readonly headers?: HeadersLike;
-    /** 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.
-     *
-     * **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). `<meta>`/`<link>` attributes pass a
-     * shared tag-specific allowlist (including inert `data-*` metadata) and values are escaped. */
-    readonly head?: Meta;
-    /** Id of the container wrapping the app markup (default `"root"`). A non-default id also gets
-     * {@link ROOT_ATTRIBUTE}, which is how the generated client entry finds the container to hydrate -
-     * the entry is built once and cannot know what a given render chose. */
-    readonly rootId?: string;
-    /** When `false`, emit a complete but **non-hydrated** document - no client entry script, data
-     * globals, or modulepreloads. Used for server-rendered `_error` pages: a terminal state that needs no
-     * client takeover, and it sidesteps an SSR/hydrate mismatch (the server rendered the boundary, not
-     * the page the client manifest maps this route id to). Default `true`. */
-    readonly hydrate?: boolean;
-    /** Island client bundles (`@nifrajs/web/islands`) to load as `<script type="module">` in the document
-     * tail - emitted **regardless of `hydrate`**, so a static (`hydrate: false`) page can still mount
-     * no-framework islands. URLs are attribute-escaped. Empty/omitted ⇒ none (unchanged output). */
-    readonly islandScripts?: readonly string[];
-    /** CSP nonce applied to every framework-owned executable script in this document. */
-    readonly nonce?: string;
-    /**
-     * Advanced: a per-route slot the renderer fills with the request-invariant document pieces (shell
-     * prefix/suffix, tail statics) on the first render and reuses afterwards, skipping their re-assembly.
-     *
-     * Only pass a cache when every shell-shaping input is IDENTICAL across the requests sharing it:
-     * same `head` content (a static meta chain - never a `meta(data)` function), `title`, `styles`,
-     * `preload`, `islandScripts`, `clientEntry`, `rootId`, `hydrate`, and `prerenderedPaths`. Per-request
-     * values (`data`, `params`, `search`, `actionData`, `layoutData`, deferred state) are always assembled
-     * fresh and safe. A per-request `nonce` disables the cache automatically. `createWebApp` wires this
-     * per route, gated on the route + layout metas being static.
-     */
-    readonly assemblyCache?: RenderAssemblyCache;
-}
-/** The mutable per-route slot {@link RenderPageOptions.assemblyCache} fills. Opaque - create as `{}`. */
-export interface RenderAssemblyCache {
-    /** Shell up to (not including) the deferred-runtime insertion point. */
-    shellPre?: string;
-    /** Shell from after the deferred-runtime insertion point through the open `#root` container. */
-    shellPost?: string;
-    /** Tail opener: the inline script open tag + the route-id global (before the action global). */
-    tailPre?: string;
-    /** Tail mid: the prerendered-paths global (between the action and layout-data globals). */
-    tailMid?: string;
-    /** Tail data prefix: the `window.<data global>=` assignment head. */
-    tailData?: string;
-    /** Tail from after the serialized data through `</html>`. */
-    tailPost?: string;
-}
-/**
- * `renderPage` input. A hydrating page (the default) must supply `clientEntry`, because the document
- * loads it as a module script; a `hydrate: false` page may omit it, because nothing in the emitted
- * document references it. Expressed as a union so the compiler enforces the pairing rather than the
- * renderer discovering an empty `src` at runtime.
- */
-export type RenderPageInput = RenderPageOptions & ({
-    readonly hydrate?: true;
-    readonly clientEntry: string;
-} | {
-    readonly hydrate: false;
-});
-/**
- * Server: render a full HTML document for a page - the adapter's hydration head + the SSR
- * markup (**streamed**) + the serialized loader data + the client module - as a `Response`.
- * The shell (`<head>` + the open container) flushes first, the adapter's app stream follows,
- * then the tail (data globals + client entry). Pure Web Standards, so it returns straight from
- * a nifra route handler and streams on any fetch runtime (Bun/Node/Deno/Workers).
- */
-export declare function renderPage(options: RenderPageInput): MaybePromise<Response>;
-export declare function renderPageResult(options: RenderPageInput): MaybePromise<RenderedPage>;
-/** Options for {@link redirect}. */
-export interface RedirectOptions {
-    /** HTTP status (default 303 See Other; pass 307/308 to preserve the method). */
-    readonly status?: number;
-    /** Allow an off-origin / absolute destination. Off by default: only a same-origin path (a single
-     * leading `/`) is permitted, so an action can't be turned into an open redirect by passing
-     * attacker-controlled input straight through. Set `true` for a deliberate external redirect. */
-    readonly external?: boolean;
-    /** Extra response headers. A redirect is no longer a `Response`, so there is no `.headers` to
-     * mutate after the fact - name them here. Cookies still ride `c.set`, as on any other response. */
-    readonly headers?: Readonly<Record<string, string>>;
-}
-/** A same-origin destination is an absolute path: one leading `/`, but NOT `//` (protocol-relative →
- * another origin), and nothing a URL parser resolves off-origin. Everything else (absolute URL with
- * a scheme, `//host`, `javascript:`, a bare relative `foo`) requires `external: true`. The predicate
- * lives in the kernel - see `isSameOriginPath` - so this gate and the auth guards' `redirectTo`
- * cannot drift apart. */
-/**
- * Build a redirect - return it from a route `action` for the Post/Redirect/Get pattern (POST
- * mutates, 303 sends the browser to a fresh GET, so a reload doesn't re-submit). Defaults to 303
- * (See Other); pass `{ status: 307 }` or `{ status: 308 }` to preserve the method.
- *
- * **Secure by default:** `location` must be a same-origin path (begins with `/`, not `//`). An
- * off-origin/absolute destination throws unless you pass `{ external: true }` - this closes the
- * open-redirect footgun of `return redirect(formData.get("next"))` on the no-JS (native-form) path,
- * which serves the action's control-flow value verbatim.
- *
- * Returns a plain render, not a `Response`. A redirect is a status line and one header - the most
- * body-less response there is - and building a `Response` for it costs the whole Web object plus, on
- * Node, a stream drained back out. As data it renders on the same lane a handler's return takes.
- * `redirect(...)` is still returned or thrown from exactly the same places; only `.status` /
- * `.headers` are gone from the value, replaced by `options.headers` and the request's `c.set`.
- *
- * @param options redirect status, extra headers, and whether an off-origin destination is intentional.
- */
-export declare function redirect(location: string, options?: RedirectOptions): ResponseResult;
-/**
- * Brand marking a `Response` as a **terminal-status signal** rather than a response to serve verbatim.
- *
- * A loader that throws a bare `Response` has always been passed straight through - that is how
- * `throw redirect(...)` works, and apps rely on it. So "render the `_404` boundary at 404" cannot be
- * expressed by throwing a plain `Response`: the framework would have no way to tell it apart from a
- * hand-rolled body the app wants served exactly as written. The brand is that distinction, and
- * checking it *before* the pass-through is what keeps every existing throw working unchanged.
- *
- * `Symbol.for` matches `RESPONSE_RESULT` above: a registry symbol survives two copies of this module,
- * which a `unique symbol` would not - and a duplicate-install turning a 404 into a raw 404 body would
- * be a maddening bug to trace.
- */
-/** Derived from the `Headers` constructor rather than the DOM lib's `HeadersInit`: `@nifrajs/web`
- * is consumed from DOM-free programs (the root tsconfig runs `types: ["bun"]`), and naming the DOM
- * type here would break their build. Same workaround as `SSEInit.headers` in core. */
-type HeadersLike = ConstructorParameters<typeof Headers>[0];
-/** Options shared by {@link notFound}, {@link gone}, and {@link statusPage}. */
-export interface StatusPageOptions {
-    /**
-     * Extra headers for the rendered response - `cache-control` above all.
-     *
-     * The defaults differ by status for a reason: a 404 may be a race with publication, so it wants a
-     * short TTL, while a 410 is a promise that the URL is permanently gone and can be cached hard.
-     * Getting this wrong is the difference between a crawler dropping a dead URL and re-fetching it
-     * for weeks.
-     */
-    readonly headers?: HeadersLike;
-}
-/**
- * Render the nearest `_404` page at status **404**. `throw` it from a loader when the record does not
- * exist.
- *
- * This is the fix for the soft 404: a matched route whose loader finds nothing has otherwise no way to
- * answer 404, so the path of least resistance is to return empty data and render "not found" inside a
- * **200**. That looks correct in a browser and is invisible in review, which is why it ships and stays
- * shipped - while search engines penalise it and keep the dead URL indexed.
- *
- * Returns `never`: these throw, so a loader narrows without a redundant `return`, and the type states
- * the thing the "loaders `throw` redirect, actions `return` it" rule already trips people on.
- */
-export declare function notFound(options?: StatusPageOptions): never;
-/**
- * Render a terminal page at status **410 Gone**. `throw` it from a loader for a record that existed and
- * was deliberately removed - a withdrawn listing, a deleted post.
- *
- * 410 is not a pedantic 404: it tells a crawler to **drop** the URL rather than re-fetch it for weeks
- * on the assumption the 404 was transient. Uses `_410.tsx` if the app has one, otherwise `_404`.
- */
-export declare function gone(options?: StatusPageOptions): never;
-/**
- * Render a terminal page at any 4xx/5xx status - the escape hatch behind {@link notFound} and
- * {@link gone} (402, 451, …). Uses `_<status>.tsx` if present, otherwise `_404`.
- */
-export declare function statusPage(status: number, options?: StatusPageOptions): never;
-/** The wrapper `revalidate()` returns: the action's `data` plus the paths it changed. A plain tagged
- * shape (not a class) so `@nifrajs/client`'s `ActionData` can unwrap it structurally without importing
- * from `@nifrajs/web`. `createWebApp` strips the wrapper - the client receives `data` as the body and
- * the paths via the `X-Nifra-Revalidate` header. */
-export interface RevalidateResult<T> {
-    readonly __nifraRevalidate: readonly string[];
-    readonly data: T;
-}
-/**
- * Return this from an action to declare which routes the mutation changed (alongside the action's
- * `data`). `createWebApp` sets the `X-Nifra-Revalidate` response header; after the submit the client
- * marks those cached routes stale - refetching the active one and any mounted fetcher showing them -
- * so a mutation can refresh views beyond the one that was submitted. `data` is still surfaced to the
- * component as `actionData` (the wrapper is transparent to `ActionData<typeof action>`).
- */
-export declare function revalidate<T>(paths: readonly string[], data: T): RevalidateResult<T>;
-/**
- * Serialize loader data for embedding inside an inline `<script>`. `JSON.stringify` alone
- * is NOT safe there: a string containing `</script>` or `<!--` would break out of the
- * script element (an XSS vector). Escape `<`/`>` to `\uXXXX`, plus the U+2028/U+2029
- * separators.
- */
-export declare function serializeData(data: unknown): string;
-/**
- * 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): MetaDescriptor[];
-/**
- * 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;
-/**
- * Deliberately unsafe escape hatch for executable inline code. The required nonce keeps the result
- * compatible with a strict CSP and makes the security-sensitive choice visible at the call site.
- */
-export declare function unsafeInlineScript(content: string, options: {
-    readonly nonce: string;
-    readonly type?: "module" | "text/javascript";
-}): UnsafeScriptDescriptor;
-export interface CreateWebAppOptions<Env = unknown> {
-    readonly adapter: RenderAdapter;
-    readonly manifest: Manifest;
-    /** URL of the built client entry (module script) injected into every page. */
-    readonly clientEntry: string;
-    /** Default document title for all pages. */
-    readonly title?: string;
-    /**
-     * Options for the underlying `server()` - `requestTimeoutMs`, `admission`, `gracefulSignals`, and
-     * the rest of {@link ServerOptions}.
-     *
-     * Needed because the `Server` is constructed in here, so a caller has no other way to reach its
-     * constructor: a page app could set no request timeout and no capacity gate, which are exactly the
-     * two knobs a production readiness check looks for. An SSR app wants them MORE than a backend does -
-     * a render is slow and allocation-heavy, so a burst that a JSON API would absorb is the one that
-     * exhausts the pod.
-     *
-     * Applies to the whole app, {@link mounts} and the {@link api} auto-mount included: the capacity gate
-     * sits at the fetch entry, ahead of the request hooks those are dispatched from.
-     */
-    readonly server?: ServerOptions;
-    /**
-     * Runs against the app BEFORE any page route is registered - the seam for `securityHeaders()`,
-     * `requestId()`, `logger()`, a rate limit, or anything else applied with `use`.
-     *
-     * ```ts
-     * createWebApp({
-     *   …,
-     *   use: (app) => {
-     *     app.use(securityHeaders())
-     *     app.use(requestId())
-     *   },
-     * })
-     * ```
-     *
-     * A callback rather than an array because `use` is overloaded - `Middleware`, `IdentityPlugin`,
-     * `ContextPlugin` - and only the real call site instantiates the right overload. The return value
-     * is ignored: this is for cross-cutting concerns, not for declaring routes (declare those on the
-     * returned app, where they get their types).
-     *
-     * **Why the timing matters.** `beforeHandle`, `afterHandle`, `around`, `derive`/`decorate`, and
-     * `onError` are snapshotted into each route AS IT IS DECLARED, and `createWebApp` declares every
-     * page (plus the `/*` catch-all) before it returns - so a caller's `app.use(…)` afterwards binds
-     * them to nothing, silently. `requestId()` is exactly that case: it is a `derive`, so applied late
-     * it leaves every page without `c.requestId`. Route assurance evidence is order-scoped the same
-     * way, so a late `securityHeaders()` leaves the pages unable to PROVE the header to `nifra assure`
-     * even though it does still set it.
-     *
-     * `onRequest`/`onResponse` (and the response header/body hooks) are app-global arrays read at
-     * request time, so those alone DO work when added late. Using this seam for everything avoids
-     * having to remember which is which.
-     *
-     * Runs ahead of the {@link mounts} / {@link api} request hooks, so an `onRequest` middleware guards
-     * a mounted auth handler too.
-     *
-     * A `ContextPlugin` applied here takes runtime effect but cannot widen the declared return type of
-     * this function, so `c.requestId` is not typed on routes you declare afterwards. Named plugins are
-     * idempotent, so `app.use(requestId())` on the returned app recovers the TYPE without applying the
-     * plugin a second time.
-     */
-    readonly use?: (app: ReturnType<typeof server<Env>>) => void;
-    /** Injected into each loader's `ctx.api` - typically an `inProcessClient(app)` (typed
-     * per-route via `@nifrajs/client`'s `createRoutes`). Opaque to the core.
-     *
-     * **Auto-mount.** Every `inProcessClient(backend)` exposes the symbol-keyed platform-aware backend
-     * 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. */
-    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. */
-    readonly apiPrefix?: string;
-    /**
-     * Strip {@link apiPrefix} from the pathname before dispatching to `api` (default `false`).
-     *
-     * The default suits a backend that declares FULL paths (`server().post("/api/sync", …)`), which is
-     * right when it is only ever mounted here. Set this when the backend declares its routes WITHOUT the
-     * prefix because it also runs standalone behind its own shell, so its paths cannot carry a prefix that
-     * only exists when it is mounted. Without it every request 404s inside the backend, and the workaround
-     * is a `Proxy` that rewrites each URL.
-     */
-    readonly apiStrip?: boolean;
-    /**
-     * Sub-apps mounted ahead of page routing - an auth handler, a webhook receiver, a stack's routes.
-     *
-     * Structural on purpose: anything with `{ path, app: { fetch } }` fits, so a library that exposes its
-     * routes as such a list mounts as `mounts: theirRoutes` without `@nifrajs/web` taking a dependency on
-     * it. `better-auth` is the motivating case - it is not a `backend` route, so `/api/auth/*` used to 404
-     * silently.
-     *
-     * 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.
-     */
-    readonly mounts?: ReadonlyArray<{
-        readonly path: string;
-        readonly app: {
-            fetch(request: Request): Response | Promise<Response>;
-        };
-        readonly stripPrefix?: boolean;
-    }>;
-    /** 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. */
-    readonly draftSecret?: string;
-    /** Per-route chunk URLs (`buildClient`'s `BuildManifest.routes`) - `routeId → [layout chunks…, own
-     * chunk]`. When present, each page `modulepreload`s its matched route's chunks alongside the entry,
-     * so the route code downloads in parallel (no entry→route-chunk waterfall). Omit ⇒ entry-only. */
-    readonly routePreload?: Readonly<Record<string, readonly string[]>>;
-    /** The app's bundled stylesheet URLs (`buildClient`'s `BuildManifest.css`) - the aggregate, injected
-     * as `<link rel="stylesheet">` in a page's `<head>`. Used as the fallback for any route absent from
-     * {@link routeStyles}. Omit ⇒ no links (dev, where Vite injects CSS, or a CSS-free app). */
-    readonly styles?: readonly string[];
-    /** Per-route stylesheet URLs (`buildClient`'s `BuildManifest.routeStyles`) - `routeId → [chain CSS]`.
-     * When a matched route has an entry here, only those (its layout chain + own CSS) are linked instead
-     * 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[]>>;
-    /** 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. */
-    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;
-    /** 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
-     * default for unmapped routes) renders unlisted paths on-demand. */
-    readonly staticFallbacks?: Readonly<Record<string, "ssr" | "404">>;
-    /** In-memory reference cache for explicitly `static` boundary values. It never persists payloads
-     * across processes; operated/durable cache implementations stay outside the public framework. */
-    readonly staticBoundaryCache?: import("./boundary.js").StaticBoundaryCache;
-    /** Observe every loader/action failure - for error-reporting plugins (Sentry-style). Called for
-     * real throws (not control-flow `Response`s like `redirect`), **before** the nearest `_error`
-     * boundary renders / a soft-nav 500 / a rethrow - so it sees errors that the boundary would
-     * otherwise hide. Observation only; its own throws are swallowed so a faulty reporter can't break
-     * rendering. (`beforeLoader` is intentionally omitted - the core HTTP hooks already cover
-     * pre-request work.) */
-    readonly onLoaderError?: (error: unknown, ctx: {
-        readonly request: Request;
-        readonly params: Readonly<Record<string, string>>;
-        readonly route: string;
-    }) => void;
-}
-/**
- * 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 declare function createWebApp<Env = unknown>(options: CreateWebAppOptions<Env>): ReturnType<typeof server<Env>>;
-export interface GenerateClientEntryOptions {
-    /**
-     * Module specifier for the adapter's client runtime, e.g. `"@nifrajs/web-solid/client"`.
-     *
-     * **Contract:** the module MUST export `mountRouter({ router, routes, container })`. The generated
-     * bootstrap imports the specifier and calls it - so a self-executing entry that mounts on import
-     * builds cleanly and then does nothing, which is the trap this contract exists to name. The type is
-     * a bare `string` because a specifier is resolved by the bundler, not the type system, so the
-     * requirement is enforced by the bootstrap instead: it throws immediately, naming this module and
-     * the missing export, rather than failing later as `mountRouter is not a function`.
-     */
-    readonly clientModule: string;
-    /** Turn a route/layout source file (relative to the routes dir) into an import specifier. */
-    readonly resolve: (file: string) => string;
-}
-/**
- * Codegen: emit a client-entry module (as source) that lazily imports each route's layout chain
- * (so `Bun.build` with `splitting` code-splits one chunk per route), builds a `patterns` list,
- * then creates the agnostic router store (with a `loadModule` hook), installs history + form
- * interception, loads the initial route's chunk, and hydrates the adapter's stateful Router. The
- * initial route is derived from the URL (falling back to the server-injected route id, e.g.
- * `_404`), so after hydration the Router owns navigation and swaps routes without full reloads.
- * Bun has no `import.meta.glob`, so file-based routing needs this. Write the result to a file and
- * bundle it with `buildClient` / `Bun.build` (+ the adapter's transform).
- */
-export declare function generateClientEntry(manifest: Manifest, options: GenerateClientEntryOptions): string;
-export interface GenerateRouteSearchTypesOptions {
-    /** Turn a route source file into a module specifier for a `typeof import(...)` type - the same contract
-     * as `generateClientEntry`'s `resolve`, but WITHOUT a file extension (a `.d.ts` imports a module, not a
-     * path). Relative to wherever the emitted `.d.ts` is written. */
-    readonly resolve: (file: string) => string;
-    /** The module whose `RouteSearch` interface is augmented (default `"@nifrajs/web"`). Every adapter's
-     * `NavigateTarget` reads `@nifrajs/web`'s `RouteSearch`, so the default types `navigate` on all of them. */
-    readonly module?: string;
-}
-/**
- * Codegen: emit a `.d.ts` that types cross-route `navigate({ to, search })` against each route's
- * `searchSchema`. It augments the {@link RouteSearch} map with `"<pattern>": SearchOf<typeof import(...)>`
- * for every **static** route (one with no `:param`/`*` segment - a concrete `to` a caller can pass; a
- * dynamic route's concrete path can't match its pattern key, so those keep the loose object form). Written
- * by `nifra sync-routes` next to the route tree and included in the app's `tsconfig`; because it is
- * regenerated from the route files, a `navigate` whose `search` no longer matches the route's schema
- * becomes a `tsc` error - the same drift guarantee as nifra's typed client, no hand-maintained map.
- */
-export declare function generateRouteSearchTypes(manifest: Manifest, options: GenerateRouteSearchTypesOptions): string;
-export interface GenerateServerManifestOptions {
-    /** Turn a route/layout source file (relative to the routes dir) into an import specifier -
-     * same contract as `generateClientEntry`'s `resolve`. */
-    readonly resolve: (file: string) => string;
-    /** The content-hashed client entry URL (from `buildClient`'s manifest), **baked** into the emitted
-     * module - a disk-less worker can't read `manifest.json` at runtime. */
-    readonly clientEntry: string;
-    /** The app's aggregate stylesheet URLs (`buildClient`'s `BuildManifest.css`) - baked as
-     * `export const styles` so the server entry can hand them to `createWebApp` (→ `<link rel="stylesheet">`
-     * in `<head>`). Without this the built SSR page ships no CSS link and renders unstyled. */
-    readonly styles?: readonly string[] | undefined;
-    /** Per-route stylesheet URLs (`buildClient`'s `BuildManifest.routeStyles`) - baked as
-     * `export const routeStyles` so a page links only the CSS its route chain uses. */
-    readonly routeStyles?: Readonly<Record<string, readonly string[]>> | undefined;
-    /** Emit **lazy** per-route loaders (`() => import("./routes/x")`, a static specifier) instead of
-     * eager `import * as`, so a bundler with code-splitting emits one chunk per route - loaded on the
-     * first request to it, not all at boot (smaller cold-start parse). Default `false` (eager). Both
-     * modes are fs-free with statically-analyzable specifiers; only the *when* differs. */
-    readonly lazy?: boolean;
-}
-export declare function generateServerManifest(manifest: Manifest, options: GenerateServerManifestOptions): string;
+export { type GenerateClientEntryOptions, type GenerateRouteSearchTypesOptions, type GenerateServerManifestOptions, generateClientEntry, generateRouteSearchTypes, generateServerManifest, } from "./internal/codegen.js";
+export { mergeHeads, resolveMeta } from "./internal/head-merge.js";
+export { canonical, gone, jsonLd, notFound, type OpenGraphInput, openGraph, type RedirectOptions, type RenderAssemblyCache, type RenderedPage, type RenderPageInput, type RenderPageOptions, type RevalidateResult, redirect, renderPage, renderPageResult, revalidate, type StatusPageOptions, serializeData, statusPage, unsafeInlineScript, } from "./internal/render-document.js";
+export { DEFAULT_DEV_PORT, PRE_HYDRATION_GUARD, type ServerOnly, } from "./internal/runtime-contract.js";
 /**
  * The two file-name conventions that decide what never reaches a browser: a `*.server` module is
  * EMPTIED in the client build, a `*.fn` module is REPLACED with client stubs.
@@ -630,4 +27,13 @@ export declare function generateServerManifest(manifest: Manifest, options: Gene
  * server-only" should import the matcher rather than re-encode it.
  */
 export { SERVER_FN_MODULE, SERVER_ONLY_MODULE } from "./internal/server-boundary.js";
+export { type CreateWebAppOptions, createWebApp, } from "./internal/web-app.js";
+export { type CachedResponse, type CacheStore, ISR_REVALIDATE_HEADER, ISR_REVALIDATE_TAGS_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, type ClientAction, type ClientActionArgs, type ClientActionResult, type ClientLoader, type ClientLoaderArgs, type ClientRequestBody, type ClientRouteHooks, enumerateStaticRoutes, filePathToPattern, filePathToPatterns, type GetStaticPaths, type InertScriptType, type LayoutEntry, type LinkDescriptor, type Loader, type LoaderContext, type Manifest, type Meta, type MetaArgs, type MetaDescriptor, type MetaInput, type RouteEntry, type RouteModule, type ScriptDescriptor, type StaticPath, type StaticPaths, type StaticRoutes, type UnsafeScriptDescriptor, } from "./manifest.js";
+export { type Blocker, type BlockerController, type BlockerFunction, type BlockerLocation, type BlockerState, type BrowserNavigate, getBrowserNavigate, IDLE_BLOCKER, type NavigateFunction, type NavigateOptions, type NavigateSearchOf, type NavigateTargetInput, type RouteSearch, registerBlocker, resolveNavigate, setBlockerController, setBrowserNavigate, } from "./navigation.js";
+export { type PublicDirCache, resolvePublicPath, type ServePublicDirOptions, servePublicDir, } from "./public-dir.js";
+export { createMutation, createQueryClient, type DehydratedState, hashQueryKey, type InfiniteData, type InfiniteQueryHandle, type InfiniteQueryOptions, type MutationCallbacks, type MutationHandle, type MutationState, type MutationStatus, type QueryClient, type QueryClientOptions, type QueryHandle, type QueryOptions, type QueryState, type QueryStatus, } from "./query.js";
+export { ACTION_GLOBAL, BOUNDARY_GLOBAL, DATA_GLOBAL, LAYOUT_DATA_GLOBAL, type RenderAdapter, type RenderProps, ROOT_ATTRIBUTE, ROUTE_GLOBAL, type SsrModuleLoader, setSsrModuleLoader, ssrModuleLoader, } from "./render-seam.js";
+export { type ClientRouter, type ClientRouterOptions, createClientRouter, createMatcher, DATA_HEADER, type Fetcher, type FetcherState, type FetchRouteData, type MountRouterOptions, NAV_FROM_HEADER, REDIRECT_HEADER, RETAIN_HEADER, REVALIDATE_HEADER, type RouteMatch, type RoutePattern, type RouterState, STATUS_HEADER, type Submission, type SubmitOptions, } from "./router.js";
+export { type SearchOf, searchOf, searchOfChain, serializeSearch } from "./search.js";
 //# sourceMappingURL=index.d.ts.map