@vertz/ui-server 0.2.24 → 0.2.26

package/dist/bun-plugin/index.d.ts

@@ -1,6 +1,6 @@
 type ErrorCategory = "build" | "resolve" | "runtime" | "ssr";
 import { CSSExtractionResult } from "@vertz/ui-compiler";
-type DebugCategory = "fields" | "manifest" | "plugin" | "ssr" | "watcher" | "ws";
+type DebugCategory = "aot" | "fields" | "manifest" | "plugin" | "prefetch" | "ssr" | "watcher" | "ws";
 interface DebugLogger {
 	log(category: DebugCategory, message: string, data?: Record<string, unknown>): void;
 	isEnabled(category: DebugCategory): boolean;

package/dist/dom-shim/index.d.ts

@@ -13,6 +13,7 @@ interface VNode {
 * Base Node class for SSR — matches the browser's Node interface minimally
 */
 declare class SSRNode {
+	nodeType: number;
 	childNodes: SSRNode[];
 	parentNode: SSRNode | null;
 	get firstChild(): SSRNode | null;
@@ -28,6 +29,7 @@ declare class SSRNode {
 * hydration cursor can claim during mount.
 */
 declare class SSRComment extends SSRNode {
+	nodeType: number;
 	text: string;
 	constructor(text: string);
 	get data(): string;
@@ -37,6 +39,7 @@ declare class SSRComment extends SSRNode {
 * SSR text node
 */
 declare class SSRTextNode extends SSRNode {
+	nodeType: number;
 	text: string;
 	constructor(text: string);
 	get data(): string;
@@ -46,6 +49,7 @@ declare class SSRTextNode extends SSRNode {
 * SSR document fragment
 */
 declare class SSRDocumentFragment extends SSRNode {
+	nodeType: number;
 	children: (SSRElement | string)[];
 	appendChild(child: SSRElement | SSRTextNode | SSRDocumentFragment): void;
 }

package/dist/dom-shim/index.js

@@ -7,7 +7,7 @@ import {
   installDomShim,
   removeDomShim,
   toVNode
-} from "../shared/chunk-zs75v8qj.js";
+} from "../shared/chunk-gcwqkynf.js";
 export {
   toVNode,
   removeDomShim,

package/dist/index.d.ts

@@ -1,3 +1,16 @@
+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;
@@ -80,7 +93,6 @@ declare function renderAssetTags(assets: AssetDescriptor[]): string;
 * Returns an empty string if the CSS is empty.
 */
 declare function inlineCriticalCss(css: string): string;
-import { FallbackFontName as FallbackFontName2, FontFallbackMetrics as FontFallbackMetrics5 } from "@vertz/ui";
 import { FallbackFontName, FontDescriptor, FontFallbackMetrics } from "@vertz/ui";
 /**
 * Auto-detect which system font to use as fallback base.
@@ -317,6 +329,85 @@ declare function resetSlotCounter(): void;
 declare function createSlotPlaceholder(fallback: VNode | string): VNode & {
 	_slotId: number;
 };
+/**
+* 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.
+*/
+/**
+* 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.
+*/
+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";
+};
+/**
+* Minimal session shape needed for prefetch access evaluation.
+* Extracted from the JWT at SSR request time.
+*/
+type PrefetchSession = {
+	status: "authenticated";
+	roles?: string[];
+	entitlements?: Record<string, boolean>;
+	tenantId?: string;
+} | {
+	status: "unauthenticated";
+};
+/**
+* Convert SSRAuth (from the JWT/session resolver) to PrefetchSession
+* for entity access evaluation during SSR prefetching.
+*/
+declare function toPrefetchSession(ssrAuth: {
+	status: string;
+	user?: {
+		role?: string;
+		[key: string]: unknown;
+	};
+} | undefined): PrefetchSession;
+/**
+* Evaluate a serialized access rule against the current session.
+*
+* Returns true if the query is eligible for prefetch (the user
+* likely has access), false if it should be skipped.
+*
+* 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 evaluateAccessRule(rule: SerializedAccessRule, session: PrefetchSession): boolean;
 import { AccessSet } from "@vertz/ui/auth";
 /**
 * Extract an AccessSet from a decoded JWT payload for SSR injection.
@@ -343,38 +434,114 @@ import { RenderAdapter } from "@vertz/ui/internals";
 * Replaces `installDomShim()` — no global mutation needed.
 */
 declare function createSSRAdapter(): RenderAdapter;
-import { AsyncLocalStorage } from "node:async_hooks";
-import { SSRQueryEntry, SSRRenderContext } from "@vertz/ui/internals";
-import { SSRQueryEntry as SSRQueryEntry2 } from "@vertz/ui/internals";
-declare const ssrStorage: AsyncLocalStorage<SSRRenderContext>;
-declare function isInSSR(): boolean;
-declare function getSSRUrl(): string | undefined;
-/**
-* Register an SSR query for awaiting before final render.
-* No-op when called outside an SSR context.
-*/
-declare function registerSSRQuery(entry: SSRQueryEntry): void;
-/**
-* Get all registered SSR queries for the current render.
-* Returns an empty array when called outside an SSR context.
-*/
-declare function getSSRQueries(): SSRRenderContext["queries"];
-/**
-* Set the global SSR timeout for queries that don't specify their own.
-* Called by the virtual SSR entry to propagate the plugin-level ssrTimeout.
-* Stored in the per-request SSR context (AsyncLocalStorage), not on globalThis.
-*/
-declare function setGlobalSSRTimeout(timeout: number): void;
 /**
-* Clear the global SSR timeout (cleanup after render).
+* AOT SSR Diagnostics
+*
+* Tracks AOT compilation results and provides a JSON snapshot
+* for the `/__vertz_ssr_aot` dev endpoint.
 */
-declare function clearGlobalSSRTimeout(): void;
+/** 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[];
+}
 /**
-* Get the global SSR timeout for the current SSR context.
-* Returns undefined if not set or outside SSR context.
+* Collects AOT compilation diagnostics and produces JSON snapshots.
+*
+* Used by the dev server to power the `/__vertz_ssr_aot` endpoint
+* and by the build pipeline for classification logging.
 */
-declare function getGlobalSSRTimeout(): number | undefined;
-import { FontFallbackMetrics as FontFallbackMetrics4 } from "@vertz/ui";
+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;
+}
+/** 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;
+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 {
@@ -393,6 +560,8 @@ interface SSRModule {
 	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;
@@ -441,6 +610,206 @@ declare function ssrRenderToString(module: SSRModule, url: string, options?: {
 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;
+}
+/**
+* Render an SSR module in a single pass via discovery-only execution.
+*
+* 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
+*
+* Falls back to two-pass (`ssrRenderToString`) when:
+* - `prefetch: false` is set
+* - A redirect is detected during discovery
+*/
+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[];
+}
+/**
+* AOT manifest — maps route patterns to pre-compiled render functions.
+*
+* Generated at build time by the AOT compiler pipeline.
+*/
+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;
+}
+/**
+* Create closure-based runtime fallback renderers for components
+* that cannot be AOT-compiled.
+*
+* 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
+*
+* @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 createHoles(holeNames: string[], module: SSRModule, url: string, queryCache: Map<string, unknown>, ssrAuth?: SSRAuth2): Record<string, () => string>;
+/**
+* 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
+*
+* 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 ssrRenderAot(module: SSRModule, url: string, options: SSRRenderAotOptions): Promise<SSRRenderResult>;
+/** Check if VERTZ_DEBUG includes the 'aot' category. */
+declare function isAotDebugEnabled(): boolean;
+/**
+* SSR AOT Runtime Helpers
+*
+* Lightweight runtime functions used by AOT-compiled SSR string-builder
+* functions. These are injected at the top of compiled output and called
+* inline during string concatenation.
+*
+* Design constraints:
+* - Must produce identical output to html-serializer.ts escapeHtml/escapeAttr
+* - Must be fast — called per-element, per-attribute during SSR
+* - No dependencies beyond this file
+*/
+type Renderable = any;
+/**
+* Escape HTML text content. Matches escapeHtml() from html-serializer.ts exactly.
+*
+* Handles: null, undefined, false → '', true → 'true', numbers → string,
+* arrays → recursive join.
+*/
+declare function __esc(value: Renderable): string;
+/**
+* Escape HTML attribute value. Matches escapeAttr() from html-serializer.ts exactly.
+*/
+declare function __esc_attr(value: Renderable): string;
+/**
+* Render a props object as an HTML attribute string for spread attributes.
+*
+* - Skips null/undefined/false values
+* - Skips event handlers (on* props)
+* - Maps className → class
+* - Boolean true → attribute name only (no value)
+* - Escapes string values
+*/
+declare function __ssr_spread(props: Record<string, Renderable>): string;
+/**
+* Convert a style object to a CSS string.
+*
+* - camelCase → kebab-case
+* - Numeric values get 'px' appended for non-unitless properties
+* - Zero is never suffixed with 'px'
+* - Skips null, undefined, empty string values
+* - Preserves CSS custom properties and vendor prefixes
+*/
+declare function __ssr_style_object(style: Record<string, Renderable>): string;
+import { AsyncLocalStorage } from "node:async_hooks";
+import { SSRQueryEntry, SSRRenderContext as SSRRenderContext2 } from "@vertz/ui/internals";
+import { SSRQueryEntry as SSRQueryEntry2 } from "@vertz/ui/internals";
+declare const ssrStorage: AsyncLocalStorage<SSRRenderContext2>;
+declare function isInSSR(): boolean;
+declare function getSSRUrl(): string | undefined;
+/**
+* Register an SSR query for awaiting before final render.
+* No-op when called outside an SSR context.
+*/
+declare function registerSSRQuery(entry: SSRQueryEntry): void;
+/**
+* Get all registered SSR queries for the current render.
+* Returns an empty array when called outside an SSR context.
+*/
+declare function getSSRQueries(): SSRRenderContext2["queries"];
+/**
+* Set the global SSR timeout for queries that don't specify their own.
+* Called by the virtual SSR entry to propagate the plugin-level ssrTimeout.
+* Stored in the per-request SSR context (AsyncLocalStorage), not on globalThis.
+*/
+declare function setGlobalSSRTimeout(timeout: number): void;
+/**
+* Clear the global SSR timeout (cleanup after render).
+*/
+declare function clearGlobalSSRTimeout(): void;
+/**
+* Get the global SSR timeout for the current SSR context.
+* 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: {
@@ -502,7 +871,7 @@ interface SSRHandlerOptions {
 	*/
 	nonce?: string;
 	/** Pre-computed font fallback metrics (computed at server startup). */
-	fallbackMetrics?: Record<string, FontFallbackMetrics4>;
+	fallbackMetrics?: Record<string, FontFallbackMetrics6>;
 	/** Paths to inject as `<link rel="modulepreload">` in `<head>`. */
 	modulepreload?: string[];
 	/**
@@ -540,6 +909,69 @@ interface GenerateSSRHtmlOptions {
 * Generate a complete HTML document from SSR render results.
 */
 declare function generateSSRHtml(options: GenerateSSRHtmlOptions): string;
+import { ExtractedQuery as ExtractedQuery2 } from "@vertz/ui-compiler";
+interface ReconstructedDescriptor {
+	key: string;
+	fetch: () => Promise<unknown>;
+}
+/**
+* Reconstruct QueryDescriptors from manifest metadata by calling the
+* real API client factories. Returns descriptors with correct `_key`
+* and `_fetch` for pre-populating the SSR query cache.
+*
+* Skips queries that:
+* - Have no entity/operation (variable references)
+* - Reference entities or operations not in the API client
+* - Have unresolvable where bindings (null = dynamic value)
+* - Reference route params not present in the URL
+*/
+declare function reconstructDescriptors(queries: ExtractedQuery2[], routeParams: Record<string, string>, apiClient: Record<string, Record<string, (...args: unknown[]) => unknown>> | undefined): ReconstructedDescriptor[];
+import { PrefetchManifest } from "@vertz/ui-compiler";
+interface PrefetchManifestManagerOptions {
+	/** Absolute path to the router file. */
+	routerPath: string;
+	/** Read a file's contents. Returns undefined if file doesn't exist. */
+	readFile: (path: string) => string | undefined;
+	/** Resolve an import specifier from a given file to an absolute path. */
+	resolveImport: (specifier: string, fromFile: string) => string | undefined;
+}
+interface PrefetchManifestSnapshot {
+	manifest: PrefetchManifest | null;
+	rebuildCount: number;
+	lastRebuildMs: number | null;
+	lastRebuildAt: string | null;
+}
+interface PrefetchManifestManager {
+	/** Initial full manifest build. */
+	build(): void;
+	/** Handle a file change — incremental for components, full for router. */
+	onFileChange(filePath: string, sourceText: string): void;
+	/** Get the SSR manifest for rendering (atomic read). */
+	getSSRManifest(): SSRPrefetchManifest | undefined;
+	/** Get diagnostic snapshot for the `/__vertz_prefetch_manifest` endpoint. */
+	getSnapshot(): PrefetchManifestSnapshot;
+}
+declare function createPrefetchManifestManager(options: PrefetchManifestManagerOptions): PrefetchManifestManager;
+/**
+* SSR route matcher — matches URLs to manifest route patterns.
+*
+* Used by the single-pass SSR pipeline to look up which components
+* and queries are expected for a given URL, enabling entity access
+* filtering before discovery-only execution.
+*/
+interface MatchedRoute {
+	/** The matched route pattern (e.g., '/projects/:projectId/board') */
+	pattern: string;
+	/** Extracted route parameter values (e.g., { projectId: 'abc123' }) */
+	params: Record<string, string>;
+}
+/**
+* Match a URL path against a list of route patterns.
+* Returns all matching patterns (layouts + page) ordered from most general to most specific.
+*
+* Patterns use Express-style `:param` syntax.
+*/
+declare function matchUrlToPatterns(url: string, patterns: string[]): MatchedRoute[];
 /**
 * Serialize data to JSON with `<` escaped as `\u003c`.
 * Prevents `<\/script>` breakout and `<!--` injection in inline scripts.
@@ -590,4 +1022,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, streamToString, ssrStorage, ssrRenderToString, ssrDiscoverQueries, setGlobalSSRTimeout, serializeToHtml, safeSerialize, resetSlotCounter, renderToStream, renderToHTMLStream, renderToHTML, renderPage, renderHeadToHtml, renderAssetTags, registerSSRQuery, rawHtml, isInSSR, inlineCriticalCss, getStreamingRuntimeScript, getSSRUrl, getSSRQueries, getGlobalSSRTimeout, getAccessSetForSSR, generateSSRHtml, extractFontMetrics, encodeChunk, detectFallbackFont, createTemplateChunk, createSlotPlaceholder, createSessionScript, createSSRHandler, createSSRDataChunk, createSSRAdapter, createAccessSetScript, collectStreamChunks, clearGlobalSSRTimeout, VNode, SessionResolver, SessionData, SSRSessionInfo, SSRRenderResult, SSRQueryEntry2 as SSRQueryEntry, SSRModule, SSRHandlerOptions, SSRDiscoverResult, RenderToStreamOptions, RenderToHTMLStreamOptions, RenderToHTMLOptions, RawHtml, PageOptions, HydrationOptions, HeadEntry, HeadCollector, GenerateSSRHtmlOptions, FontFallbackMetrics5 as FontFallbackMetrics, FallbackFontName2 as FallbackFontName, AssetDescriptor };
+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 };