import { isSameOriginPath, type ResponseResult, status as statusResult } from "@nifrajs/core/server"
import type { BoundaryRegistration, BoundaryStates } from "../boundary.ts"
import { DEFERRED_ERROR_CODE, DEFERRED_RUNTIME, prepareDeferred } from "../deferred.ts"
import { ISR_REVALIDATE_HEADER, ISR_REVALIDATE_TAGS_HEADER, serializeISRTags } from "../isr.ts"
import type {
  Loader as LayoutLoader,
  LinkDescriptor,
  Meta,
  MetaDescriptor,
  MetaInput,
  RouteModule,
  ScriptDescriptor,
  UnsafeScriptDescriptor,
} from "../manifest.ts"
import type { RenderAdapter, RenderProps } from "../render-seam.ts"
import {
  ACTION_GLOBAL,
  BOUNDARY_GLOBAL,
  DATA_GLOBAL,
  LAYOUT_DATA_GLOBAL,
  ROOT_ATTRIBUTE,
  ROUTE_GLOBAL,
} from "../render-seam.ts"
import { PRERENDERED_GLOBAL, REDIRECT_HEADER } from "../router.ts"
import { trustedHeadAttributes } from "./head-attributes.ts"
import { isStaticMeta, mergeHeads } from "./head-merge.ts"
import { PRE_HYDRATION_GUARD } from "./runtime-contract.ts"
import { EXECUTABLE_SCRIPT_TYPES, INERT_SCRIPT_TYPES } from "./script-types.ts"

const TEXT_ENCODER = new TextEncoder()

type MaybePromise<T> = T | Promise<T>

// XSS-safe `<script>` JSON escaping in a SINGLE pass: `<`/`>` would break out of the
// script element; U+2028/U+2029 are valid JSON but historically break JS string literals. Built via
// fromCharCode so no raw separator chars live in this source. One regex + one output string replaces
// the prior four sequential `replaceAll` full-string passes.
const LINE_SEP = String.fromCharCode(0x2028)
const PARA_SEP = String.fromCharCode(0x2029)
const SCRIPT_ESCAPE = new RegExp(`[<>${LINE_SEP}${PARA_SEP}]`, "g")
const SCRIPT_ESCAPE_MAP: Readonly<Record<string, string>> = {
  "<": "\\u003c",
  ">": "\\u003e",
  [LINE_SEP]: "\\u2028",
  [PARA_SEP]: "\\u2029",
}
const NODE_RESPONSE_BODY = Symbol.for("nifra.response.body")
const RESPONSE_RESULT = Symbol.for("nifra.response.result")

/**
 * A control-flow value that renders as plain data - what `redirect()` returns, and what core's
 * `status(...)` returns. Recognized here rather than imported: core keeps its own predicate internal,
 * and the registry symbol is the contract between them (two copies of core must still agree).
 */
const isResponseResult = (value: unknown): value is ResponseResult =>
  typeof value === "object" &&
  value !== null &&
  (value as { readonly [RESPONSE_RESULT]?: unknown })[RESPONSE_RESULT] === true &&
  typeof (value as { readonly toResponse?: unknown }).toResponse === "function"

/** A returned/thrown value that ends the request as-is: either shape of control-flow signal. */
export const isControlFlow = (value: unknown): value is Response | ResponseResult =>
  value instanceof Response || isResponseResult(value)

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 function renderPage(options: RenderPageInput): MaybePromise<Response> {
  const page = renderPageResult(options)
  return page instanceof Promise ? page.then((p) => p.toResponse()) : page.toResponse()
}

