import { ComponentType } from 'react';
import { PipeableStream } from 'react-dom/server';
import { PreloadSeed } from '@voltro/client';
import { ProcedureInput } from '@voltro/client';
import { ProcedureOutput } from '@voltro/client';
import { ProcedureTypeMap } from '@voltro/client';
import { ReactNode } from 'react';
import { seedPreloadedSubscription } from '@voltro/client';
import { seedPreloadedSubscriptionFailure } from '@voltro/client';
import { StoreSeed } from '@voltro/client';
import { StoreSeedBag } from '@voltro/client';

/**
 * Throw unless this page can actually stream. Verified against React 19.2.7
 * rather than assumed — each rejected combination FAILS SILENTLY otherwise,
 * which is worse than not shipping the feature:
 *
 *  - `renderMode: 'static'` — the prerender uses `renderToString`, which does
 *    not support Suspense: it emits an ERRORED boundary (`<!--$!-->`) plus a
 *    `<template data-msg="Switched to client rendering...">` and no warning.
 *    The artefact would ship a permanent client-rendered fallback.
 *  - `renderMode: 'isr'` — ISR caches a completed HTML STRING. Awaiting the
 *    deferred values to fill that string would make `defer()` a silent no-op
 *    that still reads like it streams; caching a stream is different
 *    machinery entirely.
 *  - `interactive: 'none'` — revealing a boundary needs React's inline
 *    `$RC`/`$RV` scripts, and this mode ships zero JS. The fallback would be
 *    permanent.
 *  - `interactive: 'islands'` — `mount()` returns after `hydrateIslandsOnPage()`
 *    and never hydrates the root, so nothing ever consumes the registry
 *    promises. Islands take their props from their own serialised payload, not
 *    from loader data, so there is no value in wiring them in.
 *
 * The one place `renderMode` is NOT the deciding input is the SSR layout shell
 * (`layoutShell` above): a `renderMode:'spa'` page under an SSR layout chain is
 * streamed per request by dev/serve — so a LAYOUT loader may defer there — and
 * written to a file by the build, where it may not.
 */
export declare const assertDeferralSupported: (target: DeferralTarget) => void;

/**
 * Enter a seed scope for the REST of the current async execution — no callback,
 * no restructuring of the caller.
 *
 * `withStoreSeeds` above is the right shape when a render is already a single
 * expression. The three real boot paths are not: `renderPageForRequest` spans a
 * couple of hundred lines with early returns and a streaming branch that
 * returns from the middle, and wrapping THAT in a callback is a refactor of
 * production render code in exchange for nothing the scope needs.
 *
 * `enterWith` is the Node API for exactly this case: it installs the store for
 * the current async context and everything that flows from it, which for a
 * per-request handler is precisely the intended lifetime. Call it once at the
 * top of a render, then read `currentStoreSeeds()` / `currentPreloadSeeds()`
 * where the payload is built.
 *
 * Do NOT call it from a long-lived context (a module top level, a server
 * bootstrap): there it would install one bag for the whole process, which is
 * the leak the scoping exists to prevent.
 *
 * Returns the STORE bag so existing callers keep their `{ seeds }` shape; the
 * preload bag is installed into the same scope and read via
 * `currentPreloadSeeds()`.
 */
export declare const beginStoreSeeds: () => StoreSeedBag;

/** The current request's preloaded-subscription seeds, or null outside a render. */
export declare const currentPreloadSeeds: () => ReadonlyArray<PreloadSeed> | null;

/** The current request's store seeds, or null outside a render. Tests + diagnostics. */
export declare const currentStoreSeeds: () => ReadonlyArray<StoreSeed> | null;

/** Render modes / interactive modes a page may combine with `defer()`. */
export declare interface DeferralTarget {
    /** Route pattern or source file — named in the error so it is actionable. */
    readonly page: string;
    readonly renderMode: string;
    readonly interactive: string;
    /**
     * Set ONLY on the SSR-layout-shell path — a `renderMode:'spa'` page under an
     * SSR layout chain, where the server renders the LAYOUTS around an empty page
     * slot and runs only the layout loaders. `renderMode` is `'spa'` there, so
     * without this the shell would be rejected by the rule below; the thing that
     * actually decides whether it can stream is HOW the shell is delivered:
     *
     *  - `'stream'` — a per-request response (`voltro dev` / `voltro serve`). It
     *    goes out through `renderPageToStream`, so a LAYOUT loader may `defer()`:
     *    the chain + empty slot flush immediately and the deferred value streams
     *    in behind its `<Await>` boundary, exactly as on an `ssr` page.
     *  - `'artefact'` — the build-time prerender, which writes an HTML FILE. A
     *    file has no "after", so `defer()` is refused there by name.
     *
     * Absent for every full-page render, where `renderMode` alone decides.
     */
    readonly layoutShell?: 'stream' | 'artefact' | undefined;
}

