@gyral/ssr

npm install @gyral/ssr

function contentSecurityPolicy(options?: CspOptions): Promise<string>;

function formAction<Schema extends StandardSchemaV1>(definition: FormDefinition<Schema>, handlers: FormActionHandlers<StandardSchemaV1.InferOutput<Schema>>): (request: Request) => Promise<Response>;

function rejectWith(issues: string | readonly FieldIssue[]): FormReject;

function renderPage(options: PageOptions, init?: ResponseInit): Response;

function renderToString(value: ChildValue, options?: RenderOptions): Promise<string>;

function seeOther(location: string): Response;

function styleHashes(): Promise<readonly string[]>;

const wantsJson: (request: Request) => boolean

interface ComponentAssets {
    /** URL of the loader module, which imports each rendered tag's module when it's in the page. */
    readonly loader: string;
    /** Tag → its client module. A rendered tag missing here won't hydrate (development warns). */
    readonly modules: ReadonlyMap<string, ComponentModule>;
    /** The loader's own imports, preloaded with it (production). */
    readonly preload?: readonly string[];
    /** More module scripts for pages with components (development: Vite's client). */
    readonly scripts?: readonly string[];
}

interface ComponentModule {
    /** The module's chunk and its static imports (production; empty in development). */
    readonly preload: readonly string[];
    /** Hashed CSS the module imports (production; empty in development). */
    readonly stylesheets: readonly string[];
}

type CspDirectives = Readonly<Record<string, string | readonly string[]>>;

interface CspOptions {
    /**
     * Precomputed component `<style>` hashes from `styleHashes()` at build time. Append them
     * to registered component hashes, allowing a policy-only server to read JSON metadata
     * without executing every component module. Regenerate with each release's actual CSS.
     */
    readonly componentStyleHashes?: readonly string[];
    /**
     * Your other directives (`default-src`, `script-src`, …). A `style-src` given here is kept
     * and the hashes are appended; without one it is `'self'` plus the hashes.
     */
    readonly directives?: CspDirectives;
    /**
     * The page's global styles, exactly as passed to `renderPage({ styles })`, hashed too. In
     * `renderPage({ csp })` it defaults to the page's own `styles`.
     */
    readonly styles?: string | readonly string[];
    /**
     * The page's inline head scripts, exactly as passed to `renderPage({ headScripts })`, allowed in
     * `script-src` by hash (a `script-src` given in `directives` is kept and the hashes appended;
     * without one it is `'self'` plus the hashes). In `renderPage({ csp })` it defaults to the
     * page's own `headScripts`.
     */
    readonly scripts?: string | readonly string[];
    /**
     * `'hash'` (`renderPage` only, ADR 0020): allow the `style` attributes the page writes by
     * hash, in `style-src-attr` with `'unsafe-hashes'`, so they apply on first paint under a
     * strict policy. The page is rendered to a string before the response is built (its
     * headers need every value), so the body isn't chunked. Covers static, bound, multi-part and
     * element-hook values, not `raw()` markup. A `style-src-attr` given in `directives` is kept;
     * when it allows `'unsafe-inline'`, no hashes are added (a hash would disable it).
     */
    readonly styleAttributes?: 'hash';
    /**
     * The most `style` attribute hashes one page's header lists (default 128, about 7 KB of
     * header; proxies reject large headers). Values past it are left out and logged once;
     * hydration applies them.
     */
    readonly maxStyleHashes?: number;
}

interface FormActionHandlers<T> {
    /**
     * The form's `data-intent` name. It becomes `IntentRejected.intent`, exactly as on the
     * JS path, so the component's reducer can't tell the two apart.
     */
    readonly intent: string;
    /**
     * Valid submission: do the work, then usually `seeOther(url)` (Post/Redirect/Get), or return
     * `rejectWith(…)` when a server-only check fails.
     */
    readonly valid: (data: T, request: Request) => Response | FormReject | Promise<Response | FormReject>;
    /**
     * Invalid submission without JavaScript: re-render the page with the component's
     * `.initialMessages` set to `[rejected]`, typically with status 422. The component's own
     * `IntentRejected` reducer turns it into state, so the errors render through the same view as
     * with JavaScript. Leave it out for an endpoint only `submitForm` calls: every rejection is
     * then the JSON 422.
     */
    readonly invalid?: (rejected: IntentRejected, request: Request) => Response | Promise<Response>;
}