export function renderPageResult(options: RenderPageInput): MaybePromise<RenderedPage> {
  const {
    adapter,
    chain,
    data,
    actionData,
    clientEntry,
    preload = [],
    styles = [],
    prerenderedPaths = [],
    revalidate,
    revalidateTags = [],
    routeId,
    status = 200,
    title = "nifra",
    head,
    rootId = "root",
    hydrate = true,
    islandScripts = [],
    nonce,
    boundaries,
    headers: extraHeaders,
  } = options
  if (nonce !== undefined && nonce.trim() === "") {
    throw new TypeError("[nifra/web] renderPage nonce must be non-empty when provided")
  }
  const nonceAttr = nonce === undefined ? "" : ` nonce="${escapeAttr(nonce)}"`
  const route = routeId === undefined ? "" : `window.${ROUTE_GLOBAL}=${serializeData(routeId)};`
  // The SSG prerendered-path set (when an app declares it) - the client reads it to fetch a static
  // `_data.json` on soft-nav into a prerendered route instead of hitting the worker. Empty ⇒ omitted.
  const prerendered =
    prerenderedPaths.length === 0
      ? ""
      : `window.${PRERENDERED_GLOBAL}=${serializeData(prerenderedPaths)};`
  // Split deferred values: the component sees markers (id + promise) to `<Await>`; the serialized
  // data carries `{__nifra_deferred: id}` placeholders (promises don't serialize). `actionData` may
  // also `defer()` - split it too, continuing the id space so a single registry settles both. The
  // inline registry runtime is emitted only when something defers, so non-deferred output is unchanged.
  const { forComponent, forClient, deferred } = prepareDeferred(data)
  // Each layout's data is split in turn, each continuing the id space, so a `defer()` in a layout
  // settles through the SAME registry as the page's rather than colliding on ids.
  const layoutSplits: Array<ReturnType<typeof prepareDeferred>> = []
  if (options.layoutData !== undefined) {
    let offset = deferred.length
    for (const entry of options.layoutData) {
      const split = prepareDeferred(entry, offset)
      offset += split.deferred.length
      layoutSplits.push(split)
    }
  }
  const layoutDeferred = layoutSplits.flatMap((split) => split.deferred)
  const actionSplit =
    actionData === undefined
      ? undefined
      : prepareDeferred(actionData, deferred.length + layoutDeferred.length)
  const boundarySplit =
    boundaries === undefined
      ? undefined
      : prepareDeferred(
          boundaries,
          deferred.length + layoutDeferred.length + (actionSplit?.deferred.length ?? 0),
        )
  // On the common page-only path (no layout loader, no action) reuse `deferred` directly instead of
  // allocating a fresh spread array every request.
  const allDeferred =
    layoutDeferred.length === 0 && actionSplit === undefined && boundarySplit === undefined
      ? deferred
      : [
          ...deferred,
          ...layoutDeferred,
          ...(actionSplit ? actionSplit.deferred : []),
          ...(boundarySplit ? boundarySplit.deferred : []),
        ]
  // Omitted entirely when no layout has a loader - a page-only app emits exactly what it did before.
  const layoutTail =
    options.layoutData === undefined
      ? ""
      : `window.${LAYOUT_DATA_GLOBAL}=${serializeData(layoutSplits.map((split) => split.forClient))};`

  // Only emit the action global when an action actually ran, so plain GET output is unchanged.
  const action =
    actionSplit === undefined
      ? ""
      : `window.${ACTION_GLOBAL}=${serializeData(actionSplit.forClient)};`
  const boundaryTail =
    boundarySplit === undefined
      ? ""
      : `window.${BOUNDARY_GLOBAL}=${serializeData(boundarySplit.forClient)};`
  const deferredRuntime =
    allDeferred.length > 0 ? `<script${nonceAttr}>${DEFERRED_RUNTIME}</script>` : ""
  // The regex only injects the CSP nonce into the (constant) hydration head; with no nonce it's a
  // no-op that still scans the whole script every request. Skip it on the common no-nonce path.
  // The request-invariant document pieces. With a caller-supplied per-route cache (and no per-request
  // nonce, which would bake into them) they're built once and reused; the per-request seams - the
  // deferred runtime in the shell, the action/layout-data globals and the serialized loader data in
  // the tail - are always assembled fresh. Byte-identical to building the whole document inline.
  const slot: RenderAssemblyCache =
    nonce === undefined && options.assemblyCache !== undefined ? options.assemblyCache : {}
  if (slot.shellPre === undefined) {
    // Matched-route chunk preloads, concatenated directly. De-duped against the entry, which is
    // preloaded separately below.
    let preloadLinks = ""
    for (const url of preload) {
      if (url !== clientEntry)
        preloadLinks += `<link rel="modulepreload" href="${escapeAttr(url)}">`
    }
    // The matched route's stylesheets - `<link rel="stylesheet">` in `<head>` so CSS arrives with the
    // first paint (no FOUC). Render-blocking by design, and emitted regardless of `hydrate` (a static
    // or `_error` page still wants its styles). In dev (Vite) CSS is injected client-side instead.
    let styleLinks = ""
    for (const url of styles) styleLinks += `<link rel="stylesheet" href="${escapeAttr(url)}">`
    // Island bundles are referenced only by a `<script type="module">` at the END of `<body>`, so the
    // browser doesn't discover them until the whole page is parsed. `modulepreload` them in `<head>`
    // so the fetch starts immediately, in parallel with parsing - regardless of `hydrate`.
    let islandPreloads = ""
    for (const src of islandScripts)
      islandPreloads += `<link rel="modulepreload" href="${escapeAttr(src)}">`
    // Runs in the first-paint→hydration window to swallow a JS-only form's broken native submit. Only
    // on a hydrating page (a static/_error page has no client handlers, so no footgun).
    const hydrationGuard = hydrate ? `<script${nonceAttr}>${PRE_HYDRATION_GUARD}</script>` : ""
    // `<html>` attributes. `lang` defaults to `"en"`; `dir` is omitted entirely when unset, which IS
    // HTML's `ltr` default. Both attribute-escaped. `client.ts`'s `applyHead` mirrors this exact
    // defaulting on soft-nav, so a hard load and a client navigation produce the same `<html>`.
    const htmlAttrs = ` lang="${escapeAttr(head?.lang ?? "en")}"${head?.dir === undefined ? "" : ` dir="${escapeAttr(head.dir)}"`}`
    // Marks the container for the client entry when the id is not the one the entry falls back to.
    const rootMarker = rootId === "root" ? "" : ` ${ROOT_ATTRIBUTE}`
    // A non-hydrated page omits the adapter's hydration bootstrap entirely (Solid's `_$HY` registry
    // script, etc.) - there is no client takeover to feed, so it's dead bytes on a static document.
    // The nonce rewrite only runs when a nonce is set; with none it was a whole-string no-op scan.
    const rawHydrationHead = hydrate ? adapter.hydrationHead(nonce) : ""
    const hydrationHead =
      nonce === undefined
        ? rawHydrationHead
        : rawHydrationHead.replace(/<script(?![^>]*\bnonce=)(?=[\s>])/g, `<script${nonceAttr}`)
    // Shell up to the deferred-runtime seam: on a hydrating page that seam sits after the entry +
    // route-chunk preloads; a non-hydrating page has no runtime insertion at all.
    const entryPreloads = hydrate
      ? `<link rel="modulepreload" href="${escapeAttr(clientEntry ?? "")}">${preloadLinks}`
      : ""
    slot.shellPre = `<!doctype html><html${htmlAttrs}><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">${hydrationGuard}<title>${escapeHtml(head?.title ?? title)}</title>${headTags(head)}${styleLinks}${entryPreloads}`
    slot.shellPost = `${islandPreloads}${hydrationHead}</head><body><div id="${escapeAttr(rootId)}"${rootMarker}>`
    // Island bundles load regardless of `hydrate` - a static page (hydrate:false) ships no framework
    // client but can still mount no-framework islands (`@nifrajs/web/islands`).
    let islandTags = ""
    for (const src of islandScripts)
      islandTags += `<script type="module" src="${escapeAttr(src)}"${nonceAttr}></script>`
    if (hydrate) {
      slot.tailPre = `<script${nonceAttr}>${route}`
      slot.tailMid = prerendered
      slot.tailData = `window.${DATA_GLOBAL}=`
      slot.tailPost = `</script><script type="module" src="${escapeAttr(clientEntry ?? "")}"${nonceAttr}></script>${islandTags}</body></html>`
    } else {
      slot.tailPre = ""
      slot.tailMid = ""
      slot.tailData = ""
      slot.tailPost = `${islandTags}</body></html>`
    }
  }
  // The deferred runtime rides only on a hydrating page (a static page has no client takeover), and
  // only when something actually deferred - matching the pre-cache emission exactly.
  const runtimeSeam = hydrate && allDeferred.length > 0 ? deferredRuntime : ""
  const shellHtml = `${slot.shellPre}${runtimeSeam}${slot.shellPost}`
  // Closes the hydration container; deferred resolve scripts go AFTER it (outside `#root`) so they
  // aren't part of the adapter's hydrated tree (an inline script inside it breaks hydration).
  const closeRootHtml = "</div>"
  // Tail - the loader-data globals + the client module. Module scripts defer (run after parse), so
  // the data global + every streamed deferred resolution are set before the entry hydrates.
  const tailHtml = hydrate
    ? `${slot.tailPre}${action}${slot.tailMid}${layoutTail}${boundaryTail}${slot.tailData}${serializeData(forClient)}${slot.tailPost}`
    : (slot.tailPost as string)
  const headers: Record<string, string> = { "content-type": "text/html; charset=utf-8" }
  // Caller-supplied headers (a terminal status page's `cache-control`, say). Applied before the
  // framework's own below, so `content-type` and the ISR channel stay authoritative - a caller must
  // not be able to mislabel the document or forge the freshness header by passing them here.
  if (extraHeaders !== undefined) {
    for (const [name, value] of new Headers(extraHeaders)) {
      if (name !== "content-type") headers[name] = value
    }
  }
  // ISR: advertise the route's freshness so a `withISR` wrapper can set this page's cache TTL. A
  // dedicated header (not the action-revalidation `x-nifra-revalidate`) so the TTL channel never aliases
  // the client's path-list channel.
  if (revalidate !== undefined) headers[ISR_REVALIDATE_HEADER] = String(revalidate)
  const serializedTags = serializeISRTags(revalidateTags)
  if (serializedTags !== undefined) headers[ISR_REVALIDATE_TAGS_HEADER] = serializedTags
  const renderProps: RenderProps = {
    data: forComponent,
    actionData: actionSplit?.forComponent,
    // `params`/`path` thread the matched route + URL to the adapter's `useParams`/`useLocation` so they
    // render SSR-correct. Spread only when supplied (exactOptionalPropertyTypes) - an adapter with no
    // router bindings simply never reads them.
    ...(options.params !== undefined ? { params: options.params } : {}),
    ...(options.path !== undefined ? { path: options.path } : {}),
    // Same rule for `search`: the validated query the adapter's `useSearch` reads, spread only when the
    // caller supplied it (a non-router render never has it).
    ...(options.search !== undefined ? { search: options.search } : {}),
    // Spread only when present, so a page-only render produces exactly the props it did before.
    ...(options.layoutData !== undefined
      ? { layoutData: layoutSplits.map((split) => split.forComponent) }
      : {}),
    ...(boundarySplit !== undefined
      ? { boundaries: boundarySplit.forComponent as BoundaryStates }
      : {}),
  }

  // Fast path: nothing `defer()`s and the adapter can render synchronously to a string → buffer the
  // whole document in one pass. Progressive streaming only benefits pages with deferred boundaries
  // (those take the streaming path below); for a plain page the streaming pipeline + the framework's
  // streaming renderer are pure overhead vs a single sync render + concat. A buffered string body also
  // gets an automatic Content-Length. A render throw surfaces here exactly as the streaming path's
  // shell-readiness `await` does, so the `_error` boundary still maps it to a status.
  if (allDeferred.length === 0 && adapter.renderToString !== undefined) {
    const out = adapter.renderToString(chain, renderProps)
    return typeof out === "string"
      ? new BufferedRenderedPage(shellHtml + out + closeRootHtml + tailHtml, status, headers)
      : out.then(
          (bodyHtml) =>
            new BufferedRenderedPage(
              shellHtml + bodyHtml + closeRootHtml + tailHtml,
              status,
              headers,
            ),
        )
  }

  return renderStreamedPage(
    adapter,
    chain,
    renderProps,
    shellHtml,
    closeRootHtml,
    allDeferred,
    tailHtml,
    status,
    headers,
    nonceAttr,
  ).then((response) => new ResponseRenderedPage(response))
}

