@jay-framework/stack-server-build 0.24.2 → 0.24.3

package/dist/index.d.ts

@@ -124,6 +124,8 @@ interface ScriptFragments {
  * Build the shared script fragments used by both client and hydration scripts.
  */
 declare function buildScriptFragments(parts: DevServerPagePart[], clientInitData: Record<string, Record<string, any>>, projectInit: ProjectClientInitInfo | undefined, pluginInits: PluginClientInitInfo[], options: GenerateClientScriptOptions): ScriptFragments;
+/** Dev-only: subscribe to jay:page-reload and reload when route prefix matches. */
+declare function buildPageReloadHmrScript(): string;
 /**
  * Generate the automation wrapping code.
  * @param mode - 'client' appends to DOM; 'hydrate' skips appendChild (DOM already present)
@@ -172,17 +174,23 @@ headTags?: HeadTag[],
 /** Script tags with jay-script="allow" (DL#149) */
 scripts?: JayHtmlScript[]): Promise<string>;
 /**
- * Generate a frozen page — pure SSR HTML with no client scripts (DL#127).
+ * Generate a frozen page — pure SSR HTML (DL#127).
  *
  * Uses the same server element module as generateSSRPageHtml, but:
  * - No hydration script
- * - No Vite client
  * - No component runtime
  * - Just rendered HTML + CSS
  *
+ * Script policy:
+ * - Production / `format=fragment`: no client scripts
+ * - Dev full-page (`injectDevHmr: true`): minimal reload listener only — no hydration,
+ *   automation, or freeze capture. Caller must run the result through `transformIndexHtml`.
+ *
  * @param format - 'page' for full HTML document, 'fragment' for body-only (shadow DOM)
  */
