@jay-framework/stack-server-runtime 0.15.6 → 0.16.1

package/dist/index.d.ts

@@ -1,5 +1,4 @@
-import { AnyJayStackComponentDefinition, PageProps, AnySlowlyRenderResult, UrlParams, JayStackComponentDefinition, AnyFastRenderResult, HttpMethod, CacheOptions, JayAction, JayActionDefinition, HeadTag, ServiceMarker } from '@jay-framework/fullstack-component';
-import { JayComponentCore } from '@jay-framework/component';
+import { AnyJayStackComponentDefinition, PageProps, AnySlowlyRenderResult, UrlParams, AnyFastRenderResult, HttpMethod, CacheOptions, JayAction, JayActionDefinition, JayStreamAction, JayStreamActionDefinition, HeadTag, ServiceMarker } from '@jay-framework/fullstack-component';
 import { ViteDevServer } from 'vite';
 import { JayRoute } from '@jay-framework/stack-route-scanner';
 import { WithValidations, JsonSchemaProperty, PluginManifest } from '@jay-framework/compiler-shared';
@@ -76,8 +75,11 @@ interface SlowlyChangingPhase {
 declare class DevSlowlyChangingPhase implements SlowlyChangingPhase {
     runSlowlyForPage(pageParams: UrlParams, pageProps: PageProps, parts: Array<DevServerPagePart>, discoveredInstances?: DiscoveredHeadlessInstance[], headlessInstanceComponents?: HeadlessInstanceComponent[], jayHtmlPath?: string): Promise<AnySlowlyRenderResult>;
 }
-declare function runLoadParams<Refs extends object, SlowVS extends object, FastVS extends object, InteractiveVS extends object, Services extends Array<any>, Contexts extends Array<any>, PropsT extends object, Params extends UrlParams, CompCore extends JayComponentCore<PropsT, InteractiveVS>>(compDefinition: JayStackComponentDefinition<Refs, SlowVS, FastVS, InteractiveVS, Services, Contexts, PropsT, Params, CompCore>, services: Services): Promise<void>;
-declare function runSlowlyChangingRender<Refs extends object, SlowVS extends object, FastVS extends object, InteractiveVS extends object, Services extends Array<any>, Contexts extends Array<any>, PropsT extends object, Params extends UrlParams, CompCore extends JayComponentCore<PropsT, InteractiveVS>>(compDefinition: JayStackComponentDefinition<Refs, SlowVS, FastVS, InteractiveVS, Services, Contexts, PropsT, Params, CompCore>): void;
+/**
+ * Run loadParams for all parts (page + keyed headless components).
+ * Yields param batches from each part that has loadParams.
+ */
+declare function runLoadParams(parts: DevServerPagePart[]): AsyncGenerator<Record<string, string>[]>;
 
 /**
  * Server-side slow render orchestration for headless component instances.
@@ -191,23 +193,45 @@ declare function resolveActionMetadataPath(actionPath: string, pluginDir: string
  */
 
 /**
- * Registered action entry with resolved metadata.
+ * Base fields shared by all registered action types.
  */
-interface RegisteredAction {
+interface RegisteredActionBase {
     /** Unique action name */
     actionName: string;
     /** HTTP method */
     method: HttpMethod;
-    /** Cache options (for GET requests) */
-    cacheOptions?: CacheOptions;
     /** Service markers for dependency injection */
     services: any[];
-    /** The handler function */
-    handler: (input: any, ...services: any[]) => Promise<any>;
     /** Optional metadata from .jay-action file (description, input/output schemas).
      *  Actions with metadata are exposed to AI agents; those without are not. */
     metadata?: ActionMetadata;
+    /** Whether this action accepts file uploads (DL#131) */
+    acceptsFiles?: boolean;
 }
+/**
+ * Registered request-response action entry.
+ * Uses `isStreaming` as a discriminator for the union.
+ */
+interface RegisteredAction extends RegisteredActionBase {
+    /** Discriminator: false or absent for regular actions */
+    isStreaming?: false;
+    /** Cache options (for GET requests) */
+    cacheOptions?: CacheOptions;
+    /** The handler function */
+    handler: (input: any, ...services: any[]) => Promise<any>;
+}
+/**
+ * Registered streaming action entry (DL#129).
+ */
+interface RegisteredStreamAction extends RegisteredActionBase {
+    method: 'POST';
+    /** Discriminator: true for streaming actions */
+    isStreaming: true;
+    /** The generator handler function */
+    handler: (input: any, ...services: any[]) => AsyncIterable<any>;
+}
+/** Union of all registered action types, discriminated by `isStreaming`. */
+type RegisteredActionEntry = RegisteredAction | RegisteredStreamAction;
 /**
  * Result of executing an action.
  */
@@ -258,7 +282,7 @@ declare class ActionRegistry {
      * @param actionName - The unique action name
      * @returns The registered action or undefined
      */
-    get(actionName: string): RegisteredAction | undefined;
+    get(actionName: string): RegisteredActionEntry | undefined;
     /**
      * Checks if an action is registered.
      *
@@ -310,6 +334,18 @@ declare class ActionRegistry {
      * @returns Cache-Control header value or undefined
      */
     getCacheHeaders(actionName: string): string | undefined;
+    /**
+     * Register a streaming action.
+     */
+    registerStream<I, C, S extends any[]>(action: JayStreamAction<I, C> & JayStreamActionDefinition<I, C, S>): void;
+    /**
+     * Check if a registered action is a streaming action.
+     */
+    isStreaming(actionName: string): boolean;
+    /**
+     * Execute a streaming action, returning an async iterable of chunks.
+     */
+    executeStream(actionName: string, input: unknown): AsyncGenerator<any>;
 }
 /**
  * Default action registry instance.
@@ -325,7 +361,7 @@ declare function registerAction<I, O, S extends any[]>(action: JayAction<I, O> &
  * Retrieves a registered action by name from the default registry.
  * @deprecated Use actionRegistry.get() instead
  */
-declare function getRegisteredAction(actionName: string): RegisteredAction | undefined;
+declare function getRegisteredAction(actionName: string): RegisteredActionEntry | undefined;
 /**
  * Checks if an action is registered in the default registry.
  * @deprecated Use actionRegistry.has() instead
@@ -575,6 +611,8 @@ interface GenerateClientScriptOptions {
      * so that AI/automation tools can see the complete page state.
      */
     slowViewState?: object;
+    /** Route pattern (e.g., /products/kitan{/:category}) for freeze entries */
+    routePattern?: string;
 }
 /**
  * Shared fragments generated by buildScriptFragments().
@@ -637,6 +675,18 @@ declare function generateSSRPageHtml(vite: ViteDevServer, jayHtmlContent: string
 sourceDir?: string, 
 /** Head tags to inject into <head> during SSR (Design Log #127) */
 headTags?: HeadTag[]): Promise<string>;
