npm - @vertz/ui-server - Versions diffs - 0.2.0 → 0.2.3 - Mend

@vertz/ui-server 0.2.0 → 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (21) hide show

package/README.md +298 -310
package/dist/bun-dev-server.d.ts +115 -0
package/dist/bun-dev-server.js +2032 -0
package/dist/bun-plugin/fast-refresh-dom-state.d.ts +51 -0
package/dist/bun-plugin/fast-refresh-dom-state.js +10 -0
package/dist/bun-plugin/fast-refresh-runtime.d.ts +43 -0
package/dist/bun-plugin/fast-refresh-runtime.js +150 -0
package/dist/bun-plugin/index.d.ts +44 -0
package/dist/bun-plugin/index.js +197 -0
package/dist/dom-shim/index.d.ts +37 -6
package/dist/dom-shim/index.js +12 -324
package/dist/index.d.ts +331 -64
package/dist/index.js +285 -292
package/dist/jsx-runtime/index.js +15 -2
package/dist/shared/chunk-2qsqp9xj.js +150 -0
package/dist/shared/chunk-32688jav.js +564 -0
package/dist/shared/chunk-4t0ekdyv.js +513 -0
package/dist/shared/chunk-eb80r8e8.js +4 -0
package/dist/ssr/index.d.ts +86 -0
package/dist/ssr/index.js +11 -0
package/package.json +35 -18

package/dist/index.d.ts CHANGED Viewed

@@ -3,7 +3,25 @@ interface RawHtml {
 	__raw: true;
 	html: string;
 }
-/** Create a raw HTML string that will not be escaped during serialization. */
+/**
+* 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()`.
+*
+* @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 rawHtml(html: string): RawHtml;
 /** Virtual node representing an HTML element for SSR serialization. */
 interface VNode {
@@ -62,68 +80,6 @@ declare function renderAssetTags(assets: AssetDescriptor[]): string;
 * Returns an empty string if the CSS is empty.
 */
 declare function inlineCriticalCss(css: string): string;
-import { IncomingMessage, Server, ServerResponse } from "node:http";
-import { InlineConfig, ViteDevServer } from "vite";
-interface DevServerOptions {
-	/**
-	* Path to the SSR entry module (relative to project root).
-	* This module should a `renderToString` function.
-	*/
-	entry: string;
-	/**
-	* Port to listen on.
-	* @default 5173
-	*/
-	port?: number;
-	/**
-	* Host to bind to.
-	* @default '0.0.0.0'
-	*/
-	host?: string;
-	/**
-	* Custom Vite configuration.
-	* Merged with default middleware mode config.
-	*/
-	viteConfig?: InlineConfig;
-	/**
-	* Custom middleware to run before SSR handler.
-	* Useful for API routes, static file serving, etc.
-	*/
-	middleware?: (req: IncomingMessage, res: ServerResponse, next: () => void) => void;
-	/**
-	* Skip invalidating modules on each request.
-	* Useful for debugging or performance testing.
-	* @default false
-	*/
-	skipModuleInvalidation?: boolean;
-	/**
-	* Log requests to console.
-	* @default true
-	*/
-	logRequests?: boolean;
-}
-interface DevServer {
-	/**
-	* Start the server and listen on the configured port.
-	*/
-	listen(): Promise<void>;
-	/**
-	* Close the server.
-	*/
-	close(): Promise<void>;
-	/**
-	* The underlying Vite dev server.
-	*/
-	vite: ViteDevServer;
-	/**
-	* The underlying HTTP server.
-	*/
-	httpServer: Server;
-}
-/**
-* Create a Vite SSR development server.
-*/
-declare function createDevServer(options: DevServerOptions): DevServer;
 /**
 * Collector for `<head>` metadata during SSR.
 *
@@ -169,6 +125,146 @@ declare function serializeToHtml(node: VNode | string | RawHtml): string;
 * 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;
+}
+/**
+* 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 { 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;
+}
+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 a component to a streaming HTML Response.
+*
+* 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 renderToHTMLStream<AppFn extends () => VNode>(options: RenderToHTMLStreamOptions<AppFn>): Promise<Response>;
+/**
+* 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 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 a VNode tree to a `ReadableStream` of HTML chunks.
 *
@@ -197,6 +293,177 @@ declare function resetSlotCounter(): void;
 declare function createSlotPlaceholder(fallback: VNode | string): VNode & {
 	_slotId: number;
 };
+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;
+import { AsyncLocalStorage } from "node:async_hooks";
+interface SSRQueryEntry {
+	promise: Promise<unknown>;
+	timeout: number;
+	resolve: (data: unknown) => void;
+	key: string;
+	resolved?: boolean;
+}
+interface SSRContext {
+	url: string;
+	errors: unknown[];
+	queries: SSRQueryEntry[];
+	/** Global per-query timeout override (ms). Set by the dev server entry. */
+	globalSSRTimeout?: number;
+}
+declare const ssrStorage: AsyncLocalStorage<SSRContext>;
+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(): SSRQueryEntry[];
+/**
+* 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 { Theme as Theme2 } from "@vertz/ui";
+interface SSRModule {
+	default?: () => unknown;
+	App?: () => unknown;
+	theme?: Theme2;
+	/** Global CSS strings to include in every SSR response (e.g. resets, body styles). */
+	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[];
+}
+interface SSRRenderResult {
+	html: string;
+	css: string;
+	ssrData: Array<{
+		key: string;
+		data: unknown;
+	}>;
+}
+interface SSRDiscoverResult {
+	resolved: Array<{
+		key: string;
+		data: unknown;
+	}>;
+	pending: string[];
+}
+/**
+* Render an SSR module to an HTML string with CSS and pre-fetched query data.
+*
+* 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 ssrRenderToString(module: SSRModule, url: string, options?: {
+	ssrTimeout?: number;
+}): 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>;
+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;
+}
+/**
+* Create a web-standard SSR request handler.
+*
+* Handles two types of requests:
+* - X-Vertz-Nav: 1 -> SSE Response with pre-fetched query data
+* - Normal HTML request -> SSR-rendered HTML Response
+*
+* Does NOT serve static files — that's the adapter/platform's job.
+*/
+declare function createSSRHandler(options: SSRHandlerOptions): (request: Request) => Promise<Response>;
+interface GenerateSSRHtmlOptions {
+	appHtml: string;
+	css: string;
+	ssrData: Array<{
+		key: string;
+		data: unknown;
+	}>;
+	clientEntry: string;
+	title?: string;
+}
+/**
+* Generate a complete HTML document from SSR render results.
+*/
+declare function generateSSRHtml(options: GenerateSSRHtmlOptions): string;
+/**
+* Serialize data to JSON with `<` escaped as `\u003c`.
+* Prevents `<\/script>` breakout and `<!--` injection in inline scripts.
+*/
+declare function safeSerialize(data: unknown): string;
+/**
+* Generate the inline `<script>` tag that bootstraps the SSR data streaming
+* event bus on the client. Injected into `<head>` during streaming render.
+*
+* Creates:
+* - `window.__VERTZ_SSR_DATA__` — buffered array of received data
+* - `window.__VERTZ_SSR_PUSH__` — function to push data + dispatch event
+*/
+declare function getStreamingRuntimeScript(nonce?: string): string;
+/**
+* Create an inline `<script>` chunk that pushes resolved query data
+* to the client via `__VERTZ_SSR_PUSH__`.
+*
+* @param key - The query cache key (must match client-side query key)
+* @param data - The resolved query data
+* @param nonce - Optional CSP nonce for the script tag
+*/
+declare function createSSRDataChunk(key: string, data: unknown, nonce?: string): string;
 /**
 * Encode a string as a UTF-8 Uint8Array chunk.
 */