/** Brand key on the object `defer()` returns. A single explicit container
 *  check — NOT a scan of arbitrary loader results for markers by shape. */
declare const DEFERRED_RESULT_TAG: "__voltroDeferredLoaderResult";

/** What a loader returns when it defers part of its data. Opaque to user
 *  code: build it with {@link defer}, read it with `useLoaderData()`. */
declare interface DeferredLoaderResult<TEager extends object = object, TDeferred extends Record<string, Promise<unknown>> = Record<string, Promise<unknown>>> {
    readonly [DEFERRED_RESULT_TAG]: true;
    /** Awaited before the shell renders — present in the SSR markup AND in the
     *  inlined `__voltro_state__` payload. */
    readonly eager: TEager;
    /** Streamed after the shell — each key becomes a promise on
     *  `useLoaderData()`, to be rendered through `<Await>`. */
    readonly deferred: TDeferred;
}

/** Build the wire payload from what the server render was given. */
export declare const encodeRouterState: (input: RouterStateInput) => InlinedRouterState;

declare interface ErrorBoundaryProps {
    readonly error: unknown;
    readonly reset: () => void;
}

/**
 * The wire shape. JSON cannot express `undefined`, which is why `ran` exists
 * as a separate presence record: a loader that returned `undefined` is
 * otherwise indistinguishable from one that never ran, and the client would
 * re-run it on hydration (the flash this whole payload exists to remove).
 */
export declare interface InlinedRouterState {
    /** The pathname the server rendered THIS document for.
     *
     *  Present so the client can tell "the server rendered my route" from "a
     *  static host handed me some other route's document as its SPA fallback".
     *  Without it the two are indistinguishable — the payload parses either way,
     *  and `mount()` would adopt markup for a route it is not on. */
    readonly path?: string;
    /** The page (leaf) loader's result — exactly the value the server render
     *  provided to the page's `LoaderDataContext`. */
    readonly page?: unknown;
    /** Per-layout loader results keyed by CHAIN INDEX (as a JSON string key).
     *  The index is the same one `descriptor.chain[i]` uses on both sides —
     *  see `wrapInChain` in ssr.tsx and in router.tsx. */
    readonly segments?: Readonly<Record<string, unknown>>;
    /** Which loaders actually RAN server-side. Drives cache seeding (i.e.
     *  "don't re-run this on hydration"); the values above drive the render. */
    readonly ran?: {
        readonly page?: boolean;
        readonly segments?: ReadonlyArray<number>;
    };
    /** True when the server rendered the layout chain but left the page leaf as
     *  an EMPTY slot — the `renderMode:'spa'`-under-an-SSR-layout case. The
     *  server ran only the layout loaders; the page is client-only. The client's
     *  FIRST render must reproduce the identical empty slot so the layout chain
     *  hydrates without a mismatch, then mount the real page after commit. Absent
     *  (falsy) for every full-page SSR/ISR/static document. */
    readonly pageClientOnly?: boolean;
    /**
     * Client-store values the server seeded for this document.
     *
     * Rides HERE rather than in a channel of its own, on purpose: a second
     * payload would mean a second thing to emit, a second thing to parse, and a
     * second thing to forget on one of the three SSR paths. `mount` applies these
     * before the first render, so a store a loader seeded is already full when
     * hydration compares the trees.
     */
    readonly storeSeeds?: ReadonlyArray<{
        readonly store: string;
        readonly key?: string;
        readonly value: unknown;
    }>;
    /**
     * Preloaded-subscription first values the server seeded for this document
     * (see `seedPreloadedSubscription` in `@voltro/client`). Rides the same
     * payload as `storeSeeds` for the same reason: one thing to emit, parse, and
     * remember on all three SSR paths. `mount` applies them before the first
     * render so `usePreloadedSubscription` shows real data with no flash.
     */
    readonly preloadSeeds?: ReadonlyArray<{
        readonly api: string;
        readonly key: string;
        readonly value: unknown;
    }>;
    /** Deferred (streamed) loader fields: field name -> client-registry id, for
     *  the page loader and per chain index. The VALUES are not here — they
     *  arrive later, published by the settle `<script>` each `<Await>` boundary
     *  emits as its promise resolves. Absent entirely when nothing deferred, so
     *  a non-deferring page's payload is byte-identical to what it always was. */
    readonly deferred?: {
        readonly page?: Readonly<Record<string, string>>;
        readonly segments?: Readonly<Record<string, Readonly<Record<string, string>>>>;
    };
}

