@vertz/cloudflare 0.2.0 → 0.2.1

package/.turbo/turbo-build.log

@@ -1,15 +1,16 @@
 $ bunup
-i Using bunup v0.16.26 and bun v1.3.9
-i Build started
+i Using bunup v0.16.31 and bun v1.3.9
+i Using cloudflare/bunup.config.ts
+i Build started
 
-  src/index.ts
+  src/index.ts
 
-  Output                Raw     Gzip
+  Output                 Raw       Gzip
 
-  dist/index.js       676 B    349 B
-  dist/index.d.ts     327 B    225 B
+  dist/index.js      4.80 KB    1.56 KB
+  dist/index.d.ts    2.56 KB    1.12 KB
 
-  2 files            1003 B    574 B
+  2 files            7.36 KB    2.67 KB
 
 
-✓ Build completed in 114ms
+✓ Build completed in 341ms

package/.turbo/turbo-test.log

@@ -0,0 +1,11 @@
+$ vitest run
+
+ RUN  v4.0.18 /Users/viniciusdacal/vertz-dev/vertz/.claude/worktrees/poc-ssr-hmr/packages/cloudflare
+
+ ✓ tests/handler.test.ts (23 tests) 72ms
+
+ Test Files  1 passed (1)
+      Tests  23 passed (23)
+   Start at  23:53:54
+   Duration  397ms (transform 146ms, setup 0ms, import 186ms, tests 72ms, environment 0ms)
+

package/.turbo/turbo-typecheck.log

@@ -0,0 +1 @@
+$ tsc --noEmit

package/bunup.config.ts

@@ -0,0 +1,20 @@
+import { defineConfig } from 'bunup';
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm'],
+  dts: { inferTypes: true },
+  clean: true,
+  external: ['@vertz/core', '@vertz/ui-server'],
+  // onSuccess strips the CJS createRequire shim that Bun.build injects.
+  // The shim references import.meta.url which is undefined on Cloudflare
+  // Workers, and __require is never actually called in the output.
+  onSuccess: async () => {
+    const path = 'dist/index.js';
+    const code = await Bun.file(path).text();
+    const cleaned = code
+      .replace(/import \{ createRequire \} from "node:module";\n?/, '')
+      .replace(/var __require = \/\* @__PURE__ \*\/ createRequire\(import\.meta\.url\);\n?/, '');
+    await Bun.write(path, cleaned);
+  },
+});

package/dist/index.d.ts

@@ -1,8 +1,71 @@
 import { AppBuilder } from "@vertz/core";
+import { SSRModule } from "@vertz/ui-server/ssr";
 interface CloudflareHandlerOptions {
 	basePath?: string;
 }
-declare function createHandler(app: AppBuilder, options?: CloudflareHandlerOptions): {
-	fetch(request: Request, _env: unknown, _ctx: ExecutionContext): Promise<Response>;
-};
-export { createHandler, CloudflareHandlerOptions };
+/**
+* SSR module configuration for zero-boilerplate server-side rendering.
+*
+* Pass the app module directly and the handler generates the HTML template,
+* wires up createSSRHandler, and handles the full SSR pipeline.
+*/
+interface SSRModuleConfig {
+	/** App module exporting App, theme?, styles?, getInjectedCSS? */
+	module: SSRModule;
+	/** Client-side entry script path. Default: '/assets/entry-client.js' */
+	clientScript?: string;
+	/** HTML document title. Default: 'Vertz App' */
+	title?: string;
+	/** SSR query timeout in ms. Default: 5000 (generous for D1 cold starts). */
+	ssrTimeout?: number;
+}
+/**
+* Full-stack configuration for createHandler.
+*
+* Supports lazy app initialization (for D1 bindings), SSR fallback,
+* and automatic security headers.
+*/
+interface CloudflareHandlerConfig {
+	/**
+	* Factory that creates the AppBuilder. Receives the Worker env bindings.
+	* Called once on first request, then cached.
+	*/
+	app: (env: unknown) => AppBuilder;
+	/** API path prefix. Requests matching this prefix go to the app handler. */
+	basePath: string;
+	/**
+	* SSR configuration for non-API routes.
+	*
+	* - `SSRModuleConfig` — zero-boilerplate: pass the app module directly
+	* - `(request: Request) => Promise<Response>` — custom SSR callback
+	* - `undefined` — non-API requests return 404
+	*/
+	ssr?: SSRModuleConfig | ((request: Request) => Promise<Response>);
+	/** When true, adds standard security headers to all responses. */
+	securityHeaders?: boolean;
+}
+/**
+* Create a Cloudflare Worker handler from a Vertz app.
+*
+* Simple form — wraps an AppBuilder directly:
+* ```ts
+* createHandler(app, { basePath: '/api' });
+* ```
+*
+* Config form — full-stack with lazy init, SSR, and security headers:
+* ```ts
+* createHandler({
+*   app: (env) => createServer({ entities, db: createDb({ d1: env.DB }) }),
+*   basePath: '/api',
+*   ssr: (req) => renderToString(new URL(req.url).pathname),
+*   securityHeaders: true,
+* });
+* ```
+*/
+/** Worker module shape returned by createHandler. */
+interface CloudflareWorkerModule {
+	fetch(request: Request, env: unknown, ctx: ExecutionContext): Promise<Response>;
+}
+declare function createHandler(appOrConfig: AppBuilder | CloudflareHandlerConfig, options?: CloudflareHandlerOptions): CloudflareWorkerModule;
+declare function generateHTMLTemplate(clientScript: string, title: string): string;
+export { generateHTMLTemplate, createHandler, SSRModuleConfig, CloudflareWorkerModule, CloudflareHandlerOptions, CloudflareHandlerConfig };

