@vertz/ui-server 0.2.30 → 0.2.32

package/dist/index.d.ts

@@ -1,751 +1,925 @@
-import { FallbackFontName as FallbackFontName2, FontFallbackMetrics as FontFallbackMetrics7 } from "@vertz/ui";
-interface AotBuildComponentEntry {
-	tier: "static" | "data-driven" | "conditional" | "runtime-fallback";
-	holes: string[];
-}
-interface AotBuildManifest {
-	components: Record<string, AotBuildComponentEntry>;
-	classificationLog: string[];
-}
-/**
-* Scan all TSX files in srcDir and generate an AOT build manifest.
-*/
-declare function generateAotBuildManifest(srcDir: string): AotBuildManifest;
-/** A raw HTML string that bypasses escaping during serialization. */
-interface RawHtml {
-	__raw: true;
-	html: string;
-}
+import { IncomingMessage, ServerResponse } from "node:http";
+import { FontFallbackMetrics as FontFallbackMetrics4 } from "@vertz/ui";
+import { FontFallbackMetrics as FontFallbackMetrics3 } from "@vertz/ui";
+import { SSRAuth as SSRAuth2 } from "@vertz/ui/internals";
 /**
-* Create a raw HTML string that will NOT be escaped during SSR serialization.
-*
-* **WARNING: XSS RISK** — This function bypasses all HTML escaping. Never pass
-* user-controlled input directly. Always sanitize with a trusted library (e.g.
-* DOMPurify) before wrapping in `rawHtml()`.
+* SSR prefetch access rule evaluator.
 *
-* @example Safe usage
-* ```ts
-* rawHtml('<svg>...</svg>') // static markup — OK
-* rawHtml(DOMPurify.sanitize(userInput)) // sanitized — OK
-* ```
+* Evaluates serialized entity access rules against the current session
+* to determine whether a query should be prefetched during SSR.
 *
-* @example Unsafe usage — NEVER do this
-* ```ts
-* rawHtml(userInput) // XSS vulnerability
-* rawHtml(`<div>${userInput}</div>`) // XSS via interpolation
-* ```
+* The serialized rules come from the prefetch manifest (generated at build time).
+* The session comes from the JWT decoded at request time.
 */
-declare function rawHtml(html: string): RawHtml;
-/** Virtual node representing an HTML element for SSR serialization. */
-interface VNode {
-	tag: string;
-	attrs: Record<string, string>;
-	children: (VNode | string | RawHtml)[];
-}
-/** Options for hydration marker generation. */
-interface HydrationOptions {
-	/** Component name for `data-v-id`. */
-	componentName: string;
-	/** Unique key for `data-v-key`. */
-	key: string;
-	/** Serialized props to embed as JSON. */
-	props?: Record<string, unknown>;
-}
-/** Metadata collected by the Head component during rendering. */
-interface HeadEntry {
-	tag: "title" | "meta" | "link";
-	attrs?: Record<string, string>;
-	textContent?: string;
-}
-/** Options for {@link renderToStream}. */
-interface RenderToStreamOptions {
-	/**
-	* CSP nonce to inject on all inline `<script>` tags emitted during SSR.
-	*
-	* When set, every inline script (e.g. Suspense replacement scripts) will
-	* include `nonce="<value>"` so that strict Content-Security-Policy headers
-	* do not block them.
-	*/
-	nonce?: string;
-}
-/** Asset descriptor for script/stylesheet injection. */
-interface AssetDescriptor {
-	type: "script" | "stylesheet";
-	src: string;
-	/** Whether to add `async` attribute (scripts only). */
-	async?: boolean;
-	/** Whether to add `defer` attribute (scripts only). */
-	defer?: boolean;
-}
 /**
-* Render asset descriptors to HTML tags for script/stylesheet injection.
-*
-* - Scripts: `<script src="..." [async] [defer]><\/script>`
-* - Stylesheets: `<link rel="stylesheet" href="...">`
+* Serialized access rule — the JSON-friendly format stored in the manifest.
+* Mirrors SerializedRule from @vertz/server/auth/rules but defined here
+* to avoid importing the server package into the SSR pipeline.
 */
-declare function renderAssetTags(assets: AssetDescriptor[]): string;
+type SerializedAccessRule = {
+	type: "public";
+} | {
+	type: "authenticated";
+} | {
+	type: "role";
+	roles: string[];
+} | {
+	type: "entitlement";
+	value: string;
+} | {
+	type: "where";
+	conditions: Record<string, unknown>;
+} | {
+	type: "all";
+	rules: SerializedAccessRule[];
+} | {
+	type: "any";
+	rules: SerializedAccessRule[];
+} | {
+	type: "fva";
+	maxAge: number;
+} | {
+	type: "deny";
+};
 /**
-* Inline critical CSS as a `<style>` tag.
-*
-* Wraps the provided CSS in `<style>...</style>` for embedding in the HTML head.
-* Escapes any `</style>` sequences in the CSS content to prevent injection.
-*
-* Returns an empty string if the CSS is empty.
+* Minimal session shape needed for prefetch access evaluation.
+* Extracted from the JWT at SSR request time.
 */
-declare function inlineCriticalCss(css: string): string;
-import { FallbackFontName, FontDescriptor, FontFallbackMetrics } from "@vertz/ui";
+type PrefetchSession = {
+	status: "authenticated";
+	roles?: string[];
+	entitlements?: Record<string, boolean>;
+	tenantId?: string;
+} | {
+	status: "unauthenticated";
+};
 /**
-* Auto-detect which system font to use as fallback base.
-*
-* Scans the `fallback` array for generic CSS font family keywords:
-* - 'sans-serif' or 'system-ui' → Arial
-* - 'serif' → Times New Roman
-* - 'monospace' → Courier New
-*
-* Skips non-generic entries (e.g., 'Georgia', 'Helvetica').
-* If no generic keyword found, defaults to Arial.
+* Minimal shape of an AccessSet for entitlement extraction.
+* Avoids importing @vertz/server types into the SSR pipeline.
 */
-declare function detectFallbackFont(fallback: readonly string[]): FallbackFontName;
+interface AccessSetLike {
+	entitlements: Record<string, {
+		allowed: boolean;
+	}>;
+}
 /**
-* Extract font metrics from .woff2 files and compute CSS fallback overrides.
+* Convert SSRAuth (from the JWT/session resolver) to PrefetchSession
+* for entity access evaluation during SSR prefetching.
 *
-* @param fonts - Font descriptors from theme definition.
-* @param rootDir - Project root directory for resolving font file paths.
-* @returns Map of font key → computed fallback metrics.
+* @param ssrAuth - Auth state from session resolver
+* @param accessSet - Access set from JWT acl claim (null = overflow, undefined = not configured)
 */
-declare function extractFontMetrics(fonts: Record<string, FontDescriptor>, rootDir: string): Promise<Record<string, FontFallbackMetrics>>;
+declare function toPrefetchSession(ssrAuth: {
+	status: string;
+	user?: {
+		role?: string;
+		[key: string]: unknown;
+	};
+} | undefined, accessSet?: AccessSetLike | null): PrefetchSession;
 /**
-* Collector for `<head>` metadata during SSR.
+* Evaluate a serialized access rule against the current session.
 *
-* Components call `addTitle`, `addMeta`, or `addLink` during render,
-* and the collected entries are serialized into the HTML `<head>` section.
-*/
-declare class HeadCollector {
-	private entries;
-	/** Add a `<title>` entry. */
-	addTitle(text: string): void;
-	/** Add a `<meta>` entry. */
-	addMeta(attrs: Record<string, string>): void;
-	/** Add a `<link>` entry. */
-	addLink(attrs: Record<string, string>): void;
-	/** Get all collected entries. */
-	getEntries(): HeadEntry[];
-	/** Clear all collected entries. */
-	clear(): void;
-}
-/**
-* Render head entries to an HTML string.
+* Returns true if the query is eligible for prefetch (the user
+* likely has access), false if it should be skipped.
 *
-* - `<title>` renders as `<title>text</title>`
-* - `<meta>` and `<link>` render as void elements
+* Design rationale for specific rule types:
+* - `where` → true: row-level filter, not an access gate. The query
+*   always executes; it just returns fewer rows for non-owners.
+* - `fva` → optimistic for authenticated users: MFA freshness is
+*   enforced on the actual API call. If the check fails server-side,
+*   the query returns an error result.
+* - `deny` → false: explicitly denied operations are never prefetched.
+* - Unknown types → false: fail-secure. Don't prefetch if we can't
+*   evaluate the rule.
 */
-declare function renderHeadToHtml(entries: HeadEntry[]): string;
+declare function evaluateAccessRule(rule: SerializedAccessRule, session: PrefetchSession): boolean;
 /**
-* Serialize a VNode tree (or plain string) to an HTML string.
-*
-* This is the core serialization function for SSR. It walks the virtual tree
-* recursively and produces an HTML string without requiring a real DOM.
+* AOT SSR Diagnostics
 *
-* - Text content inside `<script>` and `<style>` tags is not escaped.
-* - `RawHtml` values bypass escaping entirely.
+* Tracks AOT compilation results and provides a JSON snapshot
+* for the `/__vertz_ssr_aot` dev endpoint.
 */
