@jay-framework/dev-server 0.24.0 → 0.24.2

package/dist/index.js

@@ -7,31 +7,33 @@ import { createRequire } from "module";
 import "@jay-framework/compiler-shared";
 import * as path from "node:path";
 import path__default from "node:path";
-import { injectHeadfullFSTemplates, JAY_IMPORT_RESOLVER, parseContract, slowRenderTransform, assignCoordinatesToJayHtml, discoverHeadlessInstances } from "@jay-framework/compiler-jay-html";
+import { parseJayFile, JAY_IMPORT_RESOLVER, injectHeadfullFSTemplates, discoverHeadlessInstances, assignCoordinatesToJayHtml, parseAction, generateServerElementFile, parseContract, slowRenderTransform } from "@jay-framework/compiler-jay-html";
 import { getLogger, getDevLogger } from "@jay-framework/logger";
 import { createRequire as createRequire$1 } from "node:module";
-import * as fsSync from "node:fs";
-import fsSync__default from "node:fs";
+import * as fs from "node:fs";
+import fs__default$1 from "node:fs";
 import { scanRoutes, createRoute, routeToExpressRoute } from "@jay-framework/stack-route-scanner";
-import { discoverPluginsWithInit, sortPluginsByDependencies, executePluginServerInits, runInitCallbacks, discoverAndRegisterActions, actionRegistry, discoverAllPluginActions, runShutdownCallbacks, clearLifecycleCallbacks, clearServiceRegistry, clearClientInitData, loadPageParts, runLoadParams, DevSlowlyChangingPhase, SlowRenderCache, preparePluginClientInits, registerService, getServiceRegistry, materializeContracts, scanPlugins, clearServerElementCache, parseCookies, generateFrozenPageHtml, renderFastChangingData, generateClientScript, getClientInitData, mergeHeadTags, generateSSRPageHtml, slowRenderInstances, normalizeAndResolveInstanceProps } from "@jay-framework/stack-server-runtime";
-import * as fs from "node:fs/promises";
+import { actionRegistry, scanPlugins, serializeHeadTags, mergeHeadTags, discoverPluginsWithInit, sortPluginsByDependencies, executePluginServerInits, runInitCallbacks, runShutdownCallbacks, clearLifecycleCallbacks, clearServiceRegistry, clearClientInitData, runLoadParams, DevSlowlyChangingPhase, preparePluginClientInits, registerService, getServiceRegistry, parseCookies, renderFastChangingData, getClientInitData, slowRenderInstances, normalizeAndResolveInstanceProps } from "@jay-framework/stack-server-runtime";
+import * as fs$1 from "node:fs/promises";
 import fs__default from "node:fs/promises";
+import jsBeautify from "js-beautify";
+import fs$2 from "fs";
+import path$1 from "path";
+import YAML from "yaml";
+import crypto, { randomUUID } from "node:crypto";
+import { isJayAction, isJayStreamAction, createJayService } from "@jay-framework/fullstack-component";
 import { pathToFileURL } from "node:url";
 import Busboy from "busboy";