async function renderStreamedPage(
  adapter: RenderAdapter,
  chain: readonly unknown[],
  renderProps: RenderProps,
  shellHtml: string,
  closeRootHtml: string,
  allDeferred: ReadonlyArray<{ readonly id: number; readonly promise: Promise<unknown> }>,
  tailHtml: string,
  status: number,
  headers: Record<string, string>,
  nonceAttr: string,
): Promise<Response> {
  // Streaming path - required for `defer()` (progressive `<Await>` resolution) and used by any adapter
  // that doesn't implement `renderToString`. Awaiting `renderToStream` resolves on shell-readiness
  // (React: on-shell-ready; Solid: synchronously), so a shell-render throw surfaces before any byte is
  // sent. A *mid*-stream failure errors the body instead.
  const enc = TEXT_ENCODER
  const shell = enc.encode(shellHtml)
  const closeRoot = enc.encode(closeRootHtml)
  const tail = enc.encode(tailHtml)
  const appStream = await adapter.renderToStream(chain, renderProps)
  const body = streamDocument(shell, appStream, closeRoot, allDeferred, tail, enc, nonceAttr)
  return new Response(body, { status, headers })
}

class BufferedRenderedPage implements RenderedPage {
  readonly [RESPONSE_RESULT] = true
  private readonly body: string
  private readonly status: number
  private readonly headers: Readonly<Record<string, string>>