/**
 * How the client-side JS hydrates a server-rendered page.
 *
 *   - 'full'    — Hydrate the entire page tree as one React root.
 *                 Default for `'spa'` pages and the safe default for
 *                 `'static'` pages that haven't been thought through.
 *                 Subscriptions + interactivity work everywhere.
 *   - 'islands' — Skip the full-tree hydration. The client runtime
 *                 only hydrates `<div data-voltro-island>` markers
 *                 emitted by `island()`. Other parts of the page stay
 *                 pure static HTML with no React lifecycle running.
 *                 Best perf for content-heavy pages with isolated
 *                 interactive zones.
 *
 * Defaults to `'full'` when not specified.
 */
declare type InteractiveMode = 'full' | 'islands' | 'none';

/** True for exactly the object {@link defer} returns. */
export declare const isDeferredLoaderResult: (value: unknown) => value is DeferredLoaderResult;

/**
 * What a `loader` receives.
 *
 * **It runs on the server AND again in the browser.** A loader is not a
 * server-only hook: it runs during SSR for the first paint, and then runs
 * AGAIN, in the browser, on every in-app navigation to the route. Same
 * function, different environment.
 *
 * That precondition was never written down, and a deployment read "runs once per
 * request" into the gap — which is the reading the wording invites. It cost
 * them two days, and the reason it survived that long is the nastiest part: a
 * client-only failure is invisible to every probe that does not NAVIGATE. A
 * fresh page load, a `curl`, any SSR check goes through the server path and
 * passes. Only clicking a link inside the running app reaches the other one.
 *
 * So anything server-only in a loader must be guarded by {@link isServer}.
 */
declare interface LoaderContext<Procedures = unknown> {
    readonly params: Readonly<Record<string, string>>;
    readonly pathname: string;
    /**
     * `true` when this invocation is the SERVER one (SSR under `voltro dev` or
     * `voltro start`), `false` in the browser.
     *
     * Exists because the alternatives are traps. `query` is absent in the browser
     * and so reads as a discriminator, but branching on the ABSENCE OF A FUNCTION
     * says nothing about why it is absent and breaks the moment anything else
     * becomes conditional. `headers` is worse: it is `{}` in the browser, not
     * `undefined`, so `ctx.headers ? …` is TRUE on both paths — a deployment
     * checked exactly that and it silently did nothing.
     *
     *     export const loader = async (ctx: LoaderContext) => {
     *       if (ctx.isServer) seedStore(prefs, await ctx.query!('prefs.get'))
     *       return null
     *     }
     *
     * REQUIRED, not optional: an optional boolean is omissible, and a server path
     * that forgot it would read as `undefined` — falsy — and claim to be the
     * browser. Required means the compiler names every construction site.
     */
    readonly isServer: boolean;
    /**
     * The raw query string, INCLUDING the leading `?`, or `''` when there is
     * none. Filled on every path — client navigation, `voltro dev` SSR and
     * `voltro start` SSR.
     *
     * `pathname` deliberately excludes the query string, and for DATA that is
     * right: a loader keyed on `?tab=2` would cache badly. It is wrong for
     * CONTROL FLOW, which is what a loader does when it throws `RedirectError` —
     * a redirect target routinely depends on a query parameter, and until this
     * existed the only place a redirect belongs was the only place without access
     * to it.
     *
     * The reported case: a page redirects an unknown code back to the entry page
     * and must preserve `?mode=kiosk`, or a kiosk terminal drops to normal mode
     * after every failed scan. Both workarounds are bad — moving the redirect
     * into a component gives up the 303, and `window.location.search` only exists
     * on the client-navigation path, so a fresh SSR request loses the mode.
     *
     * Parse it with `new URLSearchParams(ctx.search)`.
     */
    readonly search: string;
    /** Aborted when the user navigates away before the loader resolves. */
    readonly signal: AbortSignal;
    /** Request headers when the loader runs server-side via `voltro
     *  start`. Lowercased keys. Empty `{}` for client-side loader
     *  invocations (browser-fetch goes through the rpc layer, not the
     *  loader). Use this for tenant resolution, auth headers, etc.
     *  until the auth slice ships a typed Subject. */
    readonly headers?: Readonly<Record<string, string>>;
    /** Server-side one-shot rpc fetch. Invokes any backend rpc (queries
     *  included — the FIRST snapshot of a streaming query is resolved and
     *  returned) over the api's HTTP rpc surface (`POST /rpc`), forwarding
     *  the request's `cookie` header so the api resolves the same Subject +
     *  tenant the WS path would. Bound to the app's single / first api.
     *
     *  Present ONLY when the loader runs server-side (`voltro start` /
     *  `voltro dev` SSR). `undefined` for client-side loader invocations —
     *  in the browser, use `useSubscription` in the component for live data
     *  instead; the loader's `query` is for SSR first-paint + `meta`.
     *
     *  UNTYPED by default, and typed by naming your app's procedure map — the
     *  same map `createHooks` already takes, and the same extraction, so the two
     *  cannot disagree about what a tag returns:
     *
     *      import type { AppProcedures } from '<your-api>/rpcGroup'
     *
     *      export const loader = async ({ query }: LoaderContext<AppProcedures>) => {
     *        const rows = await query?.('bookmarks.list', { limit: 100 })
     *        //    ^ inferred from the descriptor, and an unknown tag is an error
     *      }
     *
     *  The default parameter keeps every existing loader compiling: with no map
     *  the signature is the old `<T = unknown>(tag: string, …)`. It is opt-in for
     *  the same reason `createHooks<AppProcedures>` is — the framework cannot
     *  import an app's generated file, so the app has to name it. */
    readonly query?: LoaderQuery<Procedures>;
}