-import fs$1 from "fs";
-import path$1 from "path";
-import crypto from "crypto";
-import { randomUUID } from "node:crypto";
-import { createJayService } from "@jay-framework/fullstack-component";
-const s$1 = createRequire(import.meta.url), e$1 = s$1("typescript"), c$1 = new Proxy(e$1, {
+import crypto$1 from "crypto";
+const s$2 = createRequire(import.meta.url), e$2 = s$2("typescript"), c$1 = new Proxy(e$2, {
   get(t, r) {
     return t[r];
   }
 });
-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);
-const s = createRequire(import.meta.url), e = s("typescript"), c = new Proxy(e, {
+var __defProp$1 = Object.defineProperty;
+var __defNormalProp$1 = (obj, key, value) => key in obj ? __defProp$1(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField$1 = (obj, key, value) => __defNormalProp$1(obj, typeof key !== "symbol" ? key + "" : key, value);
+const s$1 = createRequire(import.meta.url), e$1 = s$1("typescript"), c = new Proxy(e$1, {
   get(t, r) {
     return t[r];
   }
@@ -180,7 +182,7 @@ function tsBindingNameToVariable(binding, accessedFrom, assignedFrom, propertyNa
 }
 class NameBindingResolver {
   constructor(parentNameResolver) {
-    __publicField2(this, "variables", /* @__PURE__ */ new Map());
+    __publicField$1(this, "variables", /* @__PURE__ */ new Map());
     this.parentNameResolver = parentNameResolver;
   }
   addVariable(name, variable) {
@@ -455,7 +457,7 @@ class GlobalResolvedType {
 }
 class SourceFileBindingResolver {
   constructor(sourceFile) {
-    __publicField2(this, "nameBindingResolvers", /* @__PURE__ */ new Map());
+    __publicField$1(this, "nameBindingResolvers", /* @__PURE__ */ new Map());
     this.nameBindingResolvers.set(sourceFile, new NameBindingResolver());
     const nbResolversQueue = [
       this.nameBindingResolvers.get(sourceFile)
@@ -1244,7 +1246,7 @@ function createImportChainTracker(options = {}) {
     }
   };
 }
-const require$1 = createRequire$1(import.meta.url);
+const require$1$1 = createRequire$1(import.meta.url);
 function createDefaultPluginDetector() {
   const cache = /* @__PURE__ */ new Map();
   return {
@@ -1255,9 +1257,9 @@ function createDefaultPluginDetector() {
       }
       let result = false;
       try {
-        require$1.resolve(`${packageName}/plugin.yaml`, { paths: [projectRoot] });
+        require$1$1.resolve(`${packageName}/plugin.yaml`, { paths: [projectRoot] });
         try {
-          require$1.resolve(`${packageName}/client`, { paths: [projectRoot] });
+          require$1$1.resolve(`${packageName}/client`, { paths: [projectRoot] });
           result = true;
         } catch {
           result = false;
@@ -1428,16 +1430,16 @@ function jayStackCompiler(options = {}) {
           const importerDir = path.dirname(importer);
           let resolvedPath = path.resolve(importerDir, source);
           if (!resolvedPath.endsWith(".ts") && !resolvedPath.endsWith(".js")) {
-            if (fsSync.existsSync(resolvedPath + ".ts")) {
+            if (fs.existsSync(resolvedPath + ".ts")) {
               resolvedPath += ".ts";
-            } else if (fsSync.existsSync(resolvedPath + ".js")) {
+            } else if (fs.existsSync(resolvedPath + ".js")) {
               resolvedPath += ".js";
             } else {
               return null;
             }
-          } else if (resolvedPath.endsWith(".js") && !fsSync.existsSync(resolvedPath)) {
+          } else if (resolvedPath.endsWith(".js") && !fs.existsSync(resolvedPath)) {
             const tsPath = resolvedPath.slice(0, -3) + ".ts";
-            if (fsSync.existsSync(tsPath)) {
+            if (fs.existsSync(tsPath)) {
               resolvedPath = tsPath;
             } else {
               return null;
@@ -1452,7 +1454,7 @@ function jayStackCompiler(options = {}) {
           const actualPath = id.slice("\0jay-action:".length);
           let code;
           try {
-            code = await fsSync.promises.readFile(actualPath, "utf-8");
+            code = await fs.promises.readFile(actualPath, "utf-8");
           } catch (err) {
             getLogger().error(
               `[action-transform] Could not read ${actualPath}: ${err}`
@@ -1610,6 +1612,1873 @@ async function createViteForCli(options) {
   });
   return vite;
 }
+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);
+const require$3 = createRequire(import.meta.url);
+async function loadPageParts(vite, route, pagesBase, projectBase, jayRollupConfig, options) {
+  const exists = await fs__default.access(route.compPath, fs__default.constants.F_OK).then(() => true).catch(() => false);
+  const parts = [];
+  const validations = [];
+  if (exists) {
+    const exportName = route.componentExport || "page";
+    const pageComponent = (await vite.ssrLoadModule(route.compPath))[exportName];
+    if (!pageComponent) {
+      validations.push(
+        `${route.compPath} does not export "${exportName}". The file exists but the expected export is missing — remove the file or add the export.`
+      );
+    } else {
+      const clientImportPath = route.componentExport ? route.compPath.replace(/index\.js$/, "index.client.js") : route.compPath;
+      parts.push({
+        compDefinition: pageComponent,
+        clientImport: `import {${exportName}} from '${clientImportPath}'`,
+        clientPart: `{comp: ${exportName}.comp, contextMarkers: ${exportName}.contexts || []}`
+      });
+    }
+  }
+  const jayHtmlFilePath = options?.preRenderedPath ?? route.jayHtmlPath;
+  const jayHtmlSource = options?.preRenderedContent ?? (await fs__default.readFile(jayHtmlFilePath)).toString();
+  const fileName = path__default.basename(route.jayHtmlPath);
+  const dirName = path__default.dirname(route.jayHtmlPath);
+  const jayHtmlWithValidations = await parseJayFile(
+    jayHtmlSource,
+    fileName,
+    dirName,
+    {
+      relativePath: jayRollupConfig.tsConfigFilePath
+    },
+    JAY_IMPORT_RESOLVER,
+    projectBase
+  );
+  jayHtmlWithValidations.validations.push(...validations);
+  return jayHtmlWithValidations.mapAsync(async (jayHtml) => {
+    const usedPackages = /* @__PURE__ */ new Set();
+    const headlessInstanceComponents = [];
+    for await (const headlessImport of jayHtml.headlessImports) {
+      const module = headlessImport.codeLink.module;
+      const name = headlessImport.codeLink.names[0].name;
+      const isLocalModule = module[0] === "." || module[0] === "/";
+      let compDefinition;
+      let clientModuleImport;
+      let isNpmPackage;
+      if (headlessImport.structural) {
+        continue;
+      } else {
+        const modulePath = isLocalModule ? path__default.resolve(dirName, module) : require$3.resolve(module, { paths: require$3.resolve.paths(dirName) });
+        compDefinition = (await vite.ssrLoadModule(modulePath))[name];
+        const moduleImport = isLocalModule ? path__default.resolve(dirName, module) : module;
+        isNpmPackage = !isLocalModule;
+        clientModuleImport = isNpmPackage ? `${moduleImport}/client` : `${moduleImport}`;
+      }
+      if (isNpmPackage) {
+        const packageName = module.startsWith("@") ? module.split("/").slice(0, 2).join("/") : module.split("/")[0];
+        usedPackages.add(packageName);
+      }
+      if (headlessImport.key) {
+        const key = headlessImport.key;
+        const hasClientComp = !!compDefinition?.fastRender || !!compDefinition?.hasInteractive;
+        const part = {
+          key,
+          compDefinition,
+          clientImport: hasClientComp ? `import {${name}} from '${clientModuleImport}'` : "",
+          clientPart: hasClientComp ? `{comp: ${name}.comp, contextMarkers: ${name}.contexts || [], key: '${key}'}` : "",
+          contractInfo: headlessImport.contract ? {
+            contractName: headlessImport.contract.name,
+            metadata: headlessImport.metadata
+          } : void 0,
+          headlessProps: headlessImport.headlessProps
+        };
+        parts.push(part);
+      }
+      if (!headlessImport.key && headlessImport.contract) {
+        headlessInstanceComponents.push({
+          contractName: headlessImport.contractName,
+          compDefinition,
+          contract: headlessImport.contract
+        });
+      }
+    }
+    const headlessContracts = jayHtml.headlessImports.filter((hi) => hi.contract !== void 0 && hi.key !== void 0).map((hi) => ({
+      key: hi.key,
+      contract: hi.contract,
+      contractPath: hi.contractPath
+    }));
+    const jayHtmlForDiscovery = injectHeadfullFSTemplates(
+      jayHtmlSource,
+      dirName,
+      JAY_IMPORT_RESOLVER
+    );
+    let discoveryResult;
+    if (headlessInstanceComponents.length > 0) {
+      const firstDiscovery = discoverHeadlessInstances(jayHtmlForDiscovery);
+      const headlessContractNameSet = new Set(
+        jayHtml.headlessImports.map((hi) => hi.contractName)
+      );
+      const jayHtmlWithCoords = assignCoordinatesToJayHtml(
+        firstDiscovery.preRenderedJayHtml,
+        headlessContractNameSet
+      );
+      discoveryResult = discoverHeadlessInstances(jayHtmlWithCoords);
+    } else {
+      discoveryResult = {
+        instances: [],
+        forEachInstances: [],
+        preRenderedJayHtml: jayHtmlSource
+      };
+    }
+    return {
+      parts,
+      serverTrackByMap: jayHtml.serverTrackByMap,
+      clientTrackByMap: jayHtml.clientTrackByMap,
+      usedPackages,
+      headlessContracts,
+      headlessInstanceComponents,
+      discoveredInstances: discoveryResult.instances,
+      forEachInstances: discoveryResult.forEachInstances,
+      linkedCssFiles: jayHtml.linkedCssFiles ?? [],
+      linkedComponentFiles: jayHtml.linkedComponentFiles ?? [],
+      scripts: jayHtml.scripts
+    };
+  });
+}
+var __defProp22 = Object.defineProperty;
+var __defNormalProp22 = (obj, key, value) => key in obj ? __defProp22(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField22 = (obj, key, value) => __defNormalProp22(obj, key + "", value);
+class JayAtomicType {
+  constructor(name) {
+    __publicField22(this, "kind", 0);
+    this.name = name;
+  }
+}
+new JayAtomicType("string");
+new JayAtomicType("string");
+new JayAtomicType("number");
+new JayAtomicType("boolean");
+new JayAtomicType("Date");
+new JayAtomicType("file");
+new JayAtomicType("Unknown");
+class JayObjectType {
+  constructor(name, props) {
+    __publicField22(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 === 14;
+}
+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 isRecordType(aType) {
+  return aType.kind === 11;
+}
+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 };
+    }
+    if (name === "file") {
+      return { type: "string", description: "Binary file upload (JayFile)" };
+    }
+    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 (isRecordType(type)) {
+    const valueSchema = jayTypeToJsonSchema(type.itemType);
+    if (valueSchema) {
+      return { type: "object", additionalProperties: valueSchema };
+    }
+    return { type: "object" };
+  }
+  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;
+}
+const { html: htmlBeautify } = jsBeautify;
+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$2.existsSync(pluginYamlPath)) {
+    return null;
+  }
+  try {
+    const yamlContent = fs$2.readFileSync(pluginYamlPath, "utf-8");
+    return YAML.parse(yamlContent);
+  } catch (error) {
+    return null;
+  }
+}
+const s = createRequire(import.meta.url), e = s("typescript");
+new Proxy(e, {
+  get(t, r) {
+    return t[r];
+  }
+});
+function asyncSwapScript(id, html) {
+  const escapedHtml = html.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+  return `<script>(function(){var t=document.querySelector('[jay-async="${id}:pending"]');if(t){var d=document.createElement('div');d.innerHTML='${escapedHtml}';t.replaceWith(d.firstChild);}window.__jay&&window.__jay.hydrateAsync&&window.__jay.hydrateAsync('${id}');})()<\/script>`;
+}
+function generatePromiseReconstruction(outcomes) {
+  if (outcomes.length === 0) return "";
+  return outcomes.map((outcome) => {
+    if (outcome.status === "resolved") {
+      return `      viewState[${JSON.stringify(outcome.id)}] = Promise.resolve(${JSON.stringify(outcome.value)});`;
+    } else {
+      const errMsg = outcome.value?.message ?? "Unknown error";
+      return `      viewState[${JSON.stringify(outcome.id)}] = Promise.reject(new Error(${JSON.stringify(errMsg)}));`;
+    }
+  }).join("\n") + "\n";
+}
+function buildScriptFragments(parts, clientInitData, projectInit, pluginInits, options) {
+  const { enableAutomation = true, slowViewState } = options;
+  const hasSlowViewState = slowViewState && Object.keys(slowViewState).length > 0;
+  const clientParts = parts.filter((part) => part.clientPart);
+  const partImports = clientParts.length > 0 ? clientParts.map((part) => part.clientImport).join("\n") + "\n" : "";
+  const compositeParts = clientParts.length > 0 ? `[
+${clientParts.map((part) => "        " + part.clientPart).join(",\n")}
+        ]` : "[]";
+  const hasClientInit = projectInit || pluginInits.length > 0;
+  const pluginClientInitImports = pluginInits.map((plugin, idx) => {
+    return `import { ${plugin.initExport} as jayInit${idx} } from "${plugin.importPath}";`;
+  }).join("\n      ");
+  const projectInitImport = projectInit ? `import { ${projectInit.initExport || "init"} as projectJayInit } from "${projectInit.importPath}";` : "";
+  const pluginClientInitCalls = pluginInits.map((plugin, idx) => {
+    const pluginData = clientInitData[plugin.name] || {};
+    return `if (typeof jayInit${idx}._clientInit === 'function') {
+        console.log('[DevServer] Running client init: ${plugin.name}');
+        await jayInit${idx}._clientInit(${JSON.stringify(pluginData)});
+      }`;
+  }).join("\n      ");
+  const projectInitCall = projectInit ? `if (typeof projectJayInit._clientInit === 'function') {
+        console.log('[DevServer] Running client init: project');
+        const projectData = ${JSON.stringify(clientInitData["project"] || {})};
+        await projectJayInit._clientInit(projectData);
+      }` : "";
+  const clientInitExecution = hasClientInit ? `
+      // Plugin client initialization (in dependency order)
+      ${pluginClientInitCalls}
+
+      // Project client initialization
+      ${projectInitCall}
+` : "";
+  const automationImport = enableAutomation ? hasSlowViewState ? `import { wrapWithAutomation, AUTOMATION_CONTEXT } from "@jay-framework/runtime-automation";
+      import { registerGlobalContext } from "@jay-framework/runtime";
+      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)};` : "";
+  return {
+    partImports,
+    compositeParts,
+    pluginClientInitImports,
+    projectInitImport,
+    clientInitExecution,
+    automationImport,
+    slowViewStateDecl
+  };
+}
+function buildFreezeScript(routePattern) {
+  const routePatternLiteral = routePattern ? `'${routePattern}'` : "undefined";
+  return `
+      // Page Freeze (DL#127, DL#128 iframe addendum)
+      // Sticky embed mode: URL param sets a session cookie so in-iframe navigation preserves it
+      if (new URLSearchParams(window.location.search).has('_jay_embed')) {
+        document.cookie = '_jay_embed=1;path=/;samesite=lax';
+      }
+      const __jayEmbedMode = document.cookie.split(';').some(c => c.trim().startsWith('_jay_embed='));
+
+      async function __jayDoFreeze() {
+          const automation = window.__jay?.automation;
+          if (!automation) return;
+
+          // Visual feedback: white flash
+          const flash = document.createElement('div');
+          flash.style.cssText = 'position:fixed;inset:0;background:white;z-index:999999;opacity:0.8;pointer-events:none;transition:opacity 0.3s';
+          document.body.appendChild(flash);
+          requestAnimationFrame(() => { flash.style.opacity = '0'; });
+          setTimeout(() => flash.remove(), 400);
+
+          // Audio feedback: camera shutter
+          try {
+            const ctx = new AudioContext();
+            const buf = ctx.createBuffer(1, ctx.sampleRate * 0.15, ctx.sampleRate);
+            const data = buf.getChannelData(0);
+            for (let i = 0; i < data.length; i++) {
+              data[i] = (Math.random() * 2 - 1) * Math.exp(-i / (ctx.sampleRate * 0.02));
+            }
+            const src = ctx.createBufferSource();
+            src.buffer = buf;
+            src.connect(ctx.destination);
+            src.start();
+          } catch {}
+
+          // Capture and save
+          try {
+            const state = automation.getPageState();
+            const route = window.location.pathname;
+            const routePattern = ${routePatternLiteral};
+            const resp = await fetch('/_jay/freeze', {
+              method: 'POST',
+              headers: { 'Content-Type': 'application/json' },
+              body: JSON.stringify({ route, routePattern, viewState: state.viewState }),
+            });
+            const { id } = await resp.json();
+            if (__jayEmbedMode) {
+              window.parent.postMessage({ type: 'jay:freeze', id, route }, '*');
+            } else {
+              window.open(route + '?_jay_freeze=' + id, '_blank');
+            }
+          } catch (err) {
+            console.error('[Freeze] Failed:', err);
+          }
+      }
+
+      if (__jayEmbedMode) {
+        // Notify parent of the current route on load (DL#128 route addendum)
+        window.parent.postMessage({ type: 'jay:route', route: window.location.pathname, routePattern: ${routePatternLiteral} }, '*');
+
+        // Embed mode: parent triggers freeze via postMessage
+        window.addEventListener('message', (e) => {
+          if (e.data?.type === 'jay:requestFreeze') __jayDoFreeze();
+        });
+      } else {
+        // Standalone: Alt+S / Option+S keyboard shortcut
+        document.addEventListener('keydown', (e) => {
+          if (e.altKey && e.code === 'KeyS') {
+            e.preventDefault();
+            __jayDoFreeze();
+          }
+        });
+      }
+
+      // Targeted page reload: only reload if this page matches the changed route prefix
+      if (import.meta.hot) {
+        import.meta.hot.on('jay:page-reload', (data) => {
+          const prefix = data.routePrefix;
+          const pathname = window.location.pathname;
+          if (pathname === prefix || pathname.startsWith(prefix + '/')) {
+            window.location.reload();
+          }
+        });
+      }`;
+}
+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);` : "";
+  const freezeScript = buildFreezeScript(options.routePattern);
+  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);
+      const wrapped = wrapWithAutomation(instance, { initialViewState: fullViewState, trackByMap });
+      registerGlobalContext(AUTOMATION_CONTEXT, wrapped.automation);
+      window.__jay = window.__jay || {};
+      window.__jay.automation = wrapped.automation;
+      window.dispatchEvent(new Event('jay:automation-ready'));${appendLine}
+${freezeScript}`;
+  }
+  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;
+      window.dispatchEvent(new Event('jay:automation-ready'));${appendLine}
+${freezeScript}`;
+}
+async function resolveViewStatePromises(viewState) {
+  const entries = Object.entries(viewState);
+  const hasPromises = entries.some(([, v]) => v instanceof Promise);
+  if (!hasPromises) return { resolved: viewState, outcomes: [] };
+  const result = { ...viewState };
+  const outcomes = [];
+  for (const [key, value] of entries) {
+    if (value instanceof Promise) {
+      try {
+        const val = await value;
+        result[key] = val;
+        outcomes.push({ id: key, status: "resolved", value: val });
+      } catch (err) {
+        delete result[key];
+        outcomes.push({
+          id: key,
+          status: "rejected",
+          value: { message: err?.message ?? String(err) }
+        });
+      }
+    }
+  }
+  return { resolved: result, outcomes };
+}
+async function generateClientScript(defaultViewState, fastCarryForward, parts, jayHtmlPath, trackByMap = {}, clientInitData = {}, projectInit, pluginInits = [], options = {}) {
+  const { resolved, outcomes } = await resolveViewStatePromises(defaultViewState);
+  defaultViewState = resolved;
+  const {
+    partImports,
+    compositeParts,
+    pluginClientInitImports,
+    projectInitImport,
+    clientInitExecution,
+    automationImport,
+    slowViewStateDecl
+  } = buildScriptFragments(parts, clientInitData, projectInit, pluginInits, options);
+  const automationWrap = buildAutomationWrap(options, "client");
+  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>
+  </head>
+  <body>
+    <div id="target"></div>
+    <script type="module">
+      import {makeCompositeJayComponent} from "@jay-framework/stack-client-runtime";
+      ${automationImport}
+      ${pluginClientInitImports}
+      ${projectInitImport}
+      import { render } from '${jayHtmlPath}';
+      ${partImports}${slowViewStateDecl}
+      const viewState = ${JSON.stringify(defaultViewState)};
+${generatePromiseReconstruction(outcomes)}      
+      const fastCarryForward = ${JSON.stringify(fastCarryForward)};
+      const trackByMap = ${JSON.stringify(trackByMap)};
+${clientInitExecution}
+      const target = document.getElementById('target');
+      const pageComp = makeCompositeJayComponent(render, viewState, fastCarryForward, ${compositeParts}, trackByMap)
+
+      const instance = pageComp({/* placeholder for page props */})
+${automationWrap}
+    <\/script>
+  </body>
+</html>`;
+}
+const serverModuleCache = /* @__PURE__ */ new Map();
+function clearServerElementCache() {
+  serverModuleCache.clear();
+}
+function getByPath(obj, dotPath) {
+  const segments = dotPath.split(".");
+  let current = obj;
+  for (const seg of segments) {
+    if (current == null || typeof current !== "object") return void 0;
+    current = current[seg];
+  }
+  return current;
+}
+function resolveParts(parts, viewState) {
+  return parts.map((p) => {
+    if (p.kind === "static") return p.value;
+    if (!viewState) return `{${p.value}}`;
+    const resolved = getByPath(viewState, p.value);
+    return resolved !== void 0 && resolved !== null ? String(resolved) : `{${p.value}}`;
+  }).join("");
+}
+function headMetaToHeadTags(headMeta, viewState) {
+  if (!headMeta) return [];
+  const tags = [];
+  if (headMeta.title) {
+    tags.push({ tag: "title", children: resolveParts(headMeta.title, viewState) });
+  }
+  for (const m of headMeta.meta) {
+    const attrs = {};
+    if (m.name) attrs.name = m.name;
+    if (m.property) attrs.property = m.property;
+    attrs.content = resolveParts(m.content, viewState);
+    tags.push({ tag: "meta", attrs });
+  }
+  for (const l of headMeta.links) {
+    if (l.rel === "stylesheet" || l.rel === "import") continue;
+    const attrs = { rel: l.rel };
+    attrs.href = resolveParts(l.href, viewState);
+    for (const [k, v] of Object.entries(l)) {
+      if (k !== "rel" && k !== "href" && typeof v === "string") attrs[k] = v;
+    }
+    tags.push({ tag: "link", attrs });
+  }
+  return tags;
+}
+async function generateSSRPageHtml(vite, jayHtmlContent, jayHtmlFilename, jayHtmlDir, viewState, jayHtmlImportPath, parts, carryForward, trackByMap = {}, clientInitData = {}, buildFolder, projectRoot, routeDir, tsConfigFilePath, projectInit, pluginInits = [], options = {}, sourceDir, headTags, scripts) {
+  const jayHtmlPath = path__default.join(jayHtmlDir, jayHtmlFilename);
+  let cached = serverModuleCache.get(jayHtmlPath);
+  if (!cached) {
+    cached = await compileAndLoadServerElement(
+      vite,
+      jayHtmlContent,
+      jayHtmlFilename,
+      jayHtmlDir,
+      buildFolder,
+      projectRoot,
+      routeDir,
+      tsConfigFilePath,
+      sourceDir
+    );
+    serverModuleCache.set(jayHtmlPath, cached);
+  }
+  const htmlChunks = [];
+  const asyncPromises = [];
+  const asyncOutcomes = [];
+  const ctx = {
+    write: (chunk) => {
+      htmlChunks.push(chunk);
+    },
+    onAsync: (promise, id, templates) => {
+      const asyncPromise = promise.then(
+        (val) => {
+          asyncOutcomes.push({ id, status: "resolved", value: val });
+          if (templates.resolved) {
+            return asyncSwapScript(id, templates.resolved(val));
+          }
+          return "";
+        },
+        (err) => {
+          asyncOutcomes.push({
+            id,
+            status: "rejected",
+            value: { message: err?.message ?? String(err) }
+          });
+          if (templates.rejected) {
+            return asyncSwapScript(id, 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,
+    clientInitData,
+    projectInit,
+    pluginInits,
+    options,
+    asyncOutcomes
+  );
+  const cssLink = cached.cssHref ? `    <link rel="stylesheet" href="${cached.cssHref}" />` : "";
+  const tagSources = [];
+  if (headTags && headTags.length > 0) tagSources.push(headTags);
+  const headMetaTags = headMetaToHeadTags(cached.headMeta, viewState);
+  if (headMetaTags.length > 0) tagSources.push(headMetaTags);
+  const mergedTags = mergeHeadTags(tagSources);
+  const hasCustomTitle = mergedTags.some((t) => t.tag.toLowerCase() === "title");
+  const titleTag = hasCustomTitle ? "" : "    <title>Vite + TS</title>\n";
+  const headTagsHtml = mergedTags.length > 0 ? serializeHeadTags(mergedTags) : "";
+  const headScriptsHtml = serializeScripts(scripts, "head");
+  const bodyScriptsHtml = serializeScripts(scripts, "body");
+  const headExtras = [cssLink, headTagsHtml, headScriptsHtml].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" />
+${titleTag}${headExtras ? headExtras + "\n" : ""}  </head>
+  <body>
+    <div id="target">${ssrHtml}</div>${asyncScripts}
+    ${hydrationScript}${bodyScriptsHtml ? "\n    " + bodyScriptsHtml : ""}
+  </body>
+</html>`;
+}
+async function generateFrozenPageHtml(vite, jayHtmlContent, jayHtmlFilename, jayHtmlDir, viewState, buildFolder, projectRoot, routeDir, tsConfigFilePath, sourceDir, format = "page", freezeName) {
+  const jayHtmlPath = path__default.join(jayHtmlDir, jayHtmlFilename);
+  let cached = serverModuleCache.get(jayHtmlPath);
+  if (!cached) {
+    cached = await compileAndLoadServerElement(
+      vite,
+      jayHtmlContent,
+      jayHtmlFilename,
+      jayHtmlDir,
+      buildFolder,
+      projectRoot,
+      routeDir,
+      tsConfigFilePath,
+      sourceDir
+    );
+    serverModuleCache.set(jayHtmlPath, cached);
+  }
+  const htmlChunks = [];
+  const ctx = {
+    write: (chunk) => {
+      htmlChunks.push(chunk);
+    },
+    onAsync: () => {
+    }
+  };
+  cached.renderToStream(viewState, ctx);
+  const ssrHtml = htmlChunks.join("");
+  if (format === "fragment") {
+    let inlineCss = "";
+    if (cached.cssHref) {
+      try {
+        const cssPath = cached.cssHref.replace(/^\/@fs/, "").replace(/\?.*$/, "");
+        const cssContent = await fs__default.readFile(cssPath, "utf-8");
+        inlineCss = `<style>${cssContent}</style>`;
+      } catch {
+        inlineCss = `<link rel="stylesheet" href="${cached.cssHref}" />`;
+      }
+    }
+    return `${inlineCss}
+${ssrHtml}`;
+  }
+  const frozenHeadTags = headMetaToHeadTags(cached.headMeta, viewState);
+  const frozenHeadTagsHtml = frozenHeadTags.length > 0 ? serializeHeadTags(frozenHeadTags) : "";
+  const cssLink = cached.cssHref ? `    <link rel="stylesheet" href="${cached.cssHref}" />` : "";
+  const headExtras = [cssLink, frozenHeadTagsHtml].filter((_) => _).join("\n");
+  const label = freezeName ? ` — ${freezeName}` : "";
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Frozen${label}</title>
+${headExtras ? headExtras + "\n" : ""}    <style>
+      body::before {
+        content: 'FROZEN${label ? `: ${freezeName}` : ""}';
+        position: fixed;
+        top: 0;
+        right: 0;
+        background: #1a1a2e;
+        color: #e0e0ff;
+        padding: 2px 10px;
+        font: 11px/1.6 system-ui;
+        z-index: 99999;
+        border-bottom-left-radius: 4px;
+        opacity: 0.8;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="target">${ssrHtml}</div>
+  </body>
+</html>`;
+}
+function serializeScripts(scripts, position) {
+  if (!scripts) return "";
+  const filtered = scripts.filter((s2) => s2.position === position);
+  if (filtered.length === 0) return "";
+  return filtered.map((s2) => {
+    const attrs = Object.entries(s2.attributes).map(([k, v]) => v === "" ? k : `${k}="${v}"`).join(" ");
+    const attrStr = attrs ? " " + attrs : "";
+    if (s2.src) {
+      return `    <script src="${s2.src}"${attrStr}><\/script>`;
+    }
+    return `    <script${attrStr}>${s2.inline}<\/script>`;
+  }).join("\n");
+}
+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, sourceDir) {
+  const jayFile = await parseJayFile(
+    jayHtmlContent,
+    jayHtmlFilename,
+    jayHtmlDir,
+    { relativePath: tsConfigFilePath },
+    JAY_IMPORT_RESOLVER,
+    projectRoot,
+    sourceDir
+  );
+  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__default.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__default.writeFile(serverElementPath, adjustedCode, "utf-8");
+  const existingModule = vite.moduleGraph.getModuleById(serverElementPath);
+  if (existingModule) {
+    vite.moduleGraph.invalidateModule(existingModule);
+  }
+  const jayHtmlPath = path__default.join(serverElementDir, jayHtmlFilename);
+  invalidateJayHtmlModules(vite, jayHtmlPath);
+  const serverModule = await vite.ssrLoadModule(serverElementPath);
+  let cssHref;
+  if (parsedJayFile.css) {
+    const cssFilename = jayHtmlFilename.replace(".jay-html", ".css");
+    const cssPath = path__default.join(serverElementDir, cssFilename);
+    await fs__default.writeFile(cssPath, parsedJayFile.css, "utf-8");
+    const cssModules = vite.moduleGraph.getModulesByFile(cssPath);
+    if (cssModules) {
+      for (const mod of cssModules) {
+        vite.moduleGraph.invalidateModule(mod);
+      }
+    }
+    const hash = crypto.createHash("md5").update(parsedJayFile.css).digest("hex").slice(0, 8);
+    cssHref = "/@fs" + cssPath + "?v=" + hash + "&direct";
+  }
+  return {
+    renderToStream: serverModule.renderToStream,
+    headLinks: parsedJayFile.headLinks,
+    headMeta: parsedJayFile.headMeta,
+    cssHref
+  };
+}
+function invalidateJayHtmlModules(vite, jayHtmlPath) {
+  let count = 0;
+  const byFile = vite.moduleGraph.getModulesByFile(jayHtmlPath);
+  if (byFile) {
+    for (const mod of byFile) {
+      vite.moduleGraph.invalidateModule(mod);
+      count++;
+    }
+  }
+  const knownIds = [jayHtmlPath + ".ts", jayHtmlPath + JAY_QUERY_HYDRATE + ".ts"];
+  for (const id of knownIds) {
+    const mod = vite.moduleGraph.getModuleById(id);
+    if (mod) {
+      vite.moduleGraph.invalidateModule(mod);
+      count++;
+    }
+  }
+  const idMap = vite.moduleGraph.idToModuleMap;
+  for (const [id, mod] of idMap) {
+    if (id.includes(jayHtmlPath)) {
+      vite.moduleGraph.invalidateModule(mod);
+      count++;
+    }
+  }
+  if (count > 0) {
+    getLogger().info(`[SSR] Invalidated ${count} Vite module(s) for ${jayHtmlPath}`);
+  }
+}
+function generateHydrationScript(defaultViewState, fastCarryForward, parts, jayHtmlPath, trackByMap = {}, clientInitData = {}, projectInit, pluginInits = [], options = {}, asyncOutcomes = []) {
+  const {
+    partImports,
+    compositeParts,
+    pluginClientInitImports,
+    projectInitImport,
+    clientInitExecution,
+    automationImport,
+    slowViewStateDecl
+  } = buildScriptFragments(parts, clientInitData, 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)};
+${generatePromiseReconstruction(asyncOutcomes)}      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>`;
+}
+function parseActionMetadata(yamlContent, fileName) {
+  try {
+    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;
+  }
+}
+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 {
+    projectRoot,
+    actionsDir = "src/actions",
+    registry = actionRegistry,
+    verbose = false,
+    viteServer
+  } = options;
+  const result = {
+    actionCount: 0,
+    actionNames: [],
+    scannedFiles: []
+  };
+  const actionsPath = path.resolve(projectRoot, actionsDir);
+  if (!fs.existsSync(actionsPath)) {
+    if (verbose) {
+      getLogger().info(`[Actions] No actions directory found at ${actionsPath}`);
+    }
+    return result;
+  }
+  const actionFiles = await findActionFiles(actionsPath);
+  if (verbose) {
+    getLogger().info(`[Actions] Found ${actionFiles.length} action file(s)`);
+  }
+  for (const filePath of actionFiles) {
+    result.scannedFiles.push(filePath);
+    try {
+      let module;
+      if (viteServer) {
+        module = await viteServer.ssrLoadModule(filePath);
+      } else {
+        module = await import(filePath);
+      }
+      for (const [exportName, exportValue] of Object.entries(module)) {
+        if (isJayAction(exportValue)) {
+          registry.register(exportValue);
+          result.actionNames.push(exportValue.actionName);
+          result.actionCount++;
+          if (verbose) {
+            getLogger().info(
+              `[Actions] Registered: ${exportValue.actionName}`
+            );
+          }
+        } else if (isJayStreamAction(exportValue)) {
+          registry.registerStream(exportValue);
+          result.actionNames.push(exportValue.actionName);
+          result.actionCount++;
+          if (verbose) {
+            getLogger().info(
+              `[Actions] Registered stream: ${exportValue.actionName}`
+            );
+          }
+        }
+      }
+    } catch (error) {
+      getLogger().error(`[Actions] Failed to import ${filePath}: ${error}`);
+    }
+  }
+  return result;
+}
+async function findActionFiles(dir) {
+  const files = [];
+  const entries = await fs.promises.readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      const subFiles = await findActionFiles(fullPath);
+      files.push(...subFiles);
+    } else if (entry.isFile() && entry.name.endsWith(".actions.ts")) {
+      files.push(fullPath);
+    }
+  }
+  return files;
+}
+async function discoverAllPluginActions(options) {
+  const { projectRoot, registry = actionRegistry, verbose = false, viteServer } = options;
+  const allActions = [];
+  const localPluginsPath = path.join(projectRoot, "src/plugins");
+  if (fs.existsSync(localPluginsPath)) {
+    const pluginDirs = await fs.promises.readdir(localPluginsPath, { withFileTypes: true });
+    for (const entry of pluginDirs) {
+      if (entry.isDirectory()) {
+        const pluginPath = path.join(localPluginsPath, entry.name);
+        const actions = await discoverPluginActions(
+          pluginPath,
+          projectRoot,
+          registry,
+          verbose,
+          viteServer
+        );
+        allActions.push(...actions);
+      }
+    }
+  }
+  const npmActions = await discoverNpmPluginActions(projectRoot, registry, verbose, viteServer);
+  allActions.push(...npmActions);
+  return allActions;
+}
+async function discoverNpmPluginActions(projectRoot, registry, verbose, viteServer) {
+  const allActions = [];
+  const packageJsonPath = path.join(projectRoot, "package.json");
+  if (!fs.existsSync(packageJsonPath)) {
+    return allActions;
+  }
+  try {
+    const packageJson = JSON.parse(await fs.promises.readFile(packageJsonPath, "utf-8"));
+    const dependencies = {
+      ...packageJson.dependencies,
+      ...packageJson.devDependencies
+    };
+    for (const packageName of Object.keys(dependencies)) {
+      try {
+        const pluginYamlPath = tryResolvePluginYaml(packageName, projectRoot);
+        if (!pluginYamlPath) {
+          continue;
+        }
+        const pluginDir = path.dirname(pluginYamlPath);
+        const pluginConfig = loadPluginManifest(pluginDir);
+        if (!pluginConfig || !pluginConfig.actions || !Array.isArray(pluginConfig.actions)) {
+          continue;
+        }
+        if (verbose) {
+          getLogger().info(
+            `[Actions] NPM plugin "${packageName}" declares actions: ${JSON.stringify(pluginConfig.actions)}`
+          );
+        }
+        const actions = await registerNpmPluginActions(
+          packageName,
+          pluginConfig,
+          pluginDir,
+          registry,
+          verbose,
+          viteServer
+        );
+        allActions.push(...actions);
+      } catch {
+        continue;
+      }
+    }
+  } catch (error) {
+    getLogger().error(`[Actions] Failed to read project package.json: ${error}`);
+  }
+  return allActions;
+}
+function tryResolvePluginYaml(packageName, projectRoot) {
+  try {
+    return require$2.resolve(`${packageName}/plugin.yaml`, {
+      paths: [projectRoot]
+    });
+  } catch {
+    return null;
+  }
+}
+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;
+    if (viteServer) {
+      pluginModule = await viteServer.ssrLoadModule(packageName);
+    } else {
+      pluginModule = await import(packageName);
+    }
+    for (const entry of pluginConfig.actions) {
+      const { name: actionName, action: actionPath } = normalizeActionEntry(entry);
+      const actionExport = pluginModule[actionName];
+      if (actionExport && isJayAction(actionExport)) {
+        registry.register(actionExport);
+        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 if (actionExport && isJayStreamAction(actionExport)) {
+        registry.registerStream(actionExport);
+        const registeredName = actionExport.actionName;
+        registeredActions.push(registeredName);
+        if (verbose) {
+          getLogger().info(`[Actions] Registered NPM plugin stream: ${registeredName}`);
+        }
+      } else {
+        getLogger().warn(
+          `[Actions] NPM plugin "${packageName}" declares action "${actionName}" but it's not exported or not a JayAction`
+        );
+      }
+    }
+  } catch (importError) {
+    getLogger().error(`[Actions] Failed to import NPM plugin "${packageName}": ${importError}`);
+  }
+  return registeredActions;
+}
+async function discoverPluginActions(pluginPath, projectRoot, registry = actionRegistry, verbose = false, viteServer) {
+  const pluginConfig = loadPluginManifest(pluginPath);
+  if (!pluginConfig) {
+    return [];
+  }
+  if (!pluginConfig.actions || !Array.isArray(pluginConfig.actions)) {
+    return [];
+  }
+  const registeredActions = [];
+  const pluginName = pluginConfig.name || path.basename(pluginPath);
+  if (verbose) {
+    getLogger().info(
+      `[Actions] Plugin "${pluginName}" declares actions: ${JSON.stringify(pluginConfig.actions)}`
+    );
+  }
+  let modulePath = pluginConfig.module ? path.join(pluginPath, pluginConfig.module) : path.join(pluginPath, "index.ts");
+  if (!fs.existsSync(modulePath)) {
+    const tsPath = modulePath + ".ts";
+    const jsPath = modulePath + ".js";
+    if (fs.existsSync(tsPath)) {
+      modulePath = tsPath;
+    } else if (fs.existsSync(jsPath)) {
+      modulePath = jsPath;
+    } else {
+      getLogger().warn(`[Actions] Plugin "${pluginName}" module not found at ${modulePath}`);
+      return [];
+    }
+  }
+  try {
+    let pluginModule;
+    if (viteServer) {
+      pluginModule = await viteServer.ssrLoadModule(modulePath);
+    } else {
+      pluginModule = await import(modulePath);
+    }
+    for (const entry of pluginConfig.actions) {
+      const { name: actionName, action: actionPath } = normalizeActionEntry(entry);
+      const actionExport = pluginModule[actionName];
+      if (actionExport && isJayAction(actionExport)) {
+        registry.register(actionExport);
+        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: ${registeredName}`);
+        }
+      } else if (actionExport && isJayStreamAction(actionExport)) {
+        registry.registerStream(actionExport);
+        const registeredName = actionExport.actionName;
+        registeredActions.push(registeredName);
+        if (verbose) {
+          getLogger().info(`[Actions] Registered plugin stream: ${registeredName}`);
+        }
+      } else {
+        getLogger().warn(
+          `[Actions] Plugin "${pluginName}" declares action "${actionName}" but it's not exported or not a JayAction`
+        );
+      }
+    }
+  } catch (importError) {
+    getLogger().error(
+      `[Actions] Failed to import plugin module at ${modulePath}: ${importError}`
+    );
+  }
+  return registeredActions;
+}
+const require$1 = createRequire(import.meta.url);
+async function executeDynamicGenerator(plugin, config, projectRoot, services, verbose, viteServer) {
+  const { pluginPath, name: pluginName, isLocal, packageName } = plugin;
+  if (!config.generator) {
+    throw new Error(
+      `Plugin "${pluginName}" has dynamic_contracts entry but no generator specified`
+    );
+  }
+  const isFilePath = config.generator.startsWith("./") || config.generator.startsWith("/") || config.generator.includes(".ts") || config.generator.includes(".js");
+  let generator;
+  if (isFilePath) {
+    let generatorPath;
+    if (!isLocal) {
+      try {
+        generatorPath = require$1.resolve(`${packageName}/${config.generator}`, {
+          paths: [projectRoot]
+        });
+      } catch {
+        generatorPath = path.join(pluginPath, config.generator);
+      }
+    } else {
+      generatorPath = path.join(pluginPath, config.generator);
+    }
+    if (!fs.existsSync(generatorPath)) {
+      const withTs = generatorPath + ".ts";
+      const withJs = generatorPath + ".js";
+      if (fs.existsSync(withTs)) {
+        generatorPath = withTs;
+      } else if (fs.existsSync(withJs)) {
+        generatorPath = withJs;
+      }
+    }
+    if (!fs.existsSync(generatorPath)) {
+      throw new Error(
+        `Generator file not found for plugin "${pluginName}": ${config.generator}`
+      );
+    }
+    if (verbose) {
+      getLogger().info(`   Loading generator from file: ${generatorPath}`);
+    }
+    let generatorModule;
+    if (viteServer) {
+      generatorModule = await viteServer.ssrLoadModule(generatorPath);
+    } else {
+      generatorModule = await import(generatorPath);
+    }
+    generator = generatorModule.generator || generatorModule.default;
+  } else {
+    if (verbose) {
+      getLogger().info(
+        `   Loading generator export: ${config.generator} from ${packageName}`
+      );
+    }
+    let pluginModule;
+    if (viteServer) {
+      pluginModule = await viteServer.ssrLoadModule(packageName);
+    } else {
+      pluginModule = await import(packageName);
+    }
+    generator = pluginModule[config.generator];
+    if (!generator) {
+      throw new Error(
+        `Generator "${config.generator}" not exported from plugin "${pluginName}". Ensure it's exported from the package's index.ts`
+      );
+    }
+  }
+  if (!generator || typeof generator.generate !== "function") {
+    throw new Error(
+      `Generator "${config.generator}" for plugin "${pluginName}" must have a 'generate' function. Use makeContractGenerator() to create valid generators.`
+    );
+  }
+  const resolvedServices = [];
+  for (const marker of generator.services) {
+    const service = services.get(marker);
+    if (!service) {
+      const markerName = marker.description ?? "unknown";
+      throw new Error(
+        `Service "${markerName}" required by ${pluginName} generator not found. Ensure it's registered in init.ts`
+      );
+    }
+    resolvedServices.push(service);
+  }
+  if (verbose) {
+    getLogger().info(`   Executing generator...`);
+  }
+  return await generator.generate(...resolvedServices);
+}
+function resolveStaticContractPath(plugin, contractSpec, projectRoot) {
+  const { pluginPath, isLocal, packageName } = plugin;
+  if (!isLocal) {
+    try {
+      return require$1.resolve(`${packageName}/${contractSpec}`, {
+        paths: [projectRoot]
+      });
+    } catch {
+      const possiblePaths = [
+        path.join(pluginPath, "dist", contractSpec),
+        path.join(pluginPath, "lib", contractSpec),
+        path.join(pluginPath, contractSpec)
+      ];
+      const found = possiblePaths.find((p) => fs.existsSync(p));
+      return found || possiblePaths[0];
+    }
+  } else {
+    return path.join(pluginPath, contractSpec);
+  }
+}
+function resolveActionFilePath(actionPath, packageName, pluginPath, isLocal, projectRoot) {
+  if (!isLocal && !actionPath.startsWith(".")) {
+    try {
+      return require$1.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(/^-/, "");
+}
+async function materializeContracts(options, services = /* @__PURE__ */ new Map()) {
+  const {
+    projectRoot,
+    outputDir = path.join(projectRoot, "agent-kit", "materialized-contracts"),
+    dynamicOnly = false,
+    pluginFilter,
+    verbose = false,
+    viteServer
+  } = options;
+  const pluginsIndexMap = /* @__PURE__ */ new Map();
+  let staticCount = 0;
+  let dynamicCount = 0;
+  if (verbose) {
+    getLogger().info("Scanning for plugins...");
+  }
+  const plugins = await scanPlugins({
+    projectRoot,
+    verbose,
+    includeDevDeps: true
+    // Include dev deps for contract discovery
+  });
+  if (verbose) {
+    getLogger().info(`Found ${plugins.size} plugin(s)`);
+  }
+  for (const [pluginKey, plugin] of plugins) {
+    if (pluginFilter && plugin.name !== pluginFilter && pluginKey !== pluginFilter) continue;
+    if (verbose) {
+      getLogger().info(`
+📦 Processing plugin: ${plugin.name}`);
+    }
+    const { manifest } = plugin;
+    const pluginRelPath = path.relative(projectRoot, plugin.pluginPath);
+    if (!pluginsIndexMap.has(plugin.name)) {
+      const entry = {
+        path: "./" + pluginRelPath.replace(/\\/g, "/"),
+        contracts: [],
+        actions: []
+      };
+      if (manifest.services?.length) {
+        entry.services = manifest.services.map((s2) => {
+          const docPath = s2.doc ? "./" + path.relative(projectRoot, path.resolve(plugin.pluginPath, s2.doc)) : void 0;
+          return {
+            name: s2.name,
+            marker: s2.marker,
+            ...s2.description && { description: s2.description },
+            ...docPath && { doc: docPath }
+          };
+        });
+      }
+      if (manifest.contexts?.length) {
+        entry.contexts = manifest.contexts.map((c2) => {
+          const docPath = c2.doc ? "./" + path.relative(projectRoot, path.resolve(plugin.pluginPath, c2.doc)) : void 0;
+          return {
+            name: c2.name,
+            marker: c2.marker,
+            ...c2.description && { description: c2.description },
+            ...docPath && { doc: docPath }
+          };
+        });
+      }
+      if (manifest.routes?.length) {
+        entry.routes = manifest.routes.map((r) => ({
+          path: r.path,
+          ...r.description && { description: r.description }
+        }));
+      }
+      if (manifest.commands?.length) {
+        entry.commands = manifest.commands.map((c2) => {
+          let description;
+          if (c2.command) {
+            try {
+              const cmdPath = path.resolve(plugin.pluginPath, c2.command);
+              const cmdContent = fs.readFileSync(cmdPath, "utf-8");
+              const parsed = YAML.parse(cmdContent);
+              description = parsed?.description;
+            } catch {
+            }
+          }
+          return {
+            name: c2.name,
+            ...description && { description }
+          };
+        });
+      }
+      pluginsIndexMap.set(plugin.name, entry);
+    }
+    if (!dynamicOnly && manifest.contracts) {
+      for (const contract of manifest.contracts) {
+        const contractPath = resolveStaticContractPath(
+          plugin,
+          contract.contract,
+          projectRoot
+        );
+        const relativePath = path.relative(projectRoot, contractPath);
+        let description = contract.description;
+        if (!description) {
+          try {
+            const contractContent = fs.readFileSync(contractPath, "utf-8");
+            const parsed = YAML.parse(contractContent);
+            if (parsed?.description && typeof parsed.description === "string") {
+              description = parsed.description;
+            }
+          } catch {
+          }
+        }
+        pluginsIndexMap.get(plugin.name).contracts.push({
+          name: contract.name,
+          ...description && { description },
+          type: "static",
+          path: "./" + relativePath
+        });
+        staticCount++;
+        if (verbose) {
+          getLogger().info(`   📄 Static: ${contract.name}`);
+        }
+      }
+    }
+    if (manifest.dynamic_contracts) {
+      const dynamicConfigs = Array.isArray(manifest.dynamic_contracts) ? manifest.dynamic_contracts : [manifest.dynamic_contracts];
+      const pluginOutputDir = path.join(outputDir, plugin.name.replace(/[@/]/g, "_"));
+      fs.mkdirSync(pluginOutputDir, { recursive: true });
+      for (const config of dynamicConfigs) {
+        if (verbose) {
+          getLogger().info(`   ⚡ Dynamic contracts (prefix: ${config.prefix})`);
+        }
+        try {
+          const generatedContracts = await executeDynamicGenerator(
+            plugin,
+            config,
+            projectRoot,
+            services,
+            verbose,
+            viteServer
+          );
+          const prefix = config.prefix;
+          if (generatedContracts.length > 1) {
+            const missing = generatedContracts.filter((c2) => !c2.name);
+            if (missing.length > 0) {
+              getLogger().error(
+                `   ❌ Dynamic contract generator for "${prefix}" returned ${generatedContracts.length} contracts but ${missing.length} are missing a name. Names are required when a generator returns multiple contracts.`
+              );
+              continue;
+            }
+          }
+          for (const generated of generatedContracts) {
+            const kebabName = generated.name ? toKebabCase(generated.name) : null;
+            const fullName = kebabName ? `${prefix}/${kebabName}` : prefix;
+            const fileName = kebabName ? `${prefix}-${kebabName}.jay-contract` : `${prefix}.jay-contract`;
+            const filePath = path.join(pluginOutputDir, fileName);
+            fs.writeFileSync(filePath, generated.yaml, "utf-8");
+            const relativePath = path.relative(projectRoot, filePath);
+            let dynDescription;
+            try {
+              const parsedYaml = YAML.parse(generated.yaml);
+              if (parsedYaml?.description && typeof parsedYaml.description === "string") {
+                dynDescription = parsedYaml.description;
+              }
+            } catch {
+            }
+            const contractEntry = {
+              name: fullName,
+              ...dynDescription && { description: dynDescription },
+              type: "dynamic",
+              path: "./" + relativePath,
+              ...generated.metadata && { metadata: generated.metadata }
+            };
+            pluginsIndexMap.get(plugin.name).contracts.push(contractEntry);
+            dynamicCount++;
+            if (verbose) {
+              getLogger().info(`   ⚡ Materialized: ${fullName}`);
+            }
+          }
+        } catch (error) {
+          getLogger().error(
+            `   ❌ Failed to materialize dynamic contracts for ${plugin.name} (${config.prefix}): ${error}`
+          );
+        }
+      }
+    }
+    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);
+        const pluginEntry = pluginsIndexMap.get(plugin.name);
+        if (!pluginEntry.actions) pluginEntry.actions = [];
+        pluginEntry.actions.push({
+          name: metadata.name,
+          description: metadata.description,
+          path: "./" + actionRelPath.replace(/\\/g, "/")
+        });
+        if (verbose) {
+          getLogger().info(`   🔧 Action: ${metadata.name} (${actionPath})`);
+        }
+      }
+    }
+  }
+  const pluginsIndex = {
+    plugins: Array.from(pluginsIndexMap.entries()).map(([name, data]) => ({
+      name,
+      path: data.path,
+      contracts: data.contracts,
+      ...data.actions && data.actions.length > 0 && { actions: data.actions },
+      ...data.services?.length && { services: data.services },
+      ...data.contexts?.length && { contexts: data.contexts },
+      ...data.routes?.length && { routes: data.routes },
+      ...data.commands?.length && { commands: data.commands }
+    }))
+  };
+  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(`
+✅ Plugins index written to: ${pluginsIndexPath}`);
+  }
+  return {
+    pluginsIndex,
+    staticCount,
+    dynamicCount,
+    outputDir
+  };
+}
+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) => {
+      acc[key] = params[key];
+      return acc;
+    },
+    {}
+  );
+  const json = JSON.stringify(sortedParams);
+  if (json === "{}") 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) {
+    __publicField2(this, "pathToFiles", /* @__PURE__ */ new Map());
+    __publicField2(this, "cacheDir");
+    __publicField2(this, "pagesRoot");
+    this.cacheDir = cacheDir;
+    this.pagesRoot = pagesRoot;
+  }
+  /**
+   * 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.
+   */
+  async get(jayHtmlPath, params, routeDir) {
+    const preRenderedPath = this.computeCachePath(jayHtmlPath, params, routeDir);
+    let fileContent;
+    try {
+      fileContent = await fs__default.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.
+   * 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, routeDir) {
+    const preRenderedPath = this.computeCachePath(jayHtmlPath, params, routeDir);
+    const fileContent = embedCacheMetadata(
+      preRenderedJayHtml,
+      slowViewState,
+      carryForward,
+      jayHtmlPath
+    );
+    await fs__default.mkdir(path__default.dirname(preRenderedPath), { recursive: true });
+    await fs__default.writeFile(preRenderedPath, fileContent, "utf-8");
+    this.trackFile(jayHtmlPath, preRenderedPath);
+    return {
+      preRenderedPath,
+      preRenderedContent: preRenderedJayHtml,
+      slowViewState,
+      carryForward,
+      sourcePath: jayHtmlPath
+    };
+  }
+  /**
+   * Check if a pre-rendered entry exists for the given path and params
+   */
+  async has(jayHtmlPath, params, routeDir) {
+    const preRenderedPath = this.computeCachePath(jayHtmlPath, params, routeDir);
+    try {
+      await fs__default.access(preRenderedPath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Invalidate all cached entries for a given jay-html source path.
+   * Deletes cached files from disk.
+   */
+  async invalidate(jayHtmlPath) {
+    const files = this.pathToFiles.get(jayHtmlPath);
+    if (files) {
+      for (const filePath of files) {
+        try {
+          await fs__default.unlink(filePath);
+        } catch {
+        }
+      }
+      this.pathToFiles.delete(jayHtmlPath);
+    }
+    await this.scanAndDeleteCacheFiles(jayHtmlPath);
+  }
+  /**
+   * Invalidate all entries that depend on a changed file.
+   * The changedPath could be:
+   * - A jay-html file itself
+   * - A component file (page.ts)
+   * - Any other dependency
+   *
+   * @param changedPath - Absolute path to the changed file
+   * @param resolveDependencies - Optional function to resolve which jay-html files depend on the changed file
+   */
+  async invalidateByDependency(changedPath, resolveDependencies) {
+    if (changedPath.endsWith(".jay-html")) {
+      await this.invalidate(changedPath);
+      return;
+    }
+    if (resolveDependencies) {
+      const dependentPaths = resolveDependencies(changedPath);
+      for (const depPath of dependentPaths) {
+        await this.invalidate(depPath);
+      }
+    }
+  }
+  /**
+   * Clear all cached entries and delete cached files from disk
+   */
+  async clear() {
+    for (const files of this.pathToFiles.values()) {
+      for (const filePath of files) {
+        try {
+          await fs__default.unlink(filePath);
+        } catch {
+        }
+      }
+    }
+    this.pathToFiles.clear();
+    try {
+      await fs__default.rm(this.cacheDir, { recursive: true, force: true });
+    } catch {
+    }
+  }
+  /**
+   * Get all cached jay-html paths (for debugging/monitoring)
+   */
+  getCachedPaths() {
+    return Array.from(this.pathToFiles.keys());
+  }
+  /**
+   * Compute the cache file path for a given jay-html path and params.
+   */
+  computeCachePath(jayHtmlPath, params, routeDir) {
+    let dir;
+    if (routeDir) {
+      dir = routeDir;
+    } else {
+      const relativePath = path__default.relative(this.pagesRoot, jayHtmlPath);
+      dir = relativePath.startsWith("..") ? path__default.join(
+        "_plugins",
+        crypto.createHash("md5").update(jayHtmlPath).digest("hex").slice(0, 12)
+      ) : path__default.dirname(relativePath);
+    }
+    const basename = path__default.basename(jayHtmlPath, ".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 = relativePath.startsWith("..") ? path__default.join(
+      "_plugins",
+      crypto.createHash("md5").update(jayHtmlPath).digest("hex").slice(0, 12)
+    ) : path__default.dirname(relativePath);
+    const basename = path__default.basename(jayHtmlPath, ".jay-html");
+    const cacheSubDir = path__default.join(this.cacheDir, dir);
+    try {
+      const files = await fs__default.readdir(cacheSubDir);
+      for (const file of files) {
+        if (file.startsWith(basename)) {
+          try {
+            await fs__default.unlink(path__default.join(cacheSubDir, file));
+          } catch {
+          }
+        }
+      }
+    } catch {
+    }
+  }
+}
 class ServiceLifecycleManager {
   constructor(projectRoot, sourceBase = "src") {
     /** Path to project's lib/init.ts (makeJayInit pattern) */
@@ -1634,7 +3503,7 @@ class ServiceLifecycleManager {
     const extensions = [".ts", ".js"];
     for (const ext of extensions) {
       const filePath = path.join(this.projectRoot, this.sourceBase, "init" + ext);
-      if (fsSync.existsSync(filePath)) {
+      if (fs.existsSync(filePath)) {
         return filePath;
       }
     }
@@ -2028,7 +3897,7 @@ function mergeDottedMultipartKeys(body) {
 }
 function parseMultipart(req, tempDir) {
   return new Promise((resolve, reject) => {
-    fs$1.mkdirSync(tempDir, { recursive: true });
+    fs$2.mkdirSync(tempDir, { recursive: true });
     const files = {};
     let jsonData = {};
     let fileCount = 0;
@@ -2043,7 +3912,7 @@ function parseMultipart(req, tempDir) {
       const filename = info.filename || `upload-${fileCount}`;
       const tempPath = path$1.join(tempDir, `${fileCount}-${filename}`);
       let size = 0;
-      const writeStream = fs$1.createWriteStream(tempPath);
+      const writeStream = fs$2.createWriteStream(tempPath);
       stream.pipe(writeStream);
       stream.on("data", (data) => {
         size += data.length;
@@ -2102,7 +3971,7 @@ function parseMultipart(req, tempDir) {
 }
 function cleanupTempDir(dir) {
   try {
-    fs$1.rmSync(dir, { recursive: true, force: true });
+    fs$2.rmSync(dir, { recursive: true, force: true });
   } catch {
   }
 }
@@ -2133,7 +4002,7 @@ function actionBodyParser(options) {
         });
         return;
       }
-      const requestId = crypto.randomUUID();
+      const requestId = crypto$1.randomUUID();
       const tempDir = path$1.join(buildFolder, ".tmp", "actions", requestId);
       parseMultipart(req, tempDir).then(({ body: body2, tempDir: td }) => {
         req.body = body2;
@@ -2180,7 +4049,7 @@ class FreezeStore {
     this.dir = path.join(buildFolder, "freezes");
   }
   async save(route, viewState, routePattern) {
-    await fs.mkdir(this.dir, { recursive: true });
+    await fs$1.mkdir(this.dir, { recursive: true });
     const entry = {
       id: randomUUID().slice(0, 8),
       route,
@@ -2188,7 +4057,7 @@ class FreezeStore {
       viewState,
       createdAt: (/* @__PURE__ */ new Date()).toISOString()
     };
-    await fs.writeFile(
+    await fs$1.writeFile(
       path.join(this.dir, `${entry.id}.json`),
       JSON.stringify(entry, null, 2),
       "utf-8"
@@ -2197,7 +4066,7 @@ class FreezeStore {
   }
   async get(id) {
     try {
-      const content = await fs.readFile(path.join(this.dir, `${id}.json`), "utf-8");
+      const content = await fs$1.readFile(path.join(this.dir, `${id}.json`), "utf-8");
       return JSON.parse(content);
     } catch {
       return void 0;
@@ -2205,12 +4074,12 @@ class FreezeStore {
   }
   async list(route) {
     try {
-      const files = await fs.readdir(this.dir);
+      const files = await fs$1.readdir(this.dir);
       const entries = [];
       for (const file of files) {
         if (!file.endsWith(".json")) continue;
         try {
-          const content = await fs.readFile(path.join(this.dir, file), "utf-8");
+          const content = await fs$1.readFile(path.join(this.dir, file), "utf-8");
           const entry = JSON.parse(content);
           if (!route || entry.routePattern === route || entry.route === route) {
             entries.push(entry);
@@ -2229,7 +4098,7 @@ class FreezeStore {
     const entry = await this.get(id);
     if (!entry) return false;
     entry.name = name;
-    await fs.writeFile(
+    await fs$1.writeFile(
       path.join(this.dir, `${id}.json`),
       JSON.stringify(entry, null, 2),
       "utf-8"
@@ -2238,7 +4107,7 @@ class FreezeStore {
   }
   async delete(id) {
     try {
-      await fs.unlink(path.join(this.dir, `${id}.json`));
+      await fs$1.unlink(path.join(this.dir, `${id}.json`));
       return true;
     } catch {
       return false;
@@ -2361,7 +4230,7 @@ function resolvePluginExport(pluginPath, exportSubpath) {
   const normalized = exportSubpath.replace(/^\.\//, "");
   const packageJsonPath = path__default.join(pluginPath, "package.json");
   try {
-    const packageJson = JSON.parse(fsSync__default.readFileSync(packageJsonPath, "utf-8"));
+    const packageJson = JSON.parse(fs__default$1.readFileSync(packageJsonPath, "utf-8"));
     if (packageJson.exports) {
       const exportKey = "./" + normalized;
       const exportValue = packageJson.exports[exportKey];
@@ -2378,7 +4247,7 @@ function resolvePluginExport(pluginPath, exportSubpath) {
   for (const dir of ["dist", "lib", ""]) {
     const candidate = path__default.join(pluginPath, dir, normalized);
     try {
-      fsSync__default.accessSync(candidate);
+      fs__default$1.accessSync(candidate);
       return candidate;
     } catch {
     }
@@ -2387,14 +4256,14 @@ function resolvePluginExport(pluginPath, exportSubpath) {
 }
 function resolvePluginModule(plugin) {
   const pkgJsonPath = path__default.join(plugin.pluginPath, "package.json");
-  if (fsSync__default.existsSync(pkgJsonPath)) {
+  if (fs__default$1.existsSync(pkgJsonPath)) {
     try {
-      const pkg = JSON.parse(fsSync__default.readFileSync(pkgJsonPath, "utf-8"));
+      const pkg = JSON.parse(fs__default$1.readFileSync(pkgJsonPath, "utf-8"));
       const mainExport = pkg.exports?.["."];
       const mainPath = typeof mainExport === "string" ? mainExport : mainExport?.default || mainExport?.import || pkg.main;
       if (mainPath) {
         const resolved = path__default.join(plugin.pluginPath, mainPath);
-        if (fsSync__default.existsSync(resolved)) return resolved;
+        if (fs__default$1.existsSync(resolved)) return resolved;
       }
     } catch {
     }
@@ -2403,7 +4272,7 @@ function resolvePluginModule(plugin) {
   for (const ext of [".ts", ".js", "/index.ts", "/index.js"]) {
     const candidate = path__default.join(plugin.pluginPath, modulePath + ext);
     try {
-      fsSync__default.accessSync(candidate);
+      fs__default$1.accessSync(candidate);
       return candidate;
     } catch {
     }
@@ -2411,7 +4280,7 @@ function resolvePluginModule(plugin) {
   for (const ext of [".ts", ".js"]) {
     const candidate = path__default.join(plugin.pluginPath, "lib", path__default.basename(modulePath) + ext);
     try {
-      fsSync__default.accessSync(candidate);
+      fs__default$1.accessSync(candidate);
       return candidate;
     } catch {
     }
@@ -3184,7 +5053,7 @@ async function mkDevServer(rawOptions) {
     for (let i = devServerRoutes.length - 1; i >= 0; i--) {
       const route = devServerRoutes[i];
       const fsPath = route.fsRoute.jayHtmlPath;
-      const stillOnDisk = scannedRawRoutes.has(route.fsRoute.rawRoute) && fsSync__default.existsSync(fsPath);
+      const stillOnDisk = scannedRawRoutes.has(route.fsRoute.rawRoute) && fs__default$1.existsSync(fsPath);
       if (!stillOnDisk) {
         devServerRoutes.splice(i, 1);
       }