interface FormReject {
    readonly _tag: 'FormReject';
    readonly issues: readonly FieldIssue[];
}

interface PageOptions extends RenderOptions, Head {
    /** The hydratable app: an `html` template, usually one custom element. */
    readonly body: ChildValue;
    /**
     * Server-only head content the head model doesn't cover, written with `html` (icons that
     * never change, preconnect hints, …). Never touched by `setHead()`.
     */
    readonly extraHead?: ChildValue;
    /**
     * Global CSS for the document (your app's own stylesheet text, e.g. a `?raw` import), written
     * as `<style>` elements in the head. A `</style` inside the text is escaped, so it can't
     * close the element early. Trusted CSS only: never put user input here.
     */
    readonly styles?: string | readonly string[];
    /**
     * Stylesheet URLs, written as `<link rel="stylesheet">` before `styles`: in production,
     * `clientAssetsFromManifest()`'s `css` (the hashed CSS Vite emitted for what the client entry
     * imports), served immutable and allowed by `style-src 'self'` without hashes.
     */
    readonly stylesheets?: readonly string[];
    /** Module scripts to load, e.g. the client entry. */
    readonly scripts?: readonly string[];
    /**
     * Inline classic scripts written early in the head, after the managed head entries and
     * before any stylesheet, so they run before the page paints (a theme script that sets
     * `data-theme` from storage, say). Trusted code only. A `</script` inside the text is escaped.
     * `renderPage({ csp })` allows them in `script-src` by hash.
     */
    readonly headScripts?: string | readonly string[];
    /**
     * Modules to fetch early with `<link rel="modulepreload">`, written before `scripts`: in
     * production, `clientAssetsFromManifest()`'s `modulepreload` (the entry's static imports and
     * the hydration chunk), so hydration doesn't wait for extra round trips.
     */
    readonly modulepreload?: readonly string[];
    /**
     * `renderPage` only: the `Content-Security-Policy` header. Pass `contentSecurityPolicy()`'s
     * options (`{ directives }`; the page's `styles` are included) to build it when the page
     * renders, with every component registered by then and the `<style>` elements allowed by
     * hash; or a header value, e.g. from `await contentSecurityPolicy({ styles })` (development
     * warns when it lacks a registered component's hash).
     */
    readonly csp?: string | CspOptions;
}

interface RenderOptions {
    /**
     * This request's store instances (ADR 0013). Components read them during the render; a
     * store not listed starts from its `init`. Create new instances per request.
     */
    readonly stores?: readonly AnyStoreInstance[];
    /**
     * Development markers and checks. Default: on when
     * `@gyral/core` resolves with the `development` condition (Vite's dev server, Vitest).
     */
    readonly dev?: boolean;
    /**
     * A component whose `init` or view throws (ADR 0024): by default the page goes on with that
     * component's error view (or an empty host the browser starts fresh) and the `GyralError` is
     * logged with `console.error`. A function hears each failure instead (logging, monitoring).
     * `'throw'` ends the render with the failure instead; `renderPage` then renders the whole page
     * first, so it throws before any byte is sent and the route can answer with an error page.
     */
    readonly onError?: ((error: GyralError) => void) | 'throw';
    /**
     * Automatic component loading: the page links the client modules of exactly the components
     * it rendered (their preload links and the loader), after the body, and nothing when it
     * rendered none. `productionServer` and `gyralDevServer` hand it to `createApp`.
     */
    readonly components?: ComponentAssets;
}

function assetHandler(options: AssetHandlerOptions): AssetHandler;

function clientAssetsFromManifest(manifestPath: string, entry: string, also?: readonly string[], options?: ManifestOptions): Promise<ClientAssets>;

function componentsFromManifest(clientDir: string, options?: ManifestOptions): Promise<ComponentAssets | undefined>;

function prerender(options: PrerenderOptions): Promise<readonly PrerenderedPage[]>;

function productionServer<Env = unknown>(options: ProductionOptions<Env>): Promise<FetchApp<Env>>;

function writeComponentStyleManifest(options: ComponentStyleManifestOptions): Promise<ComponentStyleManifest>;

interface AppAssets extends PageAssets {
    /** The built client entry's URL; undefined when the build has none (components only). */
    readonly clientEntry: string | undefined;
    /**
     * For `renderPage({ components })` when the build was made with
     * `gyralVitePreset({ components: true })`: each page links exactly the components it rendered.
     */
    readonly components: ComponentAssets | undefined;
    /** `modulepreload` and `stylesheets` with `modules` added (cached per list). */
    readonly assets: (modules: readonly string[]) => PageAssets;
    /** `assets(modules).modulepreload`. */
    readonly preload: (modules: readonly string[]) => readonly string[];
}