declare type LoaderFn<T = unknown, Procedures = unknown> = (ctx: LoaderContext<Procedures>) => Promise<T> | T;

/**
 * The loader's server-side `query`, typed by a procedure map when one is given.
 *
 * Reuses `ProcedureInput` / `ProcedureOutput` from `@voltro/client` rather than
 * re-deriving them. A second extraction would be a second answer to "what does
 * this tag return", and the two would drift the first time a descriptor field
 * is renamed — the shape this repo already has scars from.
 */
declare type LoaderQuery<Procedures = unknown> = Procedures extends ProcedureTypeMap ? <Tag extends keyof Procedures & string>(tag: Tag, ...input: Record<string, never> extends ProcedureInput<Procedures[Tag]> ? [input?: ProcedureInput<Procedures[Tag]>] : [input: ProcedureInput<Procedures[Tag]>]) => Promise<ProcedureOutput<Procedures[Tag]>> : <T = unknown>(tag: string, input?: Record<string, unknown>) => Promise<T>;

declare interface PageDescriptor<TLoaderData = unknown> {
    /** URL pattern, e.g. `/`, `/about`, `/users/[id]`, `/docs/[...slug]`. */
    readonly pattern: string;
    /** The page component. Present on eager routes; on a LAZY route (see
     *  `load`) it's filled by the Router once the page chunk has loaded. */
    readonly Component?: ComponentType | undefined;
    /** LAZY route: a thunk that dynamically imports the page module. When set,
     *  the page chunk is fetched only when this route first matches, so the
     *  initial bundle never imports every page. The Router resolves
     *  `Component` / `loader` / `meta` / … from the loaded module; the layout
     *  `chain` stays eager. */
    readonly load?: (() => Promise<Record<string, unknown>>) | undefined;
    /** Static meta, or a function of `{ params, loaderData, locale }` —
     *  so a document title can read what the page loader fetched (the
     *  dynamic metadata case) AND can localise per-locale at SSG time
     *  for URL-prefix i18n routing. `loaderData` is the page loader's
     *  result; `locale` is the active i18n locale during pre-render
     *  (driven by `params.locale` for `[locale]/...` routes, falling
     *  back to the app's defaultLocale). On the client, `locale` is
     *  the URL-derived locale when the route is locale-prefixed,
     *  otherwise the framework's resolved locale (cookie / Accept-
     *  Language / default). */
    readonly meta?: PageMeta | ((ctx: {
        readonly params: Readonly<Record<string, string>>;
        readonly loaderData: unknown;
        readonly locale: string;
    }) => PageMeta) | undefined;
    /** Async data preload; result available via useLoaderData<T>(). */
    readonly loader?: LoaderFn<TLoaderData> | undefined;
    /** Catches render + loader errors for THIS leaf. Tighter scope than `chain[*].Error`. */
    readonly ErrorBoundary?: ComponentType<ErrorBoundaryProps> | undefined;
    /** Shown while the loader is in flight (first navigation to the route). */
    readonly Pending?: ComponentType | undefined;
    /**
     * Outer-to-inner layer chain. Each segment maps to one directory level
     * (or route group) on the way from the pages root down to this leaf.
     * Codegen produces this from the discovery walk; user code rarely
     * writes it by hand.
     */
    readonly chain?: ReadonlyArray<RouteSegment> | undefined;
    /** How the page's HTML is produced. Defaults to 'static' so pages
     *  pre-render by default — SEO + first-paint speed are wins users
     *  pay nothing for. Opt out with `'spa'` for pages that need a
     *  per-request render. */
    readonly renderMode?: RenderMode | undefined;
    /** How the page's client-side JS hydrates. Defaults to `'full'`
     *  (whole tree). Pages designed around the islands pattern should
     *  set this to `'islands'` so only marked interactive zones
     *  hydrate; the rest stays pure static HTML. */
    readonly interactive?: InteractiveMode | undefined;
}

