/**
 * Route manifest - the fs-free heart of file-based routing. Maps route file paths to nifra
 * router patterns + their nested layout chain. `discoverRoutes` (in `@nifrajs/web/fs`) scans
 * the filesystem and feeds `buildManifest`; everything here is pure logic, so it stays
 * portable (no fs, no DOM) and fully unit-testable. Edge deploys pre-build the manifest.
 */
import type { StandardSchemaV1 } from "@nifrajs/core/server";
import type { BoundaryDescriptor, BoundaryRegistration } from "./boundary.js";
/** Context passed to a route `loader`. The `api` + `env` are injected by `createWebApp` and typed
 * per-route via `@nifrajs/client`'s `LoaderArgs<Api, Env>` (here they are opaque to the agnostic core). */
export interface LoaderContext {
    readonly params: Record<string, string>;
    readonly request: Request;
    /** Alias of {@link request} - mirrors a route handler's `c.req` so the same name works in both. */
    readonly req: Request;
    readonly api: unknown;
    /** Platform bindings forwarded from the request `c.env` (Workers env/KV/D1). Opaque here. */
    readonly env: unknown;
    /** `true` when the request carries a valid draft/preview cookie (only when `createWebApp` is given a
     * `draftSecret`; otherwise always `false`). Branch on it to load unpublished content for editors. */
    readonly draft: boolean;
    /** The URL search params, validated against the route's `searchSchema` (a Standard Schema) when it
     * declares one - failing closed to the schema's defaults - else the raw parsed query. Typed per-route
     * via `@nifrajs/client`'s `LoaderArgs<Api, Env, Search>`. */
    readonly search: Record<string, unknown>;
}
/** A route's optional data loader: params/request in, data out. */
export type Loader = (ctx: LoaderContext) => unknown | Promise<unknown>;
/**
 * A route's optional mutation, run on POST. Shares the loader context (params/request/api);
 * read the form/JSON body off `request`. Returns either a control-flow value (a `redirect()`, a
 * `status(...)` render, or a hand-rolled `Response` - all passed straight through) or data,
 * surfaced to the page component as `actionData`.
 */
export type Action = (ctx: LoaderContext) => unknown | Promise<unknown>;
/** The body a client action may prepare for the server action. The server must validate it again. */
export type ClientRequestBody = NonNullable<RequestInit["body"]>;
/** Safe, client-visible context for a client loader. It intentionally exposes no Request or headers. */
export interface ClientLoaderArgs {
    readonly url: string;
    readonly params: Readonly<Record<string, string>>;
    readonly signal: AbortSignal;
    /** Lazily obtains the server loader result; repeated calls share one per-navigation request. */
    readonly serverLoader: () => Promise<unknown>;
}
/** A client-only post-hydration data loader. Its return value replaces the route's rendered data. */
export type ClientLoader = (args: ClientLoaderArgs) => unknown | Promise<unknown>;
/** Safe, client-visible context for a client action. No secrets or raw request headers cross this seam. */
export interface ClientActionArgs extends ClientLoaderArgs {
    readonly body: ClientRequestBody;
}
/** Client action preparation. `body` is sent as untrusted input; `optimisticData` is never sent. */
export interface ClientActionResult {
    readonly body?: ClientRequestBody;
    readonly optimisticData?: unknown;
}
/** A client-only action wrapper; it never replaces the server action. */
export type ClientAction = (args: ClientActionArgs) => ClientActionResult | void | Promise<ClientActionResult | void>;
/** Client hooks populated by the generated route entry after a route chunk loads. */
export interface ClientRouteHooks {
    readonly clientLoader?: ClientLoader;
    readonly clientAction?: ClientAction;
    /** Neutral boundary descriptors needed for soft-navigation interception; no server loader crosses. */
    readonly boundaries?: readonly BoundaryDescriptor[];
}
/**
 * One `<link>` tag's attributes for a route/layout's `meta.link`. The common HTML `<link>` attributes
 * are spelled out and **optional** so a typed partial like `{ rel, href, hreflang }` is assignable -
 * the previous `Record<string, string>` required *every* value to be a present string, which rejected
 * exactly that idiomatic shape (the bug this fixes). Standard attributes are explicit and the template
 * index signature admits inert `data-*` metadata without opening executable `on*` attributes. `boolean`
 * covers `disabled` (rendered bare when `true`, omitted when `false`), and `undefined` lets a caller
 * spread in a conditionally absent attribute. SSR and soft navigation apply one runtime allowlist too,
 * so a cast or untyped route cannot widen the injection surface.
 */