  constructor(body: string, status: number, headers: Readonly<Record<string, string>>) {
    this.body = body
    this.status = status
    this.headers = headers
  }

  toResponse(): Response {
    return htmlResponse(this.body, { status: this.status, headers: this.headers })
  }

  toNodeBody(): {
    readonly status: number
    readonly headers: Readonly<Record<string, string | readonly string[]>>
    readonly body: string
  } {
    return { status: this.status, headers: this.headers, body: this.body }
  }
}

class ResponseRenderedPage implements RenderedPage {
  readonly [RESPONSE_RESULT] = true
  private readonly response: Response

  constructor(response: Response) {
    this.response = response
  }

  toResponse(): Response {
    return this.response
  }
}

function htmlResponse(body: string, init: ResponseInit): Response {
  const response = new Response(body, init)
  // @nifrajs/node can write buffered HTML straight to ServerResponse with `end(body)`, avoiding a Web
  // Response stream drain on Node. Non-enumerable + Symbol.for keeps this invisible to Web runtimes and
  // cross-package without adding a runtime dependency from @nifrajs/node to @nifrajs/web.
  Object.defineProperty(response, NODE_RESPONSE_BODY, { value: body })
  return response
}

/**
 * Assemble the document stream: `shell` → the app `stream` (forwarded chunk-by-chunk, so a streaming
 * renderer's progressive flushing is preserved) → `closeRoot` → one `__nifraResolve`/`__nifraReject`
 * script per deferred value (emitted once its promise settles - by now the app stream has awaited
 * the same Suspense boundaries - and placed OUTSIDE `#root`) → `tail`. A mid-stream app error errors
 * the result (the body breaks) rather than silently truncating a 200.
 */