declare interface PageMeta {
    readonly title?: string;
    readonly description?: string;
    /** Canonical URL for this page. Emitted as `<link rel="canonical">`.
     *  Relative paths are accepted — search engines resolve them
     *  against the document's base URL. Use this on duplicated routes
     *  (locale variants, alternate URL forms) to declare the preferred
     *  one indexable URL. */
    readonly canonical?: string;
    /** Arbitrary additional meta tags. `name` OR `property` is required. */
    readonly tags?: ReadonlyArray<{
        readonly name?: string;
        readonly property?: string;
        readonly content: string;
    }>;
    /** Arbitrary additional `<link>` tags. Use for `alternate` hreflang,
     *  prev/next pagination, RSS feeds, manifest, etc. (For the common
     *  canonical case, prefer the dedicated `canonical` field above.) */
    readonly links?: ReadonlyArray<{
        readonly rel: string;
        readonly href: string;
        readonly hreflang?: string;
        readonly type?: string;
        readonly title?: string;
    }>;
    /** JSON-LD structured-data payloads. Each entry is emitted as a
     *  separate `<script type="application/ld+json">` so search engines
     *  and LLM crawlers can pick up rich metadata (Article, Product,
     *  SoftwareApplication, BreadcrumbList, FAQPage, etc.). Anything
     *  JSON-serialisable is accepted; `@context` + `@type` are
     *  authored, not synthesised. */
    readonly jsonLd?: ReadonlyArray<Record<string, unknown>>;
    /** Keep this page out of the index. Emits
     *  `<meta name="robots" content="noindex, nofollow">`, and the build's
     *  `sitemap.xml` generator EXCLUDES the route. Use for utility pages
     *  (checkout steps, previews, thank-you pages) that should not rank. */
    readonly noIndex?: boolean;
}

export declare const parseCookieHeader: (raw: string | undefined) => Record<string, string>;

/**
 * Split one loader result for a streaming render. `scope` is `'page'` for the
 * page loader or the layout's chain index, and only feeds the registry id.
 */
export declare const prepareDeferredLoaderData: (result: unknown, scope: "page" | number) => PreparedLoaderData;

/** One loader's result, prepared for a streaming SSR render. */
export declare interface PreparedLoaderData {
    /** What the RENDERER gets: eager fields plus one tagged promise per
     *  deferred field. Identical to the plain result when nothing deferred. */
    readonly renderData: unknown;
    /** What the `__voltro_state__` payload gets: eager fields only. A promise
     *  serialises to `{}`, so the deferred half must never reach it. */
    readonly stateData: unknown;
    /** Deferred field name -> registry id, for the state payload. `undefined`
     *  when the loader did not defer — the wire shape is then byte-identical
     *  to what a non-deferring page has always emitted. */
    readonly deferredIds: Readonly<Record<string, string>> | undefined;
}

/**
 * How a page's HTML is produced.
 *
 *   - 'static'  — Pre-rendered to flat HTML at build time. Default.
 *                 Shipped as `dist/<route>/index.html`. JS bundle
 *                 still loads to hydrate islands + handle SPA-style
 *                 navigation, but the first paint is instant + SEO
 *                 friendly. Loaders MUST be side-effect-free + must
 *                 not require per-request context (subject, headers).
 *   - 'spa'     — Client-only rendering. No HTML pre-render; the
 *                 shipped HTML is a shell that mounts on the
 *                 client. Useful for pages that genuinely need a
 *                 fresh client render every load (most reactive
 *                 dashboards).
 *
 *   - 'ssr'  — Rendered on every request, server-side, via `voltro
 *               start`. Loaders run per request with access to
 *               `headers` + `query` (the api HTTP rpc); the resolved
 *               HTML is sent fresh each time. Use for personalised /
 *               tenant-scoped first paint.
 *   - 'isr'  — Like 'ssr' on the first request, then cached and
 *               revalidated in the background on a TTL.
 *
 * The value set is single-sourced from {@link RENDER_MODES} so the type and
 * every runtime check derive from ONE literal list. There are no aliases — an
 * unrecognised value is rejected at codegen/discovery time by the CLI, not
 * silently passed through.
 */
