@vertz/ui-server 0.2.23 → 0.2.25

package/dist/bun-dev-server.js

@@ -395,6 +395,58 @@ async function extractFontMetrics(fonts, rootDir) {
   return result;
 }
 
+// src/ready-gate.ts
+function createReadyGate(options) {
+  let ready = false;
+  const pendingClients = new Set;
+  let timeoutHandle = null;
+  function doOpen(currentError) {
+    if (ready)
+      return;
+    ready = true;
+    if (timeoutHandle) {
+      clearTimeout(timeoutHandle);
+      timeoutHandle = null;
+    }
+    for (const ws of pendingClients) {
+      try {
+        ws.sendText(JSON.stringify({ type: "connected" }));
+        if (currentError) {
+          ws.sendText(JSON.stringify({
+            type: "error",
+            category: currentError.category,
+            errors: currentError.errors
+          }));
+        }
+      } catch {}
+    }
+    pendingClients.clear();
+  }
+  if (options?.timeoutMs) {
+    timeoutHandle = setTimeout(() => {
+      if (!ready) {
+        options.onTimeoutWarning?.();
+        doOpen();
+      }
+    }, options.timeoutMs);
+  }
+  return {
+    get isReady() {
+      return ready;
+    },
+    onOpen(ws) {
+      if (ready)
+        return false;
+      pendingClients.add(ws);
+      return true;
+    },
+    onClose(ws) {
+      pendingClients.delete(ws);
+    },
+    open: doOpen
+  };
+}
+
 // src/source-map-resolver.ts
 import { readFileSync } from "fs";
 import { resolve as resolvePath } from "path";
@@ -540,6 +592,47 @@ function createSourceMapResolver(projectRoot) {
   };
 }
 