function streamDocument(
  shell: Uint8Array,
  stream: ReadableStream<Uint8Array>,
  closeRoot: Uint8Array,
  deferred: ReadonlyArray<{ readonly id: number; readonly promise: Promise<unknown> }>,
  tail: Uint8Array,
  enc: TextEncoder,
  nonceAttr: string,
): ReadableStream<Uint8Array> {
  return new ReadableStream({
    async start(controller) {
      const reader = stream.getReader()
      try {
        controller.enqueue(shell)
        for (;;) {
          const { done, value } = await reader.read()
          if (done) break
          controller.enqueue(value)
        }
        controller.enqueue(closeRoot)
        // Stream each resolution as ITS OWN promise settles - NOT in array order. A slow
        // defer() must not block a faster one; each script self-addresses by id, so order is irrelevant.
        await Promise.all(
          deferred.map(async (d) => {
            try {
              const value = serializeData(await d.promise)
              controller.enqueue(
                enc.encode(`<script${nonceAttr}>window.__nifraResolve(${d.id},${value})</script>`),
              )
            } catch (err) {
              // A rejected deferred streams __nifraReject (the client `<Await>` surfaces it) - it must
              // not break the whole body. Redact: stream a stable opaque code, never the raw error
              // text; log the real reason server-side.
              console.error("[nifra/web] deferred value rejected:", err)
              controller.enqueue(
                enc.encode(
                  `<script${nonceAttr}>window.__nifraReject(${d.id},${serializeData(DEFERRED_ERROR_CODE)})</script>`,
                ),
              )
            }
          }),
        )
        controller.enqueue(tail)
        controller.close()
      } catch (err) {
        controller.error(err)
      } finally {
        reader.releaseLock()
      }
    },
  })
}

/** 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 function redirect(location: string, options: RedirectOptions = {}): ResponseResult {
  if (options.external !== true && !isSameOriginPath(location)) {
    throw new Error(
      `[nifra/web] redirect(${JSON.stringify(location)}) is not a same-origin path. Use a path beginning with "/" (not "//", no backslash or control character), or redirect(location, { external: true }) for a deliberate off-origin redirect. This guards against open redirects from unvalidated input.`,
    )
  }
  // Reject CR/LF in the Location explicitly - defense-in-depth (response splitting / header
  // injection). Spec-correct runtimes' Headers setter throws on CR/LF, but `external: true` lets
  // unvalidated input reach this sink, so we don't rely on the runtime. Same posture as
  // serializeCookie / the SSE frame formatter, which strip CRLF at their sinks.
  if (/[\r\n]/.test(location)) {
    throw new Error(
      `[nifra/web] redirect location contains a CR/LF character - refusing to emit a header-injecting redirect.`,
    )
  }
  return statusResult(options.status ?? 303, undefined, {
    headers: options.headers === undefined ? { location } : { ...options.headers, location },
  })
}

/**
 * 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. */
export type HeadersLike = ConstructorParameters<typeof Headers>[0]

/**
 * The signatures a **duplicate module instance** produces during SSR, across engines.
 *
 * Two copies of React (or of `@nifrajs/core`) at the SAME version still fail, because module identity
 * is path-based: hooks read a dispatcher off the copy that rendered, and the component imported the
 * other one. The error that surfaces names a React internal, so it reads as a React bug and the actual
 * cause - two directories - is a long inference away. Naming the cause at the point of failure is the
 * difference between that and a five-second read.
 */
const DUPLICATE_INSTANCE_SIGNATURES: readonly RegExp[] = [
  /resolveDispatcher\(\)/,
  /Invalid hook call/,
  /Cannot read propert(?:y|ies) of null \(reading '(?:use[A-Z]\w*)'\)/,
  /null is not an object \(evaluating '.*\.use[A-Z]\w*'\)/,
]

/**
 * Append the likely cause to an SSR error that carries a duplicate-instance signature.
 *
 * Deliberately does NOT claim the resolved paths: `@nifrajs/web` is framework-agnostic and does not
 * depend on React, so it cannot resolve the copies without guessing. It names the condition and the
 * command that reports the paths, which is the actionable part. Returns the error untouched when the
 * signature does not match, so an ordinary render error reads exactly as before.
 */
export function withDuplicateInstanceHint(err: unknown): unknown {
  if (!(err instanceof Error)) return err
  if (!DUPLICATE_INSTANCE_SIGNATURES.some((rx) => rx.test(err.message))) return err
  const augmented = new Error(
    `${err.message}\n\n[nifra/web] This signature usually means TWO COPIES of an identity-sensitive package (react, react-dom, or @nifrajs/core) are installed at different paths. Module identity is path-based, so matching versions do NOT fix it - the copies must resolve to the same directory. Run \`nifra check\` to list the paths.`,
    { cause: err },
  )
  augmented.name = err.name
  // `stack` is optional under exactOptionalPropertyTypes; assigning `undefined` would replace a real
  // stack with nothing on engines that always populate it.
  if (err.stack !== undefined) augmented.stack = err.stack
  return augmented
}

/**
 * An action's control-flow value passes straight through - except a redirect on a client-submit data
 * request: fetch would follow the 3xx into HTML the client can't use, so the redirect rides the
 * X-Nifra-Redirect header on a 204 and the client navigates. One conversion shared by the returned-
 * and thrown- paths, so `return redirect()` and `throw redirect()` agree.
 *
 * Takes either shape: `redirect()` is a plain render, while a hand-rolled `new Response(...)` from an
 * action still arrives as a `Response`. The rewrite stays on the lane its input was on - a plain
 * redirect converts to a plain 204, and never materializes the `Response` it is replacing.
 */
