npm - @jay-framework/stack-server-runtime - Versions diffs - 0.15.5 → 0.15.6 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/dist/index.d.ts CHANGED Viewed

@@ -1,4 +1,4 @@
-import { AnyJayStackComponentDefinition, PageProps, AnySlowlyRenderResult, UrlParams, JayStackComponentDefinition, AnyFastRenderResult, HttpMethod, CacheOptions, JayAction, JayActionDefinition, ServiceMarker } from '@jay-framework/fullstack-component';
+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 { ViteDevServer } from 'vite';
 import { JayRoute } from '@jay-framework/stack-route-scanner';
@@ -49,6 +49,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 {
     /**
@@ -97,6 +101,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[];
 }
@@ -626,7 +632,11 @@ 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>;
 /**
  * Service registry for Jay Stack server-side dependency injection.
@@ -906,10 +916,25 @@ 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;
+}
 /** Entry for plugins-index.yaml (Design Log #85) */
 interface PluginsIndexEntry {
     name: string;
@@ -917,6 +942,10 @@ 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[];
 }
 interface PluginsIndex {
     plugins: PluginsIndexEntry[];
@@ -1150,4 +1179,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 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 };

package/dist/index.js CHANGED Viewed

@@ -11,12 +11,12 @@ 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,6 +172,9 @@ class DevSlowlyChangingPhase {
       carryForward.__instanceSlowViewStates = instanceSlowViewStates;
       carryForward.__instanceResolvedData = instanceResolvedData;
     }
+    if (slowHeadTagSources.length > 0) {
+      carryForward.__slowHeadTags = slowHeadTagSources;
+    }
     return phaseOutput(slowlyViewState, carryForward);
   }
 }
@@ -378,6 +388,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) {
@@ -405,6 +416,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 +433,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 +512,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)
@@ -635,7 +660,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 +677,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 +745,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 +757,8 @@ async function generateSSRPageHtml(vite, jayHtmlContent, jayHtmlFilename, jayHtm
       buildFolder,
       projectRoot,
       routeDir,
-      tsConfigFilePath
+      tsConfigFilePath,
+      sourceDir
     );
     serverModuleCache.set(jayHtmlPath, cached);
   }
@@ -728,14 +814,16 @@ 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}
@@ -752,14 +840,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 +874,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 +897,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 +1026,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 +1057,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 +1074,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 +1108,7 @@ async function slowRenderInstances(discovered, headlessInstanceComponents) {
   return {
     resolvedData,
     slowViewStates,
-    instancePhaseData: { discovered: discoveredForFast, carryForwards }
+    instancePhaseData: { discovered: discoveredForFast, carryForwards, slowViewStates }
   };
 }
 function validateForEachInstances(forEachInstances, headlessInstanceComponents) {
@@ -2153,11 +2297,34 @@ 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 }
+          };
+        });
+      }
+      pluginsIndexMap.set(plugin.name, entry);
     }
     if (!dynamicOnly && manifest.contracts) {
       for (const contract of manifest.contracts) {
@@ -2167,8 +2334,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 +2381,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 +2427,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 +2446,9 @@ 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 }
     }))
   };
   fs.mkdirSync(outputDir, { recursive: true });
@@ -2286,10 +2479,33 @@ 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 }
+          };
+        });
+      }
+      pluginsMap.set(plugin.name, entry);
     }
     if (!dynamicOnly && manifest.contracts) {
       for (const contract of manifest.contracts) {
@@ -2299,8 +2515,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 +2549,9 @@ 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 }
     }))
   };
 }
@@ -2491,6 +2721,7 @@ export {
   loadActionMetadata,
   loadPageParts,
   materializeContracts,
+  mergeHeadTags,
   onInit,
   onShutdown,
   parseActionMetadata,
@@ -2506,8 +2737,10 @@ export {
   runShutdownCallbacks,
   runSlowlyChangingRender,
   scanPlugins,
+  serializeHeadTags,
   setClientInitData,
   slowRenderInstances,
   sortPluginsByDependencies,
+  tagIdentityKey,
   validateForEachInstances
 };

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/stack-server-runtime",
-  "version": "0.15.5",
+  "version": "0.15.6",
   "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.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",
     "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.15.6",
+    "@jay-framework/jay-cli": "^0.15.6",
+    "@jay-framework/stack-client-runtime": "^0.15.6",
     "@types/express": "^5.0.2",
     "@types/node": "^22.15.21",
     "nodemon": "^3.0.3",