+/**
+ * Generate a frozen page — pure SSR HTML with no client scripts (DL#127).
+ *
+ * Uses the same server element module as generateSSRPageHtml, but:
+ * - No hydration script
+ * - No Vite client
+ * - No component runtime
+ * - Just rendered HTML + CSS
+ *
+ * @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>;
 
 /**
  * Service registry for Jay Stack server-side dependency injection.
@@ -935,6 +985,11 @@ interface ContextIndexEntry {
     description?: string;
     doc?: string;
 }
+/** Route entry in plugins-index.yaml (DL#130) */
+interface RouteIndexEntry {
+    path: string;
+    description?: string;
+}
 /** Entry for plugins-index.yaml (Design Log #85) */
 interface PluginsIndexEntry {
     name: string;
@@ -946,6 +1001,8 @@ interface PluginsIndexEntry {
     services?: ServiceIndexEntry[];
     /** Client-side contexts provided by this plugin (DL#125) */
     contexts?: ContextIndexEntry[];
+    /** Plugin-provided routes (DL#130) */
+    routes?: RouteIndexEntry[];
 }
 interface PluginsIndex {
     plugins: PluginsIndexEntry[];
@@ -1202,4 +1259,4 @@ declare function mergeHeadTags(sources: HeadTag[][]): HeadTag[];
  */
 declare function serializeHeadTags(tags: HeadTag[]): string;
 
-export { type ActionDiscoveryOptions, type ActionDiscoveryResult, type ActionErrorResponse, type ActionExecutionResult, type ActionIndexEntry, type ActionMetadata, ActionRegistry, type ActionSchema, type ContextIndexEntry, type DevServerPagePart, DevSlowlyChangingPhase, type GenerateClientScriptOptions, type HeadlessInstanceComponent, type InstancePhaseData, type InstanceSlowRenderResult, type LoadedPageParts, type MaterializeContractsOptions, type MaterializeResult, type PluginActionDiscoveryOptions, type PluginClientInitInfo, type PluginContractEntry, type PluginInitDiscoveryOptions, type PluginReferencesContext, type PluginReferencesHandler, type PluginReferencesResult, type PluginScanOptions, type PluginSetupContext, type PluginSetupHandler, type PluginSetupResult, type PluginWithInit, type PluginWithReferences, type PluginWithSetup, type PluginsIndex, type PluginsIndexEntry, type ProjectClientInitInfo, type RegisteredAction, type ScannedPlugin, type ScriptFragments, type ServiceIndexEntry, SlowRenderCache, type SlowRenderCacheEntry, type SlowlyChangingPhase, type ViteSSRLoader, actionRegistry, buildAutomationWrap, buildScriptFragments, clearActionRegistry, clearClientInitData, clearLifecycleCallbacks, clearServerElementCache, clearServiceRegistry, discoverAllPluginActions, discoverAndRegisterActions, discoverPluginActions, discoverPluginsWithInit, discoverPluginsWithReferences, discoverPluginsWithSetup, executeAction, executePluginReferences, executePluginServerInits, executePluginSetup, generateClientScript, generatePromiseReconstruction, generateSSRPageHtml, getActionCacheHeaders, getClientInitData, getClientInitDataForKey, getRegisteredAction, getRegisteredActionNames, getService, getServiceRegistry, hasAction, hasService, invalidateServerElementCache, listContracts, loadActionMetadata, loadPageParts, materializeContracts, mergeHeadTags, onInit, onShutdown, parseActionMetadata, preparePluginClientInits, registerAction, registerService, renderFastChangingData, resolveActionMetadataPath, resolveServices, resolveViewStatePromises, runInitCallbacks, runLoadParams, runShutdownCallbacks, runSlowlyChangingRender, scanPlugins, serializeHeadTags, setClientInitData, slowRenderInstances, sortPluginsByDependencies, tagIdentityKey, validateForEachInstances };
+export { type ActionDiscoveryOptions, type ActionDiscoveryResult, type ActionErrorResponse, type ActionExecutionResult, type ActionIndexEntry, type ActionMetadata, ActionRegistry, type ActionSchema, type ContextIndexEntry, type DevServerPagePart, DevSlowlyChangingPhase, type GenerateClientScriptOptions, type HeadlessInstanceComponent, type InstancePhaseData, type InstanceSlowRenderResult, type LoadedPageParts, type MaterializeContractsOptions, type MaterializeResult, type PluginActionDiscoveryOptions, type PluginClientInitInfo, type PluginContractEntry, type PluginInitDiscoveryOptions, type PluginReferencesContext, type PluginReferencesHandler, type PluginReferencesResult, type PluginScanOptions, type PluginSetupContext, type PluginSetupHandler, type PluginSetupResult, type PluginWithInit, type PluginWithReferences, type PluginWithSetup, type PluginsIndex, type PluginsIndexEntry, type ProjectClientInitInfo, type RegisteredAction, type RegisteredActionBase, type RegisteredActionEntry, type RegisteredStreamAction, type RouteIndexEntry, type ScannedPlugin, type ScriptFragments, type ServiceIndexEntry, SlowRenderCache, type SlowRenderCacheEntry, type SlowlyChangingPhase, type ViteSSRLoader, actionRegistry, buildAutomationWrap, buildScriptFragments, clearActionRegistry, clearClientInitData, clearLifecycleCallbacks, clearServerElementCache, clearServiceRegistry, discoverAllPluginActions, discoverAndRegisterActions, discoverPluginActions, discoverPluginsWithInit, discoverPluginsWithReferences, discoverPluginsWithSetup, executeAction, executePluginReferences, executePluginServerInits, executePluginSetup, generateClientScript, generateFrozenPageHtml, generatePromiseReconstruction, generateSSRPageHtml, getActionCacheHeaders, getClientInitData, getClientInitDataForKey, getRegisteredAction, getRegisteredActionNames, getService, getServiceRegistry, hasAction, hasService, invalidateServerElementCache, listContracts, loadActionMetadata, loadPageParts, materializeContracts, mergeHeadTags, onInit, onShutdown, parseActionMetadata, preparePluginClientInits, registerAction, registerService, renderFastChangingData, resolveActionMetadataPath, resolveServices, resolveViewStatePromises, runInitCallbacks, runLoadParams, runShutdownCallbacks, scanPlugins, serializeHeadTags, setClientInitData, slowRenderInstances, sortPluginsByDependencies, tagIdentityKey, validateForEachInstances };

package/dist/index.js

@@ -4,7 +4,7 @@ var __publicField = (obj, key, value) => {
   __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
   return value;
 };
-import { phaseOutput, isJayAction } from "@jay-framework/fullstack-component";
+import { phaseOutput, isJayAction, isJayStreamAction } from "@jay-framework/fullstack-component";
 import "prettier";
 import "js-beautify";
 import fs$1 from "fs";
@@ -178,10 +178,15 @@ class DevSlowlyChangingPhase {
     return phaseOutput(slowlyViewState, carryForward);
   }
 }
-async function runLoadParams(compDefinition, services) {
-  compDefinition.loadParams(services);
-}
-function runSlowlyChangingRender(compDefinition) {
+async function* runLoadParams(parts) {
+  for (const part of parts) {
+    if (part.compDefinition.loadParams) {
+      const services = resolveServices(part.compDefinition.services);
+      for await (const batch of part.compDefinition.loadParams(services)) {
+        yield batch;
+      }
+    }
+  }
 }
 var __defProp2 = Object.defineProperty;
 var __defNormalProp2 = (obj, key, value) => key in obj ? __defProp2(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
@@ -199,6 +204,7 @@ new JayAtomicType("string");
 new JayAtomicType("number");
 new JayAtomicType("boolean");
 new JayAtomicType("Date");
+new JayAtomicType("file");
 new JayAtomicType("Unknown");
 class JayObjectType {
   constructor(name, props) {
@@ -242,6 +248,9 @@ function jayTypeToJsonSchema(type) {
     if (name === "string" || name === "number" || name === "boolean") {
       return { type: name };
     }
+    if (name === "file") {
+      return { type: "string", description: "Binary file upload (JayFile)" };
+    }
     return { type: "string" };
   }
   if (isEnumType(type)) {
@@ -403,11 +412,7 @@ async function renderFastChangingData(pageParams, pageProps, carryForward, parts
           metadata: contractInfo.metadata
         }
       };
-      const fastRenderedPart = await compDefinition.fastRender(
-        partProps,
-        partSlowlyCarryForward,
-        ...services
-      );
+      const fastRenderedPart = compDefinition.slowlyRender ? await compDefinition.fastRender(partProps, partSlowlyCarryForward, ...services) : await compDefinition.fastRender(partProps, ...services);
       if (fastRenderedPart.kind === "PhaseOutput") {
         if (!key) {
           fastViewState = { ...fastViewState, ...fastRenderedPart.rendered };
@@ -576,6 +581,80 @@ ${parts.map((part) => "        " + part.clientPart).join(",\n")}
     slowViewStateDecl
   };
 }
+function buildFreezeScript(routePattern) {
+  const routePatternLiteral = routePattern ? `'${routePattern}'` : "undefined";
+  return `
+      // Page Freeze (DL#127, DL#128 iframe addendum)
+      // Sticky embed mode: URL param sets a session cookie so in-iframe navigation preserves it
+      if (new URLSearchParams(window.location.search).has('_jay_embed')) {
+        document.cookie = '_jay_embed=1;path=/;samesite=lax';
+      }
+      const __jayEmbedMode = document.cookie.split(';').some(c => c.trim().startsWith('_jay_embed='));
+
+      async function __jayDoFreeze() {
+          const automation = window.__jay?.automation;
+          if (!automation) return;
+
+          // Visual feedback: white flash
+          const flash = document.createElement('div');
+          flash.style.cssText = 'position:fixed;inset:0;background:white;z-index:999999;opacity:0.8;pointer-events:none;transition:opacity 0.3s';
+          document.body.appendChild(flash);
+          requestAnimationFrame(() => { flash.style.opacity = '0'; });
+          setTimeout(() => flash.remove(), 400);
+
+          // Audio feedback: camera shutter
+          try {
+            const ctx = new AudioContext();
+            const buf = ctx.createBuffer(1, ctx.sampleRate * 0.15, ctx.sampleRate);
+            const data = buf.getChannelData(0);
+            for (let i = 0; i < data.length; i++) {
+              data[i] = (Math.random() * 2 - 1) * Math.exp(-i / (ctx.sampleRate * 0.02));
+            }
+            const src = ctx.createBufferSource();
+            src.buffer = buf;
+            src.connect(ctx.destination);
+            src.start();
+          } catch {}
+
+          // Capture and save
+          try {
+            const state = automation.getPageState();
+            const route = window.location.pathname;
+            const routePattern = ${routePatternLiteral};
+            const resp = await fetch('/_jay/freeze', {
+              method: 'POST',
+              headers: { 'Content-Type': 'application/json' },
+              body: JSON.stringify({ route, routePattern, viewState: state.viewState }),
+            });
+            const { id } = await resp.json();
+            if (__jayEmbedMode) {
+              window.parent.postMessage({ type: 'jay:freeze', id, route }, '*');
+            } else {
+              window.open(route + '?_jay_freeze=' + id, '_blank');
+            }
+          } catch (err) {
+            console.error('[Freeze] Failed:', err);
+          }
+      }
+
+      if (__jayEmbedMode) {
+        // Notify parent of the current route on load (DL#128 route addendum)
+        window.parent.postMessage({ type: 'jay:route', route: window.location.pathname, routePattern: ${routePatternLiteral} }, '*');
+
+        // Embed mode: parent triggers freeze via postMessage
+        window.addEventListener('message', (e) => {
+          if (e.data?.type === 'jay:requestFreeze') __jayDoFreeze();
+        });
+      } else {
+        // Standalone: Alt+S / Option+S keyboard shortcut
+        document.addEventListener('keydown', (e) => {
+          if (e.altKey && e.code === 'KeyS') {
+            e.preventDefault();
+            __jayDoFreeze();
+          }
+        });
+      }`;
+}
 function buildAutomationWrap(options, mode) {
   const { enableAutomation = true, slowViewState } = options;
   const hasSlowViewState = slowViewState && Object.keys(slowViewState).length > 0;
@@ -586,6 +665,7 @@ function buildAutomationWrap(options, mode) {
   }
   const appendLine = appendDom ? `
       target.appendChild(wrapped.element.dom);` : "";
+  const freezeScript = buildFreezeScript(options.routePattern);
   if (hasSlowViewState) {
     return `
       // Wrap with automation for dev tooling
@@ -595,7 +675,8 @@ function buildAutomationWrap(options, mode) {
       registerGlobalContext(AUTOMATION_CONTEXT, wrapped.automation);
       window.__jay = window.__jay || {};
       window.__jay.automation = wrapped.automation;
-      window.dispatchEvent(new Event('jay:automation-ready'));${appendLine}`;
+      window.dispatchEvent(new Event('jay:automation-ready'));${appendLine}
+${freezeScript}`;
   }
   return `
       // Wrap with automation for dev tooling
@@ -603,7 +684,8 @@ function buildAutomationWrap(options, mode) {
       registerGlobalContext(AUTOMATION_CONTEXT, wrapped.automation);
       window.__jay = window.__jay || {};
       window.__jay.automation = wrapped.automation;
-      window.dispatchEvent(new Event('jay:automation-ready'));${appendLine}`;
+      window.dispatchEvent(new Event('jay:automation-ready'));${appendLine}
+${freezeScript}`;
 }
 async function resolveViewStatePromises(viewState) {
   const entries = Object.entries(viewState);
@@ -830,6 +912,81 @@ ${titleHtml}${headExtras ? headExtras + "\n" : ""}  </head>
   </body>
 </html>`;
 }
+async function generateFrozenPageHtml(vite, jayHtmlContent, jayHtmlFilename, jayHtmlDir, viewState, buildFolder, projectRoot, routeDir, tsConfigFilePath, sourceDir, format = "page", freezeName) {
+  const jayHtmlPath = path__default.join(jayHtmlDir, jayHtmlFilename);
+  let cached = serverModuleCache.get(jayHtmlPath);
+  if (!cached) {
+    cached = await compileAndLoadServerElement(
+      vite,
+      jayHtmlContent,
+      jayHtmlFilename,
+      jayHtmlDir,
+      buildFolder,
+      projectRoot,
+      routeDir,
+      tsConfigFilePath,
+      sourceDir
+    );
+    serverModuleCache.set(jayHtmlPath, cached);
+  }
+  const htmlChunks = [];
+  const ctx = {
+    write: (chunk) => {
+      htmlChunks.push(chunk);
+    },
+    onAsync: () => {
+    }
+  };
+  cached.renderToStream(viewState, ctx);
+  const ssrHtml = htmlChunks.join("");
+  if (format === "fragment") {
+    let inlineCss = "";
+    if (cached.cssHref) {
+      try {
+        const cssPath = cached.cssHref.replace(/^\/@fs/, "").replace(/\?.*$/, "");
+        const cssContent = await fs$2.readFile(cssPath, "utf-8");
+        inlineCss = `<style>${cssContent}</style>`;
+      } catch {
+        inlineCss = `<link rel="stylesheet" href="${cached.cssHref}" />`;
+      }
+    }
+    return `${inlineCss}
+${ssrHtml}`;
+  }
+  const headLinksHtml = cached.headLinks.map((link) => {
+    const attrs = Object.entries(link.attributes).map(([k, v]) => ` ${k}="${v}"`).join("");
+    return `    <link rel="${link.rel}" href="${link.href}"${attrs} />`;
+  }).join("\n");
+  const cssLink = cached.cssHref ? `    <link rel="stylesheet" href="${cached.cssHref}" />` : "";
+  const headExtras = [headLinksHtml, cssLink].filter((_) => _).join("\n");
+  const label = freezeName ? ` — ${freezeName}` : "";
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Frozen${label}</title>
+${headExtras ? headExtras + "\n" : ""}    <style>
+      body::before {
+        content: 'FROZEN${label ? `: ${freezeName}` : ""}';
+        position: fixed;
+        top: 0;
+        right: 0;
+        background: #1a1a2e;
+        color: #e0e0ff;
+        padding: 2px 10px;
+        font: 11px/1.6 system-ui;
+        z-index: 99999;
+        border-bottom-left-radius: 4px;
+        opacity: 0.8;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="target">${ssrHtml}</div>
+  </body>
+</html>`;
+}
 function rebaseRelativeImports(code, fromDir, toDir) {
   return code.replace(/from "(\.\.\/[^"]+)"/g, (_match, relPath) => {
     const absolutePath = path__default.resolve(fromDir, relPath);
@@ -1142,7 +1299,8 @@ class ActionRegistry {
       method: action.method,
       cacheOptions: action.cacheOptions,
       services: action.services,
-      handler: action.handler
+      handler: action.handler,
+      ...action.acceptsFiles && { acceptsFiles: true }
     };
     this.actions.set(action.actionName, entry);
   }
@@ -1226,6 +1384,16 @@ class ActionRegistry {
         }
       };
     }
+    if (action.isStreaming) {
+      return {
+        success: false,
+        error: {
+          code: "STREAMING_ACTION",
+          message: `Action '${actionName}' is a streaming action — use executeStream() instead`,
+          isActionError: false
+        }
+      };
+    }
     try {
       const services = resolveServices(action.services);
       const result = await action.handler(input, ...services);
@@ -1279,6 +1447,41 @@ class ActionRegistry {
     }
     return parts.length > 0 ? parts.join(", ") : void 0;
   }
+  // --- Streaming actions (DL#129) ---
+  /**
+   * Register a streaming action.
+   */
+  registerStream(action) {
+    const entry = {
+      actionName: action.actionName,
+      method: "POST",
+      isStreaming: true,
+      services: action.services,
+      handler: action.handler,
+      ...action.acceptsFiles && { acceptsFiles: true }
+    };
+    this.actions.set(action.actionName, entry);
+  }
+  /**
+   * Check if a registered action is a streaming action.
+   */
+  isStreaming(actionName) {
+    const action = this.actions.get(actionName);
+    return !!action?.isStreaming;
+  }
+  /**
+   * Execute a streaming action, returning an async iterable of chunks.
+   */
+  async *executeStream(actionName, input) {
+    const action = this.actions.get(actionName);
+    if (!action || !action.isStreaming) {
+      throw new Error(`Streaming action '${actionName}' not found`);
+    }
+    const services = resolveServices(action.services);
+    for await (const chunk of action.handler(input, ...services)) {
+      yield chunk;
+    }
+  }
 }
 const actionRegistry = new ActionRegistry();
 function registerAction(action) {
@@ -1402,6 +1605,15 @@ async function discoverAndRegisterActions(options) {
               `[Actions] Registered: ${exportValue.actionName}`
             );
           }
+        } else if (isJayStreamAction(exportValue)) {
+          registry.registerStream(exportValue);
+          result.actionNames.push(exportValue.actionName);
+          result.actionCount++;
+          if (verbose) {
+            getLogger().info(
+              `[Actions] Registered stream: ${exportValue.actionName}`
+            );
+          }
         }
       }
     } catch (error) {
@@ -1558,6 +1770,13 @@ async function registerNpmPluginActions(packageName, pluginConfig, pluginDir, re
         if (verbose) {
           getLogger().info(`[Actions] Registered NPM plugin action: ${registeredName}`);
         }
+      } else if (actionExport && isJayStreamAction(actionExport)) {
+        registry.registerStream(actionExport);
+        const registeredName = actionExport.actionName;
+        registeredActions.push(registeredName);
+        if (verbose) {
+          getLogger().info(`[Actions] Registered NPM plugin stream: ${registeredName}`);
+        }
       } else {
         getLogger().warn(
           `[Actions] NPM plugin "${packageName}" declares action "${actionName}" but it's not exported or not a JayAction`
@@ -1626,6 +1845,13 @@ async function discoverPluginActions(pluginPath, projectRoot, registry = actionR
         if (verbose) {
           getLogger().info(`[Actions] Registered plugin action: ${registeredName}`);
         }
+      } else if (actionExport && isJayStreamAction(actionExport)) {
+        registry.registerStream(actionExport);
+        const registeredName = actionExport.actionName;
+        registeredActions.push(registeredName);
+        if (verbose) {
+          getLogger().info(`[Actions] Registered plugin stream: ${registeredName}`);
+        }
       } else {
         getLogger().warn(
           `[Actions] Plugin "${pluginName}" declares action "${actionName}" but it's not exported or not a JayAction`
@@ -2324,6 +2550,12 @@ async function materializeContracts(options, services = /* @__PURE__ */ new Map(
           };
         });
       }
+      if (manifest.routes?.length) {
+        entry.routes = manifest.routes.map((r) => ({
+          path: r.path,
+          ...r.description && { description: r.description }
+        }));
+      }
       pluginsIndexMap.set(plugin.name, entry);
     }
     if (!dynamicOnly && manifest.contracts) {
@@ -2448,7 +2680,8 @@ async function materializeContracts(options, services = /* @__PURE__ */ new Map(
       contracts: data.contracts,
       ...data.actions && data.actions.length > 0 && { actions: data.actions },
       ...data.services?.length && { services: data.services },
-      ...data.contexts?.length && { contexts: data.contexts }
+      ...data.contexts?.length && { contexts: data.contexts },
+      ...data.routes?.length && { routes: data.routes }
     }))
   };
   fs.mkdirSync(outputDir, { recursive: true });
@@ -2505,6 +2738,12 @@ async function listContracts(options) {
           };
         });
       }