export function actionResponse(
  result: Response | ResponseResult,
  isDataRequest: boolean,
): Response | ResponseResult {
  if (!isDataRequest) return result
  if (isResponseResult(result)) {
    const plain = result.plain
    // No `plain` means a carrier that only knows how to build a `Response` (not one of ours) - fall
    // back rather than guess at its status.
    if (plain === undefined) return actionResponse(result.toResponse(), isDataRequest)
    if (plain.status < 300 || plain.status >= 400) return result
    const location = plain.headers?.location ?? "/"
    return statusResult(204, undefined, { headers: { [REDIRECT_HEADER]: location } })
  }
  if (result.status >= 300 && result.status < 400) {
    const location = result.headers.get("location") ?? "/"
    return statusResult(204, undefined, { headers: { [REDIRECT_HEADER]: location } })
  }
  return result
}

/** A loaded layout module. `loader`/`gate` are the layout-loader surface; `meta` predates it. */
export type LoadedLayoutModules = ReadonlyArray<{
  default: unknown
  meta?: MetaInput
  loader?: LayoutLoader
  action?: unknown
  gate?: boolean
  // A layout may declare its own `searchSchema`; the route's effective search merges the layout chain's
  // schemas with the page's (page-wins). Present on the raw module already - typed here so it is readable.
  searchSchema?: RouteModule["searchSchema"]
  boundaries?: readonly BoundaryRegistration[]
}>

/**
 * Narrow the route's params to the ones a layout owns.
 *
 * A layout wraps a URL prefix, so anything deeper belongs to a route beneath it. Handing it the full
 * set would let a layout read a param it does not own - which reads fine until the layout is reused
 * under a route that has no such param and the value silently becomes `undefined`.
 */
export function scopeParams(
  params: Record<string, string>,
  owned: readonly string[] | undefined,
): Record<string, string> {
  if (owned === undefined) return params // hand-built manifest with no scope info: unchanged behaviour
  if (owned.length === 0) return EMPTY_LAYOUT_PARAMS
  const scoped: Record<string, string> = {}
  for (const name of owned) {
    const value = params[name]
    if (value !== undefined) scoped[name] = value
  }
  return scoped
}

const EMPTY_LAYOUT_PARAMS: Record<string, string> = Object.freeze({})

export const EMPTY_RETAIN: ReadonlySet<number> = new Set<number>()

/**
 * Marks an error as coming from a LAYOUT loader, carrying that layout's id.
 *
 * The boundary that catches it must be at or above the failing layout's own segment. The route's
 * innermost `_error` may live BELOW the layout that failed, and rendering there would wrap the
 * boundary in a layout whose data never arrived - so the page would render inside a component that
 * threw. A registry symbol, matching the other cross-module brands here.
 */
const LAYOUT_ERROR_ID = Symbol.for("nifra.web.layout-error-id")

export const tagLayoutError = (err: unknown, layoutId: string): unknown => {
  if (typeof err === "object" && err !== null && !(LAYOUT_ERROR_ID in err)) {
    Object.defineProperty(err, LAYOUT_ERROR_ID, { value: layoutId, enumerable: false })
  }
  return err
}

export const layoutErrorId = (err: unknown): string | undefined =>
  typeof err === "object" && err !== null
    ? ((err as Record<symbol, unknown>)[LAYOUT_ERROR_ID] as string | undefined)
    : undefined

export const STATUS_SIGNAL = Symbol.for("nifra.web.status-signal")

/** Reason phrases for the plain-text fallback, used only when the app authored no `_<status>` and no
 * `_404` page. Deliberately not exhaustive - anything unlisted falls back to "Error", which is more
 * useful than shipping a table of every RFC status for a body almost nobody will see. */
export const STATUS_TEXT: Readonly<Record<number, string>> = {
  400: "Bad Request",
  401: "Unauthorized",
  402: "Payment Required",
  403: "Forbidden",
  404: "Not Found",
  410: "Gone",
  451: "Unavailable For Legal Reasons",
  500: "Internal Server Error",
}

export interface StatusSignal extends Response {
  readonly [STATUS_SIGNAL]: { readonly status: number; readonly headers?: HeadersLike }
}

export function isStatusSignal(value: unknown): value is StatusSignal {
  return value instanceof Response && STATUS_SIGNAL in value
}

function statusSignal(status: number, options: StatusPageOptions): never {
  if (!Number.isInteger(status) || status < 400 || status > 599) {
    throw new Error(
      `[nifra/web] statusPage(${JSON.stringify(status)}) must be an integer 4xx or 5xx status. Use redirect() for 3xx, and return data for a successful render.`,
    )
  }
  const response = new Response(null, { status })
  // Non-enumerable so the brand never lands in a structured clone or a JSON log of the response.
  Object.defineProperty(response, STATUS_SIGNAL, {
    value: { status, ...(options.headers !== undefined ? { headers: options.headers } : {}) },
    enumerable: false,
  })
  throw response
}

