@jay-framework/stack-server-runtime 0.12.0 → 0.14.0

package/dist/index.js

@@ -5,19 +5,19 @@ var __publicField = (obj, key, value) => {
   return value;
 };
 import { notFound, partialRender, phaseOutput, isJayAction } from "@jay-framework/fullstack-component";
-import fs$1 from "node:fs/promises";
-import * as path from "node:path";
-import path__default from "node:path";
-import { parseJayFile, JAY_IMPORT_RESOLVER } from "@jay-framework/compiler-jay-html";
-import { createRequire } from "module";
-import * as fs from "node:fs";
-import { createRequire as createRequire$1 } from "node:module";
 import "prettier";
 import "js-beautify";
-import fs$2 from "fs";
+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 fs$2 from "node:fs/promises";
+import * as path from "node:path";
+import path__default from "node:path";
 import { getLogger } from "@jay-framework/logger";
+import * as fs from "node:fs";
+import { createRequire as createRequire$1 } from "node:module";
 import crypto from "node:crypto";
 const serviceRegistry = /* @__PURE__ */ new Map();
 function registerService(marker, service) {
@@ -86,32 +86,42 @@ function clearClientInitData() {
 function isLeftSideParamsSubsetOfRightSideParams(left, right) {
   return Object.keys(left).reduce((prev, curr) => prev && left[curr] === right[curr], true);
 }
-async function findMatchingParams(search, searchTarget) {
-  for await (const paramsArray of searchTarget) {
-    if (paramsArray.find((params) => isLeftSideParamsSubsetOfRightSideParams(search, params)))
-      return true;
-  }
-  return false;
-}
 class DevSlowlyChangingPhase {
-  constructor(dontCacheSlowly) {
-    this.dontCacheSlowly = dontCacheSlowly;
-  }
-  async runSlowlyForPage(pageParams, pageProps, parts) {
-    for (const part of parts) {
-      const { compDefinition, contractInfo } = part;
-      if (compDefinition.loadParams) {
-        const services = resolveServices(compDefinition.services);
-        const loadParamsArgs = contractInfo ? [
-          ...services,
-          {
-            contractName: contractInfo.contractName,
-            metadata: contractInfo.metadata
+  constructor() {
+    /** Cached loadParams results per route (jayHtmlPath → array of UrlParams[] per part) */
+    __publicField(this, "loadParamsCache", /* @__PURE__ */ new Map());
+  }
+  async runSlowlyForPage(pageParams, pageProps, parts, discoveredInstances, headlessInstanceComponents, jayHtmlPath) {
+    const loadParamsParts = parts.filter((p) => p.compDefinition.loadParams);
+    if (loadParamsParts.length > 0) {
+      let cachedParamsArray = jayHtmlPath ? this.loadParamsCache.get(jayHtmlPath) : void 0;
+      if (!cachedParamsArray) {
+        cachedParamsArray = [];
+        for (const part of loadParamsParts) {
+          const { compDefinition, contractInfo } = part;
+          const services = resolveServices(compDefinition.services);
+          const loadParamsArgs = contractInfo ? [
+            ...services,
+            {
+              contractName: contractInfo.contractName,
+              metadata: contractInfo.metadata
+            }
+          ] : services;
+          const compParams = compDefinition.loadParams(loadParamsArgs);
+          const collected = [];
+          for await (const batch of compParams) {
+            collected.push(...batch);
           }
-        ] : services;
-        const compParams = compDefinition.loadParams(loadParamsArgs);
-        if (!await findMatchingParams(pageParams, compParams))
+          cachedParamsArray.push(collected);
+        }
+        if (jayHtmlPath) {
+          this.loadParamsCache.set(jayHtmlPath, cachedParamsArray);
+        }
+      }
+      for (const partParams of cachedParamsArray) {
+        if (!partParams.some((p) => isLeftSideParamsSubsetOfRightSideParams(pageParams, p))) {
           return notFound();
+        }
       }
     }
     let slowlyViewState = {};
@@ -144,15 +154,264 @@ class DevSlowlyChangingPhase {
           return slowlyRenderedPart;
       }
     }
+    if (discoveredInstances && discoveredInstances.length > 0 && headlessInstanceComponents) {
+      const componentByContractName = /* @__PURE__ */ new Map();
+      for (const comp of headlessInstanceComponents) {
+        componentByContractName.set(comp.contractName, comp);
+      }
+      const instancePhaseData = {
+        discovered: [],
+        carryForwards: {}
+      };
+      const instanceSlowViewStates = {};
+      const instanceResolvedData = [];
+      for (const instance of discoveredInstances) {
+        const comp = componentByContractName.get(instance.contractName);
+        if (!comp)
+          continue;
+        const coordKey = instance.coordinate.join("/");
+        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;
+        }
+        instancePhaseData.discovered.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") {
+            instanceSlowViewStates[coordKey] = slowResult.rendered;
+            instancePhaseData.carryForwards[coordKey] = slowResult.carryForward;
+            instanceResolvedData.push({
+              coordinate: instance.coordinate,
+              contract: comp.contract,
+              slowViewState: slowResult.rendered
+            });
+          }
+        }
+      }
+      carryForward.__instances = instancePhaseData;
+      carryForward.__instanceSlowViewStates = instanceSlowViewStates;
+      carryForward.__instanceResolvedData = instanceResolvedData;
+    }
     return partialRender(slowlyViewState, carryForward);
   }
+  /**
+   * Invalidate the cached loadParams result for a given route.
+   * Called when source files change (page.ts, .jay-contract, .jay-html).
+   */
+  invalidateLoadParamsCache(jayHtmlPath) {
+    this.loadParamsCache.delete(jayHtmlPath);
+  }
 }
 async function runLoadParams(compDefinition, services) {
   compDefinition.loadParams(services);
 }
 function runSlowlyChangingRender(compDefinition) {
 }
-async function renderFastChangingData(pageParams, pageProps, carryForward, parts) {
+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;
+var __publicField2 = (obj, key, value) => {
+  __defNormalProp2(obj, typeof key !== "symbol" ? key + "" : key, value);
+  return value;
+};
+class JayAtomicType {
+  constructor(name) {
+    __publicField2(this, "kind", 0);
+    this.name = name;
+  }
+}
+new JayAtomicType("string");
+new JayAtomicType("number");
+new JayAtomicType("boolean");
+new JayAtomicType("Date");
+new JayAtomicType("Unknown");
+class JayObjectType {
+  constructor(name, props) {
+    __publicField2(this, "kind", 8);
+    this.name = name;
+    this.props = props;
+  }
+}
+new JayObjectType("Error", {
+  message: new JayAtomicType("string"),
+  name: new JayAtomicType("string"),
+  stack: new JayAtomicType("string")
+});
+function isOptionalType(aType) {
+  return aType.kind === 13;
+}
+function isAtomicType(aType) {
+  return aType.kind === 0;
+}
+function isEnumType(aType) {
+  return aType.kind === 2;
+}
+function isImportedType(aType) {
+  return aType.kind === 4;
+}
+function isObjectType(aType) {
+  return aType.kind === 8;
+}
+function isArrayType(aType) {
+  return aType.kind === 9;
+}
+function jayTypeToJsonSchema(type) {
+  if (isOptionalType(type)) {
+    return jayTypeToJsonSchema(type.innerType);
+  }
+  if (isAtomicType(type)) {
+    const name = type.name.toLowerCase();
+    if (name === "string" || name === "number" || name === "boolean") {
+      return { type: name };
+    }
+    return { type: "string" };
+  }
+  if (isEnumType(type)) {
+    return { type: "string", enum: type.values };
+  }
+  if (isImportedType(type)) {
+    return { type: "object", description: `Contract: ${type.name}` };
+  }
+  if (isArrayType(type)) {
+    const itemSchema = jayTypeToJsonSchema(type.itemType);
+    if (itemSchema) {
+      return { type: "array", items: itemSchema };
+    }
+    return { type: "array" };
+  }
+  if (isObjectType(type)) {
+    const properties = {};
+    const required = [];
+    for (const [key, propType] of Object.entries(type.props)) {
+      const isOpt = isOptionalType(propType);
+      const schema = jayTypeToJsonSchema(propType);
+      if (schema) {
+        properties[key] = schema;
+        if (!isOpt) {
+          required.push(key);
+        }
+      }
+    }
+    return {
+      type: "object",
+      properties,
+      ...required.length > 0 && { required }
+    };
+  }
+  return null;
+}
+var RuntimeMode = /* @__PURE__ */ ((RuntimeMode2) => {
+  RuntimeMode2["MainTrusted"] = "mainTrusted";
+  RuntimeMode2["MainSandbox"] = "mainSandbox";
+  RuntimeMode2["WorkerTrusted"] = "workerTrusted";
+  RuntimeMode2["WorkerSandbox"] = "workerSandbox";
+  return RuntimeMode2;
+})(RuntimeMode || {});
+const TS_EXTENSION = ".ts";
+const JAY_QUERY_PREFIX = "?jay-";
+const JAY_QUERY_HYDRATE = `${JAY_QUERY_PREFIX}hydrate`;
+[
+  // Hydrate target
+  {
+    pattern: JAY_QUERY_HYDRATE,
+    buildEnv: "client",
+    isHydrate: true
+  },
+  // Build environments
+  {
+    pattern: `${JAY_QUERY_PREFIX}${"client"}`,
+    buildEnv: "client"
+    /* Client */
+  },
+  {
+    pattern: `${JAY_QUERY_PREFIX}${"server"}`,
+    buildEnv: "server"
+    /* Server */
+  },
+  // Runtime modes (with .ts suffix)
+  {
+    pattern: `${JAY_QUERY_PREFIX}${RuntimeMode.MainSandbox}${TS_EXTENSION}`,
+    runtimeMode: RuntimeMode.MainSandbox
+  },
+  {
+    pattern: `${JAY_QUERY_PREFIX}${RuntimeMode.WorkerTrusted}${TS_EXTENSION}`,
+    runtimeMode: RuntimeMode.WorkerTrusted
+  },
+  {
+    pattern: `${JAY_QUERY_PREFIX}${RuntimeMode.WorkerSandbox}${TS_EXTENSION}`,
+    runtimeMode: RuntimeMode.WorkerSandbox
+  },
+  // Runtime modes (without .ts suffix)
+  {
+    pattern: `${JAY_QUERY_PREFIX}${RuntimeMode.MainSandbox}`,
+    runtimeMode: RuntimeMode.MainSandbox
+  },
+  {
+    pattern: `${JAY_QUERY_PREFIX}${RuntimeMode.WorkerTrusted}`,
+    runtimeMode: RuntimeMode.WorkerTrusted
+  },
+  {
+    pattern: `${JAY_QUERY_PREFIX}${RuntimeMode.WorkerSandbox}`,
+    runtimeMode: RuntimeMode.WorkerSandbox
+  }
+];
+function checkValidationErrors(withValidations) {
+  const { validations } = withValidations;
+  if (validations.length > 0) {
+    throw new Error(validations.join("\n"));
+  }
+  return withValidations.val;
+}
+createRequire(import.meta.url);
+function normalizeActionEntry(entry) {
+  if (typeof entry === "string") {
+    return { name: entry };
+  }
+  return { name: entry.name, action: entry.action };
+}
+function loadPluginManifest(pluginDir) {
+  const pluginYamlPath = path$1.join(pluginDir, "plugin.yaml");
+  if (!fs$1.existsSync(pluginYamlPath)) {
+    return null;
+  }
+  try {
+    const yamlContent = fs$1.readFileSync(pluginYamlPath, "utf-8");
+    return YAML.parse(yamlContent);
+  } catch (error) {
+    return null;
+  }
+}
+function computeForEachInstanceKey(trackByValue, coordinateSuffix) {
+  return [trackByValue, coordinateSuffix].toString();
+}
+const s = createRequire(import.meta.url), e = s("typescript");
+new Proxy(e, {
+  get(t, r) {
+    return t[r];
+  }
+});
+function resolvePathValue(obj, path2) {
+  return path2.split(".").reduce((current, segment) => current?.[segment], obj);
+}
+function resolveBinding(binding, item) {
+  const match = binding.match(/^\{(.+)\}$/);
+  if (match) {
+    return String(item[match[1]] ?? "");
+  }
+  return binding;
+}
+async function renderFastChangingData(pageParams, pageProps, carryForward, parts, instancePhaseData, forEachInstances, headlessInstanceComponents, mergedSlowViewState) {
   let fastViewState = {};
   let fastCarryForward = {};
   for (const part of parts) {
@@ -185,12 +444,92 @@ async function renderFastChangingData(pageParams, pageProps, carryForward, parts
         return fastRenderedPart;
     }
   }
+  const instanceViewStates = {};
+  const instanceCarryForwards = {};
+  if (instancePhaseData && headlessInstanceComponents) {
+    const componentByContractName = /* @__PURE__ */ new Map();
+    for (const comp of headlessInstanceComponents) {
+      componentByContractName.set(comp.contractName, comp);
+    }
+    for (const instance of instancePhaseData.discovered) {
+      const coordKey = instance.coordinate.join("/");
+      const comp = componentByContractName.get(instance.contractName);
+      if (!comp || !comp.compDefinition.fastRender)
+        continue;
+      const services = resolveServices(comp.compDefinition.services);
+      const cf = instancePhaseData.carryForwards[coordKey];
+      const fastResult = comp.compDefinition.slowlyRender ? await comp.compDefinition.fastRender(instance.props, cf, ...services) : await comp.compDefinition.fastRender(instance.props, ...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;
+        }
+      }
+    }
+  }
+  if (forEachInstances && forEachInstances.length > 0 && headlessInstanceComponents) {
+    const componentByContractName = /* @__PURE__ */ new Map();
+    for (const comp of headlessInstanceComponents) {
+      componentByContractName.set(comp.contractName, comp);
+    }
+    const mergedForEachVS = { ...mergedSlowViewState || {}, ...fastViewState };
+    for (const instance of forEachInstances) {
+      const comp = componentByContractName.get(instance.contractName);
+      if (!comp)
+        continue;
+      const items = resolvePathValue(mergedForEachVS, instance.forEachPath);
+      if (!Array.isArray(items))
+        continue;
+      const contractProps = comp.contract?.props ?? [];
+      const normalizePropName = (key) => contractProps.find((p) => p.name.toLowerCase() === key.toLowerCase())?.name ?? key;
+      for (const item of items) {
+        const trackByValue = String(item[instance.trackBy]);
+        const props = {};
+        for (const [propName, binding] of Object.entries(instance.propBindings)) {
+          props[normalizePropName(propName)] = resolveBinding(String(binding), item);
+        }
+        if (comp.compDefinition.fastRender) {
+          const services = resolveServices(comp.compDefinition.services);
+          let slowVS = {};
+          let cf = {};
+          if (comp.compDefinition.slowlyRender) {
+            const slowResult = await comp.compDefinition.slowlyRender(
+              props,
+              ...services
+            );
+            if (slowResult.kind === "PhaseOutput") {
+              slowVS = slowResult.rendered;
+              cf = slowResult.carryForward;
+            }
+          }
+          const fastResult = comp.compDefinition.slowlyRender ? await comp.compDefinition.fastRender(props, cf, ...services) : await comp.compDefinition.fastRender(props, ...services);
+          if (fastResult.kind === "PhaseOutput") {
+            const coord = computeForEachInstanceKey(
+              trackByValue,
+              instance.coordinateSuffix
+            );
+            instanceViewStates[coord] = { ...slowVS, ...fastResult.rendered };
+            if (fastResult.carryForward) {
+              instanceCarryForwards[coord] = fastResult.carryForward;
+            }
+          }
+        }
+      }
+    }
+  }
+  if (Object.keys(instanceViewStates).length > 0) {
+    fastViewState.__headlessInstances = instanceViewStates;
+  }
+  if (Object.keys(instanceCarryForwards).length > 0) {
+    fastCarryForward.__headlessInstances = instanceCarryForwards;
+  }
   return Promise.resolve(phaseOutput(fastViewState, fastCarryForward));
 }
-function generateClientScript(defaultViewState, fastCarryForward, parts, jayHtmlPath, trackByMap = {}, clientInitData2 = {}, projectInit, pluginInits = [], options = {}) {
+function buildScriptFragments(parts, clientInitData2, projectInit, pluginInits, options) {
   const { enableAutomation = true, slowViewState } = options;
   const hasSlowViewState = slowViewState && Object.keys(slowViewState).length > 0;
-  const imports = parts.length > 0 ? parts.map((part) => part.clientImport).join("\n") + "\n" : "";
+  const partImports = parts.length > 0 ? parts.map((part) => part.clientImport).join("\n") + "\n" : "";
   const compositeParts = parts.length > 0 ? `[
 ${parts.map((part) => "        " + part.clientPart).join(",\n")}
         ]` : "[]";
@@ -214,7 +553,7 @@ ${parts.map((part) => "        " + part.clientPart).join(",\n")}
   const clientInitExecution = hasClientInit ? `
       // Plugin client initialization (in dependency order)
       ${pluginClientInitCalls}
-      
+
       // Project client initialization
       ${projectInitCall}
 ` : "";
@@ -223,7 +562,28 @@ ${parts.map((part) => "        " + part.clientPart).join(",\n")}
       import { deepMergeViewStates } from "@jay-framework/view-state-merge";` : `import { wrapWithAutomation, AUTOMATION_CONTEXT } from "@jay-framework/runtime-automation";
       import { registerGlobalContext } from "@jay-framework/runtime";` : "";
   const slowViewStateDecl = enableAutomation && hasSlowViewState ? `const slowViewState = ${JSON.stringify(slowViewState)};` : "";
-  const automationWrap = enableAutomation ? hasSlowViewState ? `
+  return {
+    partImports,
+    compositeParts,
+    pluginClientInitImports,
+    projectInitImport,
+    clientInitExecution,
+    automationImport,
+    slowViewStateDecl
+  };
+}
+function buildAutomationWrap(options, mode) {
+  const { enableAutomation = true, slowViewState } = options;
+  const hasSlowViewState = slowViewState && Object.keys(slowViewState).length > 0;
+  const appendDom = mode === "client";
+  if (!enableAutomation) {
+    return appendDom ? `
+      target.appendChild(instance.element.dom);` : "";
+  }
+  const appendLine = appendDom ? `
+      target.appendChild(wrapped.element.dom);` : "";
+  if (hasSlowViewState) {
+    return `
       // Wrap with automation for dev tooling
       // Deep merge slow+fast ViewState so automation can see full page state
       const fullViewState = deepMergeViewStates(slowViewState, {...viewState, ...fastCarryForward}, trackByMap);
@@ -231,14 +591,27 @@ ${parts.map((part) => "        " + part.clientPart).join(",\n")}
       registerGlobalContext(AUTOMATION_CONTEXT, wrapped.automation);
       window.__jay = window.__jay || {};
       window.__jay.automation = wrapped.automation;
-      target.appendChild(wrapped.element.dom);` : `
+      window.dispatchEvent(new Event('jay:automation-ready'));${appendLine}`;
+  }
+  return `
       // Wrap with automation for dev tooling
       const wrapped = wrapWithAutomation(instance);
       registerGlobalContext(AUTOMATION_CONTEXT, wrapped.automation);
       window.__jay = window.__jay || {};
       window.__jay.automation = wrapped.automation;
-      target.appendChild(wrapped.element.dom);` : `
-      target.appendChild(instance.element.dom);`;
+      window.dispatchEvent(new Event('jay:automation-ready'));${appendLine}`;
+}
+function generateClientScript(defaultViewState, fastCarryForward, parts, jayHtmlPath, trackByMap = {}, clientInitData2 = {}, projectInit, pluginInits = [], options = {}) {
+  const {
+    partImports,
+    compositeParts,
+    pluginClientInitImports,
+    projectInitImport,
+    clientInitExecution,
+    automationImport,
+    slowViewStateDecl
+  } = buildScriptFragments(parts, clientInitData2, projectInit, pluginInits, options);
+  const automationWrap = buildAutomationWrap(options, "client");
   return `<!doctype html>
 <html lang="en">
   <head>
@@ -254,7 +627,7 @@ ${parts.map((part) => "        " + part.clientPart).join(",\n")}
       ${pluginClientInitImports}
       ${projectInitImport}
       import { render } from '${jayHtmlPath}';
-      ${imports}${slowViewStateDecl}
+      ${partImports}${slowViewStateDecl}
       const viewState = ${JSON.stringify(defaultViewState)};
       const fastCarryForward = ${JSON.stringify(fastCarryForward)};
       const trackByMap = ${JSON.stringify(trackByMap)};
@@ -268,9 +641,171 @@ ${automationWrap}
   </body>
 </html>`;
 }
+const serverModuleCache = /* @__PURE__ */ new Map();
+function invalidateServerElementCache(jayHtmlPath) {
+  if (serverModuleCache.delete(jayHtmlPath)) {
+    getLogger().info(`[SSR] Invalidated server element cache for ${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 = {}) {
+  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
+    );
+    serverModuleCache.set(jayHtmlPath, cached);
+  }
+  const htmlChunks = [];
+  const asyncPromises = [];
+  const ctx = {
+    write: (chunk) => {
+      htmlChunks.push(chunk);
+    },
+    onAsync: (promise, id, templates) => {
+      const asyncPromise = promise.then(
+        (val) => {
+          if (templates.resolved) {
+            return templates.resolved(val);
+          }
+          return "";
+        },
+        (err) => {
+          if (templates.rejected) {
+            return templates.rejected(err);
+          }
+          return "";
+        }
+      );
+      asyncPromises.push(asyncPromise);
+    }
+  };
+  cached.renderToStream(viewState, ctx);
+  const asyncResults = await Promise.all(asyncPromises);
+  const ssrHtml = htmlChunks.join("");
+  const asyncScripts = asyncResults.filter((r) => r !== "").join("");
+  const hydrationScript = generateHydrationScript(
+    viewState,
+    carryForward,
+    parts,
+    jayHtmlImportPath,
+    trackByMap,
+    clientInitData2,
+    projectInit,
+    pluginInits,
+    options
+  );
+  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 inlineCss = cached.css ? `    <style>
+${cached.css}
+    </style>` : "";
+  const headExtras = [headLinksHtml, inlineCss].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>
+  <body>
+    <div id="target">${ssrHtml}</div>${asyncScripts}
+    ${hydrationScript}
+  </body>
+</html>`;
+}
+function rebaseRelativeImports(code, fromDir, toDir) {
+  return code.replace(/from "(\.\.\/[^"]+)"/g, (_match, relPath) => {
+    const absolutePath = path__default.resolve(fromDir, relPath);
+    let newRelPath = path__default.relative(toDir, absolutePath);
+    if (!newRelPath.startsWith(".")) {
+      newRelPath = "./" + newRelPath;
+    }
+    return `from "${newRelPath}"`;
+  });
+}
+async function compileAndLoadServerElement(vite, jayHtmlContent, jayHtmlFilename, jayHtmlDir, buildFolder, projectRoot, routeDir, tsConfigFilePath) {
+  const jayFile = await parseJayFile(
+    jayHtmlContent,
+    jayHtmlFilename,
+    jayHtmlDir,
+    { relativePath: tsConfigFilePath },
+    JAY_IMPORT_RESOLVER,
+    projectRoot
+  );
+  const parsedJayFile = checkValidationErrors(jayFile);
+  const pageName = jayHtmlFilename.replace(".jay-html", "");
+  const debugCoordinatePreprocessPath = path__default.join(
+    buildFolder,
+    "debug",
+    routeDir,
+    `${pageName}.coordinate-preprocess.jay-html`
+  );
+  const serverElementOptions = {
+    debugCoordinatePreprocessPath
+  };
+  const serverElementCode = checkValidationErrors(
+    generateServerElementFile(parsedJayFile, serverElementOptions)
+  );
+  const serverElementDir = path__default.join(buildFolder, "pre-rendered", routeDir);
+  await fs$2.mkdir(serverElementDir, { recursive: true });
+  const adjustedCode = rebaseRelativeImports(serverElementCode, jayHtmlDir, serverElementDir);
+  const serverElementFilename = jayHtmlFilename.replace(".jay-html", ".server-element.ts");
+  const serverElementPath = path__default.join(serverElementDir, serverElementFilename);
+  await fs$2.writeFile(serverElementPath, adjustedCode, "utf-8");
+  const serverModule = await vite.ssrLoadModule(serverElementPath);
+  return {
+    renderToStream: serverModule.renderToStream,
+    headLinks: parsedJayFile.headLinks,
+    css: parsedJayFile.css
+  };
+}
+function generateHydrationScript(defaultViewState, fastCarryForward, parts, jayHtmlPath, trackByMap = {}, clientInitData2 = {}, projectInit, pluginInits = [], options = {}) {
+  const {
+    partImports,
+    compositeParts,
+    pluginClientInitImports,
+    projectInitImport,
+    clientInitExecution,
+    automationImport,
+    slowViewStateDecl
+  } = buildScriptFragments(parts, clientInitData2, projectInit, pluginInits, options);
+  const automationWrap = buildAutomationWrap(options, "hydrate");
+  const hydrateImportPath = `${jayHtmlPath}${JAY_QUERY_HYDRATE}`;
+  return `<script type="module">
+      import {hydrateCompositeJayComponent} from "@jay-framework/stack-client-runtime";
+      ${automationImport}
+      ${pluginClientInitImports}
+      ${projectInitImport}
+      import { hydrate } from '${hydrateImportPath}';
+      ${partImports}${slowViewStateDecl}
+      const viewState = ${JSON.stringify(defaultViewState)};
+      const fastCarryForward = ${JSON.stringify(fastCarryForward)};
+      const trackByMap = ${JSON.stringify(trackByMap)};
+
+      const target = document.getElementById('target');
+      const rootElement = target.firstElementChild;
+      const pageComp = hydrateCompositeJayComponent(hydrate, viewState, fastCarryForward, ${compositeParts}, trackByMap, rootElement);
+${clientInitExecution}
+      const instance = pageComp({/* placeholder for page props */});
+${automationWrap}
+    <\/script>`;
+}
 const require$3 = createRequire(import.meta.url);
 async function loadPageParts(vite, route, pagesBase, projectBase, jayRollupConfig, options) {
-  const exists = await fs$1.access(route.compPath, fs$1.constants.F_OK).then(() => true).catch(() => false);
+  const exists = await fs$2.access(route.compPath, fs$2.constants.F_OK).then(() => true).catch(() => false);
   const parts = [];
   if (exists) {
     const pageComponent = (await vite.ssrLoadModule(route.compPath)).page;
@@ -281,7 +816,7 @@ async function loadPageParts(vite, route, pagesBase, projectBase, jayRollupConfi
     });
   }
   const jayHtmlFilePath = options?.preRenderedPath ?? route.jayHtmlPath;
-  const jayHtmlSource = (await fs$1.readFile(jayHtmlFilePath)).toString();
+  const jayHtmlSource = options?.preRenderedContent ?? (await fs$2.readFile(jayHtmlFilePath)).toString();
   const fileName = path__default.basename(route.jayHtmlPath);
   const dirName = path__default.dirname(route.jayHtmlPath);
   const jayHtmlWithValidations = await parseJayFile(
@@ -338,13 +873,16 @@ 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 };
     return {
       parts,
       serverTrackByMap: jayHtml.serverTrackByMap,
       clientTrackByMap: jayHtml.clientTrackByMap,
       usedPackages,
       headlessContracts,
-      headlessInstanceComponents
+      headlessInstanceComponents,
+      discoveredInstances: discoveryResult.instances,
+      forEachInstances: discoveryResult.forEachInstances
     };
   });
 }
@@ -362,8 +900,14 @@ async function slowRenderInstances(discovered, headlessInstanceComponents) {
     if (!comp || !comp.compDefinition.slowlyRender) {
       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(instance.props, ...services);
+    const slowResult = await comp.compDefinition.slowlyRender(normalizedProps, ...services);
     if (slowResult.kind === "PhaseOutput") {
       const coordKey = instance.coordinate.join("/");
       resolvedData.push({
@@ -375,7 +919,7 @@ async function slowRenderInstances(discovered, headlessInstanceComponents) {
       carryForwards[coordKey] = slowResult.carryForward;
       discoveredForFast.push({
         contractName: instance.contractName,
-        props: instance.props,
+        props: normalizedProps,
         coordinate: instance.coordinate
       });
     }
@@ -389,6 +933,22 @@ async function slowRenderInstances(discovered, headlessInstanceComponents) {
     instancePhaseData: { discovered: discoveredForFast, carryForwards }
   };
 }
+function validateForEachInstances(forEachInstances, headlessInstanceComponents) {
+  const componentByContractName = /* @__PURE__ */ new Map();
+  for (const comp of headlessInstanceComponents) {
+    componentByContractName.set(comp.contractName, comp);
+  }
+  const validations = [];
+  for (const instance of forEachInstances) {
+    const comp = componentByContractName.get(instance.contractName);
+    if (comp?.compDefinition.slowlyRender) {
+      validations.push(
+        `<jay:${instance.contractName}> inside forEach has a slow rendering phase. Headless components with slow phases cannot be used inside forEach because forEach items are only known at request time, after slow rendering completes. Use slowForEach instead, or remove the slow phase from the component.`
+      );
+    }
+  }
+  return validations;
+}
 class ActionRegistry {
   constructor() {
     __publicField(this, "actions", /* @__PURE__ */ new Map());
@@ -429,10 +989,38 @@ class ActionRegistry {
   /**
    * Gets all registered action names.
    *
-   * @returns Array of registered action names
+   * @returns Array of registered action names
+   */
+  getNames() {
+    return Array.from(this.actions.keys());
+  }
+  /**
+   * Attaches metadata from a .jay-action file to a registered action.
+   * Called during action discovery when a plugin declares action metadata.
+   *
+   * @param actionName - The action name
+   * @param metadata - Parsed ActionMetadata from .jay-action file
+   */
+  setMetadata(actionName, metadata) {
+    const action = this.actions.get(actionName);
+    if (action) {
+      action.metadata = metadata;
+    }
+  }
+  /**
+   * Gets all registered actions that have .jay-action metadata.
+   * These are the actions that should be exposed to AI agents.
+   *
+   * @returns Array of { actionName, metadata } for actions with metadata
    */
-  getNames() {
-    return Array.from(this.actions.keys());
+  getActionsWithMetadata() {
+    const result = [];
+    for (const action of this.actions.values()) {
+      if (action.metadata) {
+        result.push({ actionName: action.actionName, metadata: action.metadata });
+      }
+    }
+    return result;
   }
   /**
    * Clears all registered actions.
@@ -536,102 +1124,62 @@ async function executeAction(actionName, input) {
 function getActionCacheHeaders(actionName) {
   return actionRegistry.getCacheHeaders(actionName);
 }
-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;
-var __publicField2 = (obj, key, value) => {
-  __defNormalProp2(obj, typeof key !== "symbol" ? key + "" : key, value);
-  return value;
-};
-class JayAtomicType {
-  constructor(name) {
-    __publicField2(this, "kind", 0);
-    this.name = name;
-  }
-}
-new JayAtomicType("string");
-new JayAtomicType("number");
-new JayAtomicType("boolean");
-new JayAtomicType("Date");
-new JayAtomicType("Unknown");
-class JayObjectType {
-  constructor(name, props) {
-    __publicField2(this, "kind", 8);
-    this.name = name;
-    this.props = props;
-  }
-}
-new JayObjectType("Error", {
-  message: new JayAtomicType("string"),
-  name: new JayAtomicType("string"),
-  stack: new JayAtomicType("string")
-});
-var RuntimeMode = /* @__PURE__ */ ((RuntimeMode2) => {
-  RuntimeMode2["MainTrusted"] = "mainTrusted";
-  RuntimeMode2["MainSandbox"] = "mainSandbox";
-  RuntimeMode2["WorkerTrusted"] = "workerTrusted";
-  RuntimeMode2["WorkerSandbox"] = "workerSandbox";
-  return RuntimeMode2;
-})(RuntimeMode || {});
-const TS_EXTENSION = ".ts";
-const JAY_QUERY_PREFIX = "?jay-";
-[
-  // Build environments
-  {
-    pattern: `${JAY_QUERY_PREFIX}${"client"}`,
-    buildEnv: "client"
-    /* Client */
-  },
-  {
-    pattern: `${JAY_QUERY_PREFIX}${"server"}`,
-    buildEnv: "server"
-    /* Server */
-  },
-  // Runtime modes (with .ts suffix)
-  {
-    pattern: `${JAY_QUERY_PREFIX}${RuntimeMode.MainSandbox}${TS_EXTENSION}`,
-    runtimeMode: RuntimeMode.MainSandbox
-  },
-  {
-    pattern: `${JAY_QUERY_PREFIX}${RuntimeMode.WorkerTrusted}${TS_EXTENSION}`,
-    runtimeMode: RuntimeMode.WorkerTrusted
-  },
-  {
-    pattern: `${JAY_QUERY_PREFIX}${RuntimeMode.WorkerSandbox}${TS_EXTENSION}`,
-    runtimeMode: RuntimeMode.WorkerSandbox
-  },
-  // Runtime modes (without .ts suffix)
-  {
-    pattern: `${JAY_QUERY_PREFIX}${RuntimeMode.MainSandbox}`,
-    runtimeMode: RuntimeMode.MainSandbox
-  },
-  {
-    pattern: `${JAY_QUERY_PREFIX}${RuntimeMode.WorkerTrusted}`,
-    runtimeMode: RuntimeMode.WorkerTrusted
-  },
-  {
-    pattern: `${JAY_QUERY_PREFIX}${RuntimeMode.WorkerSandbox}`,
-    runtimeMode: RuntimeMode.WorkerSandbox
-  }
-];
-createRequire(import.meta.url);
-function loadPluginManifest(pluginDir) {
-  const pluginYamlPath = path$1.join(pluginDir, "plugin.yaml");
-  if (!fs$2.existsSync(pluginYamlPath)) {
-    return null;
-  }
+function parseActionMetadata(yamlContent, fileName) {
   try {
-    const yamlContent = fs$2.readFileSync(pluginYamlPath, "utf-8");
-    return YAML.parse(yamlContent);
+    const parsed = parseAction(yamlContent, fileName);
+    if (parsed.validations.length > 0) {
+      getLogger().warn(
+        `[ActionMetadata] ${fileName}: validation errors: ${parsed.validations.join(", ")}`
+      );
+      return null;
+    }
+    if (!parsed.val) {
+      getLogger().warn(`[ActionMetadata] ${fileName}: parsing returned no result`);
+      return null;
+    }
+    const action = parsed.val;
+    const inputJsonSchema = jayTypeToJsonSchema(action.inputType);
+    let inputSchema;
+    if (inputJsonSchema && inputJsonSchema.type === "object") {
+      inputSchema = {
+        type: "object",
+        properties: inputJsonSchema.properties || {},
+        ...inputJsonSchema.required && inputJsonSchema.required.length > 0 && { required: inputJsonSchema.required }
+      };
+    } else {
+      inputSchema = { type: "object", properties: {} };
+    }
+    const metadata = {
+      name: action.name,
+      description: action.description,
+      inputSchema
+    };
+    if (action.outputType) {
+      const outputJsonSchema = jayTypeToJsonSchema(action.outputType);
+      if (outputJsonSchema) {
+        metadata.outputSchema = outputJsonSchema;
+      }
+    }
+    return metadata;
   } catch (error) {
+    getLogger().error(
+      `[ActionMetadata] Failed to parse ${fileName}: ${error instanceof Error ? error.message : error}`
+    );
     return null;
   }
 }
-const s = createRequire(import.meta.url), e = s("typescript");
-new Proxy(e, {
-  get(t, r) {
-    return t[r];
+function loadActionMetadata(filePath) {
+  if (!fs.existsSync(filePath)) {
+    getLogger().warn(`[ActionMetadata] File not found: ${filePath}`);
+    return null;
   }
-});
+  const yamlContent = fs.readFileSync(filePath, "utf-8");
+  const fileName = path.basename(filePath);
+  return parseActionMetadata(yamlContent, fileName);
+}
+function resolveActionMetadataPath(actionPath, pluginDir) {
+  return path.resolve(pluginDir, actionPath);
+}
 const require$2 = createRequire$1(import.meta.url);
 async function discoverAndRegisterActions(options) {
   const {
@@ -753,6 +1301,7 @@ async function discoverNpmPluginActions(projectRoot, registry, verbose, viteServ
         const actions = await registerNpmPluginActions(
           packageName,
           pluginConfig,
+          pluginDir,
           registry,
           verbose,
           viteServer
@@ -776,7 +1325,25 @@ function tryResolvePluginYaml(packageName, projectRoot) {
     return null;
   }
 }
-async function registerNpmPluginActions(packageName, pluginConfig, registry, verbose, viteServer) {
+function resolveNpmActionMetadataPath(actionPath, packageName, pluginDir) {
+  if (!actionPath.startsWith(".")) {
+    try {
+      return require$2.resolve(`${packageName}/${actionPath}`, {
+        paths: [pluginDir]
+      });
+    } catch {
+    }
+  }
+  const resolved = resolveActionMetadataPath(actionPath, pluginDir);
+  if (fs.existsSync(resolved)) {
+    return resolved;
+  }
+  getLogger().warn(
+    `[Actions] Could not resolve .jay-action file "${actionPath}" for package "${packageName}"`
+  );
+  return null;
+}
+async function registerNpmPluginActions(packageName, pluginConfig, pluginDir, registry, verbose, viteServer) {
   const registeredActions = [];
   try {
     let pluginModule;
@@ -785,15 +1352,33 @@ async function registerNpmPluginActions(packageName, pluginConfig, registry, ver
     } else {
       pluginModule = await import(packageName);
     }
-    for (const actionName of pluginConfig.actions) {
+    for (const entry of pluginConfig.actions) {
+      const { name: actionName, action: actionPath } = normalizeActionEntry(entry);
       const actionExport = pluginModule[actionName];
       if (actionExport && isJayAction(actionExport)) {
         registry.register(actionExport);
-        registeredActions.push(actionExport.actionName);
-        if (verbose) {
-          getLogger().info(
-            `[Actions] Registered NPM plugin action: ${actionExport.actionName}`
+        const registeredName = actionExport.actionName;
+        registeredActions.push(registeredName);
+        if (actionPath) {
+          const metadataFilePath = resolveNpmActionMetadataPath(
+            actionPath,
+            packageName,
+            pluginDir
           );
+          if (metadataFilePath) {
+            const metadata = loadActionMetadata(metadataFilePath);
+            if (metadata) {
+              registry.setMetadata(registeredName, metadata);
+              if (verbose) {
+                getLogger().info(
+                  `[Actions] Loaded metadata for "${registeredName}" from ${actionPath}`
+                );
+              }
+            }
+          }
+        }
+        if (verbose) {
+          getLogger().info(`[Actions] Registered NPM plugin action: ${registeredName}`);
         }
       } else {
         getLogger().warn(
@@ -841,15 +1426,27 @@ async function discoverPluginActions(pluginPath, projectRoot, registry = actionR
     } else {
       pluginModule = await import(modulePath);
     }
-    for (const actionName of pluginConfig.actions) {
+    for (const entry of pluginConfig.actions) {
+      const { name: actionName, action: actionPath } = normalizeActionEntry(entry);
       const actionExport = pluginModule[actionName];
       if (actionExport && isJayAction(actionExport)) {
         registry.register(actionExport);
-        registeredActions.push(actionExport.actionName);
+        const registeredName = actionExport.actionName;
+        registeredActions.push(registeredName);
+        if (actionPath) {
+          const metadataFilePath = resolveActionMetadataPath(actionPath, pluginPath);
+          const metadata = loadActionMetadata(metadataFilePath);
+          if (metadata) {
+            registry.setMetadata(registeredName, metadata);
+            if (verbose) {
+              getLogger().info(
+                `[Actions] Loaded metadata for "${registeredName}" from ${actionPath}`
+              );
+            }
+          }
+        }
         if (verbose) {
-          getLogger().info(
-            `[Actions] Registered plugin action: ${actionExport.actionName}`
-          );
+          getLogger().info(`[Actions] Registered plugin action: ${registeredName}`);
         }
       } else {
         getLogger().warn(
@@ -999,7 +1596,8 @@ async function discoverPluginsWithInit(options) {
       isLocal: scanned.isLocal,
       initModule: initConfig.module,
       initExport: initConfig.export,
-      dependencies: scanned.dependencies
+      dependencies: scanned.dependencies,
+      global: scanned.manifest.global === true
     });
     if (verbose) {
       getLogger().info(`[PluginInit] Found plugin with init: ${scanned.name}`);
@@ -1073,6 +1671,7 @@ function sortPluginsByDependencies(plugins) {
   return sorted;
 }
 async function executePluginServerInits(plugins, viteServer, verbose = false) {
+  const initErrors = /* @__PURE__ */ new Map();
   for (const plugin of plugins) {
     try {
       let modulePath;
@@ -1106,11 +1705,14 @@ async function executePluginServerInits(plugins, viteServer, verbose = false) {
         }
       }
     } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      initErrors.set(plugin.name, err);
       getLogger().error(
         `[PluginInit] Failed to execute server init for "${plugin.name}": ${error}`
       );
     }
   }
+  return initErrors;
 }
 function preparePluginClientInits(plugins) {
   return plugins.map((plugin) => {
@@ -1129,16 +1731,8 @@ function preparePluginClientInits(plugins) {
     };
   });
 }
-function makeCacheKey(jayHtmlPath, params) {
-  const sortedParams = Object.keys(params).sort().reduce(
-    (acc, key) => {
-      acc[key] = params[key];
-      return acc;
-    },
-    {}
-  );
-  return `${jayHtmlPath}:${JSON.stringify(sortedParams)}`;
-}
+const CACHE_TAG_START = '<script type="application/jay-cache">';
+const CACHE_TAG_END = "<\/script>";
 function hashParams(params) {
   const sortedParams = Object.keys(params).sort().reduce(
     (acc, key) => {
@@ -1152,81 +1746,126 @@ function hashParams(params) {
     return "";
   return "_" + crypto.createHash("md5").update(json).digest("hex").substring(0, 8);
 }
+function embedCacheMetadata(jayHtmlContent, slowViewState, carryForward, sourcePath) {
+  const metadata = JSON.stringify({ slowViewState, carryForward, sourcePath });
+  const cacheTag = `${CACHE_TAG_START}${metadata}${CACHE_TAG_END}`;
+  const headMatch = jayHtmlContent.match(/<head[^>]*>/i);
+  if (headMatch) {
+    const insertPos = headMatch.index + headMatch[0].length;
+    return jayHtmlContent.substring(0, insertPos) + "\n" + cacheTag + jayHtmlContent.substring(insertPos);
+  }
+  return `${cacheTag}
+${jayHtmlContent}`;
+}
+function extractCacheMetadata(fileContent) {
+  const startIdx = fileContent.indexOf(CACHE_TAG_START);
+  if (startIdx === -1)
+    return void 0;
+  const jsonStart = startIdx + CACHE_TAG_START.length;
+  const endIdx = fileContent.indexOf(CACHE_TAG_END, jsonStart);
+  if (endIdx === -1)
+    return void 0;
+  const jsonStr = fileContent.substring(jsonStart, endIdx);
+  const metadata = JSON.parse(jsonStr);
+  const tagEnd = endIdx + CACHE_TAG_END.length;
+  const afterTag = fileContent[tagEnd] === "\n" ? tagEnd + 1 : tagEnd;
+  const content = fileContent.substring(0, startIdx) + fileContent.substring(afterTag);
+  return {
+    content,
+    slowViewState: metadata.slowViewState,
+    carryForward: metadata.carryForward,
+    sourcePath: metadata.sourcePath
+  };
+}
 class SlowRenderCache {
   /**
    * @param cacheDir - Directory where pre-rendered jay-html files are stored
    * @param pagesRoot - Root directory of the pages (for relative path calculation)
    */
   constructor(cacheDir, pagesRoot) {
-    __publicField(this, "cache", /* @__PURE__ */ new Map());
-    __publicField(this, "pathToKeys", /* @__PURE__ */ new Map());
+    /** Maps source jay-html path → set of pre-rendered file paths (for invalidation) */
+    __publicField(this, "pathToFiles", /* @__PURE__ */ new Map());
     __publicField(this, "cacheDir");
     __publicField(this, "pagesRoot");
     this.cacheDir = cacheDir;
     this.pagesRoot = pagesRoot;
   }
   /**
-   * Get a cached pre-rendered jay-html entry
+   * Get a cached pre-rendered jay-html entry by reading from disk.
+   * Returns undefined if the cache file doesn't exist or has no metadata tag.
    */
-  get(jayHtmlPath, params) {
-    const key = makeCacheKey(jayHtmlPath, params);
-    return this.cache.get(key);
+  async get(jayHtmlPath, params) {
+    const preRenderedPath = this.computeCachePath(jayHtmlPath, params);
+    let fileContent;
+    try {
+      fileContent = await fs$2.readFile(preRenderedPath, "utf-8");
+    } catch {
+      return void 0;
+    }
+    const extracted = extractCacheMetadata(fileContent);
+    if (!extracted)
+      return void 0;
+    this.trackFile(jayHtmlPath, preRenderedPath);
+    return {
+      preRenderedPath,
+      preRenderedContent: extracted.content,
+      slowViewState: extracted.slowViewState,
+      carryForward: extracted.carryForward,
+      sourcePath: extracted.sourcePath
+    };
   }
   /**
-   * Store a pre-rendered jay-html entry in the cache.
-   * Writes the pre-rendered content to disk and stores metadata in memory.
+   * Store a pre-rendered jay-html entry.
+   * Embeds metadata as a <script> tag and writes to disk.
+   * Returns the full cache entry with stripped content.
    */
   async set(jayHtmlPath, params, preRenderedJayHtml, slowViewState, carryForward) {
-    const key = makeCacheKey(jayHtmlPath, params);
-    const relativePath = path__default.relative(this.pagesRoot, jayHtmlPath);
-    const dir = path__default.dirname(relativePath);
-    const basename = path__default.basename(relativePath, ".jay-html");
-    const paramsHash = hashParams(params);
-    const cacheFileName = `${basename}${paramsHash}.jay-html`;
-    const preRenderedPath = path__default.join(this.cacheDir, dir, cacheFileName);
-    await fs$1.mkdir(path__default.dirname(preRenderedPath), { recursive: true });
-    await fs$1.writeFile(preRenderedPath, preRenderedJayHtml, "utf-8");
-    if (!this.pathToKeys.has(jayHtmlPath)) {
-      this.pathToKeys.set(jayHtmlPath, /* @__PURE__ */ new Set());
-    }
-    this.pathToKeys.get(jayHtmlPath).add(key);
-    const entry = {
+    const preRenderedPath = this.computeCachePath(jayHtmlPath, params);
+    const fileContent = embedCacheMetadata(
+      preRenderedJayHtml,
+      slowViewState,
+      carryForward,
+      jayHtmlPath
+    );
+    await fs$2.mkdir(path__default.dirname(preRenderedPath), { recursive: true });
+    await fs$2.writeFile(preRenderedPath, fileContent, "utf-8");
+    this.trackFile(jayHtmlPath, preRenderedPath);
+    return {
       preRenderedPath,
+      preRenderedContent: preRenderedJayHtml,
       slowViewState,
       carryForward,
-      createdAt: Date.now(),
       sourcePath: jayHtmlPath
     };
-    this.cache.set(key, entry);
-    return preRenderedPath;
   }
   /**
    * Check if a pre-rendered entry exists for the given path and params
    */
-  has(jayHtmlPath, params) {
-    const key = makeCacheKey(jayHtmlPath, params);
-    return this.cache.has(key);
+  async has(jayHtmlPath, params) {
+    const preRenderedPath = this.computeCachePath(jayHtmlPath, params);
+    try {
+      await fs$2.access(preRenderedPath);
+      return true;
+    } catch {
+      return false;
+    }
   }
   /**
    * Invalidate all cached entries for a given jay-html source path.
-   * This is called when the source file changes.
-   * Also deletes the cached files from disk.
+   * Deletes cached files from disk.
    */
   async invalidate(jayHtmlPath) {
-    const keys = this.pathToKeys.get(jayHtmlPath);
-    if (keys) {
-      for (const key of keys) {
-        const entry = this.cache.get(key);
-        if (entry) {
-          try {
-            await fs$1.unlink(entry.preRenderedPath);
-          } catch {
-          }
+    const files = this.pathToFiles.get(jayHtmlPath);
+    if (files) {
+      for (const filePath of files) {
+        try {
+          await fs$2.unlink(filePath);
+        } catch {
         }
-        this.cache.delete(key);
       }
-      this.pathToKeys.delete(jayHtmlPath);
+      this.pathToFiles.delete(jayHtmlPath);
     }
+    await this.scanAndDeleteCacheFiles(jayHtmlPath);
   }
   /**
    * Invalidate all entries that depend on a changed file.
@@ -1254,26 +1893,67 @@ class SlowRenderCache {
    * Clear all cached entries and delete cached files from disk
    */
   async clear() {
-    for (const entry of this.cache.values()) {
-      try {
-        await fs$1.unlink(entry.preRenderedPath);
-      } catch {
+    for (const files of this.pathToFiles.values()) {
+      for (const filePath of files) {
+        try {
+          await fs$2.unlink(filePath);
+        } catch {
+        }
       }
     }
-    this.cache.clear();
-    this.pathToKeys.clear();
+    this.pathToFiles.clear();
+    try {
+      await fs$2.rm(this.cacheDir, { recursive: true, force: true });
+    } catch {
+    }
   }
   /**
-   * Get the number of cached entries
+   * Get all cached jay-html paths (for debugging/monitoring)
    */
-  get size() {
-    return this.cache.size;
+  getCachedPaths() {
+    return Array.from(this.pathToFiles.keys());
   }
   /**
-   * Get all cached jay-html paths (for debugging/monitoring)
+   * Compute the cache file path for a given jay-html path and params.
    */
-  getCachedPaths() {
-    return Array.from(this.pathToKeys.keys());
+  computeCachePath(jayHtmlPath, params) {
+    const relativePath = path__default.relative(this.pagesRoot, jayHtmlPath);
+    const dir = path__default.dirname(relativePath);
+    const basename = path__default.basename(relativePath, ".jay-html");
+    const paramsHash = hashParams(params);
+    const cacheFileName = `${basename}${paramsHash}.jay-html`;
+    return path__default.join(this.cacheDir, dir, cacheFileName);
+  }
+  /**
+   * Track a pre-rendered file path for invalidation.
+   */
+  trackFile(jayHtmlPath, preRenderedPath) {
+    if (!this.pathToFiles.has(jayHtmlPath)) {
+      this.pathToFiles.set(jayHtmlPath, /* @__PURE__ */ new Set());
+    }
+    this.pathToFiles.get(jayHtmlPath).add(preRenderedPath);
+  }
+  /**
+   * Scan the cache directory for files matching a route and delete them.
+   * Handles the startup case where pathToFiles is not populated from a previous session.
+   */
+  async scanAndDeleteCacheFiles(jayHtmlPath) {
+    const relativePath = path__default.relative(this.pagesRoot, jayHtmlPath);
+    const dir = path__default.dirname(relativePath);
+    const basename = path__default.basename(relativePath, ".jay-html");
+    const cacheSubDir = path__default.join(this.cacheDir, dir);
+    try {
+      const files = await fs$2.readdir(cacheSubDir);
+      for (const file of files) {
+        if (file.startsWith(basename) && file.endsWith(".jay-html")) {
+          try {
+            await fs$2.unlink(path__default.join(cacheSubDir, file));
+          } catch {
+          }
+        }
+      }
+    } catch {
+    }
   }
 }
 const require2 = createRequire(import.meta.url);
@@ -1361,8 +2041,7 @@ async function executeDynamicGenerator(plugin, config, projectRoot, services, ve
   if (verbose) {
     getLogger().info(`   Executing generator...`);
   }
-  const result = await generator.generate(...resolvedServices);
-  return result;
+  return await generator.generate(...resolvedServices);
 }
 function resolveStaticContractPath(plugin, contractSpec, projectRoot) {
   const { pluginPath, isLocal, packageName } = plugin;
@@ -1384,6 +2063,25 @@ function resolveStaticContractPath(plugin, contractSpec, projectRoot) {
     return path.join(pluginPath, contractSpec);
   }
 }
+function resolveActionFilePath(actionPath, packageName, pluginPath, isLocal, projectRoot) {
+  if (!isLocal && !actionPath.startsWith(".")) {
+    try {
+      return require2.resolve(`${packageName}/${actionPath}`, {
+        paths: [projectRoot]
+      });
+    } catch {
+      const possiblePaths = [
+        path.join(pluginPath, "dist", actionPath),
+        path.join(pluginPath, "lib", actionPath),
+        path.join(pluginPath, actionPath)
+      ];
+      const found = possiblePaths.find((p) => fs.existsSync(p));
+      return found || null;
+    }
+  }
+  const resolved = resolveActionMetadataPath(actionPath, pluginPath);
+  return fs.existsSync(resolved) ? resolved : null;
+}
 function toKebabCase(str) {
   return str.replace(/([A-Z])/g, "-$1").toLowerCase().replace(/^-/, "");
 }
@@ -1399,13 +2097,12 @@ function getJayStackVersion() {
 async function materializeContracts(options, services = /* @__PURE__ */ new Map()) {
   const {
     projectRoot,
-    outputDir = path.join(projectRoot, "build", "materialized-contracts"),
+    outputDir = path.join(projectRoot, "agent-kit", "materialized-contracts"),
     dynamicOnly = false,
     pluginFilter,
     verbose = false,
     viteServer
   } = options;
-  const contracts = [];
   const pluginsIndexMap = /* @__PURE__ */ new Map();
   let staticCount = 0;
   let dynamicCount = 0;
@@ -1429,6 +2126,14 @@ async function materializeContracts(options, services = /* @__PURE__ */ new Map(
 📦 Processing plugin: ${plugin.name}`);
     }
     const { manifest } = plugin;
+    const pluginRelPath = path.relative(projectRoot, plugin.pluginPath);
+    if (!pluginsIndexMap.has(plugin.name)) {
+      pluginsIndexMap.set(plugin.name, {
+        path: "./" + pluginRelPath.replace(/\\/g, "/"),
+        contracts: [],
+        actions: []
+      });
+    }
     if (!dynamicOnly && manifest.contracts) {
       for (const contract of manifest.contracts) {
         const contractPath = resolveStaticContractPath(
@@ -1437,26 +2142,12 @@ async function materializeContracts(options, services = /* @__PURE__ */ new Map(
           projectRoot
         );
         const relativePath = path.relative(projectRoot, contractPath);
-        const entry = {
-          plugin: plugin.name,
-          name: contract.name,
-          type: "static",
-          path: "./" + relativePath
-        };
-        contracts.push(entry);
-        staticCount++;
-        const pluginRelPath = path.relative(projectRoot, plugin.pluginPath);
-        if (!pluginsIndexMap.has(plugin.name)) {
-          pluginsIndexMap.set(plugin.name, {
-            path: "./" + pluginRelPath.replace(/\\/g, "/"),
-            contracts: []
-          });
-        }
         pluginsIndexMap.get(plugin.name).contracts.push({
           name: contract.name,
           type: "static",
           path: "./" + relativePath
         });
+        staticCount++;
         if (verbose) {
           getLogger().info(`   📄 Static: ${contract.name}`);
         }
@@ -1486,27 +2177,14 @@ 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);
-            const dynEntry = {
-              plugin: plugin.name,
+            const contractEntry = {
               name: fullName,
               type: "dynamic",
               path: "./" + relativePath,
-              metadata: generated.metadata
+              ...generated.metadata && { metadata: generated.metadata }
             };
-            contracts.push(dynEntry);
+            pluginsIndexMap.get(plugin.name).contracts.push(contractEntry);
             dynamicCount++;
-            const pluginRelPath = path.relative(projectRoot, plugin.pluginPath);
-            if (!pluginsIndexMap.has(plugin.name)) {
-              pluginsIndexMap.set(plugin.name, {
-                path: "./" + pluginRelPath.replace(/\\/g, "/"),
-                contracts: []
-              });
-            }
-            pluginsIndexMap.get(plugin.name).contracts.push({
-              name: fullName,
-              type: "dynamic",
-              path: "./" + relativePath
-            });
             if (verbose) {
               getLogger().info(`   ⚡ Materialized: ${fullName}`);
             }
@@ -1518,33 +2196,54 @@ async function materializeContracts(options, services = /* @__PURE__ */ new Map(
         }
       }
     }
+    if (manifest.actions && Array.isArray(manifest.actions)) {
+      for (const entry of manifest.actions) {
+        const { name: actionName, action: actionPath } = normalizeActionEntry(entry);
+        if (!actionPath)
+          continue;
+        const metadataFilePath = resolveActionFilePath(
+          actionPath,
+          plugin.packageName,
+          plugin.pluginPath,
+          plugin.isLocal,
+          projectRoot
+        );
+        if (!metadataFilePath)
+          continue;
+        const metadata = loadActionMetadata(metadataFilePath);
+        if (!metadata)
+          continue;
+        const actionRelPath = path.relative(projectRoot, metadataFilePath);
+        pluginsIndexMap.get(plugin.name).actions.push({
+          name: metadata.name,
+          description: metadata.description,
+          path: "./" + actionRelPath.replace(/\\/g, "/")
+        });
+        if (verbose) {
+          getLogger().info(`   🔧 Action: ${metadata.name} (${actionPath})`);
+        }
+      }
+    }
   }
-  const index = {
-    materialized_at: (/* @__PURE__ */ new Date()).toISOString(),
-    jay_stack_version: getJayStackVersion(),
-    contracts
-  };
-  fs.mkdirSync(outputDir, { recursive: true });
-  const indexPath = path.join(outputDir, "contracts-index.yaml");
-  fs.writeFileSync(indexPath, YAML.stringify(index), "utf-8");
   const pluginsIndex = {
-    materialized_at: index.materialized_at,
-    jay_stack_version: index.jay_stack_version,
+    jay_stack_version: getJayStackVersion(),
     plugins: Array.from(pluginsIndexMap.entries()).map(([name, data]) => ({
       name,
       path: data.path,
-      contracts: data.contracts
+      contracts: data.contracts,
+      ...data.actions.length > 0 && { actions: data.actions }
     }))
   };
-  const pluginsIndexPath = path.join(outputDir, "plugins-index.yaml");
+  fs.mkdirSync(outputDir, { recursive: true });
+  const agentKitDir = path.dirname(outputDir);
+  const pluginsIndexPath = path.join(agentKitDir, "plugins-index.yaml");
   fs.writeFileSync(pluginsIndexPath, YAML.stringify(pluginsIndex), "utf-8");
   if (verbose) {
     getLogger().info(`
-✅ Contracts index written to: ${indexPath}`);
-    getLogger().info(`✅ Plugins index written to: ${pluginsIndexPath}`);
+✅ Plugins index written to: ${pluginsIndexPath}`);
   }
   return {
-    index,
+    pluginsIndex,
     staticCount,
     dynamicCount,
     outputDir
@@ -1552,7 +2251,7 @@ async function materializeContracts(options, services = /* @__PURE__ */ new Map(
 }
 async function listContracts(options) {
   const { projectRoot, dynamicOnly = false, pluginFilter } = options;
-  const contracts = [];
+  const pluginsMap = /* @__PURE__ */ new Map();
   const plugins = await scanPlugins({
     projectRoot,
     includeDevDeps: true
@@ -1561,6 +2260,13 @@ async function listContracts(options) {
     if (pluginFilter && plugin.name !== pluginFilter && pluginKey !== pluginFilter)
       continue;
     const { manifest } = plugin;
+    const pluginRelPath = path.relative(projectRoot, plugin.pluginPath);
+    if (!pluginsMap.has(plugin.name)) {
+      pluginsMap.set(plugin.name, {
+        path: "./" + pluginRelPath.replace(/\\/g, "/"),
+        contracts: []
+      });
+    }
     if (!dynamicOnly && manifest.contracts) {
       for (const contract of manifest.contracts) {
         const contractPath = resolveStaticContractPath(
@@ -1569,8 +2275,7 @@ async function listContracts(options) {
           projectRoot
         );
         const relativePath = path.relative(projectRoot, contractPath);
-        contracts.push({
-          plugin: plugin.name,
+        pluginsMap.get(plugin.name).contracts.push({
           name: contract.name,
           type: "static",
           path: "./" + relativePath
@@ -1580,8 +2285,7 @@ async function listContracts(options) {
     if (manifest.dynamic_contracts) {
       const dynamicConfigs = Array.isArray(manifest.dynamic_contracts) ? manifest.dynamic_contracts : [manifest.dynamic_contracts];
       for (const config of dynamicConfigs) {
-        contracts.push({
-          plugin: plugin.name,
+        pluginsMap.get(plugin.name).contracts.push({
           name: `${config.prefix}/*`,
           type: "dynamic",
           path: "(run materialization to generate)"
@@ -1590,9 +2294,12 @@ async function listContracts(options) {
     }
   }
   return {
-    materialized_at: (/* @__PURE__ */ new Date()).toISOString(),
     jay_stack_version: getJayStackVersion(),
-    contracts
+    plugins: Array.from(pluginsMap.entries()).map(([name, data]) => ({
+      name,
+      path: data.path,
+      contracts: data.contracts
+    }))
   };
 }
 async function discoverPluginsWithSetup(options) {
@@ -1673,13 +2380,14 @@ async function executePluginSetup(plugin, options) {
   return handler(context);
 }
 async function executePluginReferences(plugin, options) {
-  const { projectRoot, force, viteServer } = options;
+  const { projectRoot, force, initError, viteServer } = options;
   const referencesDir = path.join(projectRoot, "agent-kit", "references", plugin.name);
   const context = {
     pluginName: plugin.name,
     projectRoot,
     referencesDir,
     services: getServiceRegistry(),
+    initError,
     force
   };
   const handler = await loadHandler(
@@ -1726,9 +2434,12 @@ export {
   DevSlowlyChangingPhase,
   SlowRenderCache,
   actionRegistry,
+  buildAutomationWrap,
+  buildScriptFragments,
   clearActionRegistry,
   clearClientInitData,
   clearLifecycleCallbacks,
+  clearServerElementCache,
   clearServiceRegistry,
   discoverAllPluginActions,
   discoverAndRegisterActions,
@@ -1741,6 +2452,7 @@ export {
   executePluginServerInits,
   executePluginSetup,
   generateClientScript,
+  generateSSRPageHtml,
   getActionCacheHeaders,
   getClientInitData,
   getClientInitDataForKey,
@@ -1750,15 +2462,19 @@ export {
   getServiceRegistry,
   hasAction,
   hasService,
+  invalidateServerElementCache,
   listContracts,
+  loadActionMetadata,
   loadPageParts,
   materializeContracts,
   onInit,
   onShutdown,
+  parseActionMetadata,
   preparePluginClientInits,
   registerAction,
   registerService,
   renderFastChangingData,
+  resolveActionMetadataPath,
   resolveServices,
   runInitCallbacks,
   runLoadParams,
@@ -1767,5 +2483,6 @@ export {
   scanPlugins,
   setClientInitData,
   slowRenderInstances,
-  sortPluginsByDependencies
+  sortPluginsByDependencies,
+  validateForEachInstances
 };