-declare function serializeToHtml(node: VNode | string | RawHtml): string;
+/** AOT tier classification (mirrored from @vertz/ui-compiler to avoid cross-package dependency). */
+type AotTier = "static" | "data-driven" | "conditional" | "runtime-fallback";
+/** Per-component diagnostic entry in the snapshot. */
+interface AotComponentDiagnostic {
+	tier: AotTier;
+	holes: string[];
+}
+/** A recorded divergence between AOT and DOM shim output. */
+interface AotDivergenceEntry {
+	component: string;
+	aotHtml: string;
+	domHtml: string;
+	timestamp: string;
+}
+/** JSON snapshot returned by the `/__vertz_ssr_aot` endpoint. */
+interface AotDiagnosticsSnapshot {
+	components: Record<string, AotComponentDiagnostic>;
+	coverage: {
+		total: number;
+		aot: number;
+		runtime: number;
+		percentage: number;
+	};
+	divergences: AotDivergenceEntry[];
+}
+/** Input shape matching AotComponentInfo from @vertz/ui-compiler. */
+interface ComponentInput {
+	name: string;
+	tier: AotTier;
+	holes: string[];
+}
 /**
-* Wrap a VNode with hydration markers for interactive components.
-*
-* Adds `data-v-id` and `data-v-key` attributes to the root element,
-* and optionally embeds serialized props as a `<script type="application/json">` child.
+* Collects AOT compilation diagnostics and produces JSON snapshots.
 *
-* Returns a new VNode; the original is not mutated.
+* Used by the dev server to power the `/__vertz_ssr_aot` endpoint
+* and by the build pipeline for classification logging.
 */