-declare function generateFrozenPageHtml(vite: ViteDevServer, jayHtmlContent: string, jayHtmlFilename: string, jayHtmlDir: string, viewState: object, buildFolder: string, projectRoot: string, routeDir: string, tsConfigFilePath?: string, sourceDir?: string, format?: 'page' | 'fragment', freezeName?: string): Promise<string>;
+declare function generateFrozenPageHtml(vite: ViteDevServer, jayHtmlContent: string, jayHtmlFilename: string, jayHtmlDir: string, viewState: object, buildFolder: string, projectRoot: string, routeDir: string, tsConfigFilePath?: string, sourceDir?: string, format?: 'page' | 'fragment', freezeName?: string, options?: {
+    injectDevHmr?: boolean;
+}): Promise<string>;
 
 /**
  * Action metadata loaded from .jay-action files.
@@ -661,4 +669,4 @@ declare class SlowRenderCache {
     private scanAndDeleteCacheFiles;
 }
 
-export { type ActionDiscoveryOptions, type ActionDiscoveryResult, type ActionIndexEntry, type ActionMetadata, type ActionSchema, type CommandFlag, type CommandIndexEntry, type CommandMetadata, type ContextIndexEntry, type DevServerPagePart, type DiscoveredCommand, type GenerateClientScriptOptions, type HeadlessInstanceComponent, type LoadPagePartsOptions, type LoadedPageParts, type MaterializeContractsOptions, type MaterializeResult, type PluginActionDiscoveryOptions, type PluginContractEntry, type PluginWithAgentKit, type PluginWithSetup, type PluginsIndex, type PluginsIndexEntry, type ProjectClientInitInfo, type RouteIndexEntry, type ScriptFragments, type ServiceIndexEntry, SetupNeedsAnswerError, SlowRenderCache, type SlowRenderCacheEntry, type ViteSSRLoader, buildAutomationWrap, buildScriptFragments, clearServerElementCache, commandSchemaToFlags, discoverAllPluginActions, discoverAndRegisterActions, discoverPluginActions, discoverPluginCommands, discoverPluginsWithAgentKit, discoverPluginsWithSetup, executePluginAgentKit, executePluginCommand, executePluginSetup, generateClientScript, generateFrozenPageHtml, generatePromiseReconstruction, generateSSRPageHtml, headMetaToHeadTags, invalidateServerElementCache, listContracts, loadActionMetadata, loadPageParts, materializeContracts, parseActionMetadata, parseInputFromFlags, resolveActionMetadataPath, resolveViewStatePromises };
+export { type ActionDiscoveryOptions, type ActionDiscoveryResult, type ActionIndexEntry, type ActionMetadata, type ActionSchema, type CommandFlag, type CommandIndexEntry, type CommandMetadata, type ContextIndexEntry, type DevServerPagePart, type DiscoveredCommand, type GenerateClientScriptOptions, type HeadlessInstanceComponent, type LoadPagePartsOptions, type LoadedPageParts, type MaterializeContractsOptions, type MaterializeResult, type PluginActionDiscoveryOptions, type PluginContractEntry, type PluginWithAgentKit, type PluginWithSetup, type PluginsIndex, type PluginsIndexEntry, type ProjectClientInitInfo, type RouteIndexEntry, type ScriptFragments, type ServiceIndexEntry, SetupNeedsAnswerError, SlowRenderCache, type SlowRenderCacheEntry, type ViteSSRLoader, buildAutomationWrap, buildPageReloadHmrScript, buildScriptFragments, clearServerElementCache, commandSchemaToFlags, discoverAllPluginActions, discoverAndRegisterActions, discoverPluginActions, discoverPluginCommands, discoverPluginsWithAgentKit, discoverPluginsWithSetup, executePluginAgentKit, executePluginCommand, executePluginSetup, generateClientScript, generateFrozenPageHtml, generatePromiseReconstruction, generateSSRPageHtml, headMetaToHeadTags, invalidateServerElementCache, listContracts, loadActionMetadata, loadPageParts, materializeContracts, parseActionMetadata, parseInputFromFlags, resolveActionMetadataPath, resolveViewStatePromises };

package/dist/index.js

@@ -315,7 +315,7 @@ function normalizeActionEntry(entry) {
   if (typeof entry === "string") {
     return { name: entry };
   }
-  return { name: entry.name, action: entry.action };
+  return { name: entry.name, action: entry.action, devOnly: entry.devOnly };
 }
 function loadPluginManifest(pluginDir) {
   const pluginYamlPath = path$1.join(pluginDir, "plugin.yaml");
@@ -397,6 +397,18 @@ ${clientParts.map((part) => "        " + part.clientPart).join(",\n")}
     slowViewStateDecl
   };
 }
+function buildPageReloadHmrScript() {
+  return `
+      if (import.meta.hot) {
+        import.meta.hot.on('jay:page-reload', (data) => {
+          const prefix = data.routePrefix;
+          const pathname = window.location.pathname;
+          if (pathname === prefix || pathname.startsWith(prefix + '/')) {
+            window.location.reload();
+          }
+        });
+      }`;
+}
 function buildFreezeScript(routePattern) {
   const routePatternLiteral = routePattern ? `'${routePattern}'` : "undefined";
   return `
@@ -472,15 +484,7 @@ function buildFreezeScript(routePattern) {
       }
 
       // Targeted page reload: only reload if this page matches the changed route prefix
-      if (import.meta.hot) {
-        import.meta.hot.on('jay:page-reload', (data) => {
-          const prefix = data.routePrefix;
-          const pathname = window.location.pathname;
-          if (pathname === prefix || pathname.startsWith(prefix + '/')) {
-            window.location.reload();
-          }
-        });
-      }`;
+${buildPageReloadHmrScript()}`;
 }
 function buildAutomationWrap(options, mode) {
   const { enableAutomation = true, slowViewState } = options;
@@ -719,7 +723,7 @@ ${titleTag}${headExtras ? headExtras + "\n" : ""}  </head>
   </body>
 </html>`;
 }
-async function generateFrozenPageHtml(vite, jayHtmlContent, jayHtmlFilename, jayHtmlDir, viewState, buildFolder, projectRoot, routeDir, tsConfigFilePath, sourceDir, format = "page", freezeName) {
+async function generateFrozenPageHtml(vite, jayHtmlContent, jayHtmlFilename, jayHtmlDir, viewState, buildFolder, projectRoot, routeDir, tsConfigFilePath, sourceDir, format = "page", freezeName, options) {
   const jayHtmlPath = path__default.join(jayHtmlDir, jayHtmlFilename);
   let cached = serverModuleCache.get(jayHtmlPath);
   if (!cached) {
@@ -765,6 +769,9 @@ ${ssrHtml}`;
   const cssLink = cached.cssHref ? `    <link rel="stylesheet" href="${cached.cssHref}" />` : "";
   const headExtras = [cssLink, frozenHeadTagsHtml].filter((_) => _).join("\n");
   const label = freezeName ? ` — ${freezeName}` : "";
+  const devHmrScript = options?.injectDevHmr === true ? `
+    <script type="module">${buildPageReloadHmrScript()}
+    <\/script>` : "";
   return `<!doctype html>
 <html lang="en">
   <head>
@@ -788,7 +795,7 @@ ${headExtras ? headExtras + "\n" : ""}    <style>
     </style>
   </head>
   <body>
-    <div id="target">${ssrHtml}</div>
+    <div id="target">${ssrHtml}</div>${devHmrScript}
   </body>
 </html>`;
 }
@@ -1169,9 +1176,18 @@ async function registerNpmPluginActions(packageName, pluginConfig, pluginDir, re
     } else {
       pluginModule = await import(packageName);
     }
+    let toolsModule;
+    const loadToolsModule = async () => {
+      if (!toolsModule) {
+        const toolsEntry = `${packageName}/tools`;
+        toolsModule = viteServer ? await viteServer.ssrLoadModule(toolsEntry) : await import(toolsEntry);
+      }
+      return toolsModule;
+    };
     for (const entry of pluginConfig.actions) {
-      const { name: actionName, action: actionPath } = normalizeActionEntry(entry);
-      const actionExport = pluginModule[actionName];
+      const { name: actionName, action: actionPath, devOnly } = normalizeActionEntry(entry);
+      const sourceModule = devOnly ? await loadToolsModule() : pluginModule;
+      const actionExport = sourceModule[actionName];
       if (actionExport && isJayAction(actionExport)) {
         registry.register(actionExport);
         const registeredName = actionExport.actionName;
@@ -1243,6 +1259,13 @@ async function discoverPluginActions(pluginPath, projectRoot, registry = actionR
       return [];
     }
   }
+  const resolveLocalToolsModulePath = () => {
+    for (const candidate of ["tools.ts", "tools.js"]) {
+      const candidatePath = path.join(pluginPath, candidate);
+      if (fs.existsSync(candidatePath)) return candidatePath;
+    }
+    return null;
+  };
   try {
     let pluginModule;
     if (viteServer) {
@@ -1250,9 +1273,23 @@ async function discoverPluginActions(pluginPath, projectRoot, registry = actionR
     } else {
       pluginModule = await import(modulePath);
     }
+    let toolsModule;
+    const loadToolsModule = async () => {
+      if (toolsModule) return toolsModule;
+      const toolsPath = resolveLocalToolsModulePath();
+      if (!toolsPath) {
+        getLogger().warn(
+          `[Actions] Plugin "${pluginName}" declares a devOnly action but has no tools.ts/tools.js module`
+        );
+        return void 0;
+      }
+      toolsModule = viteServer ? await viteServer.ssrLoadModule(toolsPath) : await import(toolsPath);
+      return toolsModule;
+    };
     for (const entry of pluginConfig.actions) {
-      const { name: actionName, action: actionPath } = normalizeActionEntry(entry);
-      const actionExport = pluginModule[actionName];
+      const { name: actionName, action: actionPath, devOnly } = normalizeActionEntry(entry);
+      const sourceModule = devOnly ? await loadToolsModule() : pluginModule;
+      const actionExport = sourceModule?.[actionName];
       if (actionExport && isJayAction(actionExport)) {
         registry.register(actionExport);
         const registeredName = actionExport.actionName;
@@ -1878,10 +1915,11 @@ async function loadCommandHandler(command, viteServer) {
       module = await import(modulePath);
     }
   } else {
+    const toolsEntry = `${command.packageName}/tools`;
     if (viteServer) {
-      module = await viteServer.ssrLoadModule(command.packageName);
+      module = await viteServer.ssrLoadModule(toolsEntry);
     } else {
-      module = await import(command.packageName);
+      module = await import(toolsEntry);
     }
   }
   for (const [, exported] of Object.entries(module)) {
@@ -2015,14 +2053,15 @@ async function loadHandler(plugin, handlerName, viteServer) {
       `Handler "${handlerName}" not found in "${plugin.pluginPath}". Available exports: ${Object.keys(module).join(", ")}`
     );
   } else {
+    const toolsEntry = `${plugin.packageName}/tools`;
     if (viteServer) {
-      module = await viteServer.ssrLoadModule(plugin.packageName);
+      module = await viteServer.ssrLoadModule(toolsEntry);
     } else {
-      module = await import(plugin.packageName);
+      module = await import(toolsEntry);
     }
     if (typeof module[handlerName] !== "function") {
       throw new Error(
-        `Handler "${handlerName}" not found as export in "${plugin.packageName}". Available exports: ${Object.keys(module).join(", ")}`
+        `Handler "${handlerName}" not found as export in "${toolsEntry}". Available exports: ${Object.keys(module).join(", ")}`
       );
     }
     return module[handlerName];
@@ -2264,6 +2303,7 @@ export {
   SetupNeedsAnswerError,
   SlowRenderCache,
   buildAutomationWrap,
+  buildPageReloadHmrScript,
   buildScriptFragments,
   clearServerElementCache,
   commandSchemaToFlags,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/stack-server-build",
-  "version": "0.24.2",
+  "version": "0.24.3",
   "license": "Apache-2.0",
   "main": "dist/index.js",
   "types": "dist/index.d.mts",
@@ -24,21 +24,21 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@jay-framework/compiler-jay-html": "^0.24.2",
-    "@jay-framework/compiler-shared": "^0.24.2",
-    "@jay-framework/component": "^0.24.2",
-    "@jay-framework/fullstack-component": "^0.24.2",
-    "@jay-framework/logger": "^0.24.2",
-    "@jay-framework/runtime": "^0.24.2",
-    "@jay-framework/ssr-runtime": "^0.24.2",
-    "@jay-framework/stack-route-scanner": "^0.24.2",
-    "@jay-framework/stack-server-runtime": "^0.24.2",
-    "@jay-framework/view-state-merge": "^0.24.2",
+    "@jay-framework/compiler-jay-html": "^0.24.3",
+    "@jay-framework/compiler-shared": "^0.24.3",
+    "@jay-framework/component": "^0.24.3",
+    "@jay-framework/fullstack-component": "^0.24.3",
+    "@jay-framework/logger": "^0.24.3",
+    "@jay-framework/runtime": "^0.24.3",
+    "@jay-framework/ssr-runtime": "^0.24.3",
+    "@jay-framework/stack-route-scanner": "^0.24.3",
+    "@jay-framework/stack-server-runtime": "^0.24.3",
+    "@jay-framework/view-state-merge": "^0.24.3",
     "yaml": "^2.3.4"
   },
   "devDependencies": {
-    "@jay-framework/dev-environment": "^0.24.2",
-    "@jay-framework/rollup-plugin": "^0.24.2",
+    "@jay-framework/dev-environment": "^0.24.3",
+    "@jay-framework/rollup-plugin": "^0.24.3",
     "@types/node": "^22.15.21",
     "rimraf": "^5.0.5",
     "tsup": "^8.0.1",