declare const RENDER_MODES: readonly ["static", "spa", "ssr", "isr"];

/**
 * The `<script>` every streaming SSR emitter puts in `<head>`, before the
 * shell. Must precede any settle script — which is automatic, since settle
 * scripts ride in the body.
 */
export declare const renderDeferredRegistryScript: () => string;

/**
 * Helper for the build pipeline: stringify the resolved meta into a
 * `<head>`-ready HTML fragment. Returns an empty string when no meta
 * is set so the caller can blindly inject the result.
 */
export declare const renderMetaToHtml: (meta: PageMeta | null) => string;

/**
 * A page's render mode — one of {@link RENDER_MODES}, from which this type is
 * derived. Closed set: an unrecognised value is rejected at codegen time.
 */
declare type RenderMode = (typeof RENDER_MODES)[number];

export declare interface RenderPageOptions {
    /** Descriptor produced by codegen (`pageRoute(...)`). */
    readonly descriptor: PageDescriptor;
    /** URL pattern's resolved params. `{}` for static, no-param routes. */
    readonly params: Readonly<Record<string, string>>;
    /** Pathname this render resolves under. Used by `useLocation()` on
     *  the server side. Query-free by contract — see {@link RenderPageOptions.search}. */
    readonly pathname: string;
    /**
     * The request's query string, INCLUDING the leading `?` (or `''`).
     *
     * The server used to hardcode `''` here, on the grounds that the client reads
     * `window.location.search` on hydration. That is true, and it is exactly why
     * discarding it was a defect: the client reading the REAL value is what turns
     * a dropped query string into a hydration mismatch, on every page whose markup
     * depends on `?tab=…`. Reported from a real deployment against a sidebar's active-item
     * highlight on `/teams/:id?tab=…`.
     *
     * Omitted on the STATIC prerender, where there is genuinely no request and one
     * artefact serves every visitor — `''` is the truthful value there.
     */
    readonly search?: string;
    /** Page (leaf) loader data — pre-resolved by the caller. The build /
     *  SSR pipeline runs the descriptor's `loader` (if any) and passes the
     *  result here; reachable via `useLoaderData()` inside the page. */
    readonly loaderData: unknown;
    /** Per-layout loader data, keyed by chain-segment index. The pipeline
     *  runs each `chain[i].loader` and passes the results here; each layout
     *  reads ITS own via `useLoaderData()`. Omit when no layout loaders. */
    readonly segmentLoaderData?: Readonly<Record<number, unknown>>;
    /** Request snapshot (cookies + headers) exposed to the rendered tree
     *  via `useServerRequest()`. Optional: omit on builds (static
     *  prerender) where no per-request data exists; provide on
     *  per-request SSR so consumers can resolve cookie-driven preferences
     *  like locale or theme. */
    readonly requestContext?: ServerRequestContextValue;
    /** Outer wrapper to apply around the rendered tree. The build and
     *  the SSR runtime pass an `<I18nProvider>` wrapper here when the
     *  consumer app has `locales` configured — without it, any page
     *  calling `useT()` would crash at render time ("Could not find
     *  required `intl` object"). The wrapper is generic on purpose:
     *  any cross-cutting provider (i18n, theme, feature-flag context)
     *  rides this slot so `@voltro/web` stays free of optional deps. */
    readonly outerWrap?: (children: ReactNode) => ReactNode;
    /** Active locale for this render. Drives meta resolution so a page's
     *  `meta` function can localise title / description / canonical /
     *  hreflang per locale. The build passes `params.locale ?? defaultLocale`
     *  so locale-prefixed routes (`[locale]/...`) get their per-locale
     *  catalog at meta-resolve time. Optional: when absent, page
     *  `meta(ctx)` callbacks see `ctx.locale = 'en'` as a safe default. */
    readonly locale?: string;
    /** Render the LAYOUT CHAIN ONLY, with an empty page slot at the leaf
     *  ({@link PageSlot}) instead of the page Component — the
     *  `renderMode:'spa'`-under-an-SSR-layout case. The caller runs only the
     *  layout loaders (not the page loader) and pairs this with a state script
     *  carrying `pageClientOnly: true`, so the client reproduces the empty slot
     *  on its first render and mounts the page after hydration. When set, the
     *  descriptor need not carry a `Component`. */
    readonly pageSlot?: boolean;
}

export declare interface RenderPageResult {
    /** HTML for the page body — goes inside `<div id="root">…</div>`. */
    readonly html: string;
    /** Resolved page meta (after running the descriptor's `meta`
     *  function with `params` if present). Caller renders this into
     *  the document head. */
    readonly meta: PageMeta | null;
}