type AssetHandler = (request: Request) => Promise<Response | undefined>;

interface AssetHandlerOptions {
    /** The directory served under `prefix`, e.g. `dist/client/assets`. */
    readonly dir: string;
    /** The URL path prefix, with both slashes. Default `/assets/`. */
    readonly prefix?: string;
    /**
     * Keep served files in memory (hashed files never change): `true` (default) up to 64 MiB,
     * `{ maxBytes }` for another bound (least recently served files are dropped first), `false`
     * to read every request from disk. Misses are never cached.
     */
    readonly cache?: boolean | {
        readonly maxBytes: number;
    };
}

interface ClientAssets {
    /** The entry chunk's URL, for `renderPage({ scripts })`. */
    readonly entry: string;
    /**
     * Chunks the entry is known to need, for `renderPage({ modulepreload })`: the entry itself first
     * (when there is anything else), then its static imports and Gyral's lazily loaded hydration
     * chunk with its imports. Without the hints the browser
     * finds them only after it has fetched and parsed the entry (a server-rendered page would
     * fetch the hydration chunk a round trip later still).
     */
    readonly modulepreload: readonly string[];
    /**
     * The hashed CSS files of those chunks, for `renderPage({ stylesheets })`: what Vite emitted for
     * CSS imported by the entry, its static imports and the `also` modules, each chunk's after
     * its imports' (module order), each file once.
     */
    readonly css: readonly string[];
}

interface ComponentStyleManifest {
    readonly schema: 1;
    /** Sorted, deduplicated, quoted CSP SHA-256 sources for actual serialized shadow styles. */
    readonly hashes: readonly string[];
}

interface ComponentStyleManifestOptions {
    /** Application root used by its client build. Its component modules must be SSR-safe. */
    readonly root: string;
    /** Client output from `gyralVitePreset({ components: true })`, including `.vite` metadata. */
    readonly clientDir: string;
    /** Standalone JSON deployment artifact; no component module is needed to read it later. */
    readonly outFile: string;
    /** Build-time aliases/plugins used by application modules. No config file is loaded. */
    readonly vite?: InlineConfig;
}

interface FetchApp<Env = unknown> {
    readonly fetch: (request: Request, env?: Env) => Response | Promise<Response>;
}

interface ManifestChunk {
    readonly file: string;
    readonly imports?: readonly string[];
    readonly dynamicImports?: readonly string[];
    readonly css?: readonly string[];
}

interface ManifestOptions {
    /** Vite's `base`, e.g. `/app/` (a missing trailing slash is added). Default `/`. */
    readonly base?: string;
}

interface PageAssets {
    readonly modulepreload: readonly string[];
    readonly stylesheets: readonly string[];
}

interface PrerenderedPage {
    readonly path: string;
    readonly file: string;
    readonly status: number;
}

interface PrerenderOptions {
    readonly app: FetchApp;
    /** URL paths to render, e.g. every `ssg` route of the route table. */
    readonly paths: readonly string[];
    /** Directory the HTML files go to (`/about` → `<outDir>/about/index.html`). */
    readonly outDir: string;
    /** Origin used for the requests (absolute URLs in canonical links etc.). */
    readonly origin?: string;
}