export interface LinkDescriptor {
    readonly rel?: string;
    readonly href?: string;
    readonly hreflang?: string;
    readonly crossorigin?: string;
    readonly media?: string;
    readonly nonce?: string;
    readonly sizes?: string;
    readonly type?: string;
    readonly as?: string;
    readonly integrity?: string;
    readonly referrerpolicy?: string;
    readonly fetchpriority?: string;
    readonly title?: string;
    readonly imagesrcset?: string;
    readonly imagesizes?: string;
    readonly color?: string;
    readonly disabled?: boolean;
    readonly [attr: `data-${string}`]: string | undefined;
}
/** One managed `<meta>` tag. Standard attributes and inert `data-*` metadata only. */
export interface MetaDescriptor {
    readonly charset?: string;
    readonly content?: string;
    readonly "http-equiv"?: string;
    readonly itemprop?: string;
    readonly media?: string;
    readonly name?: string;
    readonly property?: string;
    readonly scheme?: string;
    readonly [attr: `data-${string}`]: string | undefined;
}
/** One `<script>` element a route contributes to `<head>` - for structured data (JSON-LD) and other
 * inert, non-executable head scripts. The `content` is the script body; `type` defaults to
 * `"application/ld+json"` (the common case). The renderer escapes `content` against an HTML breakout
 * (`</`, `<!--`, `]]>`) - see `escapeScriptContent` - so a JSON-LD payload can never close the
 * `<script>` element early. `content` is **JSON/text, never raw HTML**: this slot is not an XSS escape
 * hatch for arbitrary markup. */
export type InertScriptType = "application/ld+json" | "application/json";
export interface ScriptDescriptor {
    /** The script's `type` attribute. Default `"application/ld+json"`. */
    readonly type?: InertScriptType;
    /** The script body (e.g. a `JSON.stringify`'d JSON-LD object). Escaped for safe `<script>` embedding. */
    readonly content: string;
}
/** Explicit escape hatch for executable inline code. A CSP nonce is mandatory. */
export interface UnsafeScriptDescriptor {
    readonly unsafe: true;
    readonly type: "module" | "text/javascript";
    readonly nonce: string;
    readonly content: string;
}
/**
 * The document head a route contributes - title + `<meta>`/`<link>`/`<script>` tag sets. Returned by a
 * route/layout `meta` (statically, or from a {@link MetaArgs} function). Every value is serialized into
 * managed (`data-nifra`) head tags: tag-specific attribute allowlists reject event handlers and active
 * URL/refresh contexts, values are HTML-escaped at render, and `script[].content` is breakout-escaped -
 * so loader-derived strings (LLM-authored `og:*`, user content) are XSS-safe by construction.
 * Layout-chain heads merge with the page's via `mergeHeads` (arrays concat outermost→page; `title` is
 * nearest-wins). Build `og:*`/`twitter:*` with `openGraph(...)`, canonical with `canonical(...)`, and
 * JSON-LD with `jsonLd(...)` (all from `@nifrajs/web`) rather than hand-writing the records.
 */
export interface Meta {
    readonly title?: string;
    readonly meta?: readonly MetaDescriptor[];
    readonly link?: readonly LinkDescriptor[];
    /** Inert head `<script>`s (JSON-LD structured data, etc.). See {@link ScriptDescriptor}. */
    readonly script?: readonly ScriptDescriptor[];
    /** Executable inline scripts. Prefer external modules; construct only with `unsafeInlineScript()`. */
    readonly unsafeScript?: readonly UnsafeScriptDescriptor[];
    /**
     * The document language - `<html lang="...">`. Nearest-wins like `title`, so a localized route can
     * override a layout's default. Defaults to `"en"` when no head in the chain sets it.
     *
     * This is the ONLY way to set it: the shell's `<html>` is framework-owned, so a multilingual app
     * otherwise serves every URL as `lang="en"` - which tells a screen reader to pronounce every locale
     * with an English voice, and suppresses the browser's translation offer.
     */
    readonly lang?: string;
    /**
     * The document writing direction - `<html dir="...">`. Nearest-wins like `title`. Omitted from the
     * shell when unset, which is HTML's `ltr` default, so an LTR app's output is byte-identical.
     *
     * Required for Arabic/Hebrew/Urdu/Persian: without it the browser lays the page out left-to-right
     * and mis-orders trailing punctuation, so the text renders wrong rather than merely unstyled.
     */
    readonly dir?: "ltr" | "rtl" | "auto";
}
/**
 * Args for a route's `meta` function: the loader's `data` + the route `params` + the request `origin`.
 * `meta()` runs in BOTH SSR and client navigation, so it has **no `request`/`process.env`/server access** -
 * `origin` is the only server-resolved fact it gets (so you needn't thread `siteUrl` through loader data
 * for absolute `og:url`/`canonical`/`og:image` URLs). See {@link origin}.
 */
