@jay-framework/stack-server-runtime 0.15.5 → 0.16.0

package/dist/index.d.ts

@@ -1,5 +1,4 @@
-import { AnyJayStackComponentDefinition, PageProps, AnySlowlyRenderResult, UrlParams, JayStackComponentDefinition, AnyFastRenderResult, HttpMethod, CacheOptions, JayAction, JayActionDefinition, 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';
@@ -49,6 +48,10 @@ interface LoadedPageParts {
     discoveredInstances: DiscoveredHeadlessInstance[];
     /** Discovered forEach <jay:xxx> instances from the jay-html (DL#109) */
     forEachInstances: ForEachHeadlessInstance[];
+    /** Absolute paths to linked CSS files (from <link rel="stylesheet">) for dev-server watching */
+    linkedCssFiles: string[];
+    /** Absolute paths to headfull FS component jay-html files for dev-server watching */
+    linkedComponentFiles: string[];
 }
 interface LoadPagePartsOptions {
     /**
@@ -72,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.
@@ -97,6 +103,8 @@ interface InstancePhaseData {
     }>;
     /** CarryForward per instance (keyed by coordinate path, e.g. "p1/product-card:0") */
     carryForwards: Record<string, object>;
+    /** Slow ViewState per instance (keyed by coordinate path) */
+    slowViewStates?: Record<string, object>;
     /** ForEach instances that need fast-phase per-item rendering */
     forEachInstances?: ForEachHeadlessInstance[];
 }
@@ -185,23 +193,43 @@ 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;
 }
+/**
+ * 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.
  */
@@ -252,7 +280,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.
      *
@@ -304,6 +332,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.
@@ -319,7 +359,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
@@ -569,6 +609,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().
@@ -626,7 +668,23 @@ declare function clearServerElementCache(): void;
  * 3. Build hydration script (uses ?jay-hydrate query for hydrate target)
  * 4. Return full HTML page string
  */