+      if (manifest.routes?.length) {
+        entry.routes = manifest.routes.map((r) => ({
+          path: r.path,
+          ...r.description && { description: r.description }
+        }));
+      }
       pluginsMap.set(plugin.name, entry);
     }
     if (!dynamicOnly && manifest.contracts) {
@@ -2551,7 +2790,8 @@ async function listContracts(options) {
       path: data.path,
       contracts: data.contracts,
       ...data.services?.length && { services: data.services },
-      ...data.contexts?.length && { contexts: data.contexts }
+      ...data.contexts?.length && { contexts: data.contexts },
+      ...data.routes?.length && { routes: data.routes }
     }))
   };
 }
@@ -2705,6 +2945,7 @@ export {
   executePluginServerInits,
   executePluginSetup,
   generateClientScript,
+  generateFrozenPageHtml,
   generatePromiseReconstruction,
   generateSSRPageHtml,
   getActionCacheHeaders,
@@ -2735,7 +2976,6 @@ export {
   runInitCallbacks,
   runLoadParams,
   runShutdownCallbacks,
-  runSlowlyChangingRender,
   scanPlugins,
   serializeHeadTags,
   setClientInitData,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/stack-server-runtime",
-  "version": "0.15.6",
+  "version": "0.16.1",
   "license": "Apache-2.0",
   "main": "dist/index.js",
   "types": "dist/index.d.mts",
@@ -26,21 +26,21 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@jay-framework/compiler-jay-html": "^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/ssr-runtime": "^0.15.6",
-    "@jay-framework/stack-route-scanner": "^0.15.6",
-    "@jay-framework/view-state-merge": "^0.15.6",
+    "@jay-framework/compiler-jay-html": "^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/ssr-runtime": "^0.16.1",
+    "@jay-framework/stack-route-scanner": "^0.16.1",
+    "@jay-framework/view-state-merge": "^0.16.1",
     "yaml": "^2.3.4"
   },
   "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",
     "@types/express": "^5.0.2",
     "@types/node": "^22.15.21",
     "nodemon": "^3.0.3",