export interface MetaArgs<Data = unknown> {
    readonly data: Data;
    readonly params: Record<string, string>;
    /**
     * The site origin - scheme + host (+ port), e.g. `"https://news.example.com"`, **with no trailing
     * slash**. The single piece of server/env knowledge `meta()` otherwise can't see: it runs in BOTH
     * SSR and client navigation, so it has no `request`/`process.env`. The framework resolves it from the
     * request URL during SSR and from `location.origin` on client nav - and they match, so an absolute
     * `og:url`/`canonical`/`og:image` built from it never drifts between the server-rendered `<head>` and
     * a soft-nav. Use it for absolute URLs (`origin + "/posts/" + slug`) instead of threading `siteUrl`
     * through loader data. Empty string (`""`) when the origin is unknown (e.g. a hand-built test render
     * with no request URL). A `meta()` that ignores `origin` is unchanged.
     */
    readonly origin: string;
}
/** A route's `meta`: a static {@link Meta}, or a function of the loader data + params + the request
 * origin ({@link MetaArgs}). Use the `origin` arg for absolute `canonical`/`og:url`/`og:image` URLs -
 * it's resolved server-side from the request and matches the client's `location.origin`. */
export type MetaInput = Meta | ((args: MetaArgs) => Meta);
/** One concrete parameterization of a dynamic route, returned by {@link GetStaticPaths}. */
export interface StaticPath {
    /** Values for the route's `:param` segments, e.g. `{ id: "7" }` for `/users/:id`. */
    readonly params: Record<string, string>;
}
/** What a route's `getStaticPaths` returns: the param sets to prerender + the unlisted-path policy. */
export interface StaticPaths {
    readonly paths: readonly StaticPath[];
    /**
     * How a path NOT in `paths` is handled. `"ssr"` (default) → rendered on-demand by the worker
     * (the natural hybrid behavior - an unlisted path simply isn't a static file); `"404"` → only the
     * listed paths exist. Recorded by `prerenderRoutes` for the deploy layer.
     */
    readonly fallback?: "ssr" | "404";
}
/** A dynamic route's build-time param enumeration (the SSG equivalent of "which pages exist"). */
export type GetStaticPaths = () => StaticPaths | Promise<StaticPaths>;
/** A route module - the default component + optional loader / action / meta. */
export interface RouteModule {
    readonly default: unknown;
    readonly loader?: Loader;
    readonly action?: Action;
    /** Optional client-only loader. It runs after hydration and on client navigations. */
    readonly clientLoader?: ClientLoader;
    /** Optional client-only submit wrapper. The server action remains mandatory for mutations. */
    readonly clientAction?: ClientAction;
    /** Named async boundaries owned by this route. The adapter renders their neutral state seam. */
    readonly boundaries?: readonly BoundaryRegistration[];
    /** A Standard Schema validating this route's URL search params. When present, `ctx.search` is parsed +
     * validated against it (failing closed to the schema's defaults on invalid input); type it into the
     * loader with `LoaderArgs<Api, Env, typeof searchSchema>`. */
    readonly searchSchema?: StandardSchemaV1<unknown, Record<string, unknown>>;
    /** Search keys that are purely client-side UI (`"tab"`, a client-side `"sort"`, `"modal"`) and do NOT
     * affect this route's loader. When a client navigation stays on the same route + pathname and changes
     * ONLY these keys, the router updates the URL (so `useSearch` re-renders) WITHOUT re-running the loader.
     * Any other key change revalidates as usual - so omitting a data-affecting key here can never serve
     * stale data, it only forgoes the optimization. Client-only: the server always renders fresh. */
    readonly searchClientKeys?: readonly string[];
    readonly meta?: MetaInput;
    /**
     * Opt this route out of nifra's full-document client hydration. The server still renders the full
     * HTML document, loaders/actions still run, and native links/forms still work; the generated app
     * client, route chunks, and loader globals are omitted for hard navigations. Intended for static or
     * island-hydrated pages where interactivity is mounted by smaller, explicit client entries.
     */
    readonly hydrate?: boolean;
    /**
     * Opt a **static** route (no `:param`/`*`) into build-time prerendering (SSG): `prerenderRoutes`
     * (from `@nifrajs/web/build`) renders it to a static `index.html` at build. The loader runs at build
     * with the in-process `api` (build-safe data only - no per-request cookies/secrets); `defer()` on a
     * prerendered route resolves at build. For **dynamic** routes use {@link getStaticPaths} instead.
     */
    readonly prerender?: boolean;
    /**
     * Enumerate the concrete params to prerender for a **dynamic** (`:param`) route - the SSG path list
     * (blogs/docs/etc.). Runs at build; `prerenderRoutes` renders one `index.html` per returned path.
     */
    readonly getStaticPaths?: GetStaticPaths;
    /**
     * ISR freshness for this route, in **seconds**. `createWebApp` emits it as an
     * `x-nifra-isr-revalidate` response header that `withISR` reads to set the page's cache TTL
     * (overriding the wrapper's default). Older-than-`revalidate` cached pages are served stale while
     * regenerating. (Distinct from the action-revalidation `x-nifra-revalidate` header - a CSV path
     * list the client parses to refetch - so the two channels never alias.)
     */
    readonly revalidate?: number;
    /** Optional bounded tags used by ISR on-demand invalidation (`?tag=...`). */
    readonly revalidateTags?: readonly string[];
    /**
     * No-framework island bundles (`@nifrajs/web/islands`) to load on this route, as `<script
     * type="module">` in the document tail. Loaded **regardless of `hydrate`** - pair with
     * `export const hydrate = false` for a static page that ships zero framework JS and mounts
     * interactivity through `<Island>` markers + `mountIslands` enhancers instead.
     */
    readonly islandScripts?: readonly string[];
}
/** A layout (or `_404`/`_error`) entry: its source file (for client codegen) + a lazy loader.
 *
 * A `_layout.tsx` may export `meta` (static {@link Meta} or a function of the loader data + params,
 * same shape as a route's) to contribute sitewide `<head>` tags - `hreflang`/`preconnect`/etc. that
 * belong on every page under the layout. The layout chain's heads merge with the page's: arrays
 * (`meta`/`link`) concatenate outermost→innermost→page; scalars (`title`) are nearest-wins (the page
 * overrides an inner layout, which overrides an outer one). See `mergeHeads` in `@nifrajs/web`. */
