@jay-framework/dev-server 0.15.5 → 0.16.0

package/dist/index.d.ts

@@ -5,6 +5,7 @@ import { JayRollupConfig } from '@jay-framework/rollup-plugin';
 import { LogLevel } from '@jay-framework/logger';
 import { Server } from 'node:http';
 import { ProjectClientInitInfo, PluginWithInit, ActionRegistry } from '@jay-framework/stack-server-runtime';
+import * as _jay_framework_fullstack_component from '@jay-framework/fullstack-component';
 import { RequestHandler as RequestHandler$1 } from 'express';
 import { JayRollupConfig as JayRollupConfig$1 } from '@jay-framework/compiler-jay-stack';
 
@@ -103,6 +104,62 @@ declare class ServiceLifecycleManager {
     isReady(): boolean;
 }
 
+/**
+ * Page Freeze — Design Log #127
+ *
+ * Captures a page's ViewState at a point in time and serves it as a
+ * static SSR snapshot. Enables designers to create multiple frozen
+ * views of a page in different states for side-by-side comparison.
+ */
+interface FreezeEntry {
+    id: string;
+    name?: string;
+    /** The concrete URL path (e.g., /products/kitan) */
+    route: string;
+    /** The route pattern (e.g., /products/kitan{/:category}) */
+    routePattern?: string;
+    viewState: object;
+    createdAt: string;
+}
+declare class FreezeStore {
+    private readonly dir;
+    constructor(buildFolder: string);
+    save(route: string, viewState: object, routePattern?: string): Promise<FreezeEntry>;
+    get(id: string): Promise<FreezeEntry | undefined>;
+    list(route?: string): Promise<FreezeEntry[]>;
+    rename(id: string, name: string): Promise<boolean>;
+    delete(id: string): Promise<boolean>;
+}
+
+/**
+ * Service marker for DevServerService.
+ * Use with `.withServices(DEV_SERVER_SERVICE)` in actions and components.
+ */
+declare const DEV_SERVER_SERVICE: _jay_framework_fullstack_component.ServiceMarker<DevServerService>;
+interface RouteInfo {
+    path: string;
+    jayHtmlPath: string;
+    compPath: string;
+}
+declare class DevServerService {
+    private routes;
+    private vite;
+    private pagesBase;
+    private projectBase;
+    private jayRollupConfig;
+    private _freezeStore?;
+    constructor(routes: DevServerRoute[], vite: ViteDevServer, pagesBase: string, projectBase: string, jayRollupConfig: JayRollupConfig, _freezeStore?: FreezeStore);
+    get freezeStore(): FreezeStore | undefined;
+    /** List all page routes in the project. */
+    listRoutes(): RouteInfo[];
+    /**
+     * Run loadParams for a route, yielding param batches as an async generator.
+     * Loads all page parts (page component + keyed headless components) and
+     * calls loadParams on each one that defines it.
+     */
+    loadRouteParams(routePath: string): AsyncGenerator<Record<string, string>[]>;
+}
+
 interface DevServerRoute {
     path: string;
     handler: RequestHandler;
@@ -113,6 +170,9 @@ interface DevServer {
     viteServer: ViteDevServer;
     routes: DevServerRoute[];
     lifecycleManager: ServiceLifecycleManager;
+    freezeStore?: FreezeStore;
+    /** Public API for design board applications and CLI (DL#128) */
+    service: DevServerService;
 }
 declare function mkDevServer(rawOptions: DevServerOptions): Promise<DevServer>;
 
@@ -207,4 +267,4 @@ declare function createViteForCli(options: {
     tsConfigFilePath?: string;
 }): Promise<ViteDevServer>;
 
-export { ACTION_ENDPOINT_BASE, type ActionRouterOptions, type CreateViteServerOptions, type DevServer, type DevServerOptions, type DevServerRoute, actionBodyParser, createActionRouter, createViteForCli, createViteServer, mkDevServer };
+export { ACTION_ENDPOINT_BASE, type ActionRouterOptions, type CreateViteServerOptions, DEV_SERVER_SERVICE, type DevServer, type DevServerOptions, type DevServerRoute, DevServerService, type FreezeEntry, FreezeStore, type RouteInfo, actionBodyParser, createActionRouter, createViteForCli, createViteServer, mkDevServer };

package/dist/index.js

@@ -10,14 +10,18 @@ import { createRequire } from "module";
 import "@jay-framework/compiler-shared";
 import * as path from "node:path";
 import path__default from "node:path";
-import { JAY_IMPORT_RESOLVER, injectHeadfullFSTemplates, parseContract, slowRenderTransform, discoverHeadlessInstances, resolveHeadlessInstances } from "@jay-framework/compiler-jay-html";
+import { JAY_IMPORT_RESOLVER, injectHeadfullFSTemplates, parseContract, slowRenderTransform, discoverHeadlessInstances, assignCoordinatesToJayHtml, 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, clearServerElementCache, getServiceRegistry, materializeContracts, loadPageParts, renderFastChangingData, generateClientScript, getClientInitData, generateSSRPageHtml, validateForEachInstances, slowRenderInstances } from "@jay-framework/stack-server-runtime";
-import fs$1 from "node:fs/promises";
+import fs__default$1 from "node:fs";
+import { scanRoutes, createRoute, routeToExpressRoute } from "@jay-framework/stack-route-scanner";
+import { discoverPluginsWithInit, sortPluginsByDependencies, executePluginServerInits, runInitCallbacks, actionRegistry, discoverAndRegisterActions, discoverAllPluginActions, runShutdownCallbacks, clearLifecycleCallbacks, clearServiceRegistry, clearClientInitData, loadPageParts, runLoadParams, DevSlowlyChangingPhase, SlowRenderCache, preparePluginClientInits, registerService, clearServerElementCache, scanPlugins, getServiceRegistry, materializeContracts, renderFastChangingData, mergeHeadTags, generateClientScript, getClientInitData, generateSSRPageHtml, generateFrozenPageHtml, validateForEachInstances, slowRenderInstances } from "@jay-framework/stack-server-runtime";
+import * as fs$1 from "node:fs/promises";
+import fs__default from "node:fs/promises";
 import { pathToFileURL } from "node:url";
+import { randomUUID } from "node:crypto";
+import { createJayService } from "@jay-framework/fullstack-component";
 const s$1 = createRequire(import.meta.url), e$1 = s$1("typescript"), c$1 = new Proxy(e$1, {
   get(t, r) {
     return t[r];
@@ -927,9 +931,16 @@ function extractActionFromExpression(node) {
     }
     if (c$1.isIdentifier(expr)) {
       const funcName = expr.text;
-      if (funcName === "makeJayAction" || funcName === "makeJayQuery") {
+      if (funcName === "makeJayAction" || funcName === "makeJayQuery" || funcName === "makeJayStream") {
         const nameArg = current.arguments[0];
         if (nameArg && c$1.isStringLiteral(nameArg)) {
+          if (funcName === "makeJayStream") {
+            return {
+              actionName: nameArg.text,
+              method: "POST",
+              isStreaming: true
+            };
+          }
           method = funcName === "makeJayQuery" ? "GET" : "POST";
           if (explicitMethod) {
             method = explicitMethod;
@@ -1200,7 +1211,7 @@ function createPluginClientImportResolver(options = {}) {
   const pluginDetector = options.pluginDetector || createDefaultPluginDetector();
   return {
     name: "jay-stack:plugin-client-import",
-    enforce: "pre",
+    enforce: "post",
     configResolved(config) {
       projectRoot = config.root || projectRoot;
       isSSRBuild = !!config.build?.ssr;
@@ -1331,14 +1342,27 @@ function jayStackCompiler(options = {}) {
             getLogger().warn(`[action-transform] No actions found in ${actualPath}`);
             return null;
           }
+          const hasRegularActions = actions.some((a) => !a.isStreaming);
+          const hasStreamActions = actions.some((a) => a.isStreaming);
+          const importNames = [];
+          if (hasRegularActions)
+            importNames.push("createActionCaller");
+          if (hasStreamActions)
+            importNames.push("createStreamCaller");
           const lines = [
-            `import { createActionCaller } from '@jay-framework/stack-client-runtime';`,
+            `import { ${importNames.join(", ")} } from '@jay-framework/stack-client-runtime';`,
             ""
           ];
           for (const action of actions) {
-            lines.push(
-              `export const ${action.exportName} = createActionCaller('${action.actionName}', '${action.method}');`
-            );
+            if (action.isStreaming) {
+              lines.push(
+                `export const ${action.exportName} = createStreamCaller('${action.actionName}');`
+              );
+            } else {
+              lines.push(
+                `export const ${action.exportName} = createActionCaller('${action.actionName}', '${action.method}');`
+              );
+            }
           }
           if (code.includes("ActionError")) {
             lines.push(
@@ -1758,6 +1782,22 @@ function createActionRouter(options) {
       requestMethod,
       ACTION_ENDPOINT_BASE + "/" + actionName
     );
+    if (registry.isStreaming(actionName)) {
+      res.setHeader("Content-Type", "application/x-ndjson");
+      res.setHeader("Transfer-Encoding", "chunked");
+      try {
+        const generator = registry.executeStream(actionName, input);
+        for await (const chunk of generator) {
+          res.write(JSON.stringify({ chunk }) + "\n");
+        }
+        res.write(JSON.stringify({ done: true }) + "\n");
+      } catch (err) {
+        res.write(JSON.stringify({ error: err.message }) + "\n");
+      }
+      res.end();
+      timing?.end();
+      return;
+    }
     const result = await registry.execute(actionName, input);
     if (requestMethod === "GET" && result.success) {
       const cacheHeaders = registry.getCacheHeaders(actionName);
@@ -1831,12 +1871,208 @@ function actionBodyParser() {
     });
   };
 }
+class FreezeStore {
+  constructor(buildFolder) {
+    __publicField(this, "dir");
+    this.dir = path.join(buildFolder, "freezes");
+  }
+  async save(route, viewState, routePattern) {
+    await fs$1.mkdir(this.dir, { recursive: true });
+    const entry = {
+      id: randomUUID().slice(0, 8),
+      route,
+      ...routePattern && { routePattern },
+      viewState,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    await fs$1.writeFile(
+      path.join(this.dir, `${entry.id}.json`),
+      JSON.stringify(entry, null, 2),
+      "utf-8"
+    );
+    return entry;
+  }
+  async get(id) {
+    try {
+      const content = await fs$1.readFile(path.join(this.dir, `${id}.json`), "utf-8");
+      return JSON.parse(content);
+    } catch {
+      return void 0;
+    }
+  }
+  async list(route) {
+    try {
+      const files = await fs$1.readdir(this.dir);
+      const entries = [];
+      for (const file of files) {
+        if (!file.endsWith(".json"))
+          continue;
+        try {
+          const content = await fs$1.readFile(path.join(this.dir, file), "utf-8");
+          const entry = JSON.parse(content);
+          if (!route || entry.routePattern === route || entry.route === route) {
+            entries.push(entry);
+          }
+        } catch {
+        }
+      }
+      return entries.sort(
+        (a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime()
+      );
+    } catch {
+      return [];
+    }
+  }
+  async rename(id, name) {
+    const entry = await this.get(id);
+    if (!entry)
+      return false;
+    entry.name = name;
+    await fs$1.writeFile(
+      path.join(this.dir, `${id}.json`),
+      JSON.stringify(entry, null, 2),
+      "utf-8"
+    );
+    return true;
+  }
+  async delete(id) {
+    try {
+      await fs$1.unlink(path.join(this.dir, `${id}.json`));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+const DEV_SERVER_SERVICE = createJayService("DevServerService");
+class DevServerService {
+  constructor(routes, vite, pagesBase, projectBase, jayRollupConfig, _freezeStore) {
+    this.routes = routes;
+    this.vite = vite;
+    this.pagesBase = pagesBase;
+    this.projectBase = projectBase;
+    this.jayRollupConfig = jayRollupConfig;
+    this._freezeStore = _freezeStore;
+  }
+  get freezeStore() {
+    return this._freezeStore;
+  }
+  /** List all page routes in the project. */
+  listRoutes() {
+    return this.routes.map((r) => ({
+      path: r.path,
+      jayHtmlPath: r.fsRoute.jayHtmlPath,
+      compPath: r.fsRoute.compPath
+    }));
+  }
+  /**
+   * Run loadParams for a route, yielding param batches as an async generator.
+   * Loads all page parts (page component + keyed headless components) and
+   * calls loadParams on each one that defines it.
+   */
+  async *loadRouteParams(routePath) {
+    const matched = this.routes.find((r) => r.path === routePath);
+    if (!matched) {
+      getLogger().error(`[loadRouteParams] Route [${routePath}] not found`);
+      throw new Error(`Route "${routePath}" not found`);
+    }
+    const loaded = await loadPageParts(
+      this.vite,
+      matched.fsRoute,
+      this.pagesBase,
+      this.projectBase,
+      this.jayRollupConfig
+    );
+    if (!loaded.val) {
+      return;
+    }
+    yield* runLoadParams(loaded.val.parts);
+  }
+}
+let _watchLinkedFiles = () => {
+};
 async function initRoutes(pagesBaseFolder) {
   return await scanRoutes(pagesBaseFolder, {
     jayHtmlFilename: "page.jay-html",
     compFilename: "page.ts"
   });
 }
+async function scanPluginRoutes(projectRoot, projectRoutes) {
+  const plugins = await scanPlugins({ projectRoot, includeDevDeps: true });
+  const projectPaths = new Set(projectRoutes.map((r) => r.rawRoute));
+  const pluginRoutes = [];
+  for (const [, plugin] of plugins) {
+    if (!plugin.manifest.routes)
+      continue;
+    for (const route of plugin.manifest.routes) {
+      if (projectPaths.has(route.path)) {
+        getLogger().info(
+          `[Routes] Plugin "${plugin.name}" route ${route.path} skipped — project route takes precedence`
+        );
+        continue;
+      }
+      const jayHtmlPath = resolvePluginExport(plugin.pluginPath, route.jayHtml);
+      if (!jayHtmlPath) {
+        getLogger().warn(
+          `[Routes] Plugin "${plugin.name}" route ${route.path}: jayHtml "${route.jayHtml}" not found`
+        );
+        continue;
+      }
+      const compPath = route.component.startsWith(".") ? path__default.resolve(plugin.pluginPath, route.component) : resolvePluginModule(plugin);
+      pluginRoutes.push(createRoute(route.path, jayHtmlPath, compPath));
+      getLogger().info(`[Routes] Plugin "${plugin.name}" provides route ${route.path}`);
+    }
+  }
+  return pluginRoutes;
+}
+function resolvePluginExport(pluginPath, exportSubpath) {
+  const normalized = exportSubpath.replace(/^\.\//, "");
+  const packageJsonPath = path__default.join(pluginPath, "package.json");
+  try {
+    const packageJson = JSON.parse(fs__default$1.readFileSync(packageJsonPath, "utf-8"));
+    if (packageJson.exports) {
+      const exportKey = "./" + normalized;
+      const exportValue = packageJson.exports[exportKey];
+      if (exportValue) {
+        const resolved = typeof exportValue === "string" ? exportValue : exportValue.default || exportValue.import || exportValue.require;
+        if (resolved) {
+          const fullPath = path__default.join(pluginPath, resolved);
+          return fullPath;
+        }
+      }
+    }
+  } catch {
+  }
+  for (const dir of ["dist", "lib", ""]) {
+    const candidate = path__default.join(pluginPath, dir, normalized);
+    try {
+      fs__default$1.accessSync(candidate);
+      return candidate;
+    } catch {
+    }
+  }
+  return void 0;
+}
+function resolvePluginModule(plugin) {
+  const modulePath = plugin.manifest.module || "index";
+  for (const ext of [".ts", ".js", "/index.ts", "/index.js"]) {
+    const candidate = path__default.join(plugin.pluginPath, modulePath + ext);
+    try {
+      fs__default$1.accessSync(candidate);
+      return candidate;
+    } catch {
+    }
+  }
+  for (const ext of [".ts", ".js"]) {
+    const candidate = path__default.join(plugin.pluginPath, "lib", path__default.basename(modulePath) + ext);
+    try {
+      fs__default$1.accessSync(candidate);
+      return candidate;
+    } catch {
+    }
+  }
+  return path__default.join(plugin.pluginPath, modulePath);
+}
 function defaults(options) {
   const publicBaseUrlPath = options.publicBaseUrlPath || process.env.BASE || "/";
   const projectRootFolder = options.projectRootFolder || ".";
@@ -1854,7 +2090,9 @@ function defaults(options) {
     disableSSR: options.disableSSR,
     jayRollupConfig: {
       ...options.jayRollupConfig || {},
-      tsConfigFilePath
+      tsConfigFilePath,
+      pagesRoot: pagesRootFolder,
+      buildFolder
     },
     httpServer: options.httpServer
   };
@@ -1896,7 +2134,7 @@ function filterPluginsForPage(allPluginClientInits, allPluginsWithInit, usedPack
     return pluginInfo && expandedPackages.has(pluginInfo.packageName);
   });
 }
-function mkRoute(route, vite, slowlyPhase, options, slowRenderCache, projectInit, allPluginsWithInit = [], allPluginClientInits = []) {
+function mkRoute(route, vite, slowlyPhase, options, slowRenderCache, freezeStore, projectInit, allPluginsWithInit = [], allPluginClientInits = []) {
   const routePath = routeToExpressRoute(route);
   const handler = async (req, res) => {
     const timing = getDevLogger()?.startRequest(req.method, req.path);
@@ -1912,6 +2150,23 @@ function mkRoute(route, vite, slowlyPhase, options, slowRenderCache, projectInit
       for (const [key, value] of urlObj.searchParams) {
         query[key] = value;
       }
+      const freezeId = query["_jay_freeze"];
+      if (freezeId && freezeStore) {
+        timing?.annotate("[FROZEN]");
+        await handleFrozenRequest(
+          vite,
+          route,
+          options,
+          freezeStore,
+          slowRenderCache,
+          freezeId,
+          pageParams,
+          query["format"] === "fragment" ? "fragment" : "page",
+          res,
+          timing
+        );
+        return;
+      }
       if (options.disableSSR) {
         await handleClientOnlyRequest(
           vite,
@@ -1994,7 +2249,14 @@ async function handleCachedRequest(vite, route, options, cachedEntry, pageParams
     timing?.end();
     return;
   }
-  const { parts: pageParts, clientTrackByMap, usedPackages } = pagePartsResult.val;
+  const {
+    parts: pageParts,
+    clientTrackByMap,
+    usedPackages,
+    linkedCssFiles,
+    linkedComponentFiles
+  } = pagePartsResult.val;
+  _watchLinkedFiles([...linkedCssFiles || [], ...linkedComponentFiles || []]);
   const pluginsForPage = filterPluginsForPage(
     allPluginClientInits,
     allPluginsWithInit,
@@ -2023,6 +2285,7 @@ async function handleCachedRequest(vite, route, options, cachedEntry, pageParams
   }
   const fastViewState = renderedFast.rendered;
   const fastCarryForward = renderedFast.carryForward;
+  const headTags = renderedFast.headTags ?? mergeHeadTags(cachedEntry.carryForward?.__slowHeadTags ?? []);
   await sendResponse(
     vite,
     res,
@@ -2036,9 +2299,11 @@ async function handleCachedRequest(vite, route, options, cachedEntry, pageParams
     projectInit,
     pluginsForPage,
     options,
+    routeToExpressRoute(route),
     cachedEntry.slowViewState,
     timing,
-    cachedEntry.preRenderedContent
+    cachedEntry.preRenderedContent,
+    headTags
   );
 }
 async function handlePreRenderRequest(vite, route, options, slowlyPhase, slowRenderCache, pageParams, pageProps, allPluginClientInits, allPluginsWithInit, projectInit, res, url, timing, query = {}) {
@@ -2057,6 +2322,8 @@ async function handlePreRenderRequest(vite, route, options, slowlyPhase, slowRen
     timing?.end();
     return;
   }
+  const { linkedCssFiles: initCss, linkedComponentFiles: initComps } = initialPartsResult.val;
+  _watchLinkedFiles([...initCss || [], ...initComps || []]);
   const slowStart = Date.now();
   const renderedSlowly = await slowlyPhase.runSlowlyForPage(
     pageParams,
@@ -2149,8 +2416,11 @@ async function handleClientOnlyRequest(vite, route, options, slowlyPhase, pagePa
     usedPackages,
     headlessInstanceComponents,
     discoveredInstances,
-    forEachInstances
+    forEachInstances,
+    linkedCssFiles,
+    linkedComponentFiles
   } = pagePartsResult.val;
+  _watchLinkedFiles([...linkedCssFiles || [], ...linkedComponentFiles || []]);
   const pluginsForPage = filterPluginsForPage(
     allPluginClientInits,
     allPluginsWithInit,
@@ -2209,14 +2479,15 @@ async function handleClientOnlyRequest(vite, route, options, slowlyPhase, pagePa
     projectInit,
     pluginsForPage,
     {
-      enableAutomation: !options.disableAutomation
+      enableAutomation: !options.disableAutomation,
+      routePattern: routeToExpressRoute(route)
     }
   );
   if (options.buildFolder) {
     const pageName = !url || url === "/" ? "index" : url.replace(/^\//, "").replace(/\//g, "-");
     const clientScriptDir = path__default.join(options.buildFolder, "debug", "client-entry");
-    await fs$1.mkdir(clientScriptDir, { recursive: true });
-    await fs$1.writeFile(path__default.join(clientScriptDir, `${pageName}.html`), pageHtml, "utf-8");
+    await fs__default.mkdir(clientScriptDir, { recursive: true });
+    await fs__default.writeFile(path__default.join(clientScriptDir, `${pageName}.html`), pageHtml, "utf-8");
   }
   const viteStart = Date.now();
   const compiledPageHtml = await vite.transformIndexHtml(!!url ? url : "/", pageHtml);
@@ -2224,11 +2495,11 @@ async function handleClientOnlyRequest(vite, route, options, slowlyPhase, pagePa
   res.status(200).set({ "Content-Type": "text/html" }).send(compiledPageHtml);
   timing?.end();
 }
-async function sendResponse(vite, res, url, jayHtmlPath, sourceJayHtmlPath, pageParts, viewState, carryForward, clientTrackByMap, projectInit, pluginsForPage, options, slowViewState, timing, preLoadedContent) {
+async function sendResponse(vite, res, url, jayHtmlPath, sourceJayHtmlPath, pageParts, viewState, carryForward, clientTrackByMap, projectInit, pluginsForPage, options, routePattern, slowViewState, timing, preLoadedContent, headTags) {
   let pageHtml;
   const routeDir = path__default.dirname(path__default.relative(options.pagesRootFolder, sourceJayHtmlPath));
   try {
-    let jayHtmlContent = preLoadedContent ?? await fs$1.readFile(jayHtmlPath, "utf-8");
+    let jayHtmlContent = preLoadedContent ?? await fs__default.readFile(jayHtmlPath, "utf-8");
     const jayHtmlFilename = path__default.basename(jayHtmlPath);
     const jayHtmlDir = path__default.dirname(jayHtmlPath);
     const sourceDir = path__default.dirname(sourceJayHtmlPath);
@@ -2252,8 +2523,12 @@ async function sendResponse(vite, res, url, jayHtmlPath, sourceJayHtmlPath, page
       pluginsForPage,
       {
         enableAutomation: !options.disableAutomation,
-        slowViewState
-      }
+        slowViewState,
+        routePattern
+      },
+      // Pass source directory for headfull FS file resolution when using pre-rendered path
+      jayHtmlDir !== sourceDir ? sourceDir : void 0,
+      headTags
     );
   } catch (err) {
     getLogger().warn(`[SSR] Failed, falling back to client rendering: ${err.message}`);
@@ -2268,15 +2543,16 @@ async function sendResponse(vite, res, url, jayHtmlPath, sourceJayHtmlPath, page
       pluginsForPage,
       {
         enableAutomation: !options.disableAutomation,
-        slowViewState
+        slowViewState,
+        routePattern
       }
     );
   }
   if (options.buildFolder) {
     const pageName = !url || url === "/" ? "index" : url.replace(/^\//, "").replace(/\//g, "-");
     const clientScriptDir = path__default.join(options.buildFolder, "debug", "client-entry");
-    await fs$1.mkdir(clientScriptDir, { recursive: true });
-    await fs$1.writeFile(path__default.join(clientScriptDir, `${pageName}.html`), pageHtml, "utf-8");
+    await fs__default.mkdir(clientScriptDir, { recursive: true });
+    await fs__default.writeFile(path__default.join(clientScriptDir, `${pageName}.html`), pageHtml, "utf-8");
   }
   const viteStart = Date.now();
   const compiledPageHtml = await vite.transformIndexHtml(!!url ? url : "/", pageHtml);
@@ -2284,12 +2560,62 @@ async function sendResponse(vite, res, url, jayHtmlPath, sourceJayHtmlPath, page
   res.status(200).set({ "Content-Type": "text/html" }).send(compiledPageHtml);
   timing?.end();
 }
+async function handleFrozenRequest(vite, route, options, freezeStore, slowRenderCache, freezeId, pageParams, format, res, timing) {
+  const entry = await freezeStore.get(freezeId);
+  if (!entry) {
+    getLogger().warn(`[Freeze] Freeze "${freezeId}" not found`);
+    res.status(404).send(`Freeze "${freezeId}" not found`);
+    timing?.end();
+    return;
+  }
+  const label = entry.name ? `"${entry.name}" (${freezeId})` : freezeId;
+  getLogger().info(`[Freeze] Serving frozen page ${label} for ${route.rawRoute} [${format}]`);
+  try {
+    const cachedEntry = await slowRenderCache.get(route.jayHtmlPath, pageParams);
+    const jayHtmlPath = cachedEntry?.preRenderedPath ?? route.jayHtmlPath;
+    const jayHtmlContent = cachedEntry?.preRenderedContent ?? await fs__default.readFile(jayHtmlPath, "utf-8");
+    const jayHtmlFilename = path__default.basename(jayHtmlPath);
+    const jayHtmlDir = path__default.dirname(jayHtmlPath);
+    const sourceDir = path__default.dirname(route.jayHtmlPath);
+    const routeDir = path__default.dirname(path__default.relative(options.pagesRootFolder, route.jayHtmlPath));
+    const { injectHeadfullFSTemplates: injectHeadfullFSTemplates2 } = await import("@jay-framework/compiler-jay-html");
+    const { JAY_IMPORT_RESOLVER: JAY_IMPORT_RESOLVER2 } = await import("@jay-framework/compiler-jay-html");
+    const fullJayHtml = injectHeadfullFSTemplates2(
+      jayHtmlContent,
+      sourceDir,
+      JAY_IMPORT_RESOLVER2
+    );
+    const html = await generateFrozenPageHtml(
+      vite,
+      fullJayHtml,
+      jayHtmlFilename,
+      jayHtmlDir,
+      entry.viewState,
+      options.buildFolder,
+      options.projectRootFolder,
+      routeDir,
+      options.jayRollupConfig?.tsConfigFilePath,
+      void 0,
+      format,
+      entry.name
+    );
+    const headers = { "Content-Type": "text/html" };
+    if (format === "fragment") {
+      headers["Access-Control-Allow-Origin"] = "*";
+    }
+    res.status(200).set(headers).send(html);
+  } catch (err) {
+    getLogger().warn(`[Freeze] Failed to render frozen page: ${err.message}`);
+    res.status(500).send(`Failed to render frozen page: ${err.message}`);
+  }
+  timing?.end();
+}
 async function preRenderJayHtml(route, slowViewState, headlessContracts, headlessInstanceComponents, partKeys = []) {
-  const jayHtmlContent = await fs$1.readFile(route.jayHtmlPath, "utf-8");
+  const jayHtmlContent = await fs__default.readFile(route.jayHtmlPath, "utf-8");
   const contractPath = route.jayHtmlPath.replace(".jay-html", ".jay-contract");
   let contract;
   try {
-    const contractContent = await fs$1.readFile(contractPath, "utf-8");
+    const contractContent = await fs__default.readFile(contractPath, "utf-8");
     const parseResult = parseContract(contractContent, path__default.basename(contractPath));
     if (parseResult.val) {
       contract = parseResult.val;
@@ -2338,10 +2664,15 @@ async function preRenderJayHtml(route, slowViewState, headlessContracts, headles
   let forEachInstances;
   if (headlessInstanceComponents.length > 0) {
     const discoveryResult = discoverHeadlessInstances(preRenderedJayHtml);
-    preRenderedJayHtml = discoveryResult.preRenderedJayHtml;
-    if (discoveryResult.forEachInstances.length > 0) {
+    const htmlWithRefs = discoveryResult.preRenderedJayHtml;
+    const headlessContractNameSet = new Set(
+      headlessInstanceComponents.map((c2) => c2.contractName)
+    );
+    preRenderedJayHtml = assignCoordinatesToJayHtml(htmlWithRefs, headlessContractNameSet);
+    const finalDiscovery = discoverHeadlessInstances(preRenderedJayHtml);
+    if (finalDiscovery.forEachInstances.length > 0) {
       const validationErrors = validateForEachInstances(
-        discoveryResult.forEachInstances,
+        finalDiscovery.forEachInstances,
         headlessInstanceComponents
       );
       if (validationErrors.length > 0) {
@@ -2350,11 +2681,11 @@ async function preRenderJayHtml(route, slowViewState, headlessContracts, headles
         );
         return void 0;
       }
-      forEachInstances = discoveryResult.forEachInstances;
+      forEachInstances = finalDiscovery.forEachInstances;
     }
-    if (discoveryResult.instances.length > 0) {
+    if (finalDiscovery.instances.length > 0) {
       const slowResult = await slowRenderInstances(
-        discoveryResult.instances,
+        finalDiscovery.instances,
         headlessInstanceComponents
       );
       if (slowResult) {
@@ -2426,8 +2757,15 @@ async function mkDevServer(rawOptions) {
   const options = defaults(rawOptions);
   const { publicBaseUrlPath, pagesRootFolder, projectRootFolder, buildFolder, jayRollupConfig } = options;
   if (buildFolder) {
-    await fs$1.rm(buildFolder, { recursive: true, force: true }).catch(() => {
-    });
+    try {
+      const entries = await fs__default.readdir(buildFolder).catch(() => []);
+      for (const entry of entries) {
+        if (entry === "freezes")
+          continue;
+        await fs__default.rm(path__default.join(buildFolder, entry), { recursive: true, force: true });
+      }
+    } catch {
+    }
   }
   const viteLogLevel = options.logLevel === "silent" ? "silent" : options.logLevel === "verbose" ? "info" : "warn";
   const lifecycleManager = new ServiceLifecycleManager(projectRootFolder);
@@ -2445,15 +2783,25 @@ async function mkDevServer(rawOptions) {
   await materializeDynamicContracts(projectRootFolder, vite);
   setupServiceHotReload(vite, lifecycleManager);
   setupActionRouter(vite);
-  const allRoutes = await initRoutes(pagesRootFolder);
-  const routes = buildFolder ? allRoutes.filter((route) => !route.jayHtmlPath.startsWith(buildFolder)) : allRoutes;
+  const projectRoutes = await initRoutes(pagesRootFolder);
+  const filteredProjectRoutes = buildFolder ? projectRoutes.filter((route) => !route.jayHtmlPath.startsWith(buildFolder)) : projectRoutes;
+  const pluginRoutes = await scanPluginRoutes(projectRootFolder, filteredProjectRoutes);
+  const routes = [...filteredProjectRoutes, ...pluginRoutes];
   const slowlyPhase = new DevSlowlyChangingPhase();
   const slowRenderCacheDir = path__default.join(buildFolder, "pre-rendered");
   const slowRenderCache = new SlowRenderCache(slowRenderCacheDir, pagesRootFolder);
-  setupSlowRenderCacheInvalidation(vite, slowRenderCache, pagesRootFolder);
+  _watchLinkedFiles = setupSlowRenderCacheInvalidation(
+    vite,
+    slowRenderCache,
+    pagesRootFolder
+  );
   const projectInit = lifecycleManager.getProjectInit() ?? void 0;
   const pluginsWithInit = lifecycleManager.getPluginsWithInit();
   const pluginClientInits = preparePluginClientInits(pluginsWithInit);
+  const freezeStore = buildFolder ? new FreezeStore(buildFolder) : void 0;
+  if (freezeStore) {
+    setupFreezeEndpoint(vite, freezeStore);
+  }
   const devServerRoutes = routes.map(
     (route) => mkRoute(
       route,
@@ -2461,16 +2809,28 @@ async function mkDevServer(rawOptions) {
       slowlyPhase,
       options,
       slowRenderCache,
+      freezeStore,
       projectInit,
       pluginsWithInit,
       pluginClientInits
     )
   );
+  const service = new DevServerService(
+    devServerRoutes,
+    vite,
+    options.pagesRootFolder,
+    options.projectRootFolder,
+    options.jayRollupConfig,
+    freezeStore
+  );
+  registerService(DEV_SERVER_SERVICE, service);
   return {
     server: vite.middlewares,
     viteServer: vite,
     routes: devServerRoutes,
-    lifecycleManager
+    lifecycleManager,
+    freezeStore,
+    service
   };
 }
 function setupGracefulShutdown(lifecycleManager) {
@@ -2509,19 +2869,68 @@ function setupActionRouter(vite) {
   vite.middlewares.use(ACTION_ENDPOINT_BASE, createActionRouter());
   getLogger().info(`[Actions] Action router mounted at ${ACTION_ENDPOINT_BASE}`);
 }
-function setupSlowRenderCacheInvalidation(vite, cache, pagesRootFolder) {
+function setupFreezeEndpoint(vite, freezeStore) {
+  vite.middlewares.use((req, res, next) => {
+    if (req.method === "POST" && (req.url === "/_jay/freeze" || req.originalUrl === "/_jay/freeze")) {
+      let body = "";
+      req.on("data", (chunk) => body += chunk);
+      req.on("end", async () => {
+        try {
+          const { route, routePattern, viewState } = JSON.parse(body);
+          if (!route || !viewState) {
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Missing route or viewState" }));
+            return;
+          }
+          const entry = await freezeStore.save(route, viewState, routePattern);
+          getLogger().info(`[Freeze] Saved freeze "${entry.id}" for ${route}`);
+          res.writeHead(200, { "Content-Type": "application/json" });
+          res.end(JSON.stringify(entry));
+        } catch (err) {
+          getLogger().warn(`[Freeze] Failed to save: ${err.message}`);
+          res.writeHead(500, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ error: err.message }));
+        }
+      });
+    } else {
+      next();
+    }
+  });
+  getLogger().info("[Freeze] Freeze endpoint mounted at /_jay/freeze");
+}
+function setupSlowRenderCacheInvalidation(vite, cache, pagesRootFolder, projectRootFolder) {
+  const watchedFiles = /* @__PURE__ */ new Set();
+  const watchLinkedFiles = (files) => {
+    for (const file of files) {
+      if (watchedFiles.has(file))
+        continue;
+      watchedFiles.add(file);
+      vite.watcher.add(file);
+      getLogger().info(`[SlowRender] Watching: ${file}`);
+    }
+  };
   vite.watcher.on("change", (changedPath) => {
-    if (!changedPath.startsWith(pagesRootFolder)) {
+    if (watchedFiles.has(changedPath)) {
+      clearServerElementCache();
+      cache.clear().then(() => {
+        getLogger().info(
+          `[SlowRender] Cache cleared (linked file changed: ${changedPath})`
+        );
+        vite.ws.send({ type: "full-reload" });
+      });
       return;
     }
-    if (changedPath.endsWith(".jay-html")) {
+    if (changedPath.endsWith(".jay-html") && changedPath.startsWith(pagesRootFolder)) {
       clearServerElementCache();
-      cache.invalidate(changedPath).then(() => {
-        getLogger().info(`[SlowRender] Cache invalidated for ${changedPath}`);
+      cache.clear().then(() => {
+        getLogger().info(`[SlowRender] Cache cleared (jay-html changed: ${changedPath})`);
         vite.ws.send({ type: "full-reload" });
       });
       return;
     }
+    if (!changedPath.startsWith(pagesRootFolder)) {
+      return;
+    }
     if (changedPath.endsWith("page.ts")) {
       const dir = path__default.dirname(changedPath);
       const jayHtmlPath = path__default.join(dir, "page.jay-html");
@@ -2546,9 +2955,13 @@ function setupSlowRenderCacheInvalidation(vite, cache, pagesRootFolder) {
       return;
     }
   });
+  return watchLinkedFiles;
 }
 export {
   ACTION_ENDPOINT_BASE,
+  DEV_SERVER_SERVICE,
+  DevServerService,
+  FreezeStore,
   actionBodyParser,
   createActionRouter,
   createViteForCli,

package/package.json

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