/** 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 function notFound(options: StatusPageOptions = {}): never {
  return statusSignal(404, options)
}

/**
 * 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 function gone(options: StatusPageOptions = {}): never {
  return statusSignal(410, options)
}

/**
 * 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 function statusPage(status: number, options: StatusPageOptions = {}): never {
  return statusSignal(status, options)
}

/** 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 function revalidate<T>(paths: readonly string[], data: T): RevalidateResult<T> {
  return { __nifraRevalidate: paths, data }
}

/**
 * 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 function serializeData(data: unknown): string {
  const serialized = JSON.stringify(data ?? null)
  // Most loader payloads contain no script-sensitive characters. Guard with chained `indexOf`
  // rather than a regex `.test`: each probe is a native memchr-style scan, measured ~7x faster than
  // the regex scan on V8 for a multi-KB payload (and the engine rejects the two >0xFF separator
  // probes in O(1) when the string is internally one-byte, which serialized JSON almost always is).
  // The same four characters are probed as the SCRIPT_ESCAPE class, so any payload the regex would
  // escape still takes the escape path - this is only a cheaper detector, never a security
  // relaxation.
  const needsEscape =
    serialized.indexOf("<") !== -1 ||
    serialized.indexOf(">") !== -1 ||
    serialized.indexOf(LINE_SEP) !== -1 ||
    serialized.indexOf(PARA_SEP) !== -1
  return needsEscape
    ? serialized.replace(SCRIPT_ESCAPE, (ch) => SCRIPT_ESCAPE_MAP[ch] ?? ch)
    : serialized
}

function escapeHtml(value: string): string {
  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;")
}

/**
 * Escape a `<script>` element's text content so it cannot break out of the element. Per the HTML spec,
 * a script's text may contain any character EXCEPT the sequences that the parser treats as element
 * boundaries: `</` (which would begin the end tag - `</script>` is the obvious XSS vector, but ANY `</`
 * starts script-data-end-tag parsing), and the comment/CDATA edges `<!--` / `]]>`. We escape the `<`
 * (and the `>` of `]]>`) to its JS unicode escape: inside a JS/JSON string literal `<` is the
 * identical character, so a JSON-LD payload is byte-equivalent after parsing - but the raw `<`/`>` the
 * HTML tokenizer scans for is gone. This is the JSON-LD-in-HTML rule (content is JSON, never raw HTML),
 * mirroring {@link serializeData}'s posture for the data-global script. Idempotent on already-safe text.
 */
function escapeScriptContent(content: string): string {
  // Order matters: rewrite `]]>` first (its `>` becomes `>`), then every `<` (covers `</` and
  // `<!--` in one pass). `<` → `<`; the lone `>` of `]]>` → `>`. A bare `>` elsewhere is
  // harmless in script data, so only the `]]>` close is targeted for `>`.
  return content.replaceAll("]]>", "]]\\u003e").replaceAll("<", "\\u003c")
}

function escapeAttr(value: string): string {
  return value
    .replaceAll("&", "&amp;")
    .replaceAll('"', "&quot;")
    .replaceAll("<", "&lt;")
    .replaceAll(">", "&gt;")
}

/** Serialize attributes that passed the shared SSR/client head trust policy. */
function tagAttrs(tag: "meta" | "link", attrs: Readonly<object>): string | null {
  const trusted = trustedHeadAttributes(tag, attrs)
  if (trusted === null) return null
  let out = ""
  for (const [name, value] of trusted) {
    if (out !== "") out += " "
    out += value === true ? name : `${name}="${escapeAttr(value)}"`
  }
  return out
}

// Memoize the serialized head-tag string by the resolved `Meta` object's identity. A STATIC route
// `meta` is returned by-reference from resolveMeta, so the same object recurs every request → cache
// hit, and the invariant string is serialized once per route, not per request. Function results are
// never cached, even when a function deliberately reuses one mutable object across requests. WeakMap
// so a route module that's GC'd takes its entry with it.
const headTagsCache = new WeakMap<Meta, string>()

function assertExecutableScriptType(type: string): void {
  if (!EXECUTABLE_SCRIPT_TYPES.has(type)) {
    throw new TypeError(
      `[nifra/web] executable inline scripts accept ${[...EXECUTABLE_SCRIPT_TYPES].map((t) => JSON.stringify(t)).join(" or ")}; received ${JSON.stringify(type)}`,
    )
  }
}

/** Render a route's `meta`/`link`/`script` as managed (`data-nifra`) head tags. Title is set
 * separately. XSS-safe by construction: every attribute flows through the shared tag-specific trust
 * policy then value escaping, and each `script[].content` through `escapeScriptContent`
 * (breakout-escaped) - so loader-derived strings (LLM-authored `og:*`, user content) can't inject markup
 * or close the tag early. String concatenation (no intermediate `.map()` arrays + spread) - parity with
 * the already concat-based preloadLinks/styleLinks/islandPreloads loops; byte-identical output. Result
 * is memoized only for objects observed as static meta exports (serialized once per route). */