interface ProductionOptions<Env = unknown> {
    /** Build output: `client/` (Vite, with `.vite/manifest.json`) and `static/` (prerendered). */
    readonly distDir: string;
    /**
     * The client entry as named in the Vite manifest. Default `src/entry-client.ts`. A build made
     * with `gyralVitePreset({ components: true })` may have none: pages then load components
     * through `components` alone.
     */
    readonly entry?: string;
    /**
     * The directory served at `/assets/`. Default `<distDir>/client/assets`; point it at a
     * directory that keeps older releases' hashed files too, so tabs opened before a deploy keep
     * loading their chunks.
     */
    readonly assetsDir?: string;
    /**
     * Prerendered pages. Default `<distDir>/static`; `false` when the app prerenders nothing, so
     * page requests don't look for files first.
     */
    readonly staticDir?: string | false;
    /**
     * Vite's `base` when the build is served under a path (e.g. `/app/`): the entry, preload and
     * stylesheet URLs start with it, and assets are served at `<base>assets/`. Default `/`.
     */
    readonly base?: string;
    /** Keep served assets in memory (`assetHandler`'s `cache`). Default `true`. */
    readonly cache?: boolean | {
        readonly maxBytes: number;
    };
    /**
     * Builds the request-time renderer (the same app the prerender step used). Pass
     * `modulepreload` and `stylesheets` on to `renderPage` so pages preload what the entry needs
     * and link its hashed CSS. A page that imports modules lazily (a route's chunk) spreads
     * `assets(modules)` instead: both lists plus those modules, their imports and their CSS
     * (`clientAssetsFromManifest`' `also`). `preload(modules)` is `assets(modules).modulepreload`.
     */
    readonly createApp: (options: AppAssets) => FetchApp<Env>;
    /**
     * Sees every response before it goes out (built assets, prerendered pages and the app's), to
     * add headers such as a CSP or security headers, or cookies. Return the response to send.
     */
    readonly onResponse?: (response: Response, request: Request) => Response | Promise<Response>;
}

type RenderMode = 'ssg' | 'ssr' | 'csr';

type ViteManifest = Readonly<Record<string, ManifestChunk>>;

function gyralDevServer<M, S = undefined>(options: DevServerOptions<M, S>): Promise<DevServer>;

await gyralDevServer({
  entry: '/server/app.ts',
  app: (mod: typeof import('./app.js'), { components }) => mod.createApp({ components }),
});

function toNodeListener(fetch: FetchHandler, options?: NodeListenerOptions): NodeListener;

interface DevApp {
    readonly fetch: (request: Request, env: NodeEnv) => Response | Promise<Response>;
}

interface DevServer {
    /** `http://host:port/` the server listens on. */
    readonly url: string;
    readonly server: Server;
    readonly vite: ViteDevServer;
    /** Stops the HTTP server and Vite. */
    readonly close: () => Promise<void>;
}

interface DevServerContext<S> {
    /**
     * For `renderPage({ components })` when the Vite config uses `gyralVitePreset({ components })`:
     * the loader and the tags it knows. Undefined otherwise.
     */
    readonly components: ComponentAssets | undefined;
    /** The value `state` created once, kept across module reloads. */
    readonly state: S;
}

interface DevServerOptions<M, S> {
    /** The server module, from Vite's root (e.g. `/server/app.ts`), loaded per request. */
    readonly entry: string;
    /** Builds the request handler from the module just loaded. */
    readonly app: (module: M, context: DevServerContext<S>) => DevApp;
    /**
     * State that must outlive module reloads (an in-memory database, say): created once, from the
     * first module loaded, and passed to every `app` call.
     */
    readonly state?: (module: M) => S;
    /** Default: the `PORT` environment variable, else 5173. `0` picks a free port. */
    readonly port?: number;
    /** Default: Node's (all interfaces). */
    readonly host?: string;
    /** The HMR WebSocket's port, so several dev servers can run side by side. Default Vite's. */
    readonly hmrPort?: number;
    /** `toNodeListener`'s `origin`: the public origin when absolute URLs matter. */
    readonly origin?: string;
    /** More Vite settings (root, configFile, plugins, …), merged under the server settings. */
    readonly vite?: InlineConfig;
}

type FetchHandler = (request: Request, env: NodeEnv) => Response | Promise<Response>;

interface NodeEnv {
    /** The Node request, for anything `Request` doesn't carry (socket, TLS details). */
    readonly incoming: IncomingMessage;
    /**
     * The peer's IP address (`req.socket.remoteAddress`), or `undefined` once the socket is gone.
     * Behind a proxy this is the proxy: read `X-Forwarded-For` only when the proxy is known.
     */
    readonly remoteAddress: string | undefined;
}

type NodeListener = (req: IncomingMessage, res: ServerResponse) => void;

interface NodeListenerOptions {
    /**
     * The origin request URLs are built on, e.g. `https://example.com` behind a proxy. Default:
     * `http://` (`https://` on a TLS socket) plus the request's `Host` header, which the client
     * chooses: set it when the app writes absolute URLs (canonical links, redirects).
     */
    readonly origin?: string;
    /**
     * Called when the handler throws or the response body fails, before the 500 (or, once the
     * headers are out, before the connection is cut). Default: `console.error`.
     */
    readonly onError?: (error: unknown, request: Request) => void;
}