export declare interface RenderPageStreamOptions extends RenderPageOptions {
    /** Called once React commits the shell (all Suspense boundaries that
     *  weren't deferred have resolved). Flush the `<head>` (with `meta`) +
     *  opening `<body>` here, then pipe the returned stream into the response.
     *  The build pipeline uses this to send bytes before the whole tree is
     *  ready — the streaming-SSR win over `renderToString`. */
    readonly onShellReady?: () => void;
    /** Called if the shell itself fails to render (before any bytes flushed) —
     *  the pipeline should fall back to an error page / a 500. */
    readonly onShellError?: (error: unknown) => void;
    /** Called when the ENTIRE tree (incl. deferred Suspense content) has
     *  streamed. Close the response's trailing `</body></html>` here. */
    readonly onAllReady?: () => void;
    /** Bootstrap `<script>` module URLs injected by React at the end of the
     *  shell — the client bundle that hydrates the streamed HTML. */
    readonly bootstrapModules?: ReadonlyArray<string>;
}

export declare interface RenderPageStreamResult {
    /** The React pipeable stream. `pipe(res)` into a Node writable to flush the
     *  page body; `abort()` to cancel a slow render. */
    readonly stream: PipeableStream;
    /** Resolved page meta — available synchronously (meta runs before render),
     *  so the caller can write `<head>` in `onShellReady` before piping. */
    readonly meta: PageMeta | null;
}

/**
 * Render a page to an HTML string using its layout chain + loader data. The
 * returned `html` is the body fragment — the caller composes the surrounding
 * document. Renders synchronously via `renderToString`.
 *
 * This is the ARTEFACT renderer: static prerender and ISR, both of which need
 * the whole document. See the doctrine note above before switching a caller to
 * {@link renderPageToStream}.
 */
export declare const renderPageToHtml: (options: RenderPageOptions) => RenderPageResult;

/**
 * Streaming SSR — the RESPONSE renderer, for `renderMode: 'ssr'`. Renders via
 * React's `renderToPipeableStream` so the server can flush the shell (and each
 * Suspense boundary as it resolves) instead of buffering the whole document
 * into one string. Same tree, same providers, same meta as the sync path.
 *
 * The caller drives the response: write the doctype + `<head>` (using the
 * synchronously-returned `meta`) + opening `<body><div id="root">` in
 * `onShellReady`, pipe the stream, then close the document once it ends.
 * Both boot paths do that through ONE shared helper —
 * `streamSsrResponse` in `@voltro/cli`'s `ssrShell.ts` — rather than
 * hand-mirroring the sequence, which is the drift class that previously cost
 * this pipeline its layout-loader data in dev.
 *
 * Two details the caller MUST get right, both learned the hard way:
 *
 *  - **Pass `bootstrapModules`, don't leave the entry `<script type="module">`
 *    in the shell.** A plain module script is deferred until the document is
 *    fully parsed — on a streamed response that is AFTER the last deferred
 *    boundary, which deletes the entire benefit. React emits `bootstrapModules`
 *    as `async` at the end of the shell instead.
 *  - **Pipe through a `PassThrough`.** React's `pipe()` calls `end()` on the
 *    destination itself, so writing the closing `</div>` + shell tail straight
 *    to the response would land after it was already closed.
 */
export declare const renderPageToStream: (options: RenderPageStreamOptions) => RenderPageStreamResult;

/**
 * The hydration payload, with this request's client-store seeds AND
 * preloaded-subscription seeds folded in.
 *
 * The fold happens HERE and nowhere else on purpose. There are three
 * independent SSR emitters, and every one of them already calls this function —
 * so a seed cannot be collected in dev and dropped in production, which is the
 * failure mode this repo pays for most often. The alternative (each emitter
 * passing `storeSeeds` itself) is three chances to forget and one silent
 * difference between environments.
 *
 * An explicit `storeSeeds` / `preloadSeeds` on the input still wins, so the
 * build-time prerender can pass a set it computed some other way.
 */
export declare const renderRouterStateScript: (input: RouterStateInput) => string;

/** id of the `<script type="application/json">` tag carrying the payload. */
export declare const ROUTER_STATE_SCRIPT_ID = "__voltro_state__";