function headTags(head: Meta | undefined): string {
  if (head === undefined) return ""
  const cacheable = isStaticMeta(head)
  if (cacheable) {
    const cached = headTagsCache.get(head)
    if (cached !== undefined) return cached
  }
  let out = ""
  if (head.meta !== undefined)
    for (const m of head.meta) {
      const attrs = tagAttrs("meta", m)
      if (attrs !== null) out += `<meta${attrs === "" ? "" : ` ${attrs}`} data-nifra>`
    }
  if (head.link !== undefined)
    for (const l of head.link) {
      const attrs = tagAttrs("link", l)
      if (attrs !== null) out += `<link${attrs === "" ? "" : ` ${attrs}`} data-nifra>`
    }
  // `<script>` slot - JSON-LD + other inert head scripts. `type` is attribute-escaped; `content` is
  // breakout-escaped (`escapeScriptContent`) so a `</script>` (or `<!--`/`]]>`) payload can't close the
  // element early. Managed (`data-nifra`) so a soft-nav's `applyHead` cleanly replaces it.
  if (head.script !== undefined)
    for (const s of head.script) {
      const type = s.type ?? "application/ld+json"
      if (!INERT_SCRIPT_TYPES.has(type)) {
        throw new TypeError(
          `[nifra/web] head.script only accepts inert JSON script types; received ${JSON.stringify(type)}. Use unsafeInlineScript() with a CSP nonce for executable code.`,
        )
      }
      out += `<script type="${type}" data-nifra>${escapeScriptContent(s.content)}</script>`
    }
  if (head.unsafeScript !== undefined)
    for (const s of head.unsafeScript) {
      if (s.unsafe !== true || s.nonce.trim() === "") {
        throw new TypeError("[nifra/web] executable inline scripts require a non-empty CSP nonce")
      }
      // `type` is validated, not escaped, for the same reason as the inert slot above: an unknown
      // value here is a bug, and escaping one would emit a nonsense script type rather than say so.
      // It was interpolated raw while the `nonce` beside it was escaped, so a descriptor built by hand
      // - `unsafeScript` is a public field, the helper is only a convenience - could close the
      // attribute and inject markup. Measured: `type: '"><img src=x onerror=alert(1)>'` reached the
      // document. An injection in the slot whose whole purpose is to make script emission trustworthy.
      assertExecutableScriptType(s.type)
      out += `<script type="${s.type}" nonce="${escapeAttr(s.nonce)}" data-nifra>${escapeScriptContent(s.content)}</script>`
    }
  if (cacheable) headTagsCache.set(head, out)
  return out
}

/**
 * A `<link rel="canonical">` descriptor for a route's `meta.link`. The canonical URL tells search
 * engines which URL is authoritative for a page (deduping query-string / tracking variants).
 *
 * ```ts
 * export const meta = (a) => ({ link: [canonical(`https://site.com/posts/${a.params.slug}`)] })
 * ```
 */
export function canonical(href: string): LinkDescriptor {
  return { rel: "canonical", href }
}

/** 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 function openGraph(input: OpenGraphInput): MetaDescriptor[] {
  const tags: MetaDescriptor[] = []
  const add = (property: string, content: string | undefined): void => {
    if (content !== undefined) tags.push({ property, content })
  }
  add("og:title", input.title)
  add("og:description", input.description)
  add("og:image", input.image)
  add("og:url", input.url)
  // `og:type` always present (the spec's required property) - default "website" when unset.
  tags.push({ property: "og:type", content: input.type ?? "website" })
  return tags
}

/**
 * Build a JSON-LD `<script type="application/ld+json">` entry for a route's `meta.script` from a plain
 * object. `JSON.stringify` produces the body; the head renderer breakout-escapes it (see
 * `escapeScriptContent`), so a string field containing `</script>` is embedded safely.
 *
 * ```ts
 * export const meta = {
 *   script: [jsonLd({ "@context": "https://schema.org", "@type": "Article", headline: "Hi" })],
 * }
 * ```
 */
export function jsonLd(data: Record<string, unknown>): ScriptDescriptor {
  return { type: "application/ld+json", content: JSON.stringify(data) }
}

/**
 * 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 function unsafeInlineScript(
  content: string,
  options: { readonly nonce: string; readonly type?: "module" | "text/javascript" },
): UnsafeScriptDescriptor {
  if (options.nonce.trim() === "") {
    throw new TypeError("[nifra/web] unsafeInlineScript requires a non-empty CSP nonce")
  }
  const type = options.type ?? "module"
  // Checked here as well as at emit: the type union is compile-time only, and this helper is the one
  // place a caller is told what it may pass. Failing at the call site names the argument; failing at
  // render names a document.
  assertExecutableScriptType(type)
  return {
    unsafe: true,
    type,
    nonce: options.nonce,
    content,
  }
}