@jay-framework/dev-server 0.11.0 → 0.12.0

package/dist/index.d.ts

@@ -2,8 +2,10 @@ import { ViteDevServer, Connect } from 'vite';
 import { JayRoute } from '@jay-framework/stack-route-scanner';
 import { RequestHandler } from 'express-serve-static-core';
 import { JayRollupConfig } from '@jay-framework/rollup-plugin';
+import { LogLevel } from '@jay-framework/logger';
 import { ProjectClientInitInfo, PluginWithInit, ActionRegistry } from '@jay-framework/stack-server-runtime';
 import { RequestHandler as RequestHandler$1 } from 'express';
+import { JayRollupConfig as JayRollupConfig$1 } from '@jay-framework/compiler-jay-stack';
 
 interface DevServerOptions {
     publicBaseUrlPath?: string;
@@ -23,6 +25,11 @@ interface DevServerOptions {
      * The automation API is available at `window.__jay.automation` and via `AUTOMATION_CONTEXT`.
      */
     disableAutomation?: boolean;
+    /**
+     * Log level for dev server output.
+     * Controls both Jay logging and Vite logging.
+     */
+    logLevel?: LogLevel;
 }
 
 /**
@@ -100,7 +107,7 @@ interface DevServer {
     routes: DevServerRoute[];
     lifecycleManager: ServiceLifecycleManager;
 }
-declare function mkDevServer(options: DevServerOptions): Promise<DevServer>;
+declare function mkDevServer(rawOptions: DevServerOptions): Promise<DevServer>;
 
 /**
  * Action Router for Jay Stack dev server.
@@ -151,4 +158,44 @@ declare function createActionRouter(options?: ActionRouterOptions): RequestHandl
  */
 declare function actionBodyParser(): RequestHandler$1;
 
-export { ACTION_ENDPOINT_BASE, type ActionRouterOptions, type DevServer, type DevServerOptions, type DevServerRoute, actionBodyParser, createActionRouter, mkDevServer };
+/**
+ * Vite Factory
+ *
+ * Single source of truth for creating Vite servers.
+ * Used by both the dev-server and CLI commands.
+ */
+
+interface CreateViteServerOptions {
+    /** Project root directory */
+    projectRoot: string;
+    /** Root directory for pages (defaults to projectRoot) */
+    pagesRoot?: string;
+    /** Base URL path for public assets */
+    base?: string;
+    /** Jay Stack compiler config (optional, will use defaults if not provided) */
+    jayRollupConfig?: JayRollupConfig$1;
+    /** Log level (defaults to 'info' for dev-server, 'warn' for CLI) */
+    logLevel?: 'info' | 'warn' | 'error' | 'silent';
+    /** Whether to clear screen on rebuild */
+    clearScreen?: boolean;
+}
+/**
+ * Creates a Vite server configured for Jay Stack.
+ *
+ * This is the single source of truth for Vite configuration.
+ * Both dev-server and CLI use this function.
+ */
+declare function createViteServer(options: CreateViteServerOptions): Promise<ViteDevServer>;
+/**
+ * Creates a minimal Vite server for CLI usage.
+ *
+ * This is a convenience wrapper around createViteServer with CLI-appropriate defaults.
+ * Disables dependency optimization and ignores the build/ folder to avoid errors
+ * from stale build artifacts (e.g., build/client-scripts/ referencing build/slow-render-cache/).
+ */
+declare function createViteForCli(options: {
+    projectRoot: string;
+    tsConfigFilePath?: string;
+}): Promise<ViteDevServer>;
+
+export { ACTION_ENDPOINT_BASE, type ActionRouterOptions, type CreateViteServerOptions, type DevServer, type DevServerOptions, type DevServerRoute, actionBodyParser, createActionRouter, createViteForCli, createViteServer, mkDevServer };

package/dist/index.js

@@ -5,16 +5,17 @@ var __publicField = (obj, key, value) => {
   return value;
 };
 import { createServer } from "vite";
-import { scanRoutes, routeToExpressRoute } from "@jay-framework/stack-route-scanner";
-import { discoverPluginsWithInit, sortPluginsByDependencies, executePluginServerInits, runInitCallbacks, actionRegistry, discoverAndRegisterActions, discoverAllPluginActions, runShutdownCallbacks, clearLifecycleCallbacks, clearServiceRegistry, clearClientInitData, DevSlowlyChangingPhase, SlowRenderCache, preparePluginClientInits, loadPageParts, renderFastChangingData, generateClientScript, getClientInitData } from "@jay-framework/stack-server-runtime";
 import { jayRuntime } from "@jay-framework/vite-plugin";
 import { createRequire } from "module";
 import "@jay-framework/compiler-shared";
 import * as path from "node:path";
 import path__default from "node:path";
-import { parseContract, slowRenderTransform } from "@jay-framework/compiler-jay-html";
+import { discoverHeadlessInstances, parseContract, slowRenderTransform, JAY_IMPORT_RESOLVER, resolveHeadlessInstances } from "@jay-framework/compiler-jay-html";
+import { getLogger, getDevLogger } from "@jay-framework/logger";
 import { createRequire as createRequire$1 } from "node:module";
 import * as fs from "node:fs";
+import { scanRoutes, routeToExpressRoute } from "@jay-framework/stack-route-scanner";
+import { discoverPluginsWithInit, sortPluginsByDependencies, executePluginServerInits, runInitCallbacks, actionRegistry, discoverAndRegisterActions, discoverAllPluginActions, runShutdownCallbacks, clearLifecycleCallbacks, clearServiceRegistry, clearClientInitData, DevSlowlyChangingPhase, SlowRenderCache, preparePluginClientInits, getServiceRegistry, materializeContracts, loadPageParts, renderFastChangingData, slowRenderInstances, generateClientScript, getClientInitData, resolveServices } from "@jay-framework/stack-server-runtime";
 import fs$1 from "node:fs/promises";
 import { pathToFileURL } from "node:url";
 const s$1 = createRequire(import.meta.url), e$1 = s$1("typescript"), c$1 = new Proxy(e$1, {
@@ -1021,7 +1022,7 @@ function createImportChainTracker(options = {}) {
       importChain.clear();
       detectedServerModules.clear();
       if (verbose) {
-        console.log("[import-chain-tracker] Build started, tracking imports...");
+        getLogger().info("[import-chain-tracker] Build started, tracking imports...");
       }
     },
     resolveId(source, importer, options2) {
@@ -1033,7 +1034,7 @@ function createImportChainTracker(options = {}) {
       }
       if (importer) {
         if (verbose) {
-          console.log(
+          getLogger().info(
             `[import-chain-tracker] ${shortenPath(importer)} imports ${source}`
           );
         }
@@ -1050,14 +1051,14 @@ function createImportChainTracker(options = {}) {
       if (isServerOnlyModule(id)) {
         detectedServerModules.add(id);
         const chain = buildImportChain(id);
-        console.error(
+        getLogger().error(
           `
 [import-chain-tracker] ⚠️  Server-only module detected in client build!`
         );
-        console.error(`Module: ${shortenPath(id)}`);
-        console.error(`Import chain:`);
-        console.error(formatChain(chain));
-        console.error("");
+        getLogger().error(`Module: ${shortenPath(id)}`);
+        getLogger().error(`Import chain:`);
+        getLogger().error(formatChain(chain));
+        getLogger().error("");
       }
       const importRegex = /import\s+(?:(?:\{[^}]*\}|[^{}\s,]+)\s+from\s+)?['"]([^'"]+)['"]/g;
       let match;
@@ -1067,16 +1068,18 @@ function createImportChainTracker(options = {}) {
         if (isServerOnlyModule(importedModule)) {
           if (!detectedServerModules.has(importedModule)) {
             detectedServerModules.add(importedModule);
-            console.error(
+            getLogger().error(
               `
 [import-chain-tracker] ⚠️  Server-only import detected in client build!`
             );
-            console.error(`Module "${importedModule}" imported by: ${shortenPath(id)}`);
+            getLogger().error(
+              `Module "${importedModule}" imported by: ${shortenPath(id)}`
+            );
             const chain = buildImportChain(id);
             chain.push(importedModule);
-            console.error(`Import chain:`);
-            console.error(formatChain(chain));
-            console.error("");
+            getLogger().error(`Import chain:`);
+            getLogger().error(formatChain(chain));
+            getLogger().error("");
           }
         }
       }
@@ -1084,21 +1087,21 @@ function createImportChainTracker(options = {}) {
     },
     buildEnd() {
       if (detectedServerModules.size > 0) {
-        console.warn(
+        getLogger().warn(
           `
 [import-chain-tracker] ⚠️  ${detectedServerModules.size} server-only module(s) detected during transform:`
         );
         for (const mod of detectedServerModules) {
-          console.warn(`  - ${mod}`);
+          getLogger().warn(`  - ${mod}`);
         }
-        console.warn(
+        getLogger().warn(
           "\nNote: These may be stripped by the code-split transform if only used in .withServer()."
         );
-        console.warn(
+        getLogger().warn(
           'If build fails with "not exported" errors, check the import chains above.\n'
         );
       } else if (verbose) {
-        console.log(
+        getLogger().info(
           "[import-chain-tracker] ✅ No server-only modules detected in client build"
         );
       }
@@ -1165,7 +1168,7 @@ function transformImports(options) {
     hasChanges = true;
     const newSource = `${packageName}/client`;
     if (verbose) {
-      console.log(
+      getLogger().info(
         `[plugin-client-import] Rewriting import ${source} -> ${newSource} (in ${path.basename(filePath)})`
       );
     }
@@ -1182,7 +1185,7 @@ function transformImports(options) {
     hasChanges = true;
     const newSource = `${packageName}/client`;
     if (verbose) {
-      console.log(
+      getLogger().info(
         `[plugin-client-import] Rewriting export ${source} -> ${newSource} (in ${path.basename(filePath)})`
       );
     }
@@ -1258,7 +1261,7 @@ function jayStackCompiler(options = {}) {
         try {
           return transformJayStackBuilder(code, id, environment);
         } catch (error) {
-          console.error(`[jay-stack:code-split] Error transforming ${id}:`, error);
+          getLogger().error(`[jay-stack:code-split] Error transforming ${id}: ${error}`);
           return null;
         }
       }
@@ -1318,12 +1321,14 @@ function jayStackCompiler(options = {}) {
           try {
             code = await fs.promises.readFile(actualPath, "utf-8");
           } catch (err) {
-            console.error(`[action-transform] Could not read ${actualPath}:`, err);
+            getLogger().error(
+              `[action-transform] Could not read ${actualPath}: ${err}`
+            );
             return null;
           }
           const actions = extractActionsFromSource(code, actualPath);
           if (actions.length === 0) {
-            console.warn(`[action-transform] No actions found in ${actualPath}`);
+            getLogger().warn(`[action-transform] No actions found in ${actualPath}`);
             return null;
           }
           const lines = [
@@ -1350,6 +1355,69 @@ function jayStackCompiler(options = {}) {
   );
   return plugins;
 }
+async function createViteServer(options) {
+  const {
+    projectRoot,
+    pagesRoot = projectRoot,
+    base,
+    jayRollupConfig = { tsConfigFilePath: path__default.join(projectRoot, "tsconfig.json") },
+    logLevel = "info",
+    clearScreen = true
+  } = options;
+  const vite = await createServer({
+    // Don't start HTTP server - we use middleware mode
+    server: { middlewareMode: true },
+    // Use Jay Stack compiler for .jay-html and other custom transforms
+    plugins: [...jayStackCompiler(jayRollupConfig)],
+    // Custom app type (no default middleware)
+    appType: "custom",
+    // Base URL path
+    base,
+    // Root directory for module resolution
+    root: pagesRoot,
+    // SSR configuration
+    ssr: {
+      // Mark jay-framework packages as external so Vite uses Node's require
+      // This ensures all packages share the same module instances (Symbol identity)
+      external: ["@jay-framework/stack-server-runtime", "@jay-framework/fullstack-component"]
+    },
+    // Disable automatic entry point discovery for pre-bundling —
+    // we run in middleware mode with no HTML files, so Vite can't auto-detect entries
+    optimizeDeps: {
+      entries: []
+    },
+    // Logging
+    logLevel,
+    clearScreen
+  });
+  return vite;
+}
+async function createViteForCli(options) {
+  const { projectRoot, tsConfigFilePath = path__default.join(projectRoot, "tsconfig.json") } = options;
+  const vite = await createServer({
+    server: {
+      middlewareMode: true,
+      watch: {
+        ignored: ["**/build/**"]
+      }
+    },
+    plugins: [
+      ...jayStackCompiler({ tsConfigFilePath })
+    ],
+    appType: "custom",
+    root: projectRoot,
+    ssr: {
+      external: ["@jay-framework/stack-server-runtime", "@jay-framework/fullstack-component"]
+    },
+    // Disable dependency optimization — CLI only uses SSR, no browser bundles
+    optimizeDeps: {
+      entries: []
+    },
+    logLevel: "warn",
+    clearScreen: false
+  });
+  return vite;
+}
 class ServiceLifecycleManager {
   constructor(projectRoot, sourceBase = "src") {
     /** Path to project's lib/init.ts (makeJayInit pattern) */
@@ -1388,8 +1456,9 @@ class ServiceLifecycleManager {
    * 4. Auto-discovering and registering actions
    */
   async initialize() {
+    const log = getLogger();
     if (this.isInitialized) {
-      console.warn("[Services] Already initialized, skipping...");
+      log.warn("[Services] Already initialized, skipping...");
       return;
     }
     this.projectInitFilePath = this.findProjectInitFile();
@@ -1399,18 +1468,18 @@ class ServiceLifecycleManager {
     });
     this.pluginsWithInit = sortPluginsByDependencies(discoveredPlugins);
     if (this.pluginsWithInit.length > 0) {
-      console.log(
+      log.info(
         `[Services] Found ${this.pluginsWithInit.length} plugin(s) with init: ${this.pluginsWithInit.map((p) => p.name).join(", ")}`
       );
     }
     await executePluginServerInits(this.pluginsWithInit, this.viteServer ?? void 0, true);
     if (this.projectInitFilePath) {
-      console.log("[DevServer] Loading project init: src/init.ts");
+      log.info("[DevServer] Loading project init: src/init.ts");
       try {
         if (this.viteServer) {
           const module = await this.viteServer.ssrLoadModule(this.projectInitFilePath);
           if (module.init?._serverInit) {
-            console.log("[DevServer] Running server init: project");
+            log.info("[DevServer] Running server init: project");
             const { setClientInitData } = await import("@jay-framework/stack-server-runtime");
             const clientData = await module.init._serverInit();
             if (clientData !== void 0 && clientData !== null) {
@@ -1422,14 +1491,14 @@ class ServiceLifecycleManager {
           await import(fileUrl);
         }
       } catch (error) {
-        console.error("[Services] Failed to load project init:", error);
+        log.error(`[Services] Failed to load project init: ${error}`);
         throw error;
       }
     } else {
-      console.log("[Services] No init.ts found, skipping project initialization");
+      log.info("[Services] No init.ts found, skipping project initialization");
     }
     await runInitCallbacks();
-    console.log("[Services] Initialization complete");
+    log.info("[Services] Initialization complete");
     await this.discoverActions();
     this.isInitialized = true;
   }
@@ -1437,6 +1506,7 @@ class ServiceLifecycleManager {
    * Auto-discovers and registers actions from project and plugins.
    */
   async discoverActions() {
+    const log = getLogger();
     let totalActions = 0;
     try {
       const result = await discoverAndRegisterActions({
@@ -1448,7 +1518,7 @@ class ServiceLifecycleManager {
       });
       totalActions += result.actionCount;
     } catch (error) {
-      console.error("[Actions] Failed to auto-discover project actions:", error);
+      log.error(`[Actions] Failed to auto-discover project actions: ${error}`);
     }
     try {
       const pluginActions = await discoverAllPluginActions({
@@ -1459,20 +1529,21 @@ class ServiceLifecycleManager {
       });
       totalActions += pluginActions.length;
     } catch (error) {
-      console.error("[Actions] Failed to auto-discover plugin actions:", error);
+      log.error(`[Actions] Failed to auto-discover plugin actions: ${error}`);
     }
     if (totalActions > 0) {
-      console.log(`[Actions] Auto-registered ${totalActions} action(s) total`);
+      log.info(`[Actions] Auto-registered ${totalActions} action(s) total`);
     }
   }
   /**
    * Shuts down services gracefully with timeout
    */
   async shutdown(timeoutMs = 5e3) {
+    const log = getLogger();
     if (!this.isInitialized) {
       return;
     }
-    console.log("[Services] Shutting down...");
+    log.info("[Services] Shutting down...");
     try {
       await Promise.race([
         runShutdownCallbacks(),
@@ -1480,12 +1551,12 @@ class ServiceLifecycleManager {
           (_, reject) => setTimeout(() => reject(new Error("Shutdown timeout")), timeoutMs)
         )
       ]);
-      console.log("[Services] Shutdown complete");
+      log.info("[Services] Shutdown complete");
     } catch (error) {
       if (error.message === "Shutdown timeout") {
-        console.warn("[Services] Shutdown timed out after", timeoutMs, "ms");
+        log.warn(`[Services] Shutdown timed out after ${timeoutMs}ms`);
       } else {
-        console.error("[Services] Shutdown error:", error);
+        log.error(`[Services] Shutdown error: ${error}`);
       }
     } finally {
       this.isInitialized = false;
@@ -1495,7 +1566,8 @@ class ServiceLifecycleManager {
    * Hot reload: shutdown, clear caches, re-import, and re-initialize
    */
   async reload() {
-    console.log("[Services] Reloading services...");
+    const log = getLogger();
+    log.info("[Services] Reloading services...");
     await this.shutdown();
     clearLifecycleCallbacks();
     clearServiceRegistry();
@@ -1511,7 +1583,7 @@ class ServiceLifecycleManager {
     }
     this.isInitialized = false;
     await this.initialize();
-    console.log("[Services] Reload complete");
+    log.info("[Services] Reload complete");
   }
   /**
    * Returns the path to the init file if found.
@@ -1813,6 +1885,7 @@ function filterPluginsForPage(allPluginClientInits, allPluginsWithInit, usedPack
 function mkRoute(route, vite, slowlyPhase, options, slowRenderCache, projectInit, allPluginsWithInit = [], allPluginClientInits = []) {
   const routePath = routeToExpressRoute(route);
   const handler = async (req, res) => {
+    const timing = getDevLogger()?.startRequest(req.method, req.path);
     try {
       const url = req.originalUrl.replace(options.publicBaseUrlPath, "");
       const pageParams = { ...route.inferredParams, ...req.params };
@@ -1826,7 +1899,7 @@ function mkRoute(route, vite, slowlyPhase, options, slowRenderCache, projectInit
         try {
           await fs$1.access(cachedEntry.preRenderedPath);
         } catch {
-          console.log(
+          getLogger().info(
             `[SlowRender] Cached file missing, rebuilding: ${cachedEntry.preRenderedPath}`
           );
           await slowRenderCache.invalidate(route.jayHtmlPath);
@@ -1845,7 +1918,8 @@ function mkRoute(route, vite, slowlyPhase, options, slowRenderCache, projectInit
           allPluginsWithInit,
           projectInit,
           res,
-          url
+          url,
+          timing
         );
       } else if (useSlowRenderCache) {
         await handlePreRenderRequest(
@@ -1860,7 +1934,8 @@ function mkRoute(route, vite, slowlyPhase, options, slowRenderCache, projectInit
           allPluginsWithInit,
           projectInit,
           res,
-          url
+          url,
+          timing
         );
       } else {
         await handleDirectRequest(
@@ -1874,18 +1949,21 @@ function mkRoute(route, vite, slowlyPhase, options, slowRenderCache, projectInit
           allPluginsWithInit,
           projectInit,
           res,
-          url
+          url,
+          timing
         );
       }
     } catch (e2) {
       vite?.ssrFixStacktrace(e2);
-      console.log(e2.stack);
+      getLogger().error(e2.stack);
       res.status(500).end(e2.stack);
+      timing?.end();
     }
   };
   return { path: routePath, handler, fsRoute: route };
 }
-async function handleCachedRequest(vite, route, options, cachedEntry, pageParams, pageProps, allPluginClientInits, allPluginsWithInit, projectInit, res, url) {
+async function handleCachedRequest(vite, route, options, cachedEntry, pageParams, pageProps, allPluginClientInits, allPluginsWithInit, projectInit, res, url, timing) {
+  const loadStart = Date.now();
   const pagePartsResult = await loadPageParts(
     vite,
     route,
@@ -1894,9 +1972,11 @@ async function handleCachedRequest(vite, route, options, cachedEntry, pageParams
     options.jayRollupConfig,
     { preRenderedPath: cachedEntry.preRenderedPath }
   );
+  timing?.recordViteSsr(Date.now() - loadStart);
   if (!pagePartsResult.val) {
-    console.log(pagePartsResult.validations.join("\n"));
+    getLogger().info(pagePartsResult.validations.join("\n"));
     res.status(500).end(pagePartsResult.validations.join("\n"));
+    timing?.end();
     return;
   }
   const { parts: pageParts, clientTrackByMap, usedPackages } = pagePartsResult.val;
@@ -1905,32 +1985,56 @@ async function handleCachedRequest(vite, route, options, cachedEntry, pageParams
     allPluginsWithInit,
     usedPackages
   );
+  const fastStart = Date.now();
   const renderedFast = await renderFastChangingData(
     pageParams,
     pageProps,
     cachedEntry.carryForward,
     pageParts
   );
+  timing?.recordFastRender(Date.now() - fastStart);
   if (renderedFast.kind !== "PhaseOutput") {
     handleOtherResponseCodes(res, renderedFast);
+    timing?.end();
     return;
   }
+  let fastViewState = renderedFast.rendered;
+  let fastCarryForward = renderedFast.carryForward;
+  const instancePhaseData = cachedEntry.carryForward?.__instances;
+  if (instancePhaseData && pagePartsResult.val.headlessInstanceComponents.length > 0) {
+    const instanceFastResult = await renderFastChangingDataForInstances(
+      instancePhaseData,
+      pagePartsResult.val.headlessInstanceComponents
+    );
+    if (instanceFastResult) {
+      fastViewState = {
+        ...fastViewState,
+        __headlessInstances: instanceFastResult.viewStates
+      };
+      fastCarryForward = {
+        ...fastCarryForward,
+        __headlessInstances: instanceFastResult.carryForwards
+      };
+    }
+  }
   await sendResponse(
     vite,
     res,
     url,
     cachedEntry.preRenderedPath,
     pageParts,
-    renderedFast.rendered,
-    renderedFast.carryForward,
+    fastViewState,
+    fastCarryForward,
     clientTrackByMap,
     projectInit,
     pluginsForPage,
     options,
-    cachedEntry.slowViewState
+    cachedEntry.slowViewState,
+    timing
   );
 }
-async function handlePreRenderRequest(vite, route, options, slowlyPhase, slowRenderCache, pageParams, pageProps, allPluginClientInits, allPluginsWithInit, projectInit, res, url) {
+async function handlePreRenderRequest(vite, route, options, slowlyPhase, slowRenderCache, pageParams, pageProps, allPluginClientInits, allPluginsWithInit, projectInit, res, url, timing) {
+  const loadStart = Date.now();
   const initialPartsResult = await loadPageParts(
     vite,
     route,
@@ -1938,35 +2042,48 @@ async function handlePreRenderRequest(vite, route, options, slowlyPhase, slowRen
     options.projectRootFolder,
     options.jayRollupConfig
   );
+  timing?.recordViteSsr(Date.now() - loadStart);
   if (!initialPartsResult.val) {
-    console.log(initialPartsResult.validations.join("\n"));
+    getLogger().info(initialPartsResult.validations.join("\n"));
     res.status(500).end(initialPartsResult.validations.join("\n"));
+    timing?.end();
     return;
   }
+  const slowStart = Date.now();
   const renderedSlowly = await slowlyPhase.runSlowlyForPage(
     pageParams,
     pageProps,
     initialPartsResult.val.parts
   );
   if (renderedSlowly.kind !== "PhaseOutput") {
+    timing?.recordSlowRender(Date.now() - slowStart);
     if (renderedSlowly.kind === "ClientError") {
       handleOtherResponseCodes(res, renderedSlowly);
     }
+    timing?.end();
     return;
   }
-  const preRenderedContent = await preRenderJayHtml(route, renderedSlowly.rendered);
-  if (!preRenderedContent) {
+  const preRenderResult = await preRenderJayHtml(
+    route,
+    renderedSlowly.rendered,
+    initialPartsResult.val.headlessContracts,
+    initialPartsResult.val.headlessInstanceComponents
+  );
+  timing?.recordSlowRender(Date.now() - slowStart);
+  if (!preRenderResult) {
     res.status(500).end("Failed to pre-render jay-html");
+    timing?.end();
     return;
   }
+  const carryForward = preRenderResult.instancePhaseData ? { ...renderedSlowly.carryForward, __instances: preRenderResult.instancePhaseData } : renderedSlowly.carryForward;
   const preRenderedPath = await slowRenderCache.set(
     route.jayHtmlPath,
     pageParams,
-    preRenderedContent,
+    preRenderResult.preRenderedJayHtml,
     renderedSlowly.rendered,
-    renderedSlowly.carryForward
+    carryForward
   );
-  console.log(`[SlowRender] Cached pre-rendered jay-html at ${preRenderedPath}`);
+  getLogger().info(`[SlowRender] Cached pre-rendered jay-html at ${preRenderedPath}`);
   const pagePartsResult = await loadPageParts(
     vite,
     route,
@@ -1976,8 +2093,9 @@ async function handlePreRenderRequest(vite, route, options, slowlyPhase, slowRen
     { preRenderedPath }
   );
   if (!pagePartsResult.val) {
-    console.log(pagePartsResult.validations.join("\n"));
+    getLogger().info(pagePartsResult.validations.join("\n"));
     res.status(500).end(pagePartsResult.validations.join("\n"));
+    timing?.end();
     return;
   }
   const { parts: pageParts, clientTrackByMap, usedPackages } = pagePartsResult.val;
@@ -1986,32 +2104,56 @@ async function handlePreRenderRequest(vite, route, options, slowlyPhase, slowRen
     allPluginsWithInit,
     usedPackages
   );
+  const fastStart = Date.now();
   const renderedFast = await renderFastChangingData(
     pageParams,
     pageProps,
-    renderedSlowly.carryForward,
+    carryForward,
     pageParts
   );
+  timing?.recordFastRender(Date.now() - fastStart);
   if (renderedFast.kind !== "PhaseOutput") {
     handleOtherResponseCodes(res, renderedFast);
+    timing?.end();
     return;
   }
+  let fastViewState = renderedFast.rendered;
+  let fastCarryForward = renderedFast.carryForward;
+  const instancePhaseData = carryForward?.__instances;
+  if (instancePhaseData && pagePartsResult.val.headlessInstanceComponents.length > 0) {
+    const instanceFastResult = await renderFastChangingDataForInstances(
+      instancePhaseData,
+      pagePartsResult.val.headlessInstanceComponents
+    );
+    if (instanceFastResult) {
+      fastViewState = {
+        ...fastViewState,
+        __headlessInstances: instanceFastResult.viewStates
+      };
+      fastCarryForward = {
+        ...fastCarryForward,
+        __headlessInstances: instanceFastResult.carryForwards
+      };
+    }
+  }
   await sendResponse(
     vite,
     res,
     url,
     preRenderedPath,
     pageParts,
-    renderedFast.rendered,
-    renderedFast.carryForward,
+    fastViewState,
+    fastCarryForward,
     clientTrackByMap,
     projectInit,
     pluginsForPage,
     options,
-    renderedSlowly.rendered
+    renderedSlowly.rendered,
+    timing
   );
 }
-async function handleDirectRequest(vite, route, options, slowlyPhase, pageParams, pageProps, allPluginClientInits, allPluginsWithInit, projectInit, res, url) {
+async function handleDirectRequest(vite, route, options, slowlyPhase, pageParams, pageProps, allPluginClientInits, allPluginsWithInit, projectInit, res, url, timing) {
+  const loadStart = Date.now();
   const pagePartsResult = await loadPageParts(
     vite,
     route,
@@ -2019,9 +2161,11 @@ async function handleDirectRequest(vite, route, options, slowlyPhase, pageParams
     options.projectRootFolder,
     options.jayRollupConfig
   );
+  timing?.recordViteSsr(Date.now() - loadStart);
   if (!pagePartsResult.val) {
-    console.log(pagePartsResult.validations.join("\n"));
+    getLogger().info(pagePartsResult.validations.join("\n"));
     res.status(500).end(pagePartsResult.validations.join("\n"));
+    timing?.end();
     return;
   }
   const {
@@ -2035,21 +2179,59 @@ async function handleDirectRequest(vite, route, options, slowlyPhase, pageParams
     allPluginsWithInit,
     usedPackages
   );
+  const slowStart = Date.now();
   const renderedSlowly = await slowlyPhase.runSlowlyForPage(pageParams, pageProps, pageParts);
   if (renderedSlowly.kind !== "PhaseOutput") {
+    timing?.recordSlowRender(Date.now() - slowStart);
     if (renderedSlowly.kind === "ClientError") {
       handleOtherResponseCodes(res, renderedSlowly);
     }
+    timing?.end();
     return;
   }
+  let instanceViewStates;
+  let instancePhaseDataForFast;
+  const headlessInstanceComponents = pagePartsResult.val.headlessInstanceComponents ?? [];
+  if (headlessInstanceComponents.length > 0) {
+    const jayHtmlContent = await fs$1.readFile(route.jayHtmlPath, "utf-8");
+    const discoveryResult = discoverHeadlessInstances(jayHtmlContent);
+    if (discoveryResult.instances.length > 0) {
+      const slowResult = await slowRenderInstances(
+        discoveryResult.instances,
+        headlessInstanceComponents
+      );
+      if (slowResult) {
+        instanceViewStates = { ...slowResult.slowViewStates };
+        instancePhaseDataForFast = slowResult.instancePhaseData;
+      }
+    }
+  }
+  timing?.recordSlowRender(Date.now() - slowStart);
+  const fastStart = Date.now();
   const renderedFast = await renderFastChangingData(
     pageParams,
     pageProps,
     renderedSlowly.carryForward,
     pageParts
   );
+  if (instancePhaseDataForFast && instanceViewStates) {
+    const instanceFastResult = await renderFastChangingDataForInstances(
+      instancePhaseDataForFast,
+      headlessInstanceComponents
+    );
+    if (instanceFastResult) {
+      for (const [coordKey, fastVS] of Object.entries(instanceFastResult.viewStates)) {
+        instanceViewStates[coordKey] = {
+          ...instanceViewStates[coordKey] || {},
+          ...fastVS
+        };
+      }
+    }
+  }
+  timing?.recordFastRender(Date.now() - fastStart);
   if (renderedFast.kind !== "PhaseOutput") {
     handleOtherResponseCodes(res, renderedFast);
+    timing?.end();
     return;
   }
   let viewState;
@@ -2062,6 +2244,12 @@ async function handleDirectRequest(vite, route, options, slowlyPhase, pageParams
   } else {
     viewState = { ...renderedSlowly.rendered, ...renderedFast.rendered };
   }
+  if (instanceViewStates && Object.keys(instanceViewStates).length > 0) {
+    viewState = {
+      ...viewState,
+      __headlessInstances: instanceViewStates
+    };
+  }
   await sendResponse(
     vite,
     res,
@@ -2073,10 +2261,12 @@ async function handleDirectRequest(vite, route, options, slowlyPhase, pageParams
     clientTrackByMap,
     projectInit,
     pluginsForPage,
-    options
+    options,
+    void 0,
+    timing
   );
 }
-async function sendResponse(vite, res, url, jayHtmlPath, pageParts, viewState, carryForward, clientTrackByMap, projectInit, pluginsForPage, options, slowViewState) {
+async function sendResponse(vite, res, url, jayHtmlPath, pageParts, viewState, carryForward, clientTrackByMap, projectInit, pluginsForPage, options, slowViewState, timing) {
   const pageHtml = generateClientScript(
     viewState,
     carryForward,
@@ -2091,10 +2281,19 @@ async function sendResponse(vite, res, url, jayHtmlPath, pageParts, viewState, c
       slowViewState
     }
   );
+  if (options.buildFolder) {
+    const pageName = !url || url === "/" ? "index" : url.replace(/^\//, "").replace(/\//g, "-");
+    const clientScriptDir = path__default.join(options.buildFolder, "client-scripts");
+    await fs$1.mkdir(clientScriptDir, { recursive: true });
+    await fs$1.writeFile(path__default.join(clientScriptDir, `${pageName}.html`), pageHtml, "utf-8");
+  }
+  const viteStart = Date.now();
   const compiledPageHtml = await vite.transformIndexHtml(!!url ? url : "/", pageHtml);
+  timing?.recordViteClient(Date.now() - viteStart);
   res.status(200).set({ "Content-Type": "text/html" }).send(compiledPageHtml);
+  timing?.end();
 }
-async function preRenderJayHtml(route, slowViewState) {
+async function preRenderJayHtml(route, slowViewState, headlessContracts, headlessInstanceComponents) {
   const jayHtmlContent = await fs$1.readFile(route.jayHtmlPath, "utf-8");
   const contractPath = route.jayHtmlPath.replace(".jay-html", ".jay-contract");
   let contract;
@@ -2104,15 +2303,14 @@ async function preRenderJayHtml(route, slowViewState) {
     if (parseResult.val) {
       contract = parseResult.val;
     } else if (parseResult.validations.length > 0) {
-      console.error(
-        `[SlowRender] Contract parse error for ${contractPath}:`,
-        parseResult.validations
+      getLogger().error(
+        `[SlowRender] Contract parse error for ${contractPath}: ${parseResult.validations.join(", ")}`
       );
       return void 0;
     }
   } catch (error) {
     if (error.code !== "ENOENT") {
-      console.error(`[SlowRender] Error reading contract ${contractPath}:`, error);
+      getLogger().error(`[SlowRender] Error reading contract ${contractPath}: ${error}`);
       return void 0;
     }
   }
@@ -2120,20 +2318,99 @@ async function preRenderJayHtml(route, slowViewState) {
     jayHtmlContent,
     slowViewState,
     contract,
-    sourceDir: path__default.dirname(route.jayHtmlPath)
+    headlessContracts,
+    sourceDir: path__default.dirname(route.jayHtmlPath),
+    importResolver: JAY_IMPORT_RESOLVER
   });
-  if (result.val) {
-    return result.val.preRenderedJayHtml;
+  if (!result.val) {
+    if (result.validations.length > 0) {
+      getLogger().error(
+        `[SlowRender] Transform failed for ${route.jayHtmlPath}: ${result.validations.join(", ")}`
+      );
+    }
+    return void 0;
+  }
+  let preRenderedJayHtml = result.val.preRenderedJayHtml;
+  let instancePhaseData;
+  if (headlessInstanceComponents.length > 0) {
+    const discoveryResult = discoverHeadlessInstances(preRenderedJayHtml);
+    preRenderedJayHtml = discoveryResult.preRenderedJayHtml;
+    if (discoveryResult.instances.length > 0) {
+      const slowResult = await slowRenderInstances(
+        discoveryResult.instances,
+        headlessInstanceComponents
+      );
+      if (slowResult) {
+        instancePhaseData = slowResult.instancePhaseData;
+        const pass2Result = resolveHeadlessInstances(
+          preRenderedJayHtml,
+          slowResult.resolvedData,
+          JAY_IMPORT_RESOLVER
+        );
+        if (pass2Result.val) {
+          preRenderedJayHtml = pass2Result.val;
+        }
+        if (pass2Result.validations.length > 0) {
+          getLogger().error(
+            `[SlowRender] Instance resolution warnings for ${route.jayHtmlPath}: ${pass2Result.validations.join(", ")}`
+          );
+        }
+      }
+    }
   }
-  if (result.validations.length > 0) {
-    console.error(
-      `[SlowRender] Transform failed for ${route.jayHtmlPath}:`,
-      result.validations
+  return { preRenderedJayHtml, instancePhaseData };
+}
+async function renderFastChangingDataForInstances(instancePhaseData, headlessInstanceComponents) {
+  const componentByContractName = /* @__PURE__ */ new Map();
+  for (const comp of headlessInstanceComponents) {
+    componentByContractName.set(comp.contractName, comp);
+  }
+  const viewStates = {};
+  const carryForwards = {};
+  let hasResults = false;
+  for (const instance of instancePhaseData.discovered) {
+    const coordKey = instance.coordinate.join("/");
+    const comp = componentByContractName.get(instance.contractName);
+    if (!comp || !comp.compDefinition.fastRender) {
+      continue;
+    }
+    const instanceCarryForward = instancePhaseData.carryForwards[coordKey] || {};
+    const services = resolveServices(comp.compDefinition.services);
+    const fastResult = await comp.compDefinition.fastRender(
+      instance.props,
+      instanceCarryForward,
+      ...services
     );
+    if (fastResult.kind === "PhaseOutput") {
+      viewStates[coordKey] = fastResult.rendered;
+      carryForwards[coordKey] = fastResult.carryForward;
+      hasResults = true;
+    }
+  }
+  return hasResults ? { viewStates, carryForwards } : void 0;
+}
+async function materializeDynamicContracts(projectRootFolder, buildFolder, viteServer) {
+  try {
+    const services = getServiceRegistry();
+    const result = await materializeContracts(
+      {
+        projectRoot: projectRootFolder,
+        outputDir: path__default.join(buildFolder, "materialized-contracts"),
+        verbose: false,
+        viteServer
+      },
+      services
+    );
+    const dynamicCount = result.dynamicCount;
+    if (dynamicCount > 0) {
+      getLogger().info(`[Contracts] Materialized ${dynamicCount} dynamic contract(s)`);
+    }
+  } catch (error) {
+    getLogger().warn(`[Contracts] Failed to materialize dynamic contracts: ${error.message}`);
   }
-  return void 0;
 }
-async function mkDevServer(options) {
+async function mkDevServer(rawOptions) {
+  const options = defaults(rawOptions);
   const {
     publicBaseUrlPath,
     pagesRootFolder,
@@ -2141,23 +2418,20 @@ async function mkDevServer(options) {
     buildFolder,
     jayRollupConfig,
     dontCacheSlowly
-  } = defaults(options);
+  } = options;
+  const viteLogLevel = options.logLevel === "silent" ? "silent" : options.logLevel === "verbose" ? "info" : "warn";
   const lifecycleManager = new ServiceLifecycleManager(projectRootFolder);
   setupGracefulShutdown(lifecycleManager);
-  const vite = await createServer({
-    server: { middlewareMode: true },
-    plugins: [...jayStackCompiler(jayRollupConfig)],
-    appType: "custom",
+  const vite = await createViteServer({
+    projectRoot: projectRootFolder,
+    pagesRoot: pagesRootFolder,
     base: publicBaseUrlPath,
-    root: pagesRootFolder,
-    ssr: {
-      // Mark stack-server-runtime as external so Vite uses Node's require
-      // This ensures lib/init.ts and dev-server share the same module instance
-      external: ["@jay-framework/stack-server-runtime"]
-    }
+    jayRollupConfig,
+    logLevel: viteLogLevel
   });
   lifecycleManager.setViteServer(vite);
   await lifecycleManager.initialize();
+  await materializeDynamicContracts(projectRootFolder, buildFolder, vite);
   setupServiceHotReload(vite, lifecycleManager);
   setupActionRouter(vite);
   const routes = await initRoutes(pagesRootFolder);
@@ -2189,7 +2463,7 @@ async function mkDevServer(options) {
 }
 function setupGracefulShutdown(lifecycleManager) {
   const shutdown = async (signal) => {
-    console.log(`
+    getLogger().important(`
 ${signal} received, shutting down gracefully...`);
     await lifecycleManager.shutdown();
     process.exit(0);
@@ -2205,7 +2479,7 @@ function setupServiceHotReload(vite, lifecycleManager) {
   vite.watcher.add(initFilePath);
   vite.watcher.on("change", async (changedPath) => {
     if (changedPath === initFilePath) {
-      console.log("[Services] lib/init.ts changed, reloading services...");
+      getLogger().info("[Services] lib/init.ts changed, reloading services...");
       try {
         await lifecycleManager.reload();
         vite.ws.send({
@@ -2213,7 +2487,7 @@ function setupServiceHotReload(vite, lifecycleManager) {
           path: "*"
         });
       } catch (error) {
-        console.error("[Services] Failed to reload services:", error);
+        getLogger().error(`[Services] Failed to reload services: ${error}`);
       }
     }
   });
@@ -2221,7 +2495,7 @@ function setupServiceHotReload(vite, lifecycleManager) {
 function setupActionRouter(vite) {
   vite.middlewares.use(actionBodyParser());
   vite.middlewares.use(ACTION_ENDPOINT_BASE, createActionRouter());
-  console.log(`[Actions] Action router mounted at ${ACTION_ENDPOINT_BASE}`);
+  getLogger().info(`[Actions] Action router mounted at ${ACTION_ENDPOINT_BASE}`);
 }
 function setupSlowRenderCacheInvalidation(vite, cache, pagesRootFolder) {
   vite.watcher.on("change", (changedPath) => {
@@ -2230,7 +2504,7 @@ function setupSlowRenderCacheInvalidation(vite, cache, pagesRootFolder) {
     }
     if (changedPath.endsWith(".jay-html")) {
       cache.invalidate(changedPath).then(() => {
-        console.log(`[SlowRender] Cache invalidated for ${changedPath}`);
+        getLogger().info(`[SlowRender] Cache invalidated for ${changedPath}`);
       });
       return;
     }
@@ -2238,14 +2512,18 @@ function setupSlowRenderCacheInvalidation(vite, cache, pagesRootFolder) {
       const dir = path__default.dirname(changedPath);
       const jayHtmlPath = path__default.join(dir, "page.jay-html");
       cache.invalidate(jayHtmlPath).then(() => {
-        console.log(`[SlowRender] Cache invalidated for ${jayHtmlPath} (page.ts changed)`);
+        getLogger().info(
+          `[SlowRender] Cache invalidated for ${jayHtmlPath} (page.ts changed)`
+        );
       });
       return;
     }
     if (changedPath.endsWith(".jay-contract")) {
       const jayHtmlPath = changedPath.replace(".jay-contract", ".jay-html");
       cache.invalidate(jayHtmlPath).then(() => {
-        console.log(`[SlowRender] Cache invalidated for ${jayHtmlPath} (contract changed)`);
+        getLogger().info(
+          `[SlowRender] Cache invalidated for ${jayHtmlPath} (contract changed)`
+        );
       });
       return;
     }
@@ -2255,5 +2533,7 @@ export {
   ACTION_ENDPOINT_BASE,
   actionBodyParser,
   createActionRouter,
+  createViteForCli,
+  createViteServer,
   mkDevServer
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/dev-server",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "type": "module",
   "license": "Apache-2.0",
   "main": "dist/index.js",
@@ -22,21 +22,22 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@jay-framework/compiler-jay-stack": "^0.11.0",
-    "@jay-framework/compiler-shared": "^0.11.0",
-    "@jay-framework/component": "^0.11.0",
-    "@jay-framework/fullstack-component": "^0.11.0",
-    "@jay-framework/runtime": "^0.11.0",
-    "@jay-framework/stack-client-runtime": "^0.11.0",
-    "@jay-framework/stack-route-scanner": "^0.11.0",
-    "@jay-framework/stack-server-runtime": "^0.11.0",
-    "@jay-framework/view-state-merge": "^0.11.0",
+    "@jay-framework/compiler-jay-stack": "^0.12.0",
+    "@jay-framework/compiler-shared": "^0.12.0",
+    "@jay-framework/component": "^0.12.0",
+    "@jay-framework/fullstack-component": "^0.12.0",
+    "@jay-framework/logger": "^0.12.0",
+    "@jay-framework/runtime": "^0.12.0",
+    "@jay-framework/stack-client-runtime": "^0.12.0",
+    "@jay-framework/stack-route-scanner": "^0.12.0",
+    "@jay-framework/stack-server-runtime": "^0.12.0",
+    "@jay-framework/view-state-merge": "^0.12.0",
     "vite": "^5.0.11"
   },
   "devDependencies": {
-    "@jay-framework/dev-environment": "^0.11.0",
-    "@jay-framework/jay-cli": "^0.11.0",
-    "@jay-framework/stack-client-runtime": "^0.11.0",
+    "@jay-framework/dev-environment": "^0.12.0",
+    "@jay-framework/jay-cli": "^0.12.0",
+    "@jay-framework/stack-client-runtime": "^0.12.0",
     "@types/express": "^5.0.2",
     "@types/node": "^22.15.21",
     "nodemon": "^3.0.3",