export interface LayoutEntry {
    readonly file: string;
    readonly load: () => Promise<RouteModule>;
}
/** One matched route: pattern, nested layout ids (outermost → innermost), source file, loader. */
export interface RouteEntry {
    readonly id: string;
    readonly pattern: string;
    readonly layoutIds: readonly string[];
    /**
     * Param names each layout in {@link layoutIds} owns, aligned by index.
     *
     * A layout wraps a URL prefix, so these are the params it may read and the ones whose change should
     * re-run its loader - everything deeper belongs to routes beneath it. Derived per (route, layout)
     * pair rather than per layout, because one layout can own different params on different expanded
     * patterns: `[[lang]]/docs/_layout` owns nothing on `/docs/:slug` and `{lang}` on `/:lang/docs/:slug`.
     * Optional only so hand-built test manifests may omit it.
     */
    readonly layoutParams?: ReadonlyArray<readonly string[]>;
    /** `_error` boundary ids in this route's ancestor chain (outermost → innermost). The last is the
     * **nearest** boundary, rendered when the route's loader throws. Always set by `buildManifest`
     * (optional only so hand-built test manifests may omit it); absent/empty ⇒ no boundary (error 500s). */
    readonly errorIds?: readonly string[];
    readonly file: string;
    readonly load: () => Promise<RouteModule>;
}
/** The full route manifest. */
export interface Manifest {
    readonly routes: readonly RouteEntry[];
    readonly layouts: Readonly<Record<string, LayoutEntry>>;
    /** Per-segment `_error` boundary components, keyed by id (`_error`, `a/_error`, …). Always set by
     * `buildManifest` (optional only so hand-built test manifests may omit it). */
    readonly errors?: Readonly<Record<string, LayoutEntry>>;
    readonly notFound?: LayoutEntry;
    /** Per-status terminal pages from `_<status>.tsx` at the routes root (`_410`, `_451`, …), keyed by
     * the status as a string. Rendered by a loader's `gone()` / `statusPage(n)`; a status with no page
     * falls back to `_404`, and then to plain text. `_404` itself stays on {@link notFound} - it is
     * reached by unmatched paths too, which these are not. */
    readonly statusPages?: Readonly<Record<string, LayoutEntry>>;
}
export declare function filePathToPatterns(file: string): string[];
/** One URL pattern a route file expands to, plus the scope information layouts need. */
export interface FileRoutePattern {
    readonly pattern: string;
    /**
     * URL segments contributed by the first *k* path parts of the file, indexed by *k*.
     *
     * This is what makes a layout's scope derivable without turning layouts into router nodes. A layout
     * lives at a directory; the segments that directory contributes are exactly the prefix of the URL it
     * wraps, so `depths[partsIn(layoutDir)]` is how many leading pattern segments it owns - and the
     * params inside that prefix are the ones it may read.
     *
     * Per EXPANDED pattern, not per file, because the two diverge: `[[lang]]/docs/_layout` owns nothing
     * on `/docs/:slug` and `{lang}` on `/:lang/docs/:slug`. A route group contributes no segment, so
     * `(marketing)/_layout` owns nothing at all.
     */
    readonly depths: readonly number[];
}
/** Expand a route file into its URL patterns, each carrying per-directory segment counts. */
export declare function filePathToRoutes(file: string): FileRoutePattern[];
/**
 * The **canonical** single pattern for a route file - all optional segments present. A file with no
 * optionals yields its one pattern. Use {@link filePathToPatterns} to get every pattern (optionals
 * expand the set).
 */