+// src/ssr-access-evaluator.ts
+function toPrefetchSession(ssrAuth) {
+  if (!ssrAuth || ssrAuth.status !== "authenticated" || !ssrAuth.user) {
+    return { status: "unauthenticated" };
+  }
+  const roles = ssrAuth.user.role ? [ssrAuth.user.role] : undefined;
+  return {
+    status: "authenticated",
+    roles,
+    tenantId: ssrAuth.user.tenantId
+  };
+}
+function evaluateAccessRule(rule, session) {
+  switch (rule.type) {
+    case "public":
+      return true;
+    case "authenticated":
+      return session.status === "authenticated";
+    case "role":
+      if (session.status !== "authenticated")
+        return false;
+      return session.roles?.some((r) => rule.roles.includes(r)) === true;
+    case "entitlement":
+      if (session.status !== "authenticated")
+        return false;
+      return session.entitlements?.[rule.value] === true;
+    case "where":
+      return true;
+    case "fva":
+      return session.status === "authenticated";
+    case "deny":
+      return false;
+    case "all":
+      return rule.rules.every((r) => evaluateAccessRule(r, session));
+    case "any":
+      return rule.rules.some((r) => evaluateAccessRule(r, session));
+    default:
+      return false;
+  }
+}
+
 // src/ssr-access-set.ts
 function createAccessSetScript(accessSet, nonce) {
   const json = JSON.stringify(accessSet);
@@ -551,6 +644,124 @@ function escapeAttr(s) {
   return s.replace(/[&"'<>]/g, (c) => `&#${c.charCodeAt(0)};`);
 }
 
+// src/ssr-prefetch-dev.ts
+import {
+  analyzeComponentQueries,
+  generatePrefetchManifest
+} from "@vertz/ui-compiler";
+function createPrefetchManifestManager(options) {
+  const { routerPath, readFile: readFile2, resolveImport } = options;
+  let currentManifest = null;
+  let currentSSRManifest;
+  let rebuildCount = 0;
+  let lastRebuildMs = null;
+  let lastRebuildAt = null;
+  let fileToRouteIndices = new Map;
+  function buildFileIndex(routes) {
+    const index = new Map;
+    for (let i = 0;i < routes.length; i++) {
+      const file = routes[i]?.file;
+      if (file) {
+        const existing = index.get(file) ?? [];
+        existing.push(i);
+        index.set(file, existing);
+      }
+    }
+    return index;
+  }
+  function toSSRManifest(manifest) {
+    const routeEntries = {};
+    for (const route of manifest.routes) {
+      const existing = routeEntries[route.pattern];
+      if (existing) {
+        existing.queries.push(...route.queries);
+      } else {
+        routeEntries[route.pattern] = { queries: [...route.queries] };
+      }
+    }
+    return {
+      routePatterns: [...new Set(manifest.routes.map((r) => r.pattern))],
+      routeEntries
+    };
+  }
+  function fullBuild(routerSourceOverride) {
+    const start = performance.now();
+    const routerSource = routerSourceOverride ?? readFile2(routerPath);
+    if (!routerSource) {
+      return;
+    }
+    try {
+      const manifest = generatePrefetchManifest({
+        routerSource,
+        routerPath,
+        readFile: readFile2,
+        resolveImport
+      });
+      currentManifest = manifest;
+      currentSSRManifest = toSSRManifest(manifest);
+      fileToRouteIndices = buildFileIndex(manifest.routes);
+      rebuildCount++;
+      lastRebuildMs = Math.round(performance.now() - start);
+      lastRebuildAt = new Date().toISOString();
+    } catch {}
+  }
+  function incrementalUpdate(filePath, sourceText) {
+    if (!currentManifest)
+      return;
+    const indices = fileToRouteIndices.get(filePath);
+    if (!indices || indices.length === 0)
+      return;
+    const start = performance.now();
+    try {
+      const analysis = analyzeComponentQueries(sourceText, filePath);
+      const newRoutes = [...currentManifest.routes];
+      for (const idx of indices) {
+        const existing = newRoutes[idx];
+        if (existing) {
+          newRoutes[idx] = {
+            ...existing,
+            queries: analysis.queries,
+            params: analysis.params
+          };
+        }
+      }
+      const newManifest = {
+        ...currentManifest,
+        routes: newRoutes,
+        generatedAt: new Date().toISOString()
+      };
+      currentManifest = newManifest;
+      currentSSRManifest = toSSRManifest(newManifest);
+      rebuildCount++;
+      lastRebuildMs = Math.round(performance.now() - start);
+      lastRebuildAt = new Date().toISOString();
+    } catch {}
+  }
+  return {
+    build() {
+      fullBuild();
+    },
+    onFileChange(filePath, sourceText) {
+      if (filePath === routerPath) {
+        fullBuild(sourceText);
+      } else {
+        incrementalUpdate(filePath, sourceText);
+      }
+    },
+    getSSRManifest() {
+      return currentSSRManifest;
+    },
+    getSnapshot() {
+      return {
+        manifest: currentManifest,
+        rebuildCount,
+        lastRebuildMs,
+        lastRebuildAt
+      };
+    }
+  };
+}
+
 // src/ssr-render.ts
 import { compileTheme } from "@vertz/ui";
 import { EntityStore, MemoryCache, QueryEnvelopeStore } from "@vertz/ui/internals";
@@ -560,6 +771,7 @@ import { setAdapter } from "@vertz/ui/internals";
 
 // src/dom-shim/ssr-node.ts
 class SSRNode {
+  nodeType = 1;
   childNodes = [];
   parentNode = null;
   get firstChild() {
@@ -605,6 +817,7 @@ class SSRNode {
 
 // src/dom-shim/ssr-comment.ts
 class SSRComment extends SSRNode {
+  nodeType = 8;
   text;
   constructor(text) {
     super();
@@ -628,6 +841,7 @@ function rawHtml(html) {
 
 // src/dom-shim/ssr-text-node.ts
 class SSRTextNode extends SSRNode {
+  nodeType = 3;
   text;
   constructor(text) {
     super();
@@ -643,6 +857,7 @@ class SSRTextNode extends SSRNode {
 
 // src/dom-shim/ssr-fragment.ts
 class SSRDocumentFragment extends SSRNode {
+  nodeType = 11;
   children = [];
   appendChild(child) {
     if (child instanceof SSRTextNode) {
@@ -1113,19 +1328,35 @@ function installDomShim() {
     cookie: ""
   };
   globalThis.document = fakeDocument;
+  const windowStubs = {
+    scrollTo: () => {},
+    scroll: () => {},
+    addEventListener: () => {},
+    removeEventListener: () => {},
+    dispatchEvent: () => true,
+    getComputedStyle: () => ({}),
+    matchMedia: () => ({ matches: false, addListener: () => {}, removeListener: () => {} })
+  };
   if (typeof window === "undefined") {
     globalThis.window = {
       location: { pathname: ssrStorage.getStore()?.url || "/", search: "", hash: "" },
       history: {
         pushState: () => {},
         replaceState: () => {}
-      }
+      },
+      ...windowStubs
     };
   } else {
-    globalThis.window.location = {
-      ...globalThis.window.location || {},
+    const win = globalThis.window;
+    win.location = {
+      ...win.location || {},
       pathname: ssrStorage.getStore()?.url || "/"
     };
+    for (const [key, val] of Object.entries(windowStubs)) {
+      if (typeof win[key] !== "function") {
+        win[key] = val;
+      }
+    }
   }
   globalThis.Node = SSRNode;
   globalThis.HTMLElement = SSRElement;
@@ -1250,6 +1481,9 @@ function serializeToHtml(node) {
     return node.html;
   }
   const { tag, attrs, children } = node;
+  if (tag === "fragment") {
+    return children.map((child) => serializeToHtml(child)).join("");
+  }
   const attrStr = serializeAttrs(attrs);
   if (VOID_ELEMENTS.has(tag)) {
     return `<${tag}${attrStr}>`;
@@ -1326,6 +1560,9 @@ function renderToStream(tree, options) {
       return serializeToHtml(placeholder);
     }
     const { tag, attrs, children } = node;
+    if (tag === "fragment") {
+      return children.map((child) => walkAndSerialize(child)).join("");
+    }
     const isRawText = RAW_TEXT_ELEMENTS.has(tag);
     const attrStr = Object.entries(attrs).map(([k, v]) => ` ${k}="${escapeAttr2(v)}"`).join("");
     if (VOID_ELEMENTS.has(tag)) {
@@ -1621,6 +1858,426 @@ function escapeAttr3(s) {
   return s.replace(/[&"'<>]/g, (c) => `&#${c.charCodeAt(0)};`);
 }
 
+// src/ssr-single-pass.ts
+import { compileTheme as compileTheme2 } from "@vertz/ui";
+
+// src/ssr-manifest-prefetch.ts
+function reconstructDescriptors(queries, routeParams, apiClient) {
+  if (!apiClient)
+    return [];
+  const result = [];
+  for (const query of queries) {
+    const descriptor = reconstructSingle(query, routeParams, apiClient);
+    if (descriptor) {
+      result.push(descriptor);
+    }
+  }
+  return result;
+}
+function reconstructSingle(query, routeParams, apiClient) {
+  const { entity, operation } = query;
+  if (!entity || !operation)
+    return;
+  const entitySdk = apiClient[entity];
+  if (!entitySdk)
+    return;
+  const method = entitySdk[operation];
+  if (typeof method !== "function")
+    return;
+  const args = buildFactoryArgs(query, routeParams);
+  if (args === undefined)
+    return;
+  try {
+    const descriptor = method(...args);
+    if (!descriptor || typeof descriptor._key !== "string" || typeof descriptor._fetch !== "function") {
+      return;
+    }
+    return { key: descriptor._key, fetch: descriptor._fetch };
+  } catch {
+    return;
+  }
+}
+function buildFactoryArgs(query, routeParams) {
+  const { operation, idParam, queryBindings } = query;
+  if (operation === "get") {
+    if (idParam) {
+      const id = routeParams[idParam];
+      if (!id)
+        return;
+      const options = resolveQueryBindings(queryBindings, routeParams);
+      if (options === undefined && queryBindings)
+        return;
+      return options ? [id, options] : [id];
+    }
+    return;
+  }
+  if (!queryBindings)
+    return [];
+  const resolved = resolveQueryBindings(queryBindings, routeParams);
+  if (resolved === undefined)
+    return;
+  return [resolved];
+}
+function resolveQueryBindings(bindings, routeParams) {
+  if (!bindings)
+    return;
+  const resolved = {};
+  if (bindings.where) {
+    const where = {};
+    for (const [key, value] of Object.entries(bindings.where)) {
+      if (value === null)
+        return;
+      if (typeof value === "string" && value.startsWith("$")) {
+        const paramName = value.slice(1);
+        const paramValue = routeParams[paramName];
+        if (!paramValue)
+          return;
+        where[key] = paramValue;
+      } else {
+        where[key] = value;
+      }
+    }
+    resolved.where = where;
+  }
+  if (bindings.select)
+    resolved.select = bindings.select;
+  if (bindings.include)
+    resolved.include = bindings.include;
+  if (bindings.orderBy)
+    resolved.orderBy = bindings.orderBy;
+  if (bindings.limit !== undefined)
+    resolved.limit = bindings.limit;
+  return resolved;
+}
+
+// src/ssr-route-matcher.ts
+function matchUrlToPatterns(url, patterns) {
+  const path = (url.split("?")[0] ?? "").split("#")[0] ?? "";
+  const matches = [];
+  for (const pattern of patterns) {
+    const result = matchPattern(path, pattern);
+    if (result) {
+      matches.push(result);
+    }
+  }
+  matches.sort((a, b) => {
+    const aSegments = a.pattern.split("/").length;
+    const bSegments = b.pattern.split("/").length;
+    return aSegments - bSegments;
+  });
+  return matches;
+}
+function matchPattern(path, pattern) {
+  const pathSegments = path.split("/").filter(Boolean);
+  const patternSegments = pattern.split("/").filter(Boolean);
+  if (patternSegments.length > pathSegments.length)
+    return;
+  const params = {};
+  for (let i = 0;i < patternSegments.length; i++) {
+    const seg = patternSegments[i];
+    const val = pathSegments[i];
+    if (seg.startsWith(":")) {
+      params[seg.slice(1)] = val;
+    } else if (seg !== val) {
+      return;
+    }
+  }
+  return { pattern, params };
+}
+
+// src/ssr-single-pass.ts
+async function ssrRenderSinglePass(module, url, options) {
+  if (options?.prefetch === false) {
+    return ssrRenderToString(module, url, options);
+  }
+  const normalizedUrl = url.endsWith("/index.html") ? url.slice(0, -"/index.html".length) || "/" : url;
+  const ssrTimeout = options?.ssrTimeout ?? 300;
+  ensureDomShim2();
+  const zeroDiscoveryData = attemptZeroDiscovery(normalizedUrl, module, options, ssrTimeout);
+  if (zeroDiscoveryData) {
+    return renderWithPrefetchedData(module, normalizedUrl, zeroDiscoveryData, options);
+  }
+  const discoveryCtx = createRequestContext(normalizedUrl);
+  if (options?.ssrAuth) {
+    discoveryCtx.ssrAuth = options.ssrAuth;
+  }
+  const discoveredData = await ssrStorage.run(discoveryCtx, async () => {
+    try {
+      setGlobalSSRTimeout(ssrTimeout);
+      const createApp = resolveAppFactory2(module);
+      createApp();
+      if (discoveryCtx.ssrRedirect) {
+        return { redirect: discoveryCtx.ssrRedirect };
+      }
+      if (discoveryCtx.pendingRouteComponents?.size) {
+        const entries = Array.from(discoveryCtx.pendingRouteComponents.entries());
+        const results = await Promise.allSettled(entries.map(([route, promise]) => Promise.race([
+          promise.then((mod) => ({ route, factory: mod.default })),
+          new Promise((_, reject) => setTimeout(() => reject(new Error("lazy route timeout")), ssrTimeout))
+        ])));
+        discoveryCtx.resolvedComponents = new Map;
+        for (const result of results) {
+          if (result.status === "fulfilled") {
+            const { route, factory } = result.value;
+            discoveryCtx.resolvedComponents.set(route, factory);
+          }
+        }
+        discoveryCtx.pendingRouteComponents = undefined;
+      }
+      const queries = getSSRQueries();
+      const eligibleQueries = filterByEntityAccess(queries, options?.manifest?.entityAccess, options?.prefetchSession);
+      const resolvedQueries = [];
+      if (eligibleQueries.length > 0) {
+        await Promise.allSettled(eligibleQueries.map(({ promise, timeout, resolve, key }) => Promise.race([
+          promise.then((data) => {
+            resolve(data);
+            resolvedQueries.push({ key, data });
+            return "resolved";
+          }),
+          new Promise((r) => setTimeout(r, timeout || ssrTimeout)).then(() => "timeout")
+        ])));
+      }
+      return {
+        resolvedQueries,
+        resolvedComponents: discoveryCtx.resolvedComponents
+      };
+    } finally {
+      clearGlobalSSRTimeout();
+    }
+  });
+  if ("redirect" in discoveredData) {
+    return {
+      html: "",
+      css: "",
+      ssrData: [],
+      headTags: "",
+      redirect: discoveredData.redirect
+    };
+  }
+  const renderCtx = createRequestContext(normalizedUrl);
+  if (options?.ssrAuth) {
+    renderCtx.ssrAuth = options.ssrAuth;
+  }
+  for (const { key, data } of discoveredData.resolvedQueries) {
+    renderCtx.queryCache.set(key, data);
+  }
+  renderCtx.resolvedComponents = discoveredData.resolvedComponents ?? new Map;
+  return ssrStorage.run(renderCtx, async () => {
+    try {
+      setGlobalSSRTimeout(ssrTimeout);
+      const createApp = resolveAppFactory2(module);
+      let themeCss = "";
+      let themePreloadTags = "";
+      if (module.theme) {
+        try {
+          const compiled = compileTheme2(module.theme, {
+            fallbackMetrics: options?.fallbackMetrics
+          });
+          themeCss = compiled.css;
+          themePreloadTags = compiled.preloadTags;
+        } catch (e) {
+          console.error("[vertz] Failed to compile theme export. Ensure your theme is created with defineTheme().", e);
+        }
+      }
+      const app = createApp();
+      const vnode = toVNode(app);
+      const stream = renderToStream(vnode);
+      const html = await streamToString(stream);
+      const css = collectCSS2(themeCss, module);
+      const ssrData = discoveredData.resolvedQueries.map(({ key, data }) => ({
+        key,
+        data: JSON.parse(JSON.stringify(data))
+      }));
+      return {
+        html,
+        css,
+        ssrData,
+        headTags: themePreloadTags,
+        discoveredRoutes: renderCtx.discoveredRoutes,
+        matchedRoutePatterns: renderCtx.matchedRoutePatterns
+      };
+    } finally {
+      clearGlobalSSRTimeout();
+    }
+  });
+}
+function attemptZeroDiscovery(url, module, options, ssrTimeout) {
+  const manifest = options?.manifest;
+  if (!manifest?.routeEntries || !module.api)
+    return null;
+  const matches = matchUrlToPatterns(url, manifest.routePatterns);
+  if (matches.length === 0)
+    return null;
+  const allQueries = [];
+  let mergedParams = {};
+  for (const match of matches) {
+    const entry = manifest.routeEntries[match.pattern];
+    if (entry) {
+      allQueries.push(...entry.queries);
+    }
+    mergedParams = { ...mergedParams, ...match.params };
+  }
+  if (allQueries.length === 0)
+    return null;
+  const descriptors = reconstructDescriptors(allQueries, mergedParams, module.api);
+  if (descriptors.length === 0)
+    return null;
+  return prefetchFromDescriptors(descriptors, ssrTimeout);
+}
+async function prefetchFromDescriptors(descriptors, ssrTimeout) {
+  const resolvedQueries = [];
+  await Promise.allSettled(descriptors.map(({ key, fetch: fetchFn }) => Promise.race([
+    fetchFn().then((result) => {
+      const data = unwrapResult(result);
+      resolvedQueries.push({ key, data });
+      return "resolved";
+    }),
+    new Promise((r) => setTimeout(r, ssrTimeout)).then(() => "timeout")
+  ])));
+  return { resolvedQueries };
+}
+function unwrapResult(result) {
+  if (result && typeof result === "object" && "ok" in result && "data" in result) {
+    const r = result;
+    if (r.ok)
+      return r.data;
+  }
+  return result;
+}
+async function renderWithPrefetchedData(module, normalizedUrl, prefetchedData, options) {
+  const data = await prefetchedData;
+  const ssrTimeout = options?.ssrTimeout ?? 300;
+  const renderCtx = createRequestContext(normalizedUrl);
+  if (options?.ssrAuth) {
+    renderCtx.ssrAuth = options.ssrAuth;
+  }
+  for (const { key, data: queryData } of data.resolvedQueries) {
+    renderCtx.queryCache.set(key, queryData);
+  }
+  renderCtx.resolvedComponents = new Map;
+  return ssrStorage.run(renderCtx, async () => {
+    try {
+      setGlobalSSRTimeout(ssrTimeout);
+      const createApp = resolveAppFactory2(module);
+      let themeCss = "";
+      let themePreloadTags = "";
+      if (module.theme) {
+        try {
+          const compiled = compileTheme2(module.theme, {
+            fallbackMetrics: options?.fallbackMetrics
+          });
+          themeCss = compiled.css;
+          themePreloadTags = compiled.preloadTags;
+        } catch (e) {
+          console.error("[vertz] Failed to compile theme export. Ensure your theme is created with defineTheme().", e);
+        }
+      }
+      const app = createApp();
+      const vnode = toVNode(app);
+      const stream = renderToStream(vnode);
+      const html = await streamToString(stream);
+      if (renderCtx.ssrRedirect) {
+        return {
+          html: "",
+          css: "",
+          ssrData: [],
+          headTags: "",
+          redirect: renderCtx.ssrRedirect,
+          discoveredRoutes: renderCtx.discoveredRoutes,
+          matchedRoutePatterns: renderCtx.matchedRoutePatterns
+        };
+      }
+      const css = collectCSS2(themeCss, module);
+      const ssrData = data.resolvedQueries.map(({ key, data: d }) => ({
+        key,
+        data: JSON.parse(JSON.stringify(d))
+      }));
+      return {
+        html,
+        css,
+        ssrData,
+        headTags: themePreloadTags,
+        discoveredRoutes: renderCtx.discoveredRoutes,
+        matchedRoutePatterns: renderCtx.matchedRoutePatterns
+      };
+    } finally {
+      clearGlobalSSRTimeout();
+    }
+  });
+}
+var domShimInstalled2 = false;
+function ensureDomShim2() {
+  if (domShimInstalled2 && typeof document !== "undefined")
+    return;
+  domShimInstalled2 = true;
+  installDomShim();
+}
+function resolveAppFactory2(module) {
+  const createApp = module.default || module.App;
+  if (typeof createApp !== "function") {
+    throw new Error("App entry must export a default function or named App function");
+  }
+  return createApp;
+}
+function filterByEntityAccess(queries, entityAccess, session) {
+  if (!entityAccess || !session)
+    return queries;
+  return queries.filter(({ key }) => {
+    const entity = extractEntityFromKey(key);
+    const method = extractMethodFromKey(key);
+    if (!entity)
+      return true;
+    const entityRules = entityAccess[entity];
+    if (!entityRules)
+      return true;
+    const rule = entityRules[method];
+    if (!rule)
+      return true;
+    return evaluateAccessRule(rule, session);
+  });
+}
+function extractEntityFromKey(key) {
+  const pathStart = key.indexOf(":/");
+  if (pathStart === -1)
+    return;
+  const path = key.slice(pathStart + 2);
+  const firstSlash = path.indexOf("/");
+  const questionMark = path.indexOf("?");
+  if (firstSlash === -1 && questionMark === -1)
+    return path;
+  if (firstSlash === -1)
+    return path.slice(0, questionMark);
+  if (questionMark === -1)
+    return path.slice(0, firstSlash);
+  return path.slice(0, Math.min(firstSlash, questionMark));
+}
+function extractMethodFromKey(key) {
+  const pathStart = key.indexOf(":/");
+  if (pathStart === -1)
+    return "list";
+  const path = key.slice(pathStart + 2);
+  const cleanPath = path.split("?")[0] ?? "";
+  const segments = cleanPath.split("/").filter(Boolean);
+  return segments.length > 1 ? "get" : "list";
+}
+function collectCSS2(themeCss, module) {
+  const alreadyIncluded = new Set;
+  if (themeCss)
+    alreadyIncluded.add(themeCss);
+  if (module.styles) {
+    for (const s of module.styles)
+      alreadyIncluded.add(s);
+  }
+  const componentCss = module.getInjectedCSS ? module.getInjectedCSS().filter((s) => !alreadyIncluded.has(s)) : [];
+  const themeTag = themeCss ? `<style data-vertz-css>${themeCss}</style>` : "";
+  const globalTag = module.styles && module.styles.length > 0 ? `<style data-vertz-css>${module.styles.join(`
+`)}</style>` : "";
+  const componentTag = componentCss.length > 0 ? `<style data-vertz-css>${componentCss.join(`
+`)}</style>` : "";
+  return [themeTag, globalTag, componentTag].filter(Boolean).join(`
+`);
+}
+
 // src/upstream-watcher.ts
 import { existsSync, lstatSync, readdirSync, realpathSync, watch } from "fs";
 import { join as join3 } from "path";
@@ -1981,11 +2638,13 @@ function generateSSRPageHtml({
   scriptTag,
   editor = "vscode",
   headTags = "",
-  sessionScript = ""
+  sessionScript = "",
+  htmlDataTheme
 }) {
   const ssrDataScript = ssrData.length > 0 ? `<script>window.__VERTZ_SSR_DATA__=${safeSerialize(ssrData)};</script>` : "";
+  const htmlAttrs = htmlDataTheme ? ` data-theme="${htmlDataTheme}"` : "";
   return `<!doctype html>
-<html lang="en">
+<html lang="en"${htmlAttrs}>
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
@@ -2082,7 +2741,9 @@ function createBunDevServer(options) {
     editor: editorOption,
     headTags: headTagsOption = "",
     sessionResolver,
-    watchDeps
+    watchDeps,
+    themeFromRequest,
+    onRestartNeeded
   } = options;
   const faviconTag = detectFaviconTag(projectRoot);
   const headTags = [faviconTag, headTagsOption].filter(Boolean).join(`
@@ -2099,6 +2760,7 @@ function createBunDevServer(options) {
   let srcWatcherRef = null;
   let refreshTimeout = null;
   let stopped = false;
+  let ssrFallback = false;
   const wsClients = new Set;
   let currentError = null;
   const sourceMapResolver = createSourceMapResolver(projectRoot);
@@ -2412,8 +3074,8 @@ function createBunDevServer(options) {
     }
     if (!pluginsRegistered) {
       const { plugin: serverPlugin, updateManifest } = createVertzBunPlugin({
-        hmr: false,
-        fastRefresh: false,
+        hmr: true,
+        fastRefresh: true,
         logger,
         diagnostics
       });
@@ -2424,16 +3086,34 @@ function createBunDevServer(options) {
     const updateServerManifest = stableUpdateManifest;
     let ssrMod;
     try {
-      ssrMod = await import(entryPath);
+      if (isRestarting) {
+        mkdirSync(devDir, { recursive: true });
+        const ssrBootPath = resolve(devDir, "ssr-reload-entry.ts");
+        const ts = Date.now();
+        writeFileSync2(ssrBootPath, `export * from '${entryPath}';
+`);
+        ssrMod = await import(`${ssrBootPath}?t=${ts}`);
+      } else {
+        ssrMod = await import(entryPath);
+      }
+      ssrFallback = false;
       if (logRequests) {
         console.log("[Server] SSR module loaded");
       }
     } catch (e) {
       console.error("[Server] Failed to load SSR module:", e);
       if (isRestarting) {
-        throw e;
+        ssrFallback = true;
+        ssrMod = {};
+        const errMsg = e instanceof Error ? e.message : String(e);
+        const errStack = e instanceof Error ? e.stack : undefined;
+        const { message: _, ...loc } = errStack ? parseSourceFromStack(errStack) : { message: "" };
+        queueMicrotask(() => {
+          broadcastError("ssr", [{ message: errMsg, ...loc, stack: errStack }]);
+        });
+      } else {
+        process.exit(1);
       }
-      process.exit(1);
     }
     let fontFallbackMetrics;
     if (ssrMod.theme?.fonts) {
@@ -2443,6 +3123,53 @@ function createBunDevServer(options) {
         console.warn("[Server] Failed to extract font metrics:", e);
       }
     }
+    let prefetchManager = null;
+    const srcDir = resolve(projectRoot, "src");
+    const routerCandidates = [resolve(srcDir, "router.tsx"), resolve(srcDir, "router.ts")];
+    const routerPath = routerCandidates.find((p) => existsSync2(p));
+    if (routerPath) {
+      prefetchManager = createPrefetchManifestManager({
+        routerPath,
+        readFile: (path) => {
+          try {
+            return readFileSync2(path, "utf-8");
+          } catch {
+            return;
+          }
+        },
+        resolveImport: (specifier, fromFile) => {
+          if (!specifier.startsWith("."))
+            return;
+          const dir = dirname(fromFile);
+          const base = resolve(dir, specifier);
+          for (const ext of [".tsx", ".ts", ".jsx", ".js"]) {
+            const candidate = `${base}${ext}`;
+            if (existsSync2(candidate))
+              return candidate;
+          }
+          for (const ext of [".tsx", ".ts"]) {
+            const candidate = resolve(base, `index${ext}`);
+            if (existsSync2(candidate))
+              return candidate;
+          }
+          return;
+        }
+      });
+      try {
+        const buildStart = performance.now();
+        prefetchManager.build();
+        const buildMs = Math.round(performance.now() - buildStart);
+        logger.log("prefetch", "initial-build", { routerPath, durationMs: buildMs });
+        if (logRequests) {
+          const manifest = prefetchManager.getSSRManifest();
+          const routeCount = manifest?.routePatterns.length ?? 0;
+          console.log(`[Server] Prefetch manifest built (${routeCount} routes, ${buildMs}ms)`);
+        }
+      } catch (e) {
+        console.warn("[Server] Failed to build prefetch manifest:", e instanceof Error ? e.message : e);
+        prefetchManager = null;
+      }
+    }
     mkdirSync(devDir, { recursive: true });
     const frInitPath = resolve(devDir, "fast-refresh-init.ts");
     writeFileSync2(frInitPath, `import '@vertz/ui-server/fast-refresh-runtime';
@@ -2462,6 +3189,12 @@ if (import.meta.hot) import.meta.hot.accept();
     setupOpenAPIWatcher();
     let bundledScriptUrl = null;
     let hmrBootstrapScript = null;
+    const readyGate = createReadyGate({
+      timeoutMs: 5000,
+      onTimeoutWarning: () => {
+        console.warn("[Server] HMR asset discovery timed out \u2014 unblocking clients");
+      }
+    });
     const routes = {
       "/__vertz_hmr": hmrShellModule
     };
@@ -2527,6 +3260,12 @@ if (import.meta.hot) import.meta.hot.accept();
         if (pathname === "/__vertz_diagnostics") {
           return Response.json(diagnostics.getSnapshot());
         }
+        if (pathname === "/__vertz_prefetch_manifest") {
+          if (!prefetchManager) {
+            return Response.json({ error: "No prefetch manifest available (router file not found)" }, { status: 404 });
+          }
+          return Response.json(prefetchManager.getSnapshot());
+        }
         if (pathname === "/_vertz/image") {
           return handleDevImageProxy(request);
         }
@@ -2605,6 +3344,7 @@ data: {}
         if (logRequests) {
           console.log(`[Server] SSR: ${pathname}`);
         }
+        const ssrTheme = themeFromRequest?.(request) ?? undefined;
         try {
           const interceptor = apiHandler ? createFetchInterceptor({
             apiHandler,
@@ -2652,10 +3392,12 @@ data: {}
           const doRender = async () => {
             logger.log("ssr", "render-start", { url: pathname });
             const ssrStart = performance.now();
-            const result = await ssrRenderToString(ssrMod, pathname + url.search, {
+            const result = await ssrRenderSinglePass(ssrMod, pathname + url.search, {
               ssrTimeout: 300,
               fallbackMetrics: fontFallbackMetrics,
-              ssrAuth
+              ssrAuth,
+              manifest: prefetchManager?.getSSRManifest(),
+              prefetchSession: toPrefetchSession(ssrAuth)
             });
             logger.log("ssr", "render-done", {
               url: pathname,
@@ -2668,19 +3410,22 @@ data: {}
                 headers: { Location: result.redirect.to }
               });
             }
+            const bodyHtml = ssrTheme ? result.html.replace(/data-theme="[^"]*"/, `data-theme="${ssrTheme}"`) : result.html;
             const scriptTag = buildScriptTag(bundledScriptUrl, hmrBootstrapScript, clientSrc);
             const combinedHeadTags = [headTags, result.headTags].filter(Boolean).join(`
 `);
             const html = generateSSRPageHtml({
               title,
               css: result.css,
-              bodyHtml: result.html,
+              bodyHtml,
               ssrData: result.ssrData,
               scriptTag,
               editor,
               headTags: combinedHeadTags,
-              sessionScript
+              sessionScript,
+              htmlDataTheme: ssrTheme
             });
+            clearError();
             return new Response(html, {
               status: 200,
               headers: {
@@ -2704,7 +3449,8 @@ data: {}
             ssrData: [],
             scriptTag,
             editor,
-            headTags
+            headTags,
+            htmlDataTheme: ssrTheme
           });
           return new Response(fallbackHtml, {
             status: 200,
@@ -2720,13 +3466,15 @@ data: {}
           wsClients.add(ws);
           diagnostics.recordWebSocketChange(wsClients.size);
           logger.log("ws", "client-connected", { total: wsClients.size });
-          ws.sendText(JSON.stringify({ type: "connected" }));
-          if (currentError) {
-            ws.sendText(JSON.stringify({
-              type: "error",
-              category: currentError.category,
-              errors: currentError.errors
-            }));
+          if (!readyGate.onOpen(ws)) {
+            ws.sendText(JSON.stringify({ type: "connected" }));
+            if (currentError) {
+              ws.sendText(JSON.stringify({
+                type: "error",
+                category: currentError.category,
+                errors: currentError.errors
+              }));
+            }
           }
         },
         message(ws, msg) {
@@ -2818,6 +3566,7 @@ data: {}
         },
         close(ws) {
           wsClients.delete(ws);
+          readyGate.onClose(ws);
           diagnostics.recordWebSocketChange(wsClients.size);
         }
       },
@@ -2829,7 +3578,13 @@ data: {}
     if (logRequests) {
       console.log(`[Server] SSR+HMR dev server running at http://${host}:${server.port}`);
     }
-    await discoverHMRAssets();
+    try {
+      await discoverHMRAssets();
+    } finally {
+      if (!readyGate.isReady) {
+        readyGate.open(currentError);
+      }
+    }
     async function discoverHMRAssets() {
       try {
         const res = await fetch(`http://${host}:${server?.port}/__vertz_hmr`);
@@ -2852,7 +3607,6 @@ data: {}
         console.warn("[Server] Could not discover HMR bundled URL:", e);
       }
     }
-    const srcDir = resolve(projectRoot, "src");
     stopped = false;
     if (existsSync2(srcDir)) {
       srcWatcherRef = watch2(srcDir, { recursive: true }, (_event, filename) => {
@@ -2923,10 +3677,33 @@ data: {}
               const { changed } = updateServerManifest(changedFilePath, source);
               const manifestDurationMs = Math.round(performance.now() - manifestStartMs);
               diagnostics.recordManifestUpdate(lastChangedFile, changed, manifestDurationMs);
+              if (prefetchManager) {
+                const prefetchStart = performance.now();
+                prefetchManager.onFileChange(changedFilePath, source);
+                const prefetchMs = Math.round(performance.now() - prefetchStart);
+                logger.log("prefetch", "rebuild", {
+                  file: lastChangedFile,
+                  durationMs: prefetchMs,
+                  isRouter: changedFilePath === routerPath
+                });
+              }
             } catch {}
           }
           if (stopped)
             return;
+          if (ssrFallback) {
+            if (onRestartNeeded) {
+              if (logRequests) {
+                console.log("[Server] SSR in fallback mode \u2014 requesting process restart");
+              }
+              await devServer.stop();
+              onRestartNeeded();
+              return;
+            }
+            if (logRequests) {
+              console.log("[Server] SSR in fallback mode \u2014 attempting re-import (best effort)");
+            }
+          }
           const cacheCleared = clearSSRRequireCache();
           logger.log("watcher", "cache-cleared", { entries: cacheCleared });
           const ssrWrapperPath = resolve(devDir, "ssr-reload-entry.ts");
@@ -2937,6 +3714,7 @@ data: {}
           try {
             const freshMod = await import(`${ssrWrapperPath}?t=${Date.now()}`);
             ssrMod = freshMod;
+            ssrFallback = false;
             if (freshMod.theme?.fonts) {
               try {
                 fontFallbackMetrics = await extractFontMetrics(freshMod.theme.fonts, projectRoot);
@@ -2962,6 +3740,7 @@ data: {}
             try {
               const freshMod = await import(`${ssrWrapperPath}?t=${Date.now()}`);
               ssrMod = freshMod;
+              ssrFallback = false;
               if (freshMod.theme?.fonts) {
                 try {
                   fontFallbackMetrics = await extractFontMetrics(freshMod.theme.fonts, projectRoot);
@@ -2982,6 +3761,7 @@ data: {}
               logger.log("watcher", "ssr-reload", { status: "failed", error: errMsg });
               const { message: _m, ...loc2 } = errStack ? parseSourceFromStack(errStack) : { message: "" };
               broadcastError("ssr", [{ message: errMsg, ...loc2, stack: errStack }]);
+              ssrFallback = true;
             }
           }
         }, 100);
@@ -3048,6 +3828,7 @@ data: {}
       lastBroadcastedError = "";
       lastChangedFile = "";
       clearGraceUntil = 0;
+      ssrFallback = false;
       terminalDedup.reset();
       clearSSRRequireCache();
       sourceMapResolver.invalidate();