-declare function generateSSRPageHtml(vite: ViteDevServer, jayHtmlContent: string, jayHtmlFilename: string, jayHtmlDir: string, viewState: object, jayHtmlImportPath: string, parts: DevServerPagePart[], carryForward: object, trackByMap: TrackByMap, clientInitData: Record<string, Record<string, any>>, buildFolder: string, projectRoot: string, routeDir: string, tsConfigFilePath?: string, projectInit?: ProjectClientInitInfo, pluginInits?: PluginClientInitInfo[], options?: GenerateClientScriptOptions): Promise<string>;
+declare function generateSSRPageHtml(vite: ViteDevServer, jayHtmlContent: string, jayHtmlFilename: string, jayHtmlDir: string, viewState: object, jayHtmlImportPath: string, parts: DevServerPagePart[], carryForward: object, trackByMap: TrackByMap, clientInitData: Record<string, Record<string, any>>, buildFolder: string, projectRoot: string, routeDir: string, tsConfigFilePath?: string, projectInit?: ProjectClientInitInfo, pluginInits?: PluginClientInitInfo[], options?: GenerateClientScriptOptions, 
+/** Source directory for headfull FS file resolution when jayHtmlDir is pre-rendered */
+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.
@@ -906,10 +964,30 @@ interface ActionIndexEntry {
 /** Contract entry within a plugin in plugins-index.yaml */
 interface PluginContractEntry {
     name: string;
+    description?: string;
     type: 'static' | 'dynamic';
     path: string;
     metadata?: Record<string, unknown>;
 }
+/** Service entry in plugins-index.yaml (DL#125) */
+interface ServiceIndexEntry {
+    name: string;
+    marker: string;
+    description?: string;
+    doc?: string;
+}
+/** Context entry in plugins-index.yaml (DL#125) */
+interface ContextIndexEntry {
+    name: string;
+    marker: string;
+    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;
@@ -917,6 +995,12 @@ interface PluginsIndexEntry {
     contracts: PluginContractEntry[];
     /** Actions with .jay-action metadata (exposed to AI agents) */
     actions?: ActionIndexEntry[];
+    /** Server-side services provided by this plugin (DL#125) */
+    services?: ServiceIndexEntry[];
+    /** Client-side contexts provided by this plugin (DL#125) */
+    contexts?: ContextIndexEntry[];
+    /** Plugin-provided routes (DL#130) */
+    routes?: RouteIndexEntry[];
 }
 interface PluginsIndex {
     plugins: PluginsIndexEntry[];
@@ -1150,4 +1234,27 @@ declare function executePluginReferences(plugin: PluginWithReferences, options:
     verbose?: boolean;
 }): Promise<PluginReferencesResult>;
 
-export { type ActionDiscoveryOptions, type ActionDiscoveryResult, type ActionErrorResponse, type ActionExecutionResult, type ActionIndexEntry, type ActionMetadata, ActionRegistry, type ActionSchema, 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, 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, onInit, onShutdown, parseActionMetadata, preparePluginClientInits, registerAction, registerService, renderFastChangingData, resolveActionMetadataPath, resolveServices, resolveViewStatePromises, runInitCallbacks, runLoadParams, runShutdownCallbacks, runSlowlyChangingRender, scanPlugins, setClientInitData, slowRenderInstances, sortPluginsByDependencies, validateForEachInstances };
+/**
+ * Head tag utilities for SSR head injection (Design Log #127).
+ *
+ * Components declare HeadTag[] via phaseOutput(). The SSR pipeline collects
+ * tags from all sources, deduplicates with last-write-wins + collision warning,
+ * and serializes to HTML for injection into <head>.
+ */
+
+/**
+ * Compute a unique identity key for deduplication.
+ * Returns undefined for tags that should always be included (no dedup).
+ */
+declare function tagIdentityKey(tag: HeadTag): string | undefined;
+/**
+ * Merge head tags from multiple sources with last-write-wins.
+ * Warns on collision via logger.
+ */
+declare function mergeHeadTags(sources: HeadTag[][]): HeadTag[];
+/**
+ * Serialize an array of HeadTag objects into an HTML string.
+ */
+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 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,19 +4,19 @@ 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";
 import path$1 from "path";
 import YAML from "yaml";
 import { createRequire } from "module";
-import { parseJayFile, JAY_IMPORT_RESOLVER, generateServerElementFile, discoverHeadlessInstances, parseAction } from "@jay-framework/compiler-jay-html";
+import { parseJayFile, JAY_IMPORT_RESOLVER, generateServerElementFile, injectHeadfullFSTemplates, discoverHeadlessInstances, assignCoordinatesToJayHtml, parseAction } from "@jay-framework/compiler-jay-html";
+import { getLogger } from "@jay-framework/logger";
 import fs$2 from "node:fs/promises";
 import * as path from "node:path";
 import path__default from "node:path";
 import crypto from "node:crypto";
-import { getLogger } from "@jay-framework/logger";
 import * as fs from "node:fs";
 import { createRequire as createRequire$1 } from "node:module";
 const serviceRegistry = /* @__PURE__ */ new Map();
@@ -87,6 +87,7 @@ class DevSlowlyChangingPhase {
   async runSlowlyForPage(pageParams, pageProps, parts, discoveredInstances, headlessInstanceComponents, jayHtmlPath) {
     let slowlyViewState = {};
     let carryForward = {};
+    const slowHeadTagSources = [];
     for (const part of parts) {
       const { compDefinition, key, contractInfo } = part;
       if (compDefinition.slowlyRender) {
@@ -111,6 +112,9 @@ class DevSlowlyChangingPhase {
             slowlyViewState[key] = slowlyRenderedPart.rendered;
             carryForward[key] = slowlyRenderedPart.carryForward;
           }
+          if (slowlyRenderedPart.headTags) {
+            slowHeadTagSources.push(slowlyRenderedPart.headTags);
+          }
         } else
           return slowlyRenderedPart;
       }
@@ -158,6 +162,9 @@ class DevSlowlyChangingPhase {
               contract: comp.contract,
               slowViewState: slowResult.rendered
             });
+            if (slowResult.headTags) {
+              slowHeadTagSources.push(slowResult.headTags);
+            }
           }
         }
       }
@@ -165,13 +172,21 @@ class DevSlowlyChangingPhase {
       carryForward.__instanceSlowViewStates = instanceSlowViewStates;
       carryForward.__instanceResolvedData = instanceResolvedData;
     }
+    if (slowHeadTagSources.length > 0) {
+      carryForward.__slowHeadTags = slowHeadTagSources;
+    }
     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;
@@ -378,6 +393,7 @@ function resolveBinding(binding, item) {
 async function renderFastChangingData(pageParams, pageProps, carryForward, parts, instancePhaseData, forEachInstances, headlessInstanceComponents, mergedSlowViewState, query = {}) {
   let fastViewState = {};
   let fastCarryForward = {};
+  const fastHeadTagSources = [];
   for (const part of parts) {
     const { compDefinition, key, contractInfo } = part;
     if (compDefinition.fastRender) {
@@ -392,11 +408,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 };
@@ -405,6 +417,9 @@ async function renderFastChangingData(pageParams, pageProps, carryForward, parts
           fastViewState[key] = fastRenderedPart.rendered;
           fastCarryForward[key] = fastRenderedPart.carryForward;
         }
+        if (fastRenderedPart.headTags) {
+          fastHeadTagSources.push(fastRenderedPart.headTags);
+        }
       } else
         return fastRenderedPart;
     }
@@ -419,18 +434,25 @@ async function renderFastChangingData(pageParams, pageProps, carryForward, parts
     for (const instance of instancePhaseData.discovered) {
       const coordKey = instance.coordinate.join("/");
       const comp = componentByContractName.get(instance.contractName);
-      if (!comp || !comp.compDefinition.fastRender)
+      if (!comp)
         continue;
-      const services = resolveServices(comp.compDefinition.services);
-      const cf = instancePhaseData.carryForwards[coordKey];
-      const instanceProps = { ...instance.props, query };
-      const fastResult = comp.compDefinition.slowlyRender ? await comp.compDefinition.fastRender(instanceProps, cf, ...services) : await comp.compDefinition.fastRender(instanceProps, ...services);
-      if (fastResult.kind === "PhaseOutput") {
-        const instanceSlowVS = carryForward?.__instanceSlowViewStates?.[coordKey];
-        instanceViewStates[coordKey] = instanceSlowVS ? { ...instanceSlowVS, ...fastResult.rendered } : fastResult.rendered;
-        if (fastResult.carryForward) {
-          instanceCarryForwards[coordKey] = fastResult.carryForward;
+      const instanceSlowVS = instancePhaseData.slowViewStates?.[coordKey] ?? carryForward?.__instanceSlowViewStates?.[coordKey];
+      if (comp.compDefinition.fastRender) {
+        const services = resolveServices(comp.compDefinition.services);
+        const cf = instancePhaseData.carryForwards[coordKey];
+        const instanceProps = { ...instance.props, query };
+        const fastResult = comp.compDefinition.slowlyRender ? await comp.compDefinition.fastRender(instanceProps, cf, ...services) : await comp.compDefinition.fastRender(instanceProps, ...services);
+        if (fastResult.kind === "PhaseOutput") {
+          instanceViewStates[coordKey] = instanceSlowVS ? { ...instanceSlowVS, ...fastResult.rendered } : fastResult.rendered;
+          if (fastResult.carryForward) {
+            instanceCarryForwards[coordKey] = fastResult.carryForward;
+          }
+          if (fastResult.headTags) {
+            fastHeadTagSources.push(fastResult.headTags);
+          }
         }
+      } else {
+        instanceViewStates[coordKey] = instanceSlowVS ?? {};
       }
     }
   }
@@ -491,7 +513,11 @@ async function renderFastChangingData(pageParams, pageProps, carryForward, parts
   if (Object.keys(instanceCarryForwards).length > 0) {
     fastCarryForward.__headlessInstances = instanceCarryForwards;
   }
-  return Promise.resolve(phaseOutput(fastViewState, fastCarryForward));
+  const result = phaseOutput(fastViewState, fastCarryForward);
+  if (fastHeadTagSources.length > 0) {
+    result.headTags = fastHeadTagSources.flat();
+  }
+  return Promise.resolve(result);
 }
 function generatePromiseReconstruction(outcomes) {
   if (outcomes.length === 0)
@@ -551,6 +577,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;
@@ -561,6 +661,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
@@ -570,7 +671,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
@@ -578,7 +680,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);
@@ -635,7 +738,8 @@ async function generateClientScript(defaultViewState, fastCarryForward, parts, j
       import { render } from '${jayHtmlPath}';
       ${partImports}${slowViewStateDecl}
       const viewState = ${JSON.stringify(defaultViewState)};
-${generatePromiseReconstruction(outcomes)}      const fastCarryForward = ${JSON.stringify(fastCarryForward)};
+${generatePromiseReconstruction(outcomes)}      
+      const fastCarryForward = ${JSON.stringify(fastCarryForward)};
       const trackByMap = ${JSON.stringify(trackByMap)};
 ${clientInitExecution}
       const target = document.getElementById('target');
@@ -651,6 +755,65 @@ function asyncSwapScript(id, html) {
   const escapedHtml = html.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
   return `<script>(function(){var t=document.querySelector('[jay-async="${id}:pending"]');if(t){var d=document.createElement('div');d.innerHTML='${escapedHtml}';t.replaceWith(d.firstChild);}window.__jay&&window.__jay.hydrateAsync&&window.__jay.hydrateAsync('${id}');})()<\/script>`;
 }
+function tagIdentityKey(tag) {
+  const t = tag.tag.toLowerCase();
+  if (t === "title")
+    return "title";
+  if (t === "meta") {
+    if (tag.attrs?.name)
+      return `meta:name:${tag.attrs.name}`;
+    if (tag.attrs?.property)
+      return `meta:property:${tag.attrs.property}`;
+    if (tag.attrs?.charset !== void 0)
+      return "meta:charset";
+    return void 0;
+  }
+  if (t === "link") {
+    if (tag.attrs?.rel === "canonical")
+      return "link:canonical";
+    return void 0;
+  }
+  return void 0;
+}
+function mergeHeadTags(sources) {
+  const byKey = /* @__PURE__ */ new Map();
+  const result = [];
+  for (let si = 0; si < sources.length; si++) {
+    for (const tag of sources[si]) {
+      const key = tagIdentityKey(tag);
+      if (key) {
+        const existing = byKey.get(key);
+        if (existing && existing.sourceIndex !== si) {
+          getLogger().warn(
+            `[head-tags] Collision on "${key}" — overwriting with tag from source ${si}`
+          );
+        }
+        byKey.set(key, { tag, sourceIndex: si });
+      } else {
+        result.push(tag);
+      }
+    }
+  }
+  return [...[...byKey.values()].map((v) => v.tag), ...result];
+}
+function escapeAttr(value) {
+  return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function escapeHtml(value) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+const VOID_ELEMENTS = /* @__PURE__ */ new Set(["meta", "link", "base", "br", "hr", "img", "input"]);
+function serializeHeadTags(tags) {
+  return tags.map((tag) => {
+    const t = tag.tag.toLowerCase();
+    const attrs = tag.attrs ? Object.entries(tag.attrs).map(([k, v]) => ` ${k}="${escapeAttr(v)}"`).join("") : "";
+    if (VOID_ELEMENTS.has(t)) {
+      return `    <${t}${attrs} />`;
+    }
+    const children = tag.children ? escapeHtml(tag.children) : "";
+    return `    <${t}${attrs}>${children}</${t}>`;
+  }).join("\n");
+}
 const serverModuleCache = /* @__PURE__ */ new Map();
 function invalidateServerElementCache(jayHtmlPath) {
   if (serverModuleCache.delete(jayHtmlPath)) {
@@ -660,7 +823,7 @@ function invalidateServerElementCache(jayHtmlPath) {
 function clearServerElementCache() {
   serverModuleCache.clear();
 }
-async function generateSSRPageHtml(vite, jayHtmlContent, jayHtmlFilename, jayHtmlDir, viewState, jayHtmlImportPath, parts, carryForward, trackByMap = {}, clientInitData2 = {}, buildFolder, projectRoot, routeDir, tsConfigFilePath, projectInit, pluginInits = [], options = {}) {
+async function generateSSRPageHtml(vite, jayHtmlContent, jayHtmlFilename, jayHtmlDir, viewState, jayHtmlImportPath, parts, carryForward, trackByMap = {}, clientInitData2 = {}, buildFolder, projectRoot, routeDir, tsConfigFilePath, projectInit, pluginInits = [], options = {}, sourceDir, headTags) {
   const jayHtmlPath = path__default.join(jayHtmlDir, jayHtmlFilename);
   let cached = serverModuleCache.get(jayHtmlPath);
   if (!cached) {
@@ -672,7 +835,8 @@ async function generateSSRPageHtml(vite, jayHtmlContent, jayHtmlFilename, jayHtm
       buildFolder,
       projectRoot,
       routeDir,
-      tsConfigFilePath
+      tsConfigFilePath,
+      sourceDir
     );
     serverModuleCache.set(jayHtmlPath, cached);
   }
@@ -728,20 +892,97 @@ async function generateSSRPageHtml(vite, jayHtmlContent, jayHtmlFilename, jayHtm
     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 headTagsHtml = headTags && headTags.length > 0 ? serializeHeadTags(headTags) : "";
+  const hasCustomTitle = headTags?.some((t) => t.tag.toLowerCase() === "title");
+  const titleHtml = hasCustomTitle ? "" : "    <title>Vite + TS</title>\n";
+  const headExtras = [headLinksHtml, cssLink, headTagsHtml].filter((_) => _).join("\n");
   return `<!doctype html>
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Vite + TS</title>
-${headExtras ? headExtras + "\n" : ""}  </head>
+${titleHtml}${headExtras ? headExtras + "\n" : ""}  </head>
   <body>
     <div id="target">${ssrHtml}</div>${asyncScripts}
     ${hydrationScript}
   </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);
@@ -752,14 +993,15 @@ function rebaseRelativeImports(code, fromDir, toDir) {
     return `from "${newRelPath}"`;
   });
 }
-async function compileAndLoadServerElement(vite, jayHtmlContent, jayHtmlFilename, jayHtmlDir, buildFolder, projectRoot, routeDir, tsConfigFilePath) {
+async function compileAndLoadServerElement(vite, jayHtmlContent, jayHtmlFilename, jayHtmlDir, buildFolder, projectRoot, routeDir, tsConfigFilePath, sourceDir) {
   const jayFile = await parseJayFile(
     jayHtmlContent,
     jayHtmlFilename,
     jayHtmlDir,
     { relativePath: tsConfigFilePath },
     JAY_IMPORT_RESOLVER,
-    projectRoot
+    projectRoot,
+    sourceDir
   );
   const parsedJayFile = checkValidationErrors(jayFile);
   const pageName = jayHtmlFilename.replace(".jay-html", "");
@@ -785,6 +1027,8 @@ async function compileAndLoadServerElement(vite, jayHtmlContent, jayHtmlFilename
   if (existingModule) {
     vite.moduleGraph.invalidateModule(existingModule);
   }
+  const jayHtmlPath = path__default.join(serverElementDir, jayHtmlFilename);
+  invalidateJayHtmlModules(vite, jayHtmlPath);
   const serverModule = await vite.ssrLoadModule(serverElementPath);
   let cssHref;
   if (parsedJayFile.css) {
@@ -806,6 +1050,34 @@ async function compileAndLoadServerElement(vite, jayHtmlContent, jayHtmlFilename
     cssHref
   };
 }
+function invalidateJayHtmlModules(vite, jayHtmlPath) {
+  let count = 0;
+  const byFile = vite.moduleGraph.getModulesByFile(jayHtmlPath);
+  if (byFile) {
+    for (const mod of byFile) {
+      vite.moduleGraph.invalidateModule(mod);
+      count++;
+    }
+  }
+  const knownIds = [jayHtmlPath + ".ts", jayHtmlPath + JAY_QUERY_HYDRATE + ".ts"];
+  for (const id of knownIds) {
+    const mod = vite.moduleGraph.getModuleById(id);
+    if (mod) {
+      vite.moduleGraph.invalidateModule(mod);
+      count++;
+    }
+  }
+  const idMap = vite.moduleGraph.idToModuleMap;
+  for (const [id, mod] of idMap) {
+    if (id.includes(jayHtmlPath)) {
+      vite.moduleGraph.invalidateModule(mod);
+      count++;
+    }
+  }
+  if (count > 0) {
+    getLogger().info(`[SSR] Invalidated ${count} Vite module(s) for ${jayHtmlPath}`);
+  }
+}
 function generateHydrationScript(defaultViewState, fastCarryForward, parts, jayHtmlPath, trackByMap = {}, clientInitData2 = {}, projectInit, pluginInits = [], options = {}, asyncOutcomes = []) {
   const {
     partImports,
@@ -907,7 +1179,29 @@ async function loadPageParts(vite, route, pagesBase, projectBase, jayRollupConfi
       contract: hi.contract,
       contractPath: hi.contractPath
     }));
-    const discoveryResult = headlessInstanceComponents.length > 0 ? discoverHeadlessInstances(jayHtmlSource) : { instances: [], forEachInstances: [], preRenderedJayHtml: jayHtmlSource };
+    const jayHtmlForDiscovery = injectHeadfullFSTemplates(
+      jayHtmlSource,
+      dirName,
+      JAY_IMPORT_RESOLVER
+    );
+    let discoveryResult;
+    if (headlessInstanceComponents.length > 0) {
+      const firstDiscovery = discoverHeadlessInstances(jayHtmlForDiscovery);
+      const headlessContractNameSet = new Set(
+        jayHtml.headlessImports.map((hi) => hi.contractName)
+      );
+      const jayHtmlWithCoords = assignCoordinatesToJayHtml(
+        firstDiscovery.preRenderedJayHtml,
+        headlessContractNameSet
+      );
+      discoveryResult = discoverHeadlessInstances(jayHtmlWithCoords);
+    } else {
+      discoveryResult = {
+        instances: [],
+        forEachInstances: [],
+        preRenderedJayHtml: jayHtmlSource
+      };
+    }
     return {
       parts,
       serverTrackByMap: jayHtml.serverTrackByMap,
@@ -916,7 +1210,9 @@ async function loadPageParts(vite, route, pagesBase, projectBase, jayRollupConfi
       headlessContracts,
       headlessInstanceComponents,
       discoveredInstances: discoveryResult.instances,
-      forEachInstances: discoveryResult.forEachInstances
+      forEachInstances: discoveryResult.forEachInstances,
+      linkedCssFiles: jayHtml.linkedCssFiles ?? [],
+      linkedComponentFiles: jayHtml.linkedComponentFiles ?? []
     };
   });
 }
@@ -931,31 +1227,32 @@ async function slowRenderInstances(discovered, headlessInstanceComponents) {
   const carryForwards = {};
   for (const instance of discovered) {
     const comp = componentByContractName.get(instance.contractName);
-    if (!comp || !comp.compDefinition.slowlyRender) {
+    if (!comp)
       continue;
-    }
     const contractProps = comp.contract?.props ?? [];
     const normalizedProps = {};
     for (const [key, value] of Object.entries(instance.props)) {
       const match = contractProps.find((p) => p.name.toLowerCase() === key.toLowerCase());
       normalizedProps[match ? match.name : key] = value;
     }
-    const services = resolveServices(comp.compDefinition.services);
-    const slowResult = await comp.compDefinition.slowlyRender(normalizedProps, ...services);
-    if (slowResult.kind === "PhaseOutput") {
-      const coordKey = instance.coordinate.join("/");
-      resolvedData.push({
-        coordinate: instance.coordinate,
-        contract: comp.contract,
-        slowViewState: slowResult.rendered
-      });
-      slowViewStates[coordKey] = slowResult.rendered;
-      carryForwards[coordKey] = slowResult.carryForward;
-      discoveredForFast.push({
-        contractName: instance.contractName,
-        props: normalizedProps,
-        coordinate: instance.coordinate
-      });
+    discoveredForFast.push({
+      contractName: instance.contractName,
+      props: normalizedProps,
+      coordinate: instance.coordinate
+    });
+    if (comp.compDefinition.slowlyRender) {
+      const services = resolveServices(comp.compDefinition.services);
+      const slowResult = await comp.compDefinition.slowlyRender(normalizedProps, ...services);
+      if (slowResult.kind === "PhaseOutput") {
+        const coordKey = instance.coordinate.join("/");
+        resolvedData.push({
+          coordinate: instance.coordinate,
+          contract: comp.contract,
+          slowViewState: slowResult.rendered
+        });
+        slowViewStates[coordKey] = slowResult.rendered;
+        carryForwards[coordKey] = slowResult.carryForward;
+      }
     }
   }
   if (discoveredForFast.length === 0) {
@@ -964,7 +1261,7 @@ async function slowRenderInstances(discovered, headlessInstanceComponents) {
   return {
     resolvedData,
     slowViewStates,
-    instancePhaseData: { discovered: discoveredForFast, carryForwards }
+    instancePhaseData: { discovered: discoveredForFast, carryForwards, slowViewStates }
   };
 }
 function validateForEachInstances(forEachInstances, headlessInstanceComponents) {
@@ -1082,6 +1379,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);
@@ -1135,6 +1442,40 @@ 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
+    };
+    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) {
@@ -1258,6 +1599,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) {
@@ -1414,6 +1764,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`
@@ -1482,6 +1839,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`
@@ -2153,11 +2517,40 @@ async function materializeContracts(options, services = /* @__PURE__ */ new Map(
     const { manifest } = plugin;
     const pluginRelPath = path.relative(projectRoot, plugin.pluginPath);
     if (!pluginsIndexMap.has(plugin.name)) {
-      pluginsIndexMap.set(plugin.name, {
+      const entry = {
         path: "./" + pluginRelPath.replace(/\\/g, "/"),
         contracts: [],
         actions: []
-      });
+      };
+      if (manifest.services?.length) {
+        entry.services = manifest.services.map((s2) => {
+          const docPath = s2.doc ? "./" + path.relative(projectRoot, path.resolve(plugin.pluginPath, s2.doc)) : void 0;
+          return {
+            name: s2.name,
+            marker: s2.marker,
+            ...s2.description && { description: s2.description },
+            ...docPath && { doc: docPath }
+          };
+        });
+      }
+      if (manifest.contexts?.length) {
+        entry.contexts = manifest.contexts.map((c) => {
+          const docPath = c.doc ? "./" + path.relative(projectRoot, path.resolve(plugin.pluginPath, c.doc)) : void 0;
+          return {
+            name: c.name,
+            marker: c.marker,
+            ...c.description && { description: c.description },
+            ...docPath && { doc: docPath }
+          };
+        });
+      }
+      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) {
       for (const contract of manifest.contracts) {
@@ -2167,8 +2560,20 @@ async function materializeContracts(options, services = /* @__PURE__ */ new Map(
           projectRoot
         );
         const relativePath = path.relative(projectRoot, contractPath);
+        let description = contract.description;
+        if (!description) {
+          try {
+            const contractContent = fs.readFileSync(contractPath, "utf-8");
+            const parsed = YAML.parse(contractContent);
+            if (parsed?.description && typeof parsed.description === "string") {
+              description = parsed.description;
+            }
+          } catch {
+          }
+        }
         pluginsIndexMap.get(plugin.name).contracts.push({
           name: contract.name,
+          ...description && { description },
           type: "static",
           path: "./" + relativePath
         });
@@ -2202,8 +2607,17 @@ async function materializeContracts(options, services = /* @__PURE__ */ new Map(
             const filePath = path.join(pluginOutputDir, fileName);
             fs.writeFileSync(filePath, generated.yaml, "utf-8");
             const relativePath = path.relative(projectRoot, filePath);
+            let dynDescription;
+            try {
+              const parsedYaml = YAML.parse(generated.yaml);
+              if (parsedYaml?.description && typeof parsedYaml.description === "string") {
+                dynDescription = parsedYaml.description;
+              }
+            } catch {
+            }
             const contractEntry = {
               name: fullName,
+              ...dynDescription && { description: dynDescription },
               type: "dynamic",
               path: "./" + relativePath,
               ...generated.metadata && { metadata: generated.metadata }
@@ -2239,7 +2653,10 @@ async function materializeContracts(options, services = /* @__PURE__ */ new Map(
         if (!metadata)
           continue;
         const actionRelPath = path.relative(projectRoot, metadataFilePath);
-        pluginsIndexMap.get(plugin.name).actions.push({
+        const pluginEntry = pluginsIndexMap.get(plugin.name);
+        if (!pluginEntry.actions)
+          pluginEntry.actions = [];
+        pluginEntry.actions.push({
           name: metadata.name,
           description: metadata.description,
           path: "./" + actionRelPath.replace(/\\/g, "/")
@@ -2255,7 +2672,10 @@ async function materializeContracts(options, services = /* @__PURE__ */ new Map(
       name,
       path: data.path,
       contracts: data.contracts,
-      ...data.actions.length > 0 && { actions: data.actions }
+      ...data.actions && data.actions.length > 0 && { actions: data.actions },
+      ...data.services?.length && { services: data.services },
+      ...data.contexts?.length && { contexts: data.contexts },
+      ...data.routes?.length && { routes: data.routes }
     }))
   };
   fs.mkdirSync(outputDir, { recursive: true });
@@ -2286,10 +2706,39 @@ async function listContracts(options) {
     const { manifest } = plugin;
     const pluginRelPath = path.relative(projectRoot, plugin.pluginPath);
     if (!pluginsMap.has(plugin.name)) {
-      pluginsMap.set(plugin.name, {
+      const entry = {
         path: "./" + pluginRelPath.replace(/\\/g, "/"),
         contracts: []
-      });
+      };
+      if (manifest.services?.length) {
+        entry.services = manifest.services.map((s2) => {
+          const docPath = s2.doc ? "./" + path.relative(projectRoot, path.resolve(plugin.pluginPath, s2.doc)) : void 0;
+          return {
+            name: s2.name,
+            marker: s2.marker,
+            ...s2.description && { description: s2.description },
+            ...docPath && { doc: docPath }
+          };
+        });
+      }
+      if (manifest.contexts?.length) {
+        entry.contexts = manifest.contexts.map((c) => {
+          const docPath = c.doc ? "./" + path.relative(projectRoot, path.resolve(plugin.pluginPath, c.doc)) : void 0;
+          return {
+            name: c.name,
+            marker: c.marker,
+            ...c.description && { description: c.description },
+            ...docPath && { doc: docPath }
+          };
+        });
+      }
+      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) {
       for (const contract of manifest.contracts) {
@@ -2299,8 +2748,20 @@ async function listContracts(options) {
           projectRoot
         );
         const relativePath = path.relative(projectRoot, contractPath);
+        let listDescription = contract.description;
+        if (!listDescription) {
+          try {
+            const contractContent = fs.readFileSync(contractPath, "utf-8");
+            const parsed = YAML.parse(contractContent);
+            if (parsed?.description && typeof parsed.description === "string") {
+              listDescription = parsed.description;
+            }
+          } catch {
+          }
+        }
         pluginsMap.get(plugin.name).contracts.push({
           name: contract.name,
+          ...listDescription && { description: listDescription },
           type: "static",
           path: "./" + relativePath
         });
@@ -2321,7 +2782,10 @@ async function listContracts(options) {
     plugins: Array.from(pluginsMap.entries()).map(([name, data]) => ({
       name,
       path: data.path,
-      contracts: data.contracts
+      contracts: data.contracts,
+      ...data.services?.length && { services: data.services },
+      ...data.contexts?.length && { contexts: data.contexts },
+      ...data.routes?.length && { routes: data.routes }
     }))
   };
 }
@@ -2475,6 +2939,7 @@ export {
   executePluginServerInits,
   executePluginSetup,
   generateClientScript,
+  generateFrozenPageHtml,
   generatePromiseReconstruction,
   generateSSRPageHtml,
   getActionCacheHeaders,
@@ -2491,6 +2956,7 @@ export {
   loadActionMetadata,
   loadPageParts,
   materializeContracts,
+  mergeHeadTags,
   onInit,
   onShutdown,
   parseActionMetadata,
@@ -2504,10 +2970,11 @@ export {
   runInitCallbacks,
   runLoadParams,
   runShutdownCallbacks,
-  runSlowlyChangingRender,
   scanPlugins,
+  serializeHeadTags,
   setClientInitData,
   slowRenderInstances,
   sortPluginsByDependencies,
+  tagIdentityKey,
   validateForEachInstances
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/stack-server-runtime",
-  "version": "0.15.5",
+  "version": "0.16.0",
   "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.5",
-    "@jay-framework/compiler-shared": "^0.15.5",
-    "@jay-framework/component": "^0.15.5",
-    "@jay-framework/fullstack-component": "^0.15.5",
-    "@jay-framework/logger": "^0.15.5",
-    "@jay-framework/runtime": "^0.15.5",
-    "@jay-framework/ssr-runtime": "^0.15.5",
-    "@jay-framework/stack-route-scanner": "^0.15.5",
-    "@jay-framework/view-state-merge": "^0.15.5",
+    "@jay-framework/compiler-jay-html": "^0.16.0",
+    "@jay-framework/compiler-shared": "^0.16.0",
+    "@jay-framework/component": "^0.16.0",
+    "@jay-framework/fullstack-component": "^0.16.0",
+    "@jay-framework/logger": "^0.16.0",
+    "@jay-framework/runtime": "^0.16.0",
+    "@jay-framework/ssr-runtime": "^0.16.0",
+    "@jay-framework/stack-route-scanner": "^0.16.0",
+    "@jay-framework/view-state-merge": "^0.16.0",
     "yaml": "^2.3.4"
   },
   "devDependencies": {
-    "@jay-framework/dev-environment": "^0.15.5",
-    "@jay-framework/jay-cli": "^0.15.5",
-    "@jay-framework/stack-client-runtime": "^0.15.5",
+    "@jay-framework/dev-environment": "^0.16.0",
+    "@jay-framework/jay-cli": "^0.16.0",
+    "@jay-framework/stack-client-runtime": "^0.16.0",
     "@types/express": "^5.0.2",
     "@types/node": "^22.15.21",
     "nodemon": "^3.0.3",