export declare function filePathToPattern(file: string): string;
/**
 * Build a manifest from route file paths (relative to the routes dir) + an `importer` that
 * turns a path into a lazy module loader. Pure - no fs. Throws at boot (the loud-and-early
 * RouteConfigError ethos) on duplicate patterns. `_layout`/`_404`/`_error` files are special; other
 * `_`-prefixed files are ignored (private/colocated, never routed).
 */
export declare function buildManifest(files: readonly string[], importer: (file: string) => () => Promise<RouteModule>): Manifest;
/**
 * Substitute a route pattern's `:param` segments with concrete values: `/users/:id` + `{id:"7"}` →
 * `/users/7`. Returns the filled path plus any params that had no value (a `getStaticPaths` bug) so
 * the caller can skip rather than emit a path with a literal `:name`. Shared by the SSG driver and
 * {@link enumerateStaticRoutes}.
 */
export declare function fillRoutePattern(pattern: string, params: Record<string, string>): {
    path: string;
    missing: string[];
};
/** The static-routing facts a server needs from the route modules: which concrete paths are
 * prerendered, plus each dynamic route's `getStaticPaths` fallback policy. */
export interface StaticRoutes {
    /** Concrete prerendered paths - static `prerender` routes + each `getStaticPaths` entry. */
    readonly paths: string[];
    /** Per dynamic route pattern, its `getStaticPaths` `fallback` (`"ssr"` default). `createWebApp` uses
     * `"404"` to reject an unlisted path under that route at runtime (the path simply doesn't exist). */
    readonly fallbacks: Record<string, "ssr" | "404">;
}
/**
 * Enumerate the static-routing facts `prerenderRoutes` would produce - static routes opted in via
 * `export const prerender = true`, each `getStaticPaths` entry of a dynamic route, and each dynamic
 * route's `fallback` policy. Pure (no rendering), so a server can compute what to hand `createWebApp`
 * (the prerendered set for the client's static-`_data.json` soft-nav + the fallback map for
 * `"404"` enforcement). A production server may instead read the build's `prerendered.json` to avoid
 * loading every route module at startup. Catch-all/wildcard routes and dynamic routes without
 * `getStaticPaths` are omitted from `paths`.
 */
export declare function enumerateStaticRoutes(routes: readonly RouteEntry[]): Promise<StaticRoutes>;
//# sourceMappingURL=manifest.d.ts.map