-declare function wrapWithHydrationMarkers(node: VNode, options: HydrationOptions): VNode;
-interface PageOptions {
-	/** HTTP status code (default: 200) */
-	status?: number;
-	/** Page title */
-	title?: string;
-	/** Meta description */
-	description?: string;
-	/** Language attribute (default: 'en') */
-	lang?: string;
-	/** Favicon URL */
-	favicon?: string;
-	/** Open Graph meta tags */
-	og?: {
-		/** OG title (falls back to title) */
-		title?: string;
-		/** OG description (falls back to description) */
-		description?: string;
-		/** OG image URL */
-		image?: string;
-		/** OG canonical URL */
-		url?: string;
-		/** OG type (default: 'website') */
-		type?: string;
-	};
-	/** Twitter card meta tags */
-	twitter?: {
-		/** Twitter card type */
-		card?: string;
-		/** Twitter @username */
-		site?: string;
-	};
-	/** Array of script URLs to include at end of body */
-	scripts?: string[];
-	/** Array of stylesheet URLs to include in head */
+declare class AotDiagnostics {
+	private _components;
+	private _divergences;
+	/**
+	* Record components from an AOT compilation result.
+	* Called once per file during compilation or hot rebuild.
+	*/
+	recordCompilation(components: ComponentInput[]): void;
+	/** Record a divergence between AOT and DOM shim HTML output. */
+	recordDivergence(component: string, aotHtml: string, domHtml: string): void;
+	/** Clear all recorded data (used during full rebuild). */
+	clear(): void;
+	/** Clear only component classifications (preserves divergences). */
+	clearComponents(): void;
+	/**
+	* Generate per-component classification log lines.
+	* Used by the build pipeline and VERTZ_DEBUG=aot logging.
+	*
+	* Returns lines like:
+	* - "Header: static"
+	* - "Dashboard: conditional, 1 hole (SidePanel)"
+	* - "Coverage: 3/4 components (75%)"
+	*/
+	getClassificationLog(): string[];
+	/** Produce a JSON-serializable snapshot for the diagnostic endpoint. */
+	getSnapshot(): AotDiagnosticsSnapshot;
+}
+import { CompiledRoute, FontFallbackMetrics, Theme } from "@vertz/ui";
+import { SSRAuth as SSRAuth_jq1nwm } from "@vertz/ui/internals";
+interface SSRModule {
+	default?: () => unknown;
+	App?: () => unknown;
+	theme?: Theme;
+	/** Global CSS strings to include in every SSR response (e.g. resets, body styles). */
 	styles?: string[];
-	/** Raw HTML escape hatch for head */
-	head?: string;
+	/**
+	* Return all CSS tracked by the bundled @vertz/ui instance.
+	* The Vite SSR build inlines @vertz/ui into the server bundle, creating
+	* a separate module instance from @vertz/ui-server's dependency. Without
+	* this, component CSS from module-level css() calls is invisible to the
+	* SSR renderer. Export `getInjectedCSS` from @vertz/ui in the app entry.
+	*/
+	getInjectedCSS?: () => string[];
+	/** Compiled routes exported from the app for build-time SSG with generateParams. */
+	routes?: CompiledRoute[];
+	/** Code-generated API client for manifest-driven zero-discovery prefetching. */
+	api?: Record<string, Record<string, (...args: unknown[]) => unknown>>;
+}
+interface SSRRenderResult {
+	html: string;
+	css: string;
+	ssrData: Array<{
+		key: string;
+		data: unknown;
+	}>;
+	/** Font preload link tags for injection into <head>. */
+	headTags: string;
+	/** Route patterns discovered by createRouter() during SSR (for build-time pre-rendering). */
+	discoveredRoutes?: string[];
+	/** Route patterns that matched the current URL (for per-route modulepreload). */
+	matchedRoutePatterns?: string[];
+	/** Set when ProtectedRoute writes a redirect during SSR. Server should return 302. */
+	redirect?: {
+		to: string;
+	};
+}
+interface SSRDiscoverResult {
+	resolved: Array<{
+		key: string;
+		data: unknown;
+	}>;
+	pending: string[];
 }
 /**
-* Render a VNode to a full HTML Response with common page structure.
-*
-* This is the main entry point for zero-boilerplate SSR. It wraps the component
-* in a complete HTML document with doctype, head (meta, OG, Twitter, favicon,
-* styles), and body (component content + scripts).
-*
-* @param vnode - The root VNode to render
-* @param options - Optional page configuration
-* @returns A Response with text/html content-type
-*
-* @example
-* ```ts
-* // Minimal usage
-* return renderPage(App)
+* Render an SSR module to an HTML string with CSS and pre-fetched query data.
 *
-* // Full options
-* return renderPage(App, {
-*   title: 'My App',
-*   description: 'Built with vertz',
-*   og: { image: '/og.png' },
-*   scripts: ['/app.js'],
-*   styles: ['/app.css'],
-* })
-* ```
+* Performs a two-pass render:
+* - Pass 1: Discovery — calls the app to trigger query() registrations, awaits them
+* - Pass 2: Render — calls the app again with data populated, renders to HTML
 */
-declare function renderPage(vnode: VNode, options?: PageOptions): Response;
-import { FontFallbackMetrics as FontFallbackMetrics2, Theme } from "@vertz/ui";
-interface RenderToHTMLOptions<AppFn extends () => VNode> {
-	/** The app component function */
-	app: AppFn;
-	/** Request URL for SSR */
-	url: string;
-	/** Theme definition for CSS vars */
-	theme?: Theme;
-	/** Global CSS strings to inject */
-	styles?: string[];
-	/** HTML head configuration */
-	head?: {
-		title?: string;
-		meta?: Array<{
-			name?: string;
-			property?: string;
-			content: string;
-		}>;
-		links?: Array<{
-			rel: string;
-			href: string;
-		}>;
-	};
-	/** Container selector (default '#app') */
-	container?: string;
+declare function ssrRenderToString(module: SSRModule, url: string, options?: {
+	ssrTimeout?: number;
 	/** Pre-computed font fallback metrics (computed at server startup). */
-	fallbackMetrics?: Record<string, FontFallbackMetrics2>;
+	fallbackMetrics?: Record<string, FontFallbackMetrics>;
+	/** Auth state resolved from session cookie. Passed to SSRRenderContext for AuthProvider. */
+	ssrAuth?: SSRAuth_jq1nwm;
+}): Promise<SSRRenderResult>;
+/**
+* Discover queries for a given URL without rendering.
+* Runs only Pass 1 (query registration + resolution), no Pass 2 render.
+* Used by the production handler to pre-fetch query data for client-side navigations.
+*/
+declare function ssrDiscoverQueries(module: SSRModule, url: string, options?: {
+	ssrTimeout?: number;
+}): Promise<SSRDiscoverResult>;
+import { FontFallbackMetrics as FontFallbackMetrics2 } from "@vertz/ui";
+import { SSRAuth } from "@vertz/ui/internals";
+import { ExtractedQuery } from "@vertz/ui-compiler";
+/** Serialized entity access rules from the prefetch manifest. */
+type EntityAccessMap = Record<string, Partial<Record<string, SerializedAccessRule>>>;
+interface SSRPrefetchManifest {
+	/** Route patterns present in the manifest. */
+	routePatterns: string[];
+	/** Entity access rules keyed by entity name → operation → serialized rule. */
+	entityAccess?: EntityAccessMap;
+	/** Route entries with query binding metadata for zero-discovery prefetch. */
+	routeEntries?: Record<string, {
+		queries: ExtractedQuery[];
+	}>;
 }
-interface RenderToHTMLStreamOptions<AppFn extends () => VNode> extends RenderToHTMLOptions<AppFn> {
-	/** CSP nonce for inline scripts */
-	nonce?: string;
-	/** Global default for per-query ssrTimeout (ms) */
+interface SSRSinglePassOptions {
 	ssrTimeout?: number;
-	/** Hard timeout for entire stream (ms, default 30000) */
-	streamTimeout?: number;
+	/** Pre-computed font fallback metrics (computed at server startup). */
+	fallbackMetrics?: Record<string, FontFallbackMetrics2>;
+	/** Auth state resolved from session cookie. */
+	ssrAuth?: SSRAuth;
+	/** Set to false to fall back to two-pass rendering. Default: true. */
+	prefetch?: boolean;
+	/** Prefetch manifest for entity access filtering. */
+	manifest?: SSRPrefetchManifest;
+	/** Session data for access rule evaluation. */
+	prefetchSession?: PrefetchSession;
 }
 /**
-* Render a component to a streaming HTML Response.
+* Render an SSR module in a single pass via discovery-only execution.
 *
-* The initial HTML is sent immediately. For slow queries that timed out
-* during SSR, their resolved data is streamed as inline `<script>` chunks
-* that push data to the client's reactive system.
+* 1. Discovery: Run the app factory to capture query registrations (no stream render)
+* 2. Prefetch: Await all discovered queries with timeout
+* 3. Render: Create a fresh context with pre-populated cache, render once
 *
-* @returns Promise<Response> - A streaming Response with text/html content
+* Falls back to two-pass (`ssrRenderToString`) when:
+* - `prefetch: false` is set
+* - A redirect is detected during discovery
 */
-declare function renderToHTMLStream<AppFn extends () => VNode>(options: RenderToHTMLStreamOptions<AppFn>): Promise<Response>;
+declare function ssrRenderSinglePass(module: SSRModule, url: string, options?: SSRSinglePassOptions): Promise<SSRRenderResult>;
+/** Context passed to AOT render functions for accessing data and runtime holes. */
+interface SSRAotContext {
+	/** Pre-generated closures for runtime-rendered components. */
+	holes: Record<string, () => string>;
+	/** Access query data by cache key. */
+	getData(key: string): unknown;
+	/** Auth session for conditional rendering. */
+	session: PrefetchSession | undefined;
+	/** Route params for the current request. */
+	params: Record<string, string>;
+}
+/** An AOT render function: takes props/data and context, returns HTML string. */
+type AotRenderFn = (data: Record<string, unknown>, ctx: SSRAotContext) => string;
+/** Per-route AOT entry in the manifest. */
+interface AotRouteEntry {
+	/** The pre-compiled render function. */
+	render: AotRenderFn;
+	/** Component names that need runtime fallback (holes). */
+	holes: string[];
+	/** Query cache keys this route reads via ctx.getData(). */
+	queryKeys?: string[];
+}
 /**
-* Render a VNode to a full HTML string.
-*
-* This is a wrapper around renderPage() that provides a simpler API for
-* theme and style injection.
-*
-* @param options - Render options including app, url, theme, styles, head
-* @returns Promise<string> - The rendered HTML string
-*
-* @example
-* ```ts
-* import { renderToHTML, defineTheme } from '@vertz/ui-server';
-*
-* const theme = defineTheme({
-*   colors: { primary: { DEFAULT: '#3b82f6' } }
-* });
+* AOT manifest — maps route patterns to pre-compiled render functions.
 *
-* const html = await renderToHTML({
-*   app: App,
-*   url: '/',
-*   theme,
-*   styles: ['body { margin: 0; }'],
-*   head: { title: 'My App' }
-* });
-* ```
+* Generated at build time by the AOT compiler pipeline.
 */
-declare function renderToHTML<AppFn extends () => VNode>(options: RenderToHTMLOptions<AppFn>): Promise<string>;
-/**
-* @deprecated Use the options-object overload: `renderToHTML({ app, url, ... })`
-*/
-declare function renderToHTML<AppFn extends () => VNode>(app: AppFn, options: RenderToHTMLOptions<AppFn>): Promise<string>;
+interface AotManifest {
+	/** Route pattern → AOT entry. */
+	routes: Record<string, AotRouteEntry>;
+}
+/** Options for `ssrRenderAot()`. */
+interface SSRRenderAotOptions {
+	/** AOT manifest with pre-compiled render functions. */
+	aotManifest: AotManifest;
+	/** Prefetch manifest for route matching and data fetching. */
+	manifest?: SSRPrefetchManifest;
+	/** SSR timeout in ms. */
+	ssrTimeout?: number;
+	/** Pre-computed font fallback metrics. */
+	fallbackMetrics?: Record<string, FontFallbackMetrics3>;
+	/** Auth state resolved from session cookie. */
+	ssrAuth?: SSRAuth2;
+	/** Session data for access rule evaluation. */
+	prefetchSession?: PrefetchSession;
+	/** AOT diagnostics collector (dev mode). When provided with VERTZ_DEBUG=aot, enables dual rendering and divergence detection. */
+	diagnostics?: AotDiagnostics;
+}
 /**
-* Render a VNode tree to a `ReadableStream` of HTML chunks.
-*
-* This is the main SSR entry point. It walks the virtual tree, serializing
-* synchronous content immediately and deferring Suspense boundaries.
+* Create closure-based runtime fallback renderers for components
+* that cannot be AOT-compiled.
 *
-* Suspense boundaries emit:
-* 1. A `<div id="v-slot-N">fallback</div>` placeholder inline
-* 2. A `<template id="v-tmpl-N">resolved</template><script>...<\/script>` chunk
-*    appended after the main content once the async content resolves
+* Each hole closure:
+* 1. Runs inside `ssrStorage.run()` to provide SSRRenderContext
+* 2. Calls the component factory via the SSR module
+* 3. Converts the result to VNode and serializes to HTML string
+* 4. Shares the query cache with the AOT function
 *
-* This enables out-of-order streaming: the browser can paint the fallback
-* immediately and swap in the resolved content when it arrives.
+* @param holeNames - Component names that need runtime rendering
+* @param module - SSR module with component factories
+* @param url - Request URL for context
+* @param queryCache - Pre-populated query cache (shared with AOT)
+* @param ssrAuth - Auth state for the request
 */
-declare function renderToStream(tree: VNode | string | RawHtml, options?: RenderToStreamOptions): ReadableStream<Uint8Array>;
-/** Reset the slot counter (for testing). */
-declare function resetSlotCounter(): void;
+declare function createHoles(holeNames: string[], module: SSRModule, url: string, queryCache: Map<string, unknown>, ssrAuth?: SSRAuth2): Record<string, () => string>;
 /**
-* Create a Suspense slot placeholder.
+* Render a page using pre-compiled AOT string-builder functions.
 *
-* Wraps fallback content in a `<div id="v-slot-N">` so it can later
-* be replaced by the resolved async content via a template chunk.
+* Falls back to `ssrRenderSinglePass()` when:
+* - No route match in the AOT manifest
+* - No prefetch manifest for route matching
 *
-* Returns the placeholder VNode and the assigned slot ID.
+* Pipeline:
+* 1. Match URL to route pattern
+* 2. Look up AOT entry in manifest
+* 3. Prefetch query data (reuses single-pass prefetch logic)
+* 4. Create runtime holes (closures for non-AOT components)
+* 5. Call AOT render function with data + context
+* 6. Collect CSS, ssrData, headTags
+* 7. Return SSRRenderResult
 */
-declare function createSlotPlaceholder(fallback: VNode | string): VNode & {
-	_slotId: number;
-};
+declare function ssrRenderAot(module: SSRModule, url: string, options: SSRRenderAotOptions): Promise<SSRRenderResult>;
+/** Check if VERTZ_DEBUG includes the 'aot' category. */
+declare function isAotDebugEnabled(): boolean;
+import { AccessSet } from "@vertz/ui/auth";
+interface SessionData {
+	user: {
+		id: string;
+		email: string;
+		role: string;
+		[key: string]: unknown;
+	};
+	/** Unix timestamp in milliseconds (JWT exp * 1000). */
+	expiresAt: number;
+}
+/** Resolved session data for SSR injection. */
+interface SSRSessionInfo {
+	session: SessionData;
+	/**
+	* Access set from JWT acl claim.
+	* - Present (object): inline access set (no overflow)
+	* - null: access control is configured but the set overflowed the JWT
+	* - undefined: access control is not configured
+	*/
+	accessSet?: AccessSet | null;
+}
 /**
-* SSR prefetch access rule evaluator.
-*
-* Evaluates serialized entity access rules against the current session
-* to determine whether a query should be prefetched during SSR.
-*
-* The serialized rules come from the prefetch manifest (generated at build time).
-* The session comes from the JWT decoded at request time.
+* Callback that extracts session data from a request.
+* Returns null when no valid session exists (expired, missing, or invalid cookie).
 */
+type SessionResolver = (request: Request) => Promise<SSRSessionInfo | null>;
 /**
-* Serialized access rule — the JSON-friendly format stored in the manifest.
-* Mirrors SerializedRule from @vertz/server/auth/rules but defined here
-* to avoid importing the server package into the SSR pipeline.
+* Serialize a session into a `<script>` tag that sets
+* `window.__VERTZ_SESSION__`.
+*
+* @param session - The session data to serialize
+* @param nonce - Optional CSP nonce for the script tag
 */
-type SerializedAccessRule = {
-	type: "public";
-} | {
-	type: "authenticated";
-} | {
-	type: "role";
-	roles: string[];
-} | {
-	type: "entitlement";
-	value: string;
-} | {
-	type: "where";
-	conditions: Record<string, unknown>;
-} | {
-	type: "all";
-	rules: SerializedAccessRule[];
-} | {
-	type: "any";
-	rules: SerializedAccessRule[];
-} | {
-	type: "fva";
-	maxAge: number;
-} | {
-	type: "deny";
-};
+declare function createSessionScript(session: SessionData, nonce?: string): string;
+interface SSRHandlerOptions {
+	/** The loaded SSR module (import('./dist/server/index.js')) */
+	module: SSRModule;
+	/** HTML template string (contents of dist/client/index.html) */
+	template: string;
+	/** SSR timeout for queries (default: 300ms) */
+	ssrTimeout?: number;
+	/**
+	* Map of CSS asset URLs to their content for inlining.
+	* Replaces `<link rel="stylesheet" href="...">` tags with inline `<style>` tags.
+	* Eliminates extra network requests, preventing FOUC on slow connections.
+	*
+	* @example
+	* ```ts
+	* inlineCSS: { '/assets/vertz.css': await Bun.file('./dist/client/assets/vertz.css').text() }
+	* ```
+	*/
+	inlineCSS?: Record<string, string>;
+	/**
+	* CSP nonce to inject on all inline `<script>` tags emitted during SSR.
+	*
+	* When set, the SSR data hydration script will include `nonce="<value>"`
+	* so that strict Content-Security-Policy headers do not block it.
+	*/
+	nonce?: string;
+	/** Pre-computed font fallback metrics (computed at server startup). */
+	fallbackMetrics?: Record<string, FontFallbackMetrics4>;
+	/** Paths to inject as `<link rel="modulepreload">` in `<head>`. */
+	modulepreload?: string[];
+	/**
+	* Route chunk manifest for per-route modulepreload injection.
+	* When provided, only chunks for the matched route are preloaded instead of all chunks.
+	*/
+	routeChunkManifest?: {
+		routes: Record<string, string[]>;
+	};
+	/** Cache-Control header for HTML responses. Omit or undefined = no header (safe default). */
+	cacheControl?: string;
+	/**
+	* Resolves session data from request cookies for SSR injection.
+	* When provided, SSR HTML includes `window.__VERTZ_SESSION__` and
+	* optionally `window.__VERTZ_ACCESS_SET__` for instant auth hydration.
+	*/
+	sessionResolver?: SessionResolver;
+	/**
+	* Prefetch manifest for single-pass SSR optimization.
+	*
+	* When provided with route entries and an API client export, enables
+	* zero-discovery rendering — queries are prefetched from the manifest
+	* without executing the component tree, then a single render pass
+	* produces the HTML. Without a manifest, SSR still uses the single-pass
+	* discovery-then-render approach (cheaper than two-pass).
+	*/
+	manifest?: SSRPrefetchManifest;
+	/**
+	* Enable progressive HTML streaming. Default: false.
+	*
+	* When true, the Response body is a ReadableStream that sends `<head>`
+	* content (CSS, preloads, fonts) before `<body>` rendering is complete.
+	* This improves TTFB and FCP.
+	*
+	* Has no effect on zero-discovery routes (manifest with routeEntries),
+	* which always use buffered rendering.
+	*/
+	progressiveHTML?: boolean;
+	/**
+	* AOT manifest with pre-compiled render functions.
+	*
+	* When provided, routes matching AOT entries are rendered via string-builder
+	* functions (no DOM shim), bypassing the reactive runtime for 4-6x speedup.
+	* Routes not in the manifest fall back to `ssrRenderSinglePass()`.
+	*
+	* Load via `loadAotManifest(serverDir)` at startup.
+	*/
+	aotManifest?: AotManifest;
+}
+declare function createSSRHandler(options: SSRHandlerOptions): (request: Request) => Promise<Response>;
+type NodeHandlerOptions = SSRHandlerOptions;
+declare function createNodeHandler(options: NodeHandlerOptions): (req: IncomingMessage, res: ServerResponse) => void;
+import { FallbackFontName as FallbackFontName2, FontFallbackMetrics as FontFallbackMetrics7 } from "@vertz/ui";
+import { ExtractedRoute } from "@vertz/ui-compiler";
+import { extractRoutes } from "@vertz/ui-compiler";
+import { AotComponentInfo } from "@vertz/ui-compiler";
+interface AotBuildComponentEntry {
+	tier: "static" | "data-driven" | "conditional" | "runtime-fallback";
+	holes: string[];
+	queryKeys: string[];
+}
+/** Compiled file output from AOT compilation. */
+interface AotCompiledFile {
+	/** Transformed source code containing __ssr_* functions. */
+	code: string;
+	/** Per-component AOT info from the compilation. */
+	components: AotComponentInfo[];
+}
+/** Route map entry for the AOT manifest JSON. */
+interface AotRouteMapEntry {
+	/** Name of the __ssr_* render function (e.g., '__ssr_HomePage'). */
+	renderFn: string;
+	/** Component names that need runtime fallback rendering. */
+	holes: string[];
+	/** Query cache keys this route reads via ctx.getData(). */
+	queryKeys: string[];
+}
+interface AotBuildManifest {
+	components: Record<string, AotBuildComponentEntry>;
+	/** Compiled files keyed by source file path. */
+	compiledFiles: Record<string, AotCompiledFile>;
+	classificationLog: string[];
+}
 /**
-* Minimal session shape needed for prefetch access evaluation.
-* Extracted from the JWT at SSR request time.
+* Scan all TSX files in srcDir and generate an AOT build manifest.
 */
-type PrefetchSession = {
-	status: "authenticated";
-	roles?: string[];
-	entitlements?: Record<string, boolean>;
-	tenantId?: string;
-} | {
-	status: "unauthenticated";
-};
+declare function generateAotBuildManifest(srcDir: string): AotBuildManifest;
 /**
-* Minimal shape of an AccessSet for entitlement extraction.
-* Avoids importing @vertz/server types into the SSR pipeline.
+* Build AOT route map — maps route patterns to render function names.
+*
+* Skips routes for runtime-fallback components (they can't be AOT-rendered)
+* and routes for unknown components (not found in AOT manifest).
 */
-interface AccessSetLike {
-	entitlements: Record<string, {
-		allowed: boolean;
-	}>;
+declare function buildAotRouteMap(components: Record<string, AotBuildComponentEntry>, routes: Array<{
+	pattern: string;
+	componentName: string;
+}>): Record<string, AotRouteMapEntry>;
+/** Result of barrel generation — barrel source + file mapping for temp dir. */
+interface AotBarrelResult {
+	/** Barrel module source code (import/re-statements). */
+	barrelSource: string;
+	/**
+	* Mapping of temp file names → compiled source code.
+	* Write each entry as `<tempDir>/<filename>.ts` alongside the barrel.
+	*/
+	files: Record<string, string>;
 }
 /**
-* Convert SSRAuth (from the JWT/session resolver) to PrefetchSession
-* for entity access evaluation during SSR prefetching.
+* Generate a barrel module that re-exports __ssr_* functions from compiled files.
 *
-* @param ssrAuth - Auth state from session resolver
-* @param accessSet - Access set from JWT acl claim (null = overflow, undefined = not configured)
+* Returns the barrel source code and a mapping of temp filenames → compiled code
+* that must be written alongside the barrel for bundling.
 */
-declare function toPrefetchSession(ssrAuth: {
-	status: string;
-	user?: {
-		role?: string;
-		[key: string]: unknown;
-	};
-} | undefined, accessSet?: AccessSetLike | null): PrefetchSession;
+declare function generateAotBarrel(compiledFiles: Record<string, AotCompiledFile>, routeMap: Record<string, AotRouteMapEntry>): AotBarrelResult;
 /**
-* Evaluate a serialized access rule against the current session.
+* Load AOT manifest and routes module from a server build directory.
 *
-* Returns true if the query is eligible for prefetch (the user
-* likely has access), false if it should be skipped.
+* Returns `null` if either `aot-manifest.json` or `aot-routes.js` is missing,
+* or if no routes can be wired to render functions.
 *
-* Design rationale for specific rule types:
-* - `where` → true: row-level filter, not an access gate. The query
-*   always executes; it just returns fewer rows for non-owners.
-* - `fva` → optimistic for authenticated users: MFA freshness is
-*   enforced on the actual API call. If the check fails server-side,
-*   the query returns an error result.
-* - `deny` → false: explicitly denied operations are never prefetched.
-* - Unknown types → false: fail-secure. Don't prefetch if we can't
-*   evaluate the rule.
+* @param serverDir - Path to `dist/server/` directory
 */
-declare function evaluateAccessRule(rule: SerializedAccessRule, session: PrefetchSession): boolean;
-import { AccessSet } from "@vertz/ui/auth";
+declare function loadAotManifest(serverDir: string): Promise<AotManifest | null>;
+/** A raw HTML string that bypasses escaping during serialization. */
+interface RawHtml {
+	__raw: true;
+	html: string;
+}
 /**
-* Extract an AccessSet from a decoded JWT payload for SSR injection.
+* Create a raw HTML string that will NOT be escaped during SSR serialization.
 *
-* - If the JWT has an inline `acl.set` (no overflow), returns the decoded AccessSet.
-* - If `acl.overflow` is true, returns `null` — caller should re-compute from live stores.
-* - If no `acl` claim exists, returns `null`.
+* **WARNING: XSS RISK** — This function bypasses all HTML escaping. Never pass
+* user-controlled input directly. Always sanitize with a trusted library (e.g.
+* DOMPurify) before wrapping in `rawHtml()`.
 *
-* @param jwtPayload - The decoded JWT payload (from verifyJWT)
-* @returns The AccessSet for SSR injection, or null
+* @example Safe usage
+* ```ts
+* rawHtml('<svg>...</svg>') // static markup — OK
+* rawHtml(DOMPurify.sanitize(userInput)) // sanitized — OK
+* ```
+*
+* @example Unsafe usage — NEVER do this
+* ```ts
+* rawHtml(userInput) // XSS vulnerability
+* rawHtml(`<div>${userInput}</div>`) // XSS via interpolation
+* ```
 */
-declare function getAccessSetForSSR(jwtPayload: Record<string, unknown> | null): AccessSet | null;
+declare function rawHtml(html: string): RawHtml;
+/** Virtual node representing an HTML element for SSR serialization. */
+interface VNode {
+	tag: string;
+	attrs: Record<string, string>;
+	children: (VNode | string | RawHtml)[];
+}
+/** Options for hydration marker generation. */
+interface HydrationOptions {
+	/** Component name for `data-v-id`. */
+	componentName: string;
+	/** Unique key for `data-v-key`. */
+	key: string;
+	/** Serialized props to embed as JSON. */
+	props?: Record<string, unknown>;
+}
+/** Metadata collected by the Head component during rendering. */
+interface HeadEntry {
+	tag: "title" | "meta" | "link";
+	attrs?: Record<string, string>;
+	textContent?: string;
+}
+/** Options for {@link renderToStream}. */
+interface RenderToStreamOptions {
+	/**
+	* CSP nonce to inject on all inline `<script>` tags emitted during SSR.
+	*
+	* When set, every inline script (e.g. Suspense replacement scripts) will
+	* include `nonce="<value>"` so that strict Content-Security-Policy headers
+	* do not block them.
+	*/
+	nonce?: string;
+}
+/** Asset descriptor for script/stylesheet injection. */
+interface AssetDescriptor {
+	type: "script" | "stylesheet";
+	src: string;
+	/** Whether to add `async` attribute (scripts only). */
+	async?: boolean;
+	/** Whether to add `defer` attribute (scripts only). */
+	defer?: boolean;
+}
 /**
-* Serialize an AccessSet into a `<script>` tag that sets
-* `window.__VERTZ_ACCESS_SET__`.
+* Render asset descriptors to HTML tags for script/stylesheet injection.
 *
-* @param accessSet - The access set to serialize
-* @param nonce - Optional CSP nonce for the script tag
+* - Scripts: `<script src="..." [async] [defer]><\/script>`
+* - Stylesheets: `<link rel="stylesheet" href="...">`
 */
-declare function createAccessSetScript(accessSet: AccessSet, nonce?: string): string;
-import { RenderAdapter } from "@vertz/ui/internals";
+declare function renderAssetTags(assets: AssetDescriptor[]): string;
 /**
-* Create an SSR adapter that uses in-memory SSR node classes.
-* Replaces `installDomShim()` — no global mutation needed.
+* Inline critical CSS as a `<style>` tag.
+*
+* Wraps the provided CSS in `<style>...</style>` for embedding in the HTML head.
+* Escapes any `</style>` sequences in the CSS content to prevent injection.
+*
+* Returns an empty string if the CSS is empty.
 */
-declare function createSSRAdapter(): RenderAdapter;
+declare function inlineCriticalCss(css: string): string;
+import { FallbackFontName, FontDescriptor, FontFallbackMetrics as FontFallbackMetrics5 } from "@vertz/ui";
 /**
-* AOT SSR Diagnostics
+* Auto-detect which system font to use as fallback base.
 *
-* Tracks AOT compilation results and provides a JSON snapshot
-* for the `/__vertz_ssr_aot` dev endpoint.
+* Scans the `fallback` array for generic CSS font family keywords:
+* - 'sans-serif' or 'system-ui' → Arial
+* - 'serif' → Times New Roman
+* - 'monospace' → Courier New
+*
+* Skips non-generic entries (e.g., 'Georgia', 'Helvetica').
+* If no generic keyword found, defaults to Arial.
 */
-/** AOT tier classification (mirrored from @vertz/ui-compiler to avoid cross-package dependency). */
-type AotTier = "static" | "data-driven" | "conditional" | "runtime-fallback";
-/** Per-component diagnostic entry in the snapshot. */
-interface AotComponentDiagnostic {
-	tier: AotTier;
-	holes: string[];
-}
-/** A recorded divergence between AOT and DOM shim output. */
-interface AotDivergenceEntry {
-	component: string;
-	aotHtml: string;
-	domHtml: string;
-	timestamp: string;
-}
-/** JSON snapshot returned by the `/__vertz_ssr_aot` endpoint. */
-interface AotDiagnosticsSnapshot {
-	components: Record<string, AotComponentDiagnostic>;
-	coverage: {
-		total: number;
-		aot: number;
-		runtime: number;
-		percentage: number;
-	};
-	divergences: AotDivergenceEntry[];
-}
-/** Input shape matching AotComponentInfo from @vertz/ui-compiler. */
-interface ComponentInput {
-	name: string;
-	tier: AotTier;
-	holes: string[];
-}
+declare function detectFallbackFont(fallback: readonly string[]): FallbackFontName;
 /**
-* Collects AOT compilation diagnostics and produces JSON snapshots.
+* Extract font metrics from .woff2 files and compute CSS fallback overrides.
 *
-* Used by the dev server to power the `/__vertz_ssr_aot` endpoint
-* and by the build pipeline for classification logging.
+* @param fonts - Font descriptors from theme definition.
+* @param rootDir - Project root directory for resolving font file paths.
+* @returns Map of font key → computed fallback metrics.
 */
-declare class AotDiagnostics {
-	private _components;
-	private _divergences;
-	/**
-	* Record components from an AOT compilation result.
-	* Called once per file during compilation or hot rebuild.
-	*/
-	recordCompilation(components: ComponentInput[]): void;
-	/** Record a divergence between AOT and DOM shim HTML output. */
-	recordDivergence(component: string, aotHtml: string, domHtml: string): void;
-	/** Clear all recorded data (used during full rebuild). */
+declare function extractFontMetrics(fonts: Record<string, FontDescriptor>, rootDir: string): Promise<Record<string, FontFallbackMetrics5>>;
+/**
+* Collector for `<head>` metadata during SSR.
+*
+* Components call `addTitle`, `addMeta`, or `addLink` during render,
+* and the collected entries are serialized into the HTML `<head>` section.
+*/
+declare class HeadCollector {
+	private entries;
+	/** Add a `<title>` entry. */
+	addTitle(text: string): void;
+	/** Add a `<meta>` entry. */
+	addMeta(attrs: Record<string, string>): void;
+	/** Add a `<link>` entry. */
+	addLink(attrs: Record<string, string>): void;
+	/** Get all collected entries. */
+	getEntries(): HeadEntry[];
+	/** Clear all collected entries. */
 	clear(): void;
-	/** Clear only component classifications (preserves divergences). */
-	clearComponents(): void;
-	/**
-	* Generate per-component classification log lines.
-	* Used by the build pipeline and VERTZ_DEBUG=aot logging.
-	*
-	* Returns lines like:
-	* - "Header: static"
-	* - "Dashboard: conditional, 1 hole (SidePanel)"
-	* - "Coverage: 3/4 components (75%)"
-	*/
-	getClassificationLog(): string[];
-	/** Produce a JSON-serializable snapshot for the diagnostic endpoint. */
-	getSnapshot(): AotDiagnosticsSnapshot;
 }
-/** Per-component entry in the dev AOT manifest. */
-interface AotDevComponentEntry {
-	tier: "static" | "data-driven" | "conditional" | "runtime-fallback";
-	holes: string[];
-	/** The file this component was compiled from. */
-	file: string;
-}
-/** Dev-mode AOT manifest — tracks all components across all files. */
-interface AotDevManifest {
-	components: Record<string, AotDevComponentEntry>;
-}
-interface AotManifestSnapshot {
-	manifest: AotDevManifest | null;
-	rebuildCount: number;
-	lastRebuildMs: number | null;
-	lastRebuildAt: string | null;
-}
-interface AotManifestManagerOptions {
-	/** Read a file's contents. Returns undefined if file doesn't exist. */
-	readFile: (path: string) => string | undefined;
-	/** List all files in the source directory (absolute paths). */
-	listFiles: () => string[];
-}
-interface AotManifestManager {
-	/** Initial full build — compile all TSX files. */
-	build(): void;
-	/** Handle a file change — recompile a single file. */
-	onFileChange(filePath: string, sourceText: string): void;
-	/** Get the current manifest (atomic read). */
-	getManifest(): AotDevManifest | null;
-	/** Get diagnostic snapshot for endpoints. */
-	getSnapshot(): AotManifestSnapshot;
-	/** Get AotDiagnostics instance for the diagnostics endpoint. */
-	getDiagnostics(): AotDiagnostics;
+/**
+* Render head entries to an HTML string.
+*
+* - `<title>` renders as `<title>text</title>`
+* - `<meta>` and `<link>` render as void elements
+*/
+declare function renderHeadToHtml(entries: HeadEntry[]): string;
+/**
+* Serialize a VNode tree (or plain string) to an HTML string.
+*
+* This is the core serialization function for SSR. It walks the virtual tree
+* recursively and produces an HTML string without requiring a real DOM.
+*
+* - Text content inside `<script>` and `<style>` tags is not escaped.
+* - `RawHtml` values bypass escaping entirely.
+*/
+declare function serializeToHtml(node: VNode | string | RawHtml): string;
+/**
+* Wrap a VNode with hydration markers for interactive components.
+*
+* Adds `data-v-id` and `data-v-key` attributes to the root element,
+* and optionally embeds serialized props as a `<script type="application/json">` child.
+*
+* Returns a new VNode; the original is not mutated.
+*/
+declare function wrapWithHydrationMarkers(node: VNode, options: HydrationOptions): VNode;
+interface PageOptions {
+	/** HTTP status code (default: 200) */
+	status?: number;
+	/** Page title */
+	title?: string;
+	/** Meta description */
+	description?: string;
+	/** Language attribute (default: 'en') */
+	lang?: string;
+	/** Favicon URL */
+	favicon?: string;
+	/** Open Graph meta tags */
+	og?: {
+		/** OG title (falls back to title) */
+		title?: string;
+		/** OG description (falls back to description) */
+		description?: string;
+		/** OG image URL */
+		image?: string;
+		/** OG canonical URL */
+		url?: string;
+		/** OG type (default: 'website') */
+		type?: string;
+	};
+	/** Twitter card meta tags */
+	twitter?: {
+		/** Twitter card type */
+		card?: string;
+		/** Twitter @username */
+		site?: string;
+	};
+	/** Array of script URLs to include at end of body */
+	scripts?: string[];
+	/** Array of stylesheet URLs to include in head */
+	styles?: string[];
+	/** Raw HTML escape hatch for head */
+	head?: string;
 }
-declare function createAotManifestManager(options: AotManifestManagerOptions): AotManifestManager;
-import { FontFallbackMetrics as FontFallbackMetrics5 } from "@vertz/ui";
-import { SSRAuth as SSRAuth2 } from "@vertz/ui/internals";
-import { CompiledRoute, FontFallbackMetrics as FontFallbackMetrics3, Theme as Theme2 } from "@vertz/ui";
-import { SSRAuth as SSRAuth_jq1nwm } from "@vertz/ui/internals";
-interface SSRModule {
-	default?: () => unknown;
-	App?: () => unknown;
+/**
+* Render a VNode to a full HTML Response with common page structure.
+*
+* This is the main entry point for zero-boilerplate SSR. It wraps the component
+* in a complete HTML document with doctype, head (meta, OG, Twitter, favicon,
+* styles), and body (component content + scripts).
+*
+* @param vnode - The root VNode to render
+* @param options - Optional page configuration
+* @returns A Response with text/html content-type
+*
+* @example
+* ```ts
+* // Minimal usage
+* return renderPage(App)
+*
+* // Full options
+* return renderPage(App, {
+*   title: 'My App',
+*   description: 'Built with vertz',
+*   og: { image: '/og.png' },
+*   scripts: ['/app.js'],
+*   styles: ['/app.css'],
+* })
+* ```
+*/
+declare function renderPage(vnode: VNode, options?: PageOptions): Response;
+import { FontFallbackMetrics as FontFallbackMetrics6, Theme as Theme2 } from "@vertz/ui";
+interface RenderToHTMLOptions<AppFn extends () => VNode> {
+	/** The app component function */
+	app: AppFn;
+	/** Request URL for SSR */
+	url: string;
+	/** Theme definition for CSS vars */
 	theme?: Theme2;
-	/** Global CSS strings to include in every SSR response (e.g. resets, body styles). */
+	/** Global CSS strings to inject */
 	styles?: string[];
-	/**
-	* Return all CSS tracked by the bundled @vertz/ui instance.
-	* The Vite SSR build inlines @vertz/ui into the server bundle, creating
-	* a separate module instance from @vertz/ui-server's dependency. Without
-	* this, component CSS from module-level css() calls is invisible to the
-	* SSR renderer. Export `getInjectedCSS` from @vertz/ui in the app entry.
-	*/
-	getInjectedCSS?: () => string[];
-	/** Compiled routes exported from the app for build-time SSG with generateParams. */
-	routes?: CompiledRoute[];
-	/** Code-generated API client for manifest-driven zero-discovery prefetching. */
-	api?: Record<string, Record<string, (...args: unknown[]) => unknown>>;
-}
-interface SSRRenderResult {
-	html: string;
-	css: string;
-	ssrData: Array<{
-		key: string;
-		data: unknown;
-	}>;
-	/** Font preload link tags for injection into <head>. */
-	headTags: string;
-	/** Route patterns discovered by createRouter() during SSR (for build-time pre-rendering). */
-	discoveredRoutes?: string[];
-	/** Route patterns that matched the current URL (for per-route modulepreload). */
-	matchedRoutePatterns?: string[];
-	/** Set when ProtectedRoute writes a redirect during SSR. Server should return 302. */
-	redirect?: {
-		to: string;
+	/** HTML head configuration */
+	head?: {
+		title?: string;
+		meta?: Array<{
+			name?: string;
+			property?: string;
+			content: string;
+		}>;
+		links?: Array<{
+			rel: string;
+			href: string;
+		}>;
 	};
+	/** Container selector (default '#app') */
+	container?: string;
+	/** Pre-computed font fallback metrics (computed at server startup). */
+	fallbackMetrics?: Record<string, FontFallbackMetrics6>;
 }
-interface SSRDiscoverResult {
-	resolved: Array<{
-		key: string;
-		data: unknown;
-	}>;
-	pending: string[];
+interface RenderToHTMLStreamOptions<AppFn extends () => VNode> extends RenderToHTMLOptions<AppFn> {
+	/** CSP nonce for inline scripts */
+	nonce?: string;
+	/** Global default for per-query ssrTimeout (ms) */
+	ssrTimeout?: number;
+	/** Hard timeout for entire stream (ms, default 30000) */
+	streamTimeout?: number;
 }
 /**
-* Render an SSR module to an HTML string with CSS and pre-fetched query data.
+* Render a component to a streaming HTML Response.
 *
-* Performs a two-pass render:
-* - Pass 1: Discovery — calls the app to trigger query() registrations, awaits them
-* - Pass 2: Render — calls the app again with data populated, renders to HTML
+* The initial HTML is sent immediately. For slow queries that timed out
+* during SSR, their resolved data is streamed as inline `<script>` chunks
+* that push data to the client's reactive system.
+*
+* @returns Promise<Response> - A streaming Response with text/html content
 */
-declare function ssrRenderToString(module: SSRModule, url: string, options?: {
-	ssrTimeout?: number;
-	/** Pre-computed font fallback metrics (computed at server startup). */
-	fallbackMetrics?: Record<string, FontFallbackMetrics3>;
-	/** Auth state resolved from session cookie. Passed to SSRRenderContext for AuthProvider. */
-	ssrAuth?: SSRAuth_jq1nwm;
-}): Promise<SSRRenderResult>;
+declare function renderToHTMLStream<AppFn extends () => VNode>(options: RenderToHTMLStreamOptions<AppFn>): Promise<Response>;
 /**
-* Discover queries for a given URL without rendering.
-* Runs only Pass 1 (query registration + resolution), no Pass 2 render.
-* Used by the production handler to pre-fetch query data for client-side navigations.
+* Render a VNode to a full HTML string.
+*
+* This is a wrapper around renderPage() that provides a simpler API for
+* theme and style injection.
+*
+* @param options - Render options including app, url, theme, styles, head
+* @returns Promise<string> - The rendered HTML string
+*
+* @example
+* ```ts
+* import { renderToHTML, defineTheme } from '@vertz/ui-server';
+*
+* const theme = defineTheme({
+*   colors: { primary: { DEFAULT: '#3b82f6' } }
+* });
+*
+* const html = await renderToHTML({
+*   app: App,
+*   url: '/',
+*   theme,
+*   styles: ['body { margin: 0; }'],
+*   head: { title: 'My App' }
+* });
+* ```
 */
-declare function ssrDiscoverQueries(module: SSRModule, url: string, options?: {
-	ssrTimeout?: number;
-}): Promise<SSRDiscoverResult>;
-import { FontFallbackMetrics as FontFallbackMetrics4 } from "@vertz/ui";
-import { SSRAuth } from "@vertz/ui/internals";
-import { ExtractedQuery } from "@vertz/ui-compiler";
-/** Serialized entity access rules from the prefetch manifest. */
-type EntityAccessMap = Record<string, Partial<Record<string, SerializedAccessRule>>>;
-interface SSRPrefetchManifest {
-	/** Route patterns present in the manifest. */
-	routePatterns: string[];
-	/** Entity access rules keyed by entity name → operation → serialized rule. */
-	entityAccess?: EntityAccessMap;
-	/** Route entries with query binding metadata for zero-discovery prefetch. */
-	routeEntries?: Record<string, {
-		queries: ExtractedQuery[];
-	}>;
-}
-interface SSRSinglePassOptions {
-	ssrTimeout?: number;
-	/** Pre-computed font fallback metrics (computed at server startup). */
-	fallbackMetrics?: Record<string, FontFallbackMetrics4>;
-	/** Auth state resolved from session cookie. */
-	ssrAuth?: SSRAuth;
-	/** Set to false to fall back to two-pass rendering. Default: true. */
-	prefetch?: boolean;
-	/** Prefetch manifest for entity access filtering. */
-	manifest?: SSRPrefetchManifest;
-	/** Session data for access rule evaluation. */
-	prefetchSession?: PrefetchSession;
-}
+declare function renderToHTML<AppFn extends () => VNode>(options: RenderToHTMLOptions<AppFn>): Promise<string>;
+/**
+* @deprecated Use the options-object overload: `renderToHTML({ app, url, ... })`
+*/
+declare function renderToHTML<AppFn extends () => VNode>(app: AppFn, options: RenderToHTMLOptions<AppFn>): Promise<string>;
 /**
-* Render an SSR module in a single pass via discovery-only execution.
+* Render a VNode tree to a `ReadableStream` of HTML chunks.
 *
-* 1. Discovery: Run the app factory to capture query registrations (no stream render)
-* 2. Prefetch: Await all discovered queries with timeout
-* 3. Render: Create a fresh context with pre-populated cache, render once
+* This is the main SSR entry point. It walks the virtual tree, serializing
+* synchronous content immediately and deferring Suspense boundaries.
 *
-* Falls back to two-pass (`ssrRenderToString`) when:
-* - `prefetch: false` is set
-* - A redirect is detected during discovery
+* Suspense boundaries emit:
+* 1. A `<div id="v-slot-N">fallback</div>` placeholder inline
+* 2. A `<template id="v-tmpl-N">resolved</template><script>...<\/script>` chunk
+*    appended after the main content once the async content resolves
+*
+* This enables out-of-order streaming: the browser can paint the fallback
+* immediately and swap in the resolved content when it arrives.
 */
-declare function ssrRenderSinglePass(module: SSRModule, url: string, options?: SSRSinglePassOptions): Promise<SSRRenderResult>;
-/** Context passed to AOT render functions for accessing data and runtime holes. */
-interface SSRAotContext {
-	/** Pre-generated closures for runtime-rendered components. */
-	holes: Record<string, () => string>;
-	/** Access query data by cache key. */
-	getData(key: string): unknown;
-	/** Auth session for conditional rendering. */
-	session: PrefetchSession | undefined;
-	/** Route params for the current request. */
-	params: Record<string, string>;
-}
-/** An AOT render function: takes props/data and context, returns HTML string. */
-type AotRenderFn = (data: Record<string, unknown>, ctx: SSRAotContext) => string;
-/** Per-route AOT entry in the manifest. */
-interface AotRouteEntry {
-	/** The pre-compiled render function. */
-	render: AotRenderFn;
-	/** Component names that need runtime fallback (holes). */
-	holes: string[];
-	/** Query cache keys this route reads via ctx.getData(). */
-	queryKeys?: string[];
-}
+declare function renderToStream(tree: VNode | string | RawHtml, options?: RenderToStreamOptions): ReadableStream<Uint8Array>;
+/** Reset the slot counter (for testing). */
+declare function resetSlotCounter(): void;
 /**
-* AOT manifest — maps route patterns to pre-compiled render functions.
+* Create a Suspense slot placeholder.
 *
-* Generated at build time by the AOT compiler pipeline.
+* Wraps fallback content in a `<div id="v-slot-N">` so it can later
+* be replaced by the resolved async content via a template chunk.
+*
+* Returns the placeholder VNode and the assigned slot ID.
 */
-interface AotManifest {
-	/** Route pattern → AOT entry. */
-	routes: Record<string, AotRouteEntry>;
-}
-/** Options for `ssrRenderAot()`. */
-interface SSRRenderAotOptions {
-	/** AOT manifest with pre-compiled render functions. */
-	aotManifest: AotManifest;
-	/** Prefetch manifest for route matching and data fetching. */
-	manifest?: SSRPrefetchManifest;
-	/** SSR timeout in ms. */
-	ssrTimeout?: number;
-	/** Pre-computed font fallback metrics. */
-	fallbackMetrics?: Record<string, FontFallbackMetrics5>;
-	/** Auth state resolved from session cookie. */
-	ssrAuth?: SSRAuth2;
-	/** Session data for access rule evaluation. */
-	prefetchSession?: PrefetchSession;
-	/** AOT diagnostics collector (dev mode). When provided with VERTZ_DEBUG=aot, enables dual rendering and divergence detection. */
-	diagnostics?: AotDiagnostics;
-}
+declare function createSlotPlaceholder(fallback: VNode | string): VNode & {
+	_slotId: number;
+};
+import { AccessSet as AccessSet2 } from "@vertz/ui/auth";
 /**
-* Create closure-based runtime fallback renderers for components
-* that cannot be AOT-compiled.
+* Extract an AccessSet from a decoded JWT payload for SSR injection.
 *
-* Each hole closure:
-* 1. Runs inside `ssrStorage.run()` to provide SSRRenderContext
-* 2. Calls the component factory via the SSR module
-* 3. Converts the result to VNode and serializes to HTML string
-* 4. Shares the query cache with the AOT function
+* - If the JWT has an inline `acl.set` (no overflow), returns the decoded AccessSet.
+* - If `acl.overflow` is true, returns `null` — caller should re-compute from live stores.
+* - If no `acl` claim exists, returns `null`.
 *
-* @param holeNames - Component names that need runtime rendering
-* @param module - SSR module with component factories
-* @param url - Request URL for context
-* @param queryCache - Pre-populated query cache (shared with AOT)
-* @param ssrAuth - Auth state for the request
+* @param jwtPayload - The decoded JWT payload (from verifyJWT)
+* @returns The AccessSet for SSR injection, or null
 */
-declare function createHoles(holeNames: string[], module: SSRModule, url: string, queryCache: Map<string, unknown>, ssrAuth?: SSRAuth2): Record<string, () => string>;
+declare function getAccessSetForSSR(jwtPayload: Record<string, unknown> | null): AccessSet2 | null;
 /**
-* Render a page using pre-compiled AOT string-builder functions.
-*
-* Falls back to `ssrRenderSinglePass()` when:
-* - No route match in the AOT manifest
-* - No prefetch manifest for route matching
+* Serialize an AccessSet into a `<script>` tag that sets
+* `window.__VERTZ_ACCESS_SET__`.
 *
-* Pipeline:
-* 1. Match URL to route pattern
-* 2. Look up AOT entry in manifest
-* 3. Prefetch query data (reuses single-pass prefetch logic)
-* 4. Create runtime holes (closures for non-AOT components)
-* 5. Call AOT render function with data + context
-* 6. Collect CSS, ssrData, headTags
-* 7. Return SSRRenderResult
+* @param accessSet - The access set to serialize
+* @param nonce - Optional CSP nonce for the script tag
 */
-declare function ssrRenderAot(module: SSRModule, url: string, options: SSRRenderAotOptions): Promise<SSRRenderResult>;
-/** Check if VERTZ_DEBUG includes the 'aot' category. */
-declare function isAotDebugEnabled(): boolean;
+declare function createAccessSetScript(accessSet: AccessSet2, nonce?: string): string;
+import { RenderAdapter } from "@vertz/ui/internals";
+/**
+* Create an SSR adapter that uses in-memory SSR node classes.
+* Replaces `installDomShim()` — no global mutation needed.
+*/
+declare function createSSRAdapter(): RenderAdapter;
+/** Per-component entry in the dev AOT manifest. */
+interface AotDevComponentEntry {
+	tier: "static" | "data-driven" | "conditional" | "runtime-fallback";
+	holes: string[];
+	/** The file this component was compiled from. */
+	file: string;
+}
+/** Dev-mode AOT manifest — tracks all components across all files. */
+interface AotDevManifest {
+	components: Record<string, AotDevComponentEntry>;
+}
+interface AotManifestSnapshot {
+	manifest: AotDevManifest | null;
+	rebuildCount: number;
+	lastRebuildMs: number | null;
+	lastRebuildAt: string | null;
+}
+interface AotManifestManagerOptions {
+	/** Read a file's contents. Returns undefined if file doesn't exist. */
+	readFile: (path: string) => string | undefined;
+	/** List all files in the source directory (absolute paths). */
+	listFiles: () => string[];
+}
+interface AotManifestManager {
+	/** Initial full build — compile all TSX files. */
+	build(): void;
+	/** Handle a file change — recompile a single file. */
+	onFileChange(filePath: string, sourceText: string): void;
+	/** Get the current manifest (atomic read). */
+	getManifest(): AotDevManifest | null;
+	/** Get diagnostic snapshot for endpoints. */
+	getSnapshot(): AotManifestSnapshot;
+	/** Get AotDiagnostics instance for the diagnostics endpoint. */
+	getDiagnostics(): AotDiagnostics;
+}
+declare function createAotManifestManager(options: AotManifestManagerOptions): AotManifestManager;
 /**
 * SSR AOT Runtime Helpers
 *
@@ -821,109 +995,6 @@ declare function clearGlobalSSRTimeout(): void;
 * Returns undefined if not set or outside SSR context.
 */
 declare function getGlobalSSRTimeout(): number | undefined;
-import { FontFallbackMetrics as FontFallbackMetrics6 } from "@vertz/ui";
-import { AccessSet as AccessSet2 } from "@vertz/ui/auth";
-interface SessionData {
-	user: {
-		id: string;
-		email: string;
-		role: string;
-		[key: string]: unknown;
-	};
-	/** Unix timestamp in milliseconds (JWT exp * 1000). */
-	expiresAt: number;
-}
-/** Resolved session data for SSR injection. */
-interface SSRSessionInfo {
-	session: SessionData;
-	/**
-	* Access set from JWT acl claim.
-	* - Present (object): inline access set (no overflow)
-	* - null: access control is configured but the set overflowed the JWT
-	* - undefined: access control is not configured
-	*/
-	accessSet?: AccessSet2 | null;
-}
-/**
-* Callback that extracts session data from a request.
-* Returns null when no valid session exists (expired, missing, or invalid cookie).
-*/
-type SessionResolver = (request: Request) => Promise<SSRSessionInfo | null>;
-/**
-* Serialize a session into a `<script>` tag that sets
-* `window.__VERTZ_SESSION__`.
-*
-* @param session - The session data to serialize
-* @param nonce - Optional CSP nonce for the script tag
-*/
-declare function createSessionScript(session: SessionData, nonce?: string): string;
-interface SSRHandlerOptions {
-	/** The loaded SSR module (import('./dist/server/index.js')) */
-	module: SSRModule;
-	/** HTML template string (contents of dist/client/index.html) */
-	template: string;
-	/** SSR timeout for queries (default: 300ms) */
-	ssrTimeout?: number;
-	/**
-	* Map of CSS asset URLs to their content for inlining.
-	* Replaces `<link rel="stylesheet" href="...">` tags with inline `<style>` tags.
-	* Eliminates extra network requests, preventing FOUC on slow connections.
-	*
-	* @example
-	* ```ts
-	* inlineCSS: { '/assets/vertz.css': await Bun.file('./dist/client/assets/vertz.css').text() }
-	* ```
-	*/
-	inlineCSS?: Record<string, string>;
-	/**
-	* CSP nonce to inject on all inline `<script>` tags emitted during SSR.
-	*
-	* When set, the SSR data hydration script will include `nonce="<value>"`
-	* so that strict Content-Security-Policy headers do not block it.
-	*/
-	nonce?: string;
-	/** Pre-computed font fallback metrics (computed at server startup). */
-	fallbackMetrics?: Record<string, FontFallbackMetrics6>;
-	/** Paths to inject as `<link rel="modulepreload">` in `<head>`. */
-	modulepreload?: string[];
-	/**
-	* Route chunk manifest for per-route modulepreload injection.
-	* When provided, only chunks for the matched route are preloaded instead of all chunks.
-	*/
-	routeChunkManifest?: {
-		routes: Record<string, string[]>;
-	};
-	/** Cache-Control header for HTML responses. Omit or undefined = no header (safe default). */
-	cacheControl?: string;
-	/**
-	* Resolves session data from request cookies for SSR injection.
-	* When provided, SSR HTML includes `window.__VERTZ_SESSION__` and
-	* optionally `window.__VERTZ_ACCESS_SET__` for instant auth hydration.
-	*/
-	sessionResolver?: SessionResolver;
-	/**
-	* Prefetch manifest for single-pass SSR optimization.
-	*
-	* When provided with route entries and an API client export, enables
-	* zero-discovery rendering — queries are prefetched from the manifest
-	* without executing the component tree, then a single render pass
-	* produces the HTML. Without a manifest, SSR still uses the single-pass
-	* discovery-then-render approach (cheaper than two-pass).
-	*/
-	manifest?: SSRPrefetchManifest;
-	/**
-	* Enable progressive HTML streaming. Default: false.
-	*
-	* When true, the Response body is a ReadableStream that sends `<head>`
-	* content (CSS, preloads, fonts) before `<body>` rendering is complete.
-	* This improves TTFB and FCP.
-	*
-	* Has no effect on zero-discovery routes (manifest with routeEntries),
-	* which always use buffered rendering.
-	*/
-	progressiveHTML?: boolean;
-}
-declare function createSSRHandler(options: SSRHandlerOptions): (request: Request) => Promise<Response>;
 interface GenerateSSRHtmlOptions {
 	appHtml: string;
 	css: string;
@@ -1055,4 +1126,4 @@ declare function collectStreamChunks(stream: ReadableStream<Uint8Array>): Promis
 * @param nonce - Optional CSP nonce to add to the inline script tag.
 */
 declare function createTemplateChunk(slotId: number, resolvedHtml: string, nonce?: string): string;
-export { wrapWithHydrationMarkers, toPrefetchSession, streamToString, ssrStorage, ssrRenderToString, ssrRenderSinglePass, ssrRenderAot, ssrDiscoverQueries, setGlobalSSRTimeout, serializeToHtml, safeSerialize, resetSlotCounter, renderToStream, renderToHTMLStream, renderToHTML, renderPage, renderHeadToHtml, renderAssetTags, registerSSRQuery, reconstructDescriptors, rawHtml, matchUrlToPatterns, isInSSR, isAotDebugEnabled, inlineCriticalCss, getStreamingRuntimeScript, getSSRUrl, getSSRQueries, getGlobalSSRTimeout, getAccessSetForSSR, generateSSRHtml, generateAotBuildManifest, extractFontMetrics, evaluateAccessRule, encodeChunk, detectFallbackFont, createTemplateChunk, createSlotPlaceholder, createSessionScript, createSSRHandler, createSSRDataChunk, createSSRAdapter, createPrefetchManifestManager, createHoles, createAotManifestManager, createAccessSetScript, collectStreamChunks, clearGlobalSSRTimeout, __ssr_style_object, __ssr_spread, __esc_attr, __esc, VNode, SessionResolver, SessionData, SerializedAccessRule, SSRSinglePassOptions, SSRSessionInfo, SSRRenderResult, SSRRenderAotOptions, SSRQueryEntry2 as SSRQueryEntry, SSRPrefetchManifest, SSRModule, SSRHandlerOptions, SSRDiscoverResult, SSRAotContext, RenderToStreamOptions, RenderToHTMLStreamOptions, RenderToHTMLOptions, ReconstructedDescriptor, RawHtml, PrefetchSession, PrefetchManifestSnapshot, PrefetchManifestManagerOptions, PrefetchManifestManager, PageOptions, MatchedRoute, HydrationOptions, HeadEntry, HeadCollector, GenerateSSRHtmlOptions, FontFallbackMetrics7 as FontFallbackMetrics, FallbackFontName2 as FallbackFontName, EntityAccessMap, AssetDescriptor, AotTier, AotRouteEntry, AotRenderFn, AotManifestSnapshot, AotManifestManagerOptions, AotManifestManager, AotManifest, AotDivergenceEntry, AotDiagnosticsSnapshot, AotDiagnostics, AotDevManifest, AotDevComponentEntry, AotComponentDiagnostic, AotBuildManifest, AotBuildComponentEntry };
+export { wrapWithHydrationMarkers, toPrefetchSession, streamToString, ssrStorage, ssrRenderToString, ssrRenderSinglePass, ssrRenderAot, ssrDiscoverQueries, setGlobalSSRTimeout, serializeToHtml, safeSerialize, resetSlotCounter, renderToStream, renderToHTMLStream, renderToHTML, renderPage, renderHeadToHtml, renderAssetTags, registerSSRQuery, reconstructDescriptors, rawHtml, matchUrlToPatterns, loadAotManifest, isInSSR, isAotDebugEnabled, inlineCriticalCss, getStreamingRuntimeScript, getSSRUrl, getSSRQueries, getGlobalSSRTimeout, getAccessSetForSSR, generateSSRHtml, generateAotBuildManifest, generateAotBarrel, extractRoutes, extractFontMetrics, evaluateAccessRule, encodeChunk, detectFallbackFont, createTemplateChunk, createSlotPlaceholder, createSessionScript, createSSRHandler, createSSRDataChunk, createSSRAdapter, createPrefetchManifestManager, createNodeHandler, createHoles, createAotManifestManager, createAccessSetScript, collectStreamChunks, clearGlobalSSRTimeout, buildAotRouteMap, __ssr_style_object, __ssr_spread, __esc_attr, __esc, VNode, SessionResolver, SessionData, SerializedAccessRule, SSRSinglePassOptions, SSRSessionInfo, SSRRenderResult, SSRRenderAotOptions, SSRQueryEntry2 as SSRQueryEntry, SSRPrefetchManifest, SSRModule, SSRHandlerOptions, SSRDiscoverResult, SSRAotContext, RenderToStreamOptions, RenderToHTMLStreamOptions, RenderToHTMLOptions, ReconstructedDescriptor, RawHtml, PrefetchSession, PrefetchManifestSnapshot, PrefetchManifestManagerOptions, PrefetchManifestManager, PageOptions, NodeHandlerOptions, MatchedRoute, HydrationOptions, HeadEntry, HeadCollector, GenerateSSRHtmlOptions, FontFallbackMetrics7 as FontFallbackMetrics, FallbackFontName2 as FallbackFontName, ExtractedRoute, EntityAccessMap, AssetDescriptor, AotTier, AotRouteMapEntry, AotRouteEntry, AotRenderFn, AotManifestSnapshot, AotManifestManagerOptions, AotManifestManager, AotManifest, AotDivergenceEntry, AotDiagnosticsSnapshot, AotDiagnostics, AotDevManifest, AotDevComponentEntry, AotComponentDiagnostic, AotCompiledFile, AotBuildManifest, AotBuildComponentEntry, AotBarrelResult };