@vertz/ui-server 0.2.23 → 0.2.25

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { FallbackFontName as FallbackFontName2, FontFallbackMetrics as FontFallbackMetrics6 } from "@vertz/ui";
 /** A raw HTML string that bypasses escaping during serialization. */
 interface RawHtml {
 	__raw: true;
@@ -80,7 +81,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 +317,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.
@@ -393,6 +472,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;
@@ -540,6 +621,109 @@ interface GenerateSSRHtmlOptions {
 * Generate a complete HTML document from SSR render results.
 */
 declare function generateSSRHtml(options: GenerateSSRHtmlOptions): string;
+import { PrefetchManifest } from "@vertz/ui-compiler";
+import { FontFallbackMetrics as FontFallbackMetrics5 } 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, FontFallbackMetrics5>;
+	/** 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>;
+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;
+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[];
+/**
+* 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 +774,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, ssrDiscoverQueries, setGlobalSSRTimeout, serializeToHtml, safeSerialize, resetSlotCounter, renderToStream, renderToHTMLStream, renderToHTML, renderPage, renderHeadToHtml, renderAssetTags, registerSSRQuery, reconstructDescriptors, rawHtml, matchUrlToPatterns, isInSSR, inlineCriticalCss, getStreamingRuntimeScript, getSSRUrl, getSSRQueries, getGlobalSSRTimeout, getAccessSetForSSR, generateSSRHtml, extractFontMetrics, evaluateAccessRule, encodeChunk, detectFallbackFont, createTemplateChunk, createSlotPlaceholder, createSessionScript, createSSRHandler, createSSRDataChunk, createSSRAdapter, createPrefetchManifestManager, createAccessSetScript, collectStreamChunks, clearGlobalSSRTimeout, VNode, SessionResolver, SessionData, SerializedAccessRule, SSRSinglePassOptions, SSRSessionInfo, SSRRenderResult, SSRQueryEntry2 as SSRQueryEntry, SSRPrefetchManifest, SSRModule, SSRHandlerOptions, SSRDiscoverResult, RenderToStreamOptions, RenderToHTMLStreamOptions, RenderToHTMLOptions, ReconstructedDescriptor, RawHtml, PrefetchSession, PrefetchManifestSnapshot, PrefetchManifestManagerOptions, PrefetchManifestManager, PageOptions, MatchedRoute, HydrationOptions, HeadEntry, HeadCollector, GenerateSSRHtmlOptions, FontFallbackMetrics6 as FontFallbackMetrics, FallbackFontName2 as FallbackFontName, EntityAccessMap, AssetDescriptor };