export declare interface RouterStateInput {
    /** The pathname this render is FOR. Every emitter has it — it is the same
     *  value handed to the renderer as `pathname` — and passing it is required
     *  rather than optional on purpose: a payload without it cannot be matched
     *  against the document it lands in, which is the whole point of carrying
     *  it (see {@link parseRouterState}). */
    readonly path: string;
    /** Page loader result passed to `renderPageToHtml` / `renderPageToStream`. */
    readonly loaderData: unknown;
    /** Layout loader results, keyed by chain index — the same object passed to
     *  the renderer, so the inlined payload cannot disagree with the markup. */
    readonly segmentLoaderData?: Readonly<Record<number, unknown>> | undefined;
    /** Whether the page module actually exported a `loader`. Not derivable from
     *  `loaderData` (a loader may legitimately resolve to `undefined`/`null`,
     *  and the SSR paths default the field to `null` when there is no loader). */
    readonly pageLoaderRan: boolean;
    /** Client-store values seeded during this render (see `InlinedRouterState`). */
    readonly storeSeeds?: ReadonlyArray<{
        readonly store: string;
        readonly key?: string;
        readonly value: unknown;
    }>;
    /** Preloaded-subscription first values seeded during this render (see
     *  `InlinedRouterState`). */
    readonly preloadSeeds?: ReadonlyArray<{
        readonly api: string;
        readonly key: string;
        readonly value: unknown;
    }>;
    /** Set by the SSR-layout-shell path (a `renderMode:'spa'` page under an SSR
     *  layout chain): the server rendered the layouts + an empty page slot and
     *  ran only the layout loaders. Tells the client to reproduce the empty slot
     *  on its first render, then mount the page after hydration. Omit for every
     *  full-page render. */
    readonly pageClientOnly?: boolean | undefined;
    /** Page-loader deferred fields: name -> registry id. Produced by
     *  `prepareDeferredLoaderData` in the SSR pipeline; omit when nothing
     *  deferred (which is every non-streaming emitter). */
    readonly deferredPageIds?: Readonly<Record<string, string>> | undefined;
    /** Layout-loader deferred fields, keyed by chain index. */
    readonly deferredSegmentIds?: Readonly<Record<number, Readonly<Record<string, string>>>> | undefined;
}

/**
 * One layer in a page's nesting chain. Each represents a directory level
 * in the file-convention layout (or a route group).
 *
 * Layouts wrap their children — outer layers wrap inner ones. Errors are
 * caught by the deepest layer with an `Error` component; if none, the
 * error bubbles up the chain. NotFound applies when an URL is under this
 * layer's scope but no concrete page matches.
 *
 * The chain persists across navigation within its scope — React preserves
 * the layout component instances because their position in the tree is
 * stable for any leaf within that subtree.
 */
declare interface RouteSegment {
    /** Outer-vs-inner ordering label (debug only). */
    readonly id?: string | undefined;
    readonly Layout?: ComponentType<{
        children: ReactNode;
    }> | undefined;
    readonly Error?: ComponentType<ErrorBoundaryProps> | undefined;
    readonly Pending?: ComponentType | undefined;
    readonly NotFound?: ComponentType | undefined;
    /** Async data preload for THIS layout level. Runs in parallel with the
     *  page loader (and the other layouts') before mount; the result is
     *  reachable via `useLoaderData<T>()` from INSIDE this layout (each
     *  level sees its own loader's data). A `layout.tsx` exports it like a
     *  page does — codegen wires it onto the segment. Server-side it
     *  receives request `headers` (session/tenant resolution). */
    readonly loader?: LoaderFn | undefined;
}

export { seedPreloadedSubscription }

export { seedPreloadedSubscriptionFailure }

/**
 * Serialise arbitrary data for inlining into an HTML `<script>` body.
 *
 * Escaping `<` is the well-known SSR XSS fix: it makes a `</script>` inside a
 * string value un-parseable as a closing tag while staying valid JSON (`\u003c`
 * decodes back to `<`), so no consumer has to un-escape anything.
 */
export declare const serialiseStateForInlining: (state: unknown) => string;

declare interface ServerRequestContextValue {
    readonly cookies: Readonly<Record<string, string>>;
    readonly headers: Readonly<Record<string, string>>;
    /** Raw request URL as it came off the wire (path + query). Useful
     *  for SSR pages that need to read `?q=…` style search params
     *  without touching anything client-only. Empty string for build-
     *  time SSG renders where there is no incoming request. */
    readonly url: string;
}

/**
 * Run one request's render with a fresh seed bag; return what it collected
 * alongside the render's own result.
 *
 * Wrap the WHOLE render — page loader, layout loaders AND the React render —
 * not just the loaders. A component may seed during SSR (a modal deciding its
 * own initial step), and a bag closed after the loaders would drop that
 * silently.
 */
export declare const withStoreSeeds: <T>(render: () => Promise<T>) => Promise<{
    readonly result: T;
    readonly storeSeeds: ReadonlyArray<StoreSeed>;
    readonly preloadSeeds: ReadonlyArray<PreloadSeed>;
}>;

export { }