@@ -224,4 +491,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, serializeToHtml, resetSlotCounter, renderToStream, renderHeadToHtml, renderAssetTags, rawHtml, inlineCriticalCss, encodeChunk, createTemplateChunk, createSlotPlaceholder, createDevServer, collectStreamChunks, VNode, RenderToStreamOptions, RawHtml, HydrationOptions, HeadEntry, HeadCollector, DevServerOptions, DevServer, AssetDescriptor };
+export { wrapWithHydrationMarkers, streamToString, ssrStorage, ssrRenderToString, ssrDiscoverQueries, setGlobalSSRTimeout, serializeToHtml, safeSerialize, resetSlotCounter, renderToStream, renderToHTMLStream, renderToHTML, renderPage, renderHeadToHtml, renderAssetTags, registerSSRQuery, rawHtml, isInSSR, inlineCriticalCss, getStreamingRuntimeScript, getSSRUrl, getSSRQueries, getGlobalSSRTimeout, generateSSRHtml, encodeChunk, createTemplateChunk, createSlotPlaceholder, createSSRHandler, createSSRDataChunk, createSSRAdapter, collectStreamChunks, clearGlobalSSRTimeout, VNode, SSRRenderResult, SSRQueryEntry, SSRModule, SSRHandlerOptions, SSRDiscoverResult, RenderToStreamOptions, RenderToHTMLStreamOptions, RenderToHTMLOptions, RawHtml, PageOptions, HydrationOptions, HeadEntry, HeadCollector, GenerateSSRHtmlOptions, AssetDescriptor };