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

package/dist/index.d.ts

@@ -58,6 +58,17 @@ interface LoadedPageParts {
     /** Script tags with jay-script="allow" to include in SSR output */
     scripts?: JayHtmlScript[];
 }
+/**
+ * Resolve the browser hydration import path for a route (DL#182).
+ *
+ * SSR loads `route.compPath` (which is `./tools` for devOnly plugin routes, `.` otherwise); the
+ * browser must never load those server bundles. Prefer the explicit `clientCompPath` resolved from
+ * the plugin's `./client` export. Fall back to the legacy `index.js`→`index.client.js` rewrite only
+ * for NPM plugin routes (`componentExport` set) that carry no `clientCompPath` — note this rewrite
+ * silently no-ops for a devOnly `compPath` ending in `tools.js`, which is the bug DL#182 fixes.
+ * Local (project) components hydrate directly from `compPath`.
+ */
+declare function resolveClientImportPath(route: JayRoute): string;
 interface LoadPagePartsOptions {
     /**
      * Path to pre-rendered jay-html file to use instead of the original.
@@ -124,6 +135,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 +185,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 +680,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, resolveClientImportPath, resolveViewStatePromises };

package/dist/index.js

@@ -18,6 +18,11 @@ import * as fs from "node:fs";
 import { createRequire as createRequire$1 } from "node:module";
 import { isJayAction, isJayStreamAction, isJayCliCommand } from "@jay-framework/fullstack-component";
 const require$3 = createRequire(import.meta.url);
+function resolveClientImportPath(route) {
+  if (route.clientCompPath) return route.clientCompPath;
+  if (route.componentExport) return route.compPath.replace(/index\.js$/, "index.client.js");
+  return route.compPath;
+}
 async function loadPageParts(vite, route, pagesBase, projectBase, jayRollupConfig, options) {
   const exists = await fs$1.access(route.compPath, fs$1.constants.F_OK).then(() => true).catch(() => false);
   const parts = [];
@@ -30,7 +35,7 @@ async function loadPageParts(vite, route, pagesBase, projectBase, jayRollupConfi
         `${route.compPath} does not export "${exportName}". The file exists but the expected export is missing — remove the file or add the export.`
       );
     } else {
-      const clientImportPath = route.componentExport ? route.compPath.replace(/index\.js$/, "index.client.js") : route.compPath;
+      const clientImportPath = resolveClientImportPath(route);
       parts.push({
         compDefinition: pageComponent,
         clientImport: `import {${exportName}} from '${clientImportPath}'`,
@@ -315,7 +320,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 +402,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 +489,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 +728,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 +774,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 +800,7 @@ ${headExtras ? headExtras + "\n" : ""}    <style>
     </style>
   </head>
   <body>
-    <div id="target">${ssrHtml}</div>
+    <div id="target">${ssrHtml}</div>${devHmrScript}
   </body>
 </html>`;
 }
@@ -1169,9 +1181,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 +1264,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 +1278,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 +1920,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 +2058,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 +2308,7 @@ export {
   SetupNeedsAnswerError,
   SlowRenderCache,
   buildAutomationWrap,
+  buildPageReloadHmrScript,
   buildScriptFragments,
   clearServerElementCache,
   commandSchemaToFlags,
@@ -2289,5 +2334,6 @@ export {
   parseActionMetadata,
   parseInputFromFlags,
   resolveActionMetadataPath,
+  resolveClientImportPath,
   resolveViewStatePromises
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/stack-server-build",
-  "version": "0.24.2",
+  "version": "0.24.4",
   "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.4",
+    "@jay-framework/compiler-shared": "^0.24.4",
+    "@jay-framework/component": "^0.24.4",
+    "@jay-framework/fullstack-component": "^0.24.4",
+    "@jay-framework/logger": "^0.24.4",
+    "@jay-framework/runtime": "^0.24.4",
+    "@jay-framework/ssr-runtime": "^0.24.4",
+    "@jay-framework/stack-route-scanner": "^0.24.4",
+    "@jay-framework/stack-server-runtime": "^0.24.4",
+    "@jay-framework/view-state-merge": "^0.24.4",
     "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.4",
+    "@jay-framework/rollup-plugin": "^0.24.4",
     "@types/node": "^22.15.21",
     "rimraf": "^5.0.5",
     "tsup": "^8.0.1",