@jay-framework/stack-server-runtime 0.13.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, parseAction } 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
       });
     }
@@ -551,200 +1095,35 @@ class ActionRegistry {
     const parts = [];
     if (maxAge !== void 0) {
       parts.push(`max-age=${maxAge}`);
-    }
-    if (staleWhileRevalidate !== void 0) {
-      parts.push(`stale-while-revalidate=${staleWhileRevalidate}`);
-    }
-    return parts.length > 0 ? parts.join(", ") : void 0;
-  }
-}
-const actionRegistry = new ActionRegistry();
-function registerAction(action) {
-  actionRegistry.register(action);
-}
-function getRegisteredAction(actionName) {
-  return actionRegistry.get(actionName);
-}
-function hasAction(actionName) {
-  return actionRegistry.has(actionName);
-}
-function getRegisteredActionNames() {
-  return actionRegistry.getNames();
-}
-function clearActionRegistry() {
-  actionRegistry.clear();
-}
-async function executeAction(actionName, input) {
-  return actionRegistry.execute(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;
+    }
+    if (staleWhileRevalidate !== void 0) {
+      parts.push(`stale-while-revalidate=${staleWhileRevalidate}`);
+    }
+    return parts.length > 0 ? parts.join(", ") : void 0;
   }
 }
-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;
+const actionRegistry = new ActionRegistry();
+function registerAction(action) {
+  actionRegistry.register(action);
 }
-function isImportedType(aType) {
-  return aType.kind === 4;
+function getRegisteredAction(actionName) {
+  return actionRegistry.get(actionName);
 }
-function isObjectType(aType) {
-  return aType.kind === 8;
+function hasAction(actionName) {
+  return actionRegistry.has(actionName);
 }
-function isArrayType(aType) {
-  return aType.kind === 9;
+function getRegisteredActionNames() {
+  return actionRegistry.getNames();
 }
-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;
+function clearActionRegistry() {
+  actionRegistry.clear();
 }
-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 normalizeActionEntry(entry) {
-  if (typeof entry === "string") {
-    return { name: entry };
-  }
-  return { name: entry.name, action: entry.action };
+async function executeAction(actionName, input) {
+  return actionRegistry.execute(actionName, input);
 }
-function loadPluginManifest(pluginDir) {
-  const pluginYamlPath = path$1.join(pluginDir, "plugin.yaml");
-  if (!fs$2.existsSync(pluginYamlPath)) {
-    return null;
-  }
-  try {
-    const yamlContent = fs$2.readFileSync(pluginYamlPath, "utf-8");
-    return YAML.parse(yamlContent);
-  } catch (error) {
-    return null;
-  }
+function getActionCacheHeaders(actionName) {
+  return actionRegistry.getCacheHeaders(actionName);
 }
-const s = createRequire(import.meta.url), e = s("typescript");
-new Proxy(e, {
-  get(t, r) {
-    return t[r];
-  }
-});
 function parseActionMetadata(yamlContent, fileName) {
   try {
     const parsed = parseAction(yamlContent, fileName);
@@ -1352,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) => {
@@ -1375,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.
@@ -1477,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);
@@ -1640,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;
@@ -1670,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(
@@ -1678,27 +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: [],
-            actions: []
-          });
-        }
         pluginsIndexMap.get(plugin.name).contracts.push({
           name: contract.name,
           type: "static",
           path: "./" + relativePath
         });
+        staticCount++;
         if (verbose) {
           getLogger().info(`   📄 Static: ${contract.name}`);
         }
@@ -1728,28 +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: [],
-                actions: []
-              });
-            }
-            pluginsIndexMap.get(plugin.name).contracts.push({
-              name: fullName,
-              type: "dynamic",
-              path: "./" + relativePath
-            });
             if (verbose) {
               getLogger().info(`   ⚡ Materialized: ${fullName}`);
             }
@@ -1778,14 +2213,6 @@ async function materializeContracts(options, services = /* @__PURE__ */ new Map(
         const metadata = loadActionMetadata(metadataFilePath);
         if (!metadata)
           continue;
-        const pluginRelPath = path.relative(projectRoot, plugin.pluginPath);
-        if (!pluginsIndexMap.has(plugin.name)) {
-          pluginsIndexMap.set(plugin.name, {
-            path: "./" + pluginRelPath.replace(/\\/g, "/"),
-            contracts: [],
-            actions: []
-          });
-        }
         const actionRelPath = path.relative(projectRoot, metadataFilePath);
         pluginsIndexMap.get(plugin.name).actions.push({
           name: metadata.name,
@@ -1798,17 +2225,8 @@ async function materializeContracts(options, services = /* @__PURE__ */ new Map(
       }
     }
   }
-  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,
@@ -1816,15 +2234,16 @@ async function materializeContracts(options, services = /* @__PURE__ */ new Map(
       ...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
@@ -1832,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
@@ -1841,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(
@@ -1849,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
@@ -1860,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)"
@@ -1870,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) {
@@ -2007,9 +2434,12 @@ export {
   DevSlowlyChangingPhase,
   SlowRenderCache,
   actionRegistry,
+  buildAutomationWrap,
+  buildScriptFragments,
   clearActionRegistry,
   clearClientInitData,
   clearLifecycleCallbacks,
+  clearServerElementCache,
   clearServiceRegistry,
   discoverAllPluginActions,
   discoverAndRegisterActions,
@@ -2022,6 +2452,7 @@ export {
   executePluginServerInits,
   executePluginSetup,
   generateClientScript,
+  generateSSRPageHtml,
   getActionCacheHeaders,
   getClientInitData,
   getClientInitDataForKey,
@@ -2031,6 +2462,7 @@ export {
   getServiceRegistry,
   hasAction,
   hasService,
+  invalidateServerElementCache,
   listContracts,
   loadActionMetadata,
   loadPageParts,