@jay-framework/dev-server 0.15.6 → 0.16.1

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>;
 
@@ -160,10 +220,20 @@ interface ActionRouterOptions {
  */
 declare function createActionRouter(options?: ActionRouterOptions): RequestHandler$1;
 /**
- * Express middleware to parse JSON body for action requests.
+ * Options for the action body parser middleware.
+ */
+interface ActionBodyParserOptions {
+    /** Build folder for temp file storage (DL#131) */
+    buildFolder: string;
+    /** Action registry to check for acceptsFiles (default: global actionRegistry) */
+    registry?: ActionRegistry;
+}
+/**
+ * Express middleware to parse request body for action requests.
+ * Supports JSON (default) and multipart/form-data (for actions with .withFiles()).
  * Should be applied before the action router.
  */
-declare function actionBodyParser(): RequestHandler$1;
+declare function actionBodyParser(options: ActionBodyParserOptions): RequestHandler$1;
 
 /**
  * Vite Factory
@@ -207,4 +277,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 ActionBodyParserOptions, 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

@@ -14,10 +14,18 @@ import { JAY_IMPORT_RESOLVER, injectHeadfullFSTemplates, parseContract, slowRend
 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, mergeHeadTags, 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 Busboy from "busboy";
+import fs$2 from "fs";
+import path$1 from "path";
+import crypto from "crypto";
+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];
@@ -911,6 +919,7 @@ function extractActionFromExpression(node) {
   let current = node;
   let method = "POST";
   let explicitMethod = null;
+  let acceptsFiles = false;
   while (c$1.isCallExpression(current)) {
     const expr = current.expression;
     if (c$1.isPropertyAccessExpression(expr) && expr.name.text === "withMethod") {
@@ -921,22 +930,36 @@ function extractActionFromExpression(node) {
       current = expr.expression;
       continue;
     }
+    if (c$1.isPropertyAccessExpression(expr) && expr.name.text === "withFiles") {
+      acceptsFiles = true;
+      current = expr.expression;
+      continue;
+    }
     if (c$1.isPropertyAccessExpression(expr) && ["withServices", "withCaching", "withHandler", "withTimeout"].includes(expr.name.text)) {
       current = expr.expression;
       continue;
     }
     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,
+              ...acceptsFiles && { acceptsFiles: true }
+            };
+          }
           method = funcName === "makeJayQuery" ? "GET" : "POST";
           if (explicitMethod) {
             method = explicitMethod;
           }
           return {
             actionName: nameArg.text,
-            method
+            method,
+            ...acceptsFiles && { acceptsFiles: true }
           };
         }
       }
@@ -1331,14 +1354,28 @@ 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}');`
-            );
+            const filesOpt = action.acceptsFiles ? ", { acceptsFiles: true }" : "";
+            if (action.isStreaming) {
+              lines.push(
+                `export const ${action.exportName} = createStreamCaller('${action.actionName}'${filesOpt});`
+              );
+            } else {
+              lines.push(
+                `export const ${action.exportName} = createActionCaller('${action.actionName}', '${action.method}'${filesOpt});`
+              );
+            }
           }
           if (code.includes("ActionError")) {
             lines.push(
@@ -1758,7 +1795,30 @@ function createActionRouter(options) {
       requestMethod,
       ACTION_ENDPOINT_BASE + "/" + actionName
     );
+    const tempDir = req._jayTempDir;
+    const cleanup = () => {
+      if (tempDir)
+        cleanupTempDir(tempDir);
+    };
+    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");
+      }
+      cleanup();
+      res.end();
+      timing?.end();
+      return;
+    }
     const result = await registry.execute(actionName, input);
+    cleanup();
     if (requestMethod === "GET" && result.success) {
       const cacheHeaders = registry.getCacheHeaders(actionName);
       if (cacheHeaders) {
@@ -1799,7 +1859,106 @@ function getStatusCodeForError(code, isActionError) {
       return 500;
   }
 }
-function actionBodyParser() {
+const DEFAULT_MAX_FILE_SIZE = 10 * 1024 * 1024;
+const DEFAULT_MAX_FILES = 10;
+function parseMultipart(req, tempDir, maxFileSize, maxFiles) {
+  return new Promise((resolve, reject) => {
+    fs$2.mkdirSync(tempDir, { recursive: true });
+    const files = {};
+    let jsonData = {};
+    let fileCount = 0;
+    let errored = false;
+    const pendingWrites = [];
+    const bb = Busboy({
+      headers: req.headers,
+      limits: {
+        fileSize: maxFileSize,
+        files: maxFiles
+      }
+    });
+    bb.on("file", (fieldname, stream, info) => {
+      if (errored)
+        return;
+      fileCount++;
+      const filename = info.filename || `upload-${fileCount}`;
+      const tempPath = path$1.join(tempDir, `${fileCount}-${filename}`);
+      let size = 0;
+      let truncated = false;
+      const writeStream = fs$2.createWriteStream(tempPath);
+      stream.pipe(writeStream);
+      stream.on("data", (data) => {
+        size += data.length;
+      });
+      stream.on("limit", () => {
+        truncated = true;
+      });
+      pendingWrites.push(
+        new Promise((resolveWrite, rejectWrite) => {
+          writeStream.on("close", () => {
+            if (truncated) {
+              rejectWrite(
+                new Error(
+                  `File "${filename}" exceeds maximum size of ${maxFileSize} bytes`
+                )
+              );
+              return;
+            }
+            const jayFile = {
+              name: filename,
+              type: info.mimeType,
+              size,
+              path: tempPath
+            };
+            if (files[fieldname]) {
+              const existing = files[fieldname];
+              if (Array.isArray(existing)) {
+                existing.push(jayFile);
+              } else {
+                files[fieldname] = [existing, jayFile];
+              }
+            } else {
+              files[fieldname] = jayFile;
+            }
+            resolveWrite();
+          });
+        })
+      );
+    });
+    bb.on("field", (fieldname, value) => {
+      if (errored)
+        return;
+      if (fieldname === "_json") {
+        try {
+          jsonData = JSON.parse(value);
+        } catch {
+          errored = true;
+          reject(new Error("Invalid JSON in _json field"));
+        }
+      }
+    });
+    bb.on("close", () => {
+      if (errored)
+        return;
+      Promise.all(pendingWrites).then(() => resolve({ body: { ...jsonData, ...files }, tempDir })).catch((err) => reject(err));
+    });
+    bb.on("error", (err) => {
+      if (!errored) {
+        errored = true;
+        reject(err);
+      }
+    });
+    req.pipe(bb);
+  });
+}
+function cleanupTempDir(dir) {
+  try {
+    fs$2.rmSync(dir, { recursive: true, force: true });
+  } catch {
+  }
+}
+function actionBodyParser(options) {
+  const { buildFolder, registry: reg } = options;
+  const registryToUse = reg ?? actionRegistry;
   return (req, res, next) => {
     if (!req.path.startsWith(ACTION_ENDPOINT_BASE)) {
       next();
@@ -1809,6 +1968,42 @@ function actionBodyParser() {
       next();
       return;
     }
+    const contentType = req.headers["content-type"] || "";
+    if (contentType.startsWith("multipart/form-data")) {
+      const actionName = req.path.slice(ACTION_ENDPOINT_BASE.length + 1);
+      const action = registryToUse.get(actionName);
+      if (!action?.acceptsFiles) {
+        res.status(400).json({
+          success: false,
+          error: {
+            code: "FILES_NOT_ACCEPTED",
+            message: `Action '${actionName}' does not accept file uploads. Use .withFiles() on the action builder.`,
+            isActionError: false
+          }
+        });
+        return;
+      }
+      const requestId = crypto.randomUUID();
+      const tempDir = path$1.join(buildFolder, ".tmp", "actions", requestId);
+      const maxFileSize = action.fileOptions?.maxFileSize ?? DEFAULT_MAX_FILE_SIZE;
+      const maxFiles = action.fileOptions?.maxFiles ?? DEFAULT_MAX_FILES;
+      parseMultipart(req, tempDir, maxFileSize, maxFiles).then(({ body: body2, tempDir: td }) => {
+        req.body = body2;
+        req._jayTempDir = td;
+        next();
+      }).catch((err) => {
+        cleanupTempDir(tempDir);
+        res.status(400).json({
+          success: false,
+          error: {
+            code: "MULTIPART_PARSE_ERROR",
+            message: err.message,
+            isActionError: false
+          }
+        });
+      });
+      return;
+    }
     let body = "";
     req.setEncoding("utf8");
     req.on("data", (chunk) => {
@@ -1831,6 +2026,124 @@ 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) {
@@ -1839,6 +2152,82 @@ async function initRoutes(pagesBaseFolder) {
     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 || ".";
@@ -1900,7 +2289,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);
@@ -1916,6 +2305,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,
@@ -2048,6 +2454,7 @@ async function handleCachedRequest(vite, route, options, cachedEntry, pageParams
     projectInit,
     pluginsForPage,
     options,
+    routeToExpressRoute(route),
     cachedEntry.slowViewState,
     timing,
     cachedEntry.preRenderedContent,
@@ -2227,14 +2634,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);
@@ -2242,11 +2650,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, headTags) {
+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);
@@ -2270,7 +2678,8 @@ 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,
@@ -2289,15 +2698,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);
@@ -2305,12 +2715,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;
@@ -2452,8 +2912,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);
@@ -2470,9 +2937,11 @@ async function mkDevServer(rawOptions) {
   await lifecycleManager.initialize();
   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;
+  setupActionRouter(vite, buildFolder);
+  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);
@@ -2484,6 +2953,10 @@ async function mkDevServer(rawOptions) {
   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,
@@ -2491,16 +2964,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) {
@@ -2534,11 +3019,40 @@ function setupServiceHotReload(vite, lifecycleManager) {
     }
   });
 }
-function setupActionRouter(vite) {
-  vite.middlewares.use(actionBodyParser());
+function setupActionRouter(vite, buildFolder) {
+  vite.middlewares.use(actionBodyParser({ buildFolder }));
   vite.middlewares.use(ACTION_ENDPOINT_BASE, createActionRouter());
   getLogger().info(`[Actions] Action router mounted at ${ACTION_ENDPOINT_BASE}`);
 }
+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) => {
@@ -2600,6 +3114,9 @@ function setupSlowRenderCacheInvalidation(vite, cache, pagesRootFolder, projectR
 }
 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.6",
+  "version": "0.16.1",
   "type": "module",
   "license": "Apache-2.0",
   "main": "dist/index.js",
@@ -23,23 +23,25 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@jay-framework/compiler-jay-stack": "^0.15.6",
-    "@jay-framework/compiler-shared": "^0.15.6",
-    "@jay-framework/component": "^0.15.6",
-    "@jay-framework/fullstack-component": "^0.15.6",
-    "@jay-framework/logger": "^0.15.6",
-    "@jay-framework/runtime": "^0.15.6",
-    "@jay-framework/stack-client-runtime": "^0.15.6",
-    "@jay-framework/stack-route-scanner": "^0.15.6",
-    "@jay-framework/stack-server-runtime": "^0.15.6",
-    "@jay-framework/view-state-merge": "^0.15.6",
+    "@jay-framework/compiler-jay-stack": "^0.16.1",
+    "@jay-framework/compiler-shared": "^0.16.1",
+    "@jay-framework/component": "^0.16.1",
+    "@jay-framework/fullstack-component": "^0.16.1",
+    "@jay-framework/logger": "^0.16.1",
+    "@jay-framework/runtime": "^0.16.1",
+    "@jay-framework/stack-client-runtime": "^0.16.1",
+    "@jay-framework/stack-route-scanner": "^0.16.1",
+    "@jay-framework/stack-server-runtime": "^0.16.1",
+    "@jay-framework/view-state-merge": "^0.16.1",
+    "busboy": "^1.6.0",
     "vite": "^5.0.11"
   },
   "devDependencies": {
-    "@jay-framework/dev-environment": "^0.15.6",
-    "@jay-framework/jay-cli": "^0.15.6",
-    "@jay-framework/stack-client-runtime": "^0.15.6",
+    "@jay-framework/dev-environment": "^0.16.1",
+    "@jay-framework/jay-cli": "^0.16.1",
+    "@jay-framework/stack-client-runtime": "^0.16.1",
     "@playwright/test": "^1.58.2",
+    "@types/busboy": "^1.5.4",
     "@types/express": "^5.0.2",
     "@types/node": "^22.15.21",
     "jsdom": "^23.2.0",