@vertz/ui-server 0.2.0 → 0.2.3

package/dist/bun-dev-server.d.ts

@@ -0,0 +1,115 @@
+interface BunDevServerOptions {
+	/** SSR entry module (e.g., './src/app.tsx') */
+	entry: string;
+	/** Port to listen on. @default 3000 */
+	port?: number;
+	/** Host to bind to. @default 'localhost' */
+	host?: string;
+	/** API handler for full-stack mode */
+	apiHandler?: (req: Request) => Promise<Response>;
+	/** Paths to skip SSR (delegate to apiHandler). @default ['/api/'] */
+	skipSSRPaths?: string[];
+	/** OpenAPI spec options */
+	openapi?: {
+		specPath: string;
+	};
+	/** When true, entry is SSRModule (exports App/theme/styles). @default false */
+	ssrModule?: boolean;
+	/** Client entry path (for hydration). */
+	clientEntry?: string;
+	/** HTML page title. @default 'Vertz App' */
+	title?: string;
+	/** Project root. @default process.cwd() */
+	projectRoot?: string;
+	/** Log requests. @default true */
+	logRequests?: boolean;
+}
+interface ErrorDetail {
+	message: string;
+	file?: string;
+	absFile?: string;
+	line?: number;
+	column?: number;
+	lineText?: string;
+	stack?: string;
+}
+type ErrorCategory = "build" | "resolve" | "runtime" | "ssr";
+interface BunDevServer {
+	start(): Promise<void>;
+	stop(): Promise<void>;
+	/** Broadcast an error to all connected WebSocket clients. */
+	broadcastError(category: ErrorCategory, errors: ErrorDetail[]): void;
+	/** Clear current error and notify all connected WebSocket clients.
+	*  Sets a 5s grace period that suppresses stale runtime errors. */
+	clearError(): void;
+	/** Clear error for a file change — no grace period, since HMR may trigger new errors. */
+	clearErrorForFileChange(): void;
+	/** Set the last changed file path (for testing). */
+	setLastChangedFile(file: string): void;
+}
+interface IndexHtmlStasher {
+	stash(): void;
+	restore(): void;
+}
+/**
+* Create a stasher that renames index.html during dev so Bun's built-in
+* HMR server doesn't auto-serve it, bypassing our SSR fetch handler.
+*/
+declare function createIndexHtmlStasher(projectRoot: string): IndexHtmlStasher;
+interface HMRAssets {
+	/** Discovered `/_bun/client/<hash>.js` URL, or null if not found */
+	scriptUrl: string | null;
+	/** HMR bootstrap `<script>` tag, or null if not found */
+	bootstrapScript: string | null;
+}
+/**
+* Parse the HTML returned by the HMR shell route (`/__vertz_hmr`) to extract
+* the bundled client script URL and HMR bootstrap snippet.
+*/
+declare function parseHMRAssets(html: string): HMRAssets;
+interface SSRPageHtmlOptions {
+	title: string;
+	css: string;
+	bodyHtml: string;
+	ssrData: unknown[];
+	scriptTag: string;
+}
+/**
+* Generate a full SSR HTML page with the given content, CSS, SSR data, and script tag.
+*/
+declare function generateSSRPageHtml({ title, css, bodyHtml, ssrData, scriptTag }: SSRPageHtmlOptions): string;
+interface FetchInterceptorOptions {
+	apiHandler: (req: Request) => Promise<Response>;
+	origin: string;
+	skipSSRPaths: string[];
+	originalFetch: typeof fetch;
+}
+/**
+* Create a fetch interceptor that routes local API requests through the
+* in-memory apiHandler instead of making HTTP self-fetch calls.
+* Matches production (Cloudflare) behavior where fetch('/api/...') during
+* SSR goes through the same handler.
+*/
+declare function createFetchInterceptor({ apiHandler, origin, skipSSRPaths, originalFetch }: FetchInterceptorOptions): typeof fetch;
+/**
+* Build the `<script>` tag for SSR HTML output.
+*
+* When `bundledScriptUrl` is available (HMR discovered), generates a
+* non-executing placeholder (`type="text/plain"`) plus a loader script that
+* fetch-validates the bundle before loading it. This prevents the infinite
+* reload loop when Bun serves its reload stub for a failed compilation.
+*
+* The placeholder preserves `data-bun-dev-server-script` and `src` attributes
+* so Bun's HMR bootstrap (which reads `.src` via IDL) still works.
+*
+* Falls back to a plain `<script type="module">` when no bundled URL is
+* available (source-only mode, no Bun compilation).
+*/
+declare function buildScriptTag(bundledScriptUrl: string | null, hmrBootstrapScript: string | null, clientSrc: string): string;
+/**
+* Create a unified Bun dev server with SSR + HMR.
+*
+* SSR is always on. HMR always works. No mode toggle needed.
+*/
+declare function createBunDevServer(options: BunDevServerOptions): BunDevServer;
+export { parseHMRAssets, generateSSRPageHtml, createIndexHtmlStasher, createFetchInterceptor, createBunDevServer, buildScriptTag, SSRPageHtmlOptions, IndexHtmlStasher, HMRAssets, FetchInterceptorOptions, ErrorDetail, ErrorCategory, BunDevServerOptions, BunDevServer };