package/dist/index.js

@@ -1,14 +1,43 @@
+
 // src/handler.ts
-function createHandler(app, options) {
+var SECURITY_HEADERS = {
+  "X-Content-Type-Options": "nosniff",
+  "X-Frame-Options": "DENY",
+  "X-XSS-Protection": "1; mode=block",
+  "Referrer-Policy": "strict-origin-when-cross-origin",
+  "Content-Security-Policy": "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data:;"
+};
+function withSecurityHeaders(response) {
+  const headers = new Headers(response.headers);
+  for (const [key, value] of Object.entries(SECURITY_HEADERS)) {
+    headers.set(key, value);
+  }
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers
+  });
+}
+function stripBasePath(request, basePath) {
+  const url = new URL(request.url);
+  if (url.pathname.startsWith(basePath)) {
+    url.pathname = url.pathname.slice(basePath.length) || "/";
+    return new Request(url.toString(), request);
+  }
+  return request;
+}
+function createHandler(appOrConfig, options) {
+  if ("app" in appOrConfig && typeof appOrConfig.app === "function") {
+    return createFullStackHandler(appOrConfig);
+  }
+  return createSimpleHandler(appOrConfig, options);
+}
+function createSimpleHandler(app, options) {
   const handler = app.handler;
   return {
     async fetch(request, _env, _ctx) {
       if (options?.basePath) {
-        const url = new URL(request.url);
-        if (url.pathname.startsWith(options.basePath)) {
-          url.pathname = url.pathname.slice(options.basePath.length) || "/";
-          request = new Request(url.toString(), request);
-        }
+        request = stripBasePath(request, options.basePath);
       }
       try {
         return await handler(request);
@@ -19,6 +48,105 @@ function createHandler(app, options) {
     }
   };
 }
+function generateHTMLTemplate(clientScript, title) {
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>${title}</title>
+</head>
+<body>
+<div id="app"><!--ssr-outlet--></div>
+<script type="module" src="${clientScript}"></script>
+</body>
+</html>`;
+}
+function isSSRModuleConfig(ssr) {
+  return typeof ssr === "object" && "module" in ssr;
+}
+function createFullStackHandler(config) {
+  const { basePath, ssr, securityHeaders } = config;
+  let cachedApp = null;
+  let ssrHandler = null;
+  let ssrResolved = false;
+  function getApp(env) {
+    if (!cachedApp) {
+      cachedApp = config.app(env);
+    }
+    return cachedApp;
+  }
+  async function resolveSSR() {
+    if (ssrResolved)
+      return;
+    ssrResolved = true;
+    if (!ssr)
+      return;
+    if (isSSRModuleConfig(ssr)) {
+      const { createSSRHandler } = await import("@vertz/ui-server/ssr");
+      const {
+        module,
+        clientScript = "/assets/entry-client.js",
+        title = "Vertz App",
+        ssrTimeout = 5000
+      } = ssr;
+      ssrHandler = createSSRHandler({
+        module,
+        template: generateHTMLTemplate(clientScript, title),
+        ssrTimeout
+      });
+    } else {
+      ssrHandler = ssr;
+    }
+  }
+  function applyHeaders(response) {
+    return securityHeaders ? withSecurityHeaders(response) : response;
+  }
+  return {
+    async fetch(request, env, _ctx) {
+      await resolveSSR();
+      const url = new URL(request.url);
+      if (url.pathname.startsWith(basePath)) {
+        try {
+          const app = getApp(env);
+          const response = await app.handler(request);
+          return applyHeaders(response);
+        } catch (error) {
+          console.error("Unhandled error in worker:", error);
+          return applyHeaders(new Response("Internal Server Error", { status: 500 }));
+        }
+      }
+      if (ssrHandler) {
+        const app = getApp(env);
+        const origin = url.origin;
+        const originalFetch = globalThis.fetch;
+        globalThis.fetch = (input, init) => {
+          const rawUrl = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+          const isRelative = rawUrl.startsWith("/");
+          const pathname = isRelative ? rawUrl.split("?")[0] : new URL(rawUrl).pathname;
+          const isLocal = isRelative || new URL(rawUrl).origin === origin;
+          if (isLocal && pathname.startsWith(basePath)) {
+            const absoluteUrl = isRelative ? `${origin}${rawUrl}` : rawUrl;
+            const req = new Request(absoluteUrl, init);
+            return app.handler(req);
+          }
+          return originalFetch(input, init);
+        };
+        try {
+          const response = await ssrHandler(request);
+          return applyHeaders(response);
+        } catch (error) {
+          console.error("Unhandled error in worker:", error);
+          return applyHeaders(new Response("Internal Server Error", { status: 500 }));
+        } finally {
+          globalThis.fetch = originalFetch;
+        }
+      }
+      return applyHeaders(new Response("Not Found", { status: 404 }));
+    }
+  };
+}
 export {
+  generateHTMLTemplate,
   createHandler
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertz/cloudflare",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Cloudflare Workers adapter for vertz",
   "type": "module",
   "main": "dist/index.js",
@@ -22,15 +22,17 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@vertz/core": "workspace:*"
+    "@vertz/core": "0.2.1"
   },
   "devDependencies": {
-    "@cloudflare/workers-types": "^4.20250214.0",
+    "@cloudflare/workers-types": "^4.20260305.0",
+    "@vertz/ui-server": "0.2.1",
+    "@vitest/coverage-v8": "^4.0.18",
     "bunup": "latest",
     "typescript": "^5.7.3"
   },
   "peerDependencies": {
-    "@vertz/ui-server": "workspace:*"
+    "@vertz/ui-server": "0.2.1"
   },
   "peerDependenciesMeta": {
     "@vertz/ui-server": {

package/src/handler.ts

@@ -1,21 +1,152 @@
 import type { AppBuilder } from '@vertz/core';
+import type { SSRModule } from '@vertz/ui-server/ssr';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
 
 export interface CloudflareHandlerOptions {
   basePath?: string;
 }
 
-export function createHandler(app: AppBuilder, options?: CloudflareHandlerOptions) {
+/**
+ * SSR module configuration for zero-boilerplate server-side rendering.
+ *
+ * Pass the app module directly and the handler generates the HTML template,
+ * wires up createSSRHandler, and handles the full SSR pipeline.
+ */
+export interface SSRModuleConfig {
+  /** App module exporting App, theme?, styles?, getInjectedCSS? */
+  module: SSRModule;
+  /** Client-side entry script path. Default: '/assets/entry-client.js' */
+  clientScript?: string;
+  /** HTML document title. Default: 'Vertz App' */
+  title?: string;
+  /** SSR query timeout in ms. Default: 5000 (generous for D1 cold starts). */
+  ssrTimeout?: number;
+}
+
+/**
+ * Full-stack configuration for createHandler.
+ *
+ * Supports lazy app initialization (for D1 bindings), SSR fallback,
+ * and automatic security headers.
+ */
+export interface CloudflareHandlerConfig {
+  /**
+   * Factory that creates the AppBuilder. Receives the Worker env bindings.
+   * Called once on first request, then cached.
+   */
+  app: (env: unknown) => AppBuilder;
+
+  /** API path prefix. Requests matching this prefix go to the app handler. */
+  basePath: string;
+
+  /**
+   * SSR configuration for non-API routes.
+   *
+   * - `SSRModuleConfig` — zero-boilerplate: pass the app module directly
+   * - `(request: Request) => Promise<Response>` — custom SSR callback
+   * - `undefined` — non-API requests return 404
+   */
+  ssr?: SSRModuleConfig | ((request: Request) => Promise<Response>);
+
+  /** When true, adds standard security headers to all responses. */
+  securityHeaders?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Security headers
+// ---------------------------------------------------------------------------
+
+const SECURITY_HEADERS: Record<string, string> = {
+  'X-Content-Type-Options': 'nosniff',
+  'X-Frame-Options': 'DENY',
+  'X-XSS-Protection': '1; mode=block',
+  'Referrer-Policy': 'strict-origin-when-cross-origin',
+  'Content-Security-Policy':
+    "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data:;",
+};
+
+function withSecurityHeaders(response: Response): Response {
+  const headers = new Headers(response.headers);
+  for (const [key, value] of Object.entries(SECURITY_HEADERS)) {
+    headers.set(key, value);
+  }
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function stripBasePath(request: Request, basePath: string): Request {
+  const url = new URL(request.url);
+  if (url.pathname.startsWith(basePath)) {
+    url.pathname = url.pathname.slice(basePath.length) || '/';
+    return new Request(url.toString(), request);
+  }
+  return request;
+}
+
+// ---------------------------------------------------------------------------
+// createHandler overloads
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a Cloudflare Worker handler from a Vertz app.
+ *
+ * Simple form — wraps an AppBuilder directly:
+ * ```ts
+ * export default createHandler(app, { basePath: '/api' });
+ * ```
+ *
+ * Config form — full-stack with lazy init, SSR, and security headers:
+ * ```ts
+ * export default createHandler({
+ *   app: (env) => createServer({ entities, db: createDb({ d1: env.DB }) }),
+ *   basePath: '/api',
+ *   ssr: (req) => renderToString(new URL(req.url).pathname),
+ *   securityHeaders: true,
+ * });
+ * ```
+ */
+/** Worker module shape returned by createHandler. */
+export interface CloudflareWorkerModule {
+  fetch(request: Request, env: unknown, ctx: ExecutionContext): Promise<Response>;
+}
+
+export function createHandler(
+  appOrConfig: AppBuilder | CloudflareHandlerConfig,
+  options?: CloudflareHandlerOptions,
+): CloudflareWorkerModule {
+  // Config object form
+  if ('app' in appOrConfig && typeof appOrConfig.app === 'function') {
+    return createFullStackHandler(appOrConfig);
+  }
+
+  // Simple AppBuilder form (backward compat)
+  return createSimpleHandler(appOrConfig as AppBuilder, options);
+}
+
+// ---------------------------------------------------------------------------
+// Simple handler (backward compat)
+// ---------------------------------------------------------------------------
+
+function createSimpleHandler(
+  app: AppBuilder,
+  options?: CloudflareHandlerOptions,
+): CloudflareWorkerModule {
   const handler = app.handler;
 
   return {
     async fetch(request: Request, _env: unknown, _ctx: ExecutionContext): Promise<Response> {
-      // If basePath, strip it from the URL before routing
       if (options?.basePath) {
-        const url = new URL(request.url);
-        if (url.pathname.startsWith(options.basePath)) {
-          url.pathname = url.pathname.slice(options.basePath.length) || '/';
-          request = new Request(url.toString(), request);
-        }
+        request = stripBasePath(request, options.basePath);
       }
       try {
         return await handler(request);
@@ -26,3 +157,137 @@ export function createHandler(app: AppBuilder, options?: CloudflareHandlerOption
     },
   };
 }
+
+// ---------------------------------------------------------------------------
+// HTML template generation
+// ---------------------------------------------------------------------------
+
+export function generateHTMLTemplate(clientScript: string, title: string): string {
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>${title}</title>
+</head>
+<body>
+<div id="app"><!--ssr-outlet--></div>
+<script type="module" src="${clientScript}"></script>
+</body>
+</html>`;
+}
+
+// ---------------------------------------------------------------------------
+// Full-stack handler
+// ---------------------------------------------------------------------------
+
+function isSSRModuleConfig(
+  ssr: SSRModuleConfig | ((request: Request) => Promise<Response>),
+): ssr is SSRModuleConfig {
+  return typeof ssr === 'object' && 'module' in ssr;
+}
+
+function createFullStackHandler(config: CloudflareHandlerConfig): CloudflareWorkerModule {
+  const { basePath, ssr, securityHeaders } = config;
+  let cachedApp: AppBuilder | null = null;
+  let ssrHandler: ((request: Request) => Promise<Response>) | null = null;
+  let ssrResolved = false;
+
+  function getApp(env: unknown): AppBuilder {
+    if (!cachedApp) {
+      cachedApp = config.app(env);
+    }
+    return cachedApp;
+  }
+
+  async function resolveSSR(): Promise<void> {
+    if (ssrResolved) return;
+    ssrResolved = true;
+
+    if (!ssr) return;
+
+    if (isSSRModuleConfig(ssr)) {
+      const { createSSRHandler } = await import('@vertz/ui-server/ssr');
+      const {
+        module,
+        clientScript = '/assets/entry-client.js',
+        title = 'Vertz App',
+        ssrTimeout = 5000,
+      } = ssr;
+      ssrHandler = createSSRHandler({
+        module,
+        template: generateHTMLTemplate(clientScript, title),
+        ssrTimeout,
+      });
+    } else {
+      ssrHandler = ssr;
+    }
+  }
+
+  function applyHeaders(response: Response): Response {
+    return securityHeaders ? withSecurityHeaders(response) : response;
+  }
+
+  return {
+    async fetch(request: Request, env: unknown, _ctx: ExecutionContext): Promise<Response> {
+      await resolveSSR();
+      const url = new URL(request.url);
+
+      // Route splitting: basePath/* → API handler (no URL rewriting — the
+      // app's own basePath/apiPrefix handles prefix matching internally)
+      if (url.pathname.startsWith(basePath)) {
+        try {
+          const app = getApp(env);
+          const response = await app.handler(request);
+          return applyHeaders(response);
+        } catch (error) {
+          console.error('Unhandled error in worker:', error);
+          return applyHeaders(new Response('Internal Server Error', { status: 500 }));
+        }
+      }
+
+      // Non-API routes → SSR or 404
+      if (ssrHandler) {
+        const app = getApp(env);
+        const origin = url.origin;
+        // Patch fetch during SSR so API requests (e.g. query() calling
+        // fetch('/api/todos')) are routed through the in-memory app handler
+        // instead of attempting a network self-fetch (which fails on Workers).
+        const originalFetch = globalThis.fetch;
+        globalThis.fetch = (input, init) => {
+          // Determine the pathname from the input (string, URL, or Request)
+          const rawUrl =
+            typeof input === 'string'
+              ? input
+              : input instanceof URL
+                ? input.href
+                : input.url;
+          const isRelative = rawUrl.startsWith('/');
+          const pathname = isRelative
+            ? rawUrl.split('?')[0]
+            : new URL(rawUrl).pathname;
+          const isLocal = isRelative || new URL(rawUrl).origin === origin;
+
+          if (isLocal && pathname.startsWith(basePath)) {
+            // Build an absolute URL so Request() doesn't reject relative URLs
+            const absoluteUrl = isRelative ? `${origin}${rawUrl}` : rawUrl;
+            const req = new Request(absoluteUrl, init);
+            return app.handler(req);
+          }
+          return originalFetch(input, init);
+        };
+        try {
+          const response = await ssrHandler(request);
+          return applyHeaders(response);
+        } catch (error) {
+          console.error('Unhandled error in worker:', error);
+          return applyHeaders(new Response('Internal Server Error', { status: 500 }));
+        } finally {
+          globalThis.fetch = originalFetch;
+        }
+      }
+
+      return applyHeaders(new Response('Not Found', { status: 404 }));
+    },
+  };
+}

package/src/index.ts

@@ -1,2 +1,7 @@
-export type { CloudflareHandlerOptions } from './handler.js';
-export { createHandler } from './handler.js';
+export type {
+  CloudflareHandlerConfig,
+  CloudflareHandlerOptions,
+  CloudflareWorkerModule,
+  SSRModuleConfig,
+} from './handler.js';
+export { createHandler, generateHTMLTemplate } from './handler.js';

package/tests/handler.test.ts

@@ -1,6 +1,12 @@
 import type { AppBuilder } from '@vertz/core';
-import { describe, expect, it, vi } from 'vitest';
-import { createHandler } from '../src/handler.js';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { createHandler, generateHTMLTemplate } from '../src/handler.js';
+
+function mockApp(handler?: (...args: unknown[]) => Promise<Response>): AppBuilder {
+  return {
+    handler: handler ?? vi.fn().mockResolvedValue(new Response('OK')),
+  } as unknown as AppBuilder;
+}
 
 describe('createHandler', () => {
   it('returns proper Worker export with fetch method', () => {
@@ -176,3 +182,330 @@ describe('createHandler', () => {
     consoleErrorSpy.mockRestore();
   });
 });
+
+// ---------------------------------------------------------------------------
+// Full-stack config-based createHandler
+// ---------------------------------------------------------------------------
+
+describe('createHandler (config object)', () => {
+  const mockEnv = { DB: {} };
+  const mockCtx = {} as ExecutionContext;
+
+  it('routes API requests to app handler and SSR to ssr handler', async () => {
+    const apiHandler = vi.fn().mockResolvedValue(
+      new Response('{"items":[]}', {
+        headers: { 'Content-Type': 'application/json' },
+      }),
+    );
+    const ssrHandler = vi.fn().mockResolvedValue(
+      new Response('<html>SSR</html>', {
+        headers: { 'Content-Type': 'text/html' },
+      }),
+    );
+
+    const worker = createHandler({
+      app: () => mockApp(apiHandler),
+      basePath: '/api',
+      ssr: ssrHandler,
+    });
+
+    // API request → app handler
+    const apiResponse = await worker.fetch(
+      new Request('https://example.com/api/todos'),
+      mockEnv,
+      mockCtx,
+    );
+    expect(apiHandler).toHaveBeenCalled();
+    expect(await apiResponse.text()).toBe('{"items":[]}');
+
+    // SSR request → ssr handler
+    const ssrResponse = await worker.fetch(new Request('https://example.com/'), mockEnv, mockCtx);
+    expect(ssrHandler).toHaveBeenCalled();
+    expect(await ssrResponse.text()).toBe('<html>SSR</html>');
+  });
+
+  it('passes env to the app factory and caches the result', async () => {
+    const apiHandler = vi.fn().mockResolvedValue(new Response('OK'));
+    const appFactory = vi.fn().mockReturnValue(mockApp(apiHandler));
+
+    const worker = createHandler({
+      app: appFactory,
+      basePath: '/api',
+    });
+
+    // First request — factory called
+    await worker.fetch(new Request('https://example.com/api/x'), mockEnv, mockCtx);
+    expect(appFactory).toHaveBeenCalledTimes(1);
+    expect(appFactory).toHaveBeenCalledWith(mockEnv);
+
+    // Second request — factory NOT called again (cached)
+    await worker.fetch(new Request('https://example.com/api/y'), mockEnv, mockCtx);
+    expect(appFactory).toHaveBeenCalledTimes(1);
+  });
+
+  it('adds security headers when securityHeaders is true', async () => {
+    const worker = createHandler({
+      app: () => mockApp(vi.fn().mockResolvedValue(new Response('OK'))),
+      basePath: '/api',
+      securityHeaders: true,
+    });
+
+    const response = await worker.fetch(
+      new Request('https://example.com/api/test'),
+      mockEnv,
+      mockCtx,
+    );
+
+    expect(response.headers.get('X-Content-Type-Options')).toBe('nosniff');
+    expect(response.headers.get('X-Frame-Options')).toBe('DENY');
+    expect(response.headers.get('Referrer-Policy')).toBe('strict-origin-when-cross-origin');
+  });
+
+  it('adds security headers to SSR responses too', async () => {
+    const worker = createHandler({
+      app: () => mockApp(),
+      basePath: '/api',
+      ssr: () => Promise.resolve(new Response('<html></html>')),
+      securityHeaders: true,
+    });
+
+    const response = await worker.fetch(new Request('https://example.com/'), mockEnv, mockCtx);
+
+    expect(response.headers.get('X-Content-Type-Options')).toBe('nosniff');
+    expect(response.headers.get('X-Frame-Options')).toBe('DENY');
+  });
+
+  it('passes full URL to app handler (no basePath stripping)', async () => {
+    const apiHandler = vi.fn().mockResolvedValue(new Response('OK'));
+
+    const worker = createHandler({
+      app: () => mockApp(apiHandler),
+      basePath: '/api',
+    });
+
+    await worker.fetch(new Request('https://example.com/api/todos/123'), mockEnv, mockCtx);
+
+    const calledRequest = apiHandler.mock.calls[0][0] as Request;
+    const url = new URL(calledRequest.url);
+    expect(url.pathname).toBe('/api/todos/123');
+  });
+
+  it('returns 500 with error message when app handler throws', async () => {
+    const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    const worker = createHandler({
+      app: () => mockApp(vi.fn().mockRejectedValue(new Error('DB connection failed'))),
+      basePath: '/api',
+    });
+
+    const response = await worker.fetch(
+      new Request('https://example.com/api/test'),
+      mockEnv,
+      mockCtx,
+    );
+
+    expect(response.status).toBe(500);
+    expect(await response.text()).toBe('Internal Server Error');
+    consoleErrorSpy.mockRestore();
+  });
+
+  it('returns 500 with error message when SSR handler throws', async () => {
+    const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    const worker = createHandler({
+      app: () => mockApp(),
+      basePath: '/api',
+      ssr: () => Promise.reject(new Error('SSR render failed')),
+    });
+
+    const response = await worker.fetch(new Request('https://example.com/'), mockEnv, mockCtx);
+
+    expect(response.status).toBe(500);
+    expect(await response.text()).toBe('Internal Server Error');
+    consoleErrorSpy.mockRestore();
+  });
+
+  it('returns 404 for non-API routes when no SSR handler is provided', async () => {
+    const worker = createHandler({
+      app: () => mockApp(),
+      basePath: '/api',
+    });
+
+    const response = await worker.fetch(
+      new Request('https://example.com/some-page'),
+      mockEnv,
+      mockCtx,
+    );
+
+    expect(response.status).toBe(404);
+    expect(await response.text()).toBe('Not Found');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// generateHTMLTemplate
+// ---------------------------------------------------------------------------
+
+describe('generateHTMLTemplate', () => {
+  it('generates HTML with ssr-outlet, client script, and title', () => {
+    const html = generateHTMLTemplate('/assets/client.js', 'My App');
+
+    expect(html).toContain('<!--ssr-outlet-->');
+    expect(html).toContain('<script type="module" src="/assets/client.js"></script>');
+    expect(html).toContain('<title>My App</title>');
+    expect(html).toContain('<!doctype html>');
+    expect(html).toContain('<div id="app">');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// SSR module config
+// ---------------------------------------------------------------------------
+
+describe('createHandler (SSR module config)', () => {
+  const mockEnv = { DB: {} };
+  const mockCtx = {} as ExecutionContext;
+
+  // We mock @vertz/ui-server's createSSRHandler to isolate wiring logic.
+  // The mock returns a handler that echoes 'SSR Module' so we can verify routing.
+  const mockSSRRequestHandler = vi.fn().mockResolvedValue(
+    new Response('<html>SSR Module</html>', {
+      headers: { 'Content-Type': 'text/html' },
+    }),
+  );
+  const mockCreateSSRHandler = vi.fn().mockReturnValue(mockSSRRequestHandler);
+
+  beforeEach(() => {
+    vi.doMock('@vertz/ui-server/ssr', () => ({
+      createSSRHandler: mockCreateSSRHandler,
+    }));
+    mockSSRRequestHandler.mockClear();
+    mockCreateSSRHandler.mockClear();
+  });
+
+  afterEach(() => {
+    vi.doUnmock('@vertz/ui-server/ssr');
+  });
+
+  it('routes non-API requests through the SSR handler created from module config', async () => {
+    const { createHandler: freshCreateHandler } = await import('../src/handler.js');
+
+    const ssrModule = { App: () => ({}) };
+    const worker = freshCreateHandler({
+      app: () => mockApp(),
+      basePath: '/api',
+      ssr: { module: ssrModule },
+    });
+
+    const response = await worker.fetch(new Request('https://example.com/'), mockEnv, mockCtx);
+
+    expect(mockCreateSSRHandler).toHaveBeenCalledOnce();
+    expect(mockSSRRequestHandler).toHaveBeenCalled();
+    expect(await response.text()).toBe('<html>SSR Module</html>');
+  });
+
+  it('passes default clientScript and title to createSSRHandler', async () => {
+    const { createHandler: freshCreateHandler } = await import('../src/handler.js');
+
+    const ssrModule = { App: () => ({}) };
+    const worker = freshCreateHandler({
+      app: () => mockApp(),
+      basePath: '/api',
+      ssr: { module: ssrModule },
+    });
+
+    await worker.fetch(new Request('https://example.com/'), mockEnv, mockCtx);
+
+    expect(mockCreateSSRHandler).toHaveBeenCalledWith(
+      expect.objectContaining({
+        module: ssrModule,
+        template: expect.stringContaining('/assets/entry-client.js'),
+      }),
+    );
+    expect(mockCreateSSRHandler).toHaveBeenCalledWith(
+      expect.objectContaining({
+        module: ssrModule,
+        template: expect.stringContaining('<title>Vertz App</title>'),
+      }),
+    );
+  });
+
+  it('passes custom clientScript and title to createSSRHandler', async () => {
+    const { createHandler: freshCreateHandler } = await import('../src/handler.js');
+
+    const ssrModule = { App: () => ({}) };
+    const worker = freshCreateHandler({
+      app: () => mockApp(),
+      basePath: '/api',
+      ssr: {
+        module: ssrModule,
+        clientScript: '/custom/client.js',
+        title: 'My Custom App',
+      },
+    });
+
+    await worker.fetch(new Request('https://example.com/'), mockEnv, mockCtx);
+
+    expect(mockCreateSSRHandler).toHaveBeenCalledWith(
+      expect.objectContaining({
+        module: ssrModule,
+        template: expect.stringContaining('/custom/client.js'),
+      }),
+    );
+    expect(mockCreateSSRHandler).toHaveBeenCalledWith(
+      expect.objectContaining({
+        module: ssrModule,
+        template: expect.stringContaining('<title>My Custom App</title>'),
+      }),
+    );
+  });
+
+  it('still works with ssr callback (backward compat)', async () => {
+    const { createHandler: freshCreateHandler } = await import('../src/handler.js');
+
+    const ssrCallback = vi.fn().mockResolvedValue(
+      new Response('<html>Callback SSR</html>', {
+        headers: { 'Content-Type': 'text/html' },
+      }),
+    );
+
+    const worker = freshCreateHandler({
+      app: () => mockApp(),
+      basePath: '/api',
+      ssr: ssrCallback,
+    });
+
+    const response = await worker.fetch(new Request('https://example.com/'), mockEnv, mockCtx);
+
+    // createSSRHandler should NOT be called — callback is used directly
+    expect(mockCreateSSRHandler).not.toHaveBeenCalled();
+    expect(ssrCallback).toHaveBeenCalled();
+    expect(await response.text()).toBe('<html>Callback SSR</html>');
+  });
+
+  it('routes API requests to app handler even with SSR module config', async () => {
+    const { createHandler: freshCreateHandler } = await import('../src/handler.js');
+
+    const apiHandler = vi.fn().mockResolvedValue(
+      new Response('{"items":[]}', {
+        headers: { 'Content-Type': 'application/json' },
+      }),
+    );
+
+    const worker = freshCreateHandler({
+      app: () => mockApp(apiHandler),
+      basePath: '/api',
+      ssr: { module: { App: () => ({}) } },
+    });
+
+    const response = await worker.fetch(
+      new Request('https://example.com/api/todos'),
+      mockEnv,
+      mockCtx,
+    );
+
+    expect(apiHandler).toHaveBeenCalled();
+    expect(mockSSRRequestHandler).not.toHaveBeenCalled();
+    expect(await response.text()).toBe('{"items":[]}');
+  });
+});

package/vitest.config.ts

@@ -15,7 +15,7 @@ export default defineConfig({
       reporter: ['text', 'json-summary', 'json'],
       provider: 'v8',
       include: ['src/**/*.ts'],
-      exclude: ['src/**/*.test.ts', 'src/index.ts'],
+      exclude: ['src/**/*.test.ts', 'src/**/*.test-d.ts', 'src/index.ts'],
     },
   },
 });