@jay-framework/compiler-jay-html 0.12.0 → 0.13.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { JayType, WithValidations, PluginComponentResolution, JayEnumType, RefsTree, CompilerSourceFile, SourceFileFormat, JayImportLink, MainRuntimeModes, GenerateTarget, Imports } from '@jay-framework/compiler-shared';
+import { JayType, WithValidations, PluginComponentResolution, PluginManifest, JayEnumType, RefsTree, CompilerSourceFile, SourceFileFormat, JayImportLink, MainRuntimeModes, GenerateTarget, Imports, JayObjectType } from '@jay-framework/compiler-shared';
 import { HTMLElement } from 'node-html-parser';
 import { ResolveTsConfigOptions } from '@jay-framework/compiler-analyze-exported-types';
 import { Coordinate } from '@jay-framework/runtime';
@@ -89,6 +89,7 @@ interface JayImportResolver {
         contractPath: string;
         metadata?: Record<string, unknown>;
     }>;
+    resolvePluginManifest(pluginName: string, projectRoot: string): WithValidations<PluginManifest>;
 }
 declare const JAY_IMPORT_RESOLVER: JayImportResolver;
 
@@ -211,6 +212,58 @@ declare function renderRefsType(refs: RefsTree, refsType: string, generateTarget
 
 declare function generateTypes(types: JayType): string;
 
+/**
+ * Parser for .jay-action files (compact jay-type notation).
+ *
+ * Produces JayType from the compact format used by jay-html data scripts:
+ * - Primitives: string, number, boolean → JayAtomicType
+ * - Enums: enum(a | b | c) → JayEnumType
+ * - Arrays: YAML list / type[] shorthand → JayArrayType
+ * - Objects: nested YAML maps → JayObjectType (with optionalProps tracking)
+ * - Optional: ? suffix on property keys → tracked in JayObjectType.optionalProps
+ * - Contract imports: import: block → JayImportedType
+ */
+
+/**
+ * Parsed action definition from a .jay-action file.
+ * Uses JayType for the type representation.
+ */
+interface ActionDefinition {
+    name: string;
+    description: string;
+    /** Import aliases: alias → contract subpath (e.g., productCard → product-card.jay-contract) */
+    imports: Record<string, string>;
+    /** Input schema as a JayObjectType. Optional props tracked in optionalProps. */
+    inputType: JayObjectType;
+    /** Output type (any JayType shape, or undefined if no output). */
+    outputType?: JayType;
+}
+/**
+ * Parses a .jay-action YAML string into an ActionDefinition using JayType.
+ */
+declare function parseAction(actionYaml: string, fileName: string): WithValidations<ActionDefinition>;
+
+/**
+ * Compiler for .jay-action files → .jay-action.d.ts
+ *
+ * Generates TypeScript Input/Output interfaces from JayType trees,
+ * including import statements for contract references (JayImportedType).
+ */
+
+interface ContractImportInfo {
+    importPath: string;
+    viewStateName: string;
+}
+type ContractResolver = (contractSubpath: string) => ContractImportInfo | null;
+/**
+ * Default contract resolver that derives names from the subpath.
+ */
+declare function defaultContractResolver(contractSubpath: string): ContractImportInfo;
+/**
+ * Compiles an ActionDefinition (with JayType) into a TypeScript .d.ts string.
+ */
+declare function compileAction(actionWithValidations: WithValidations<ActionDefinition>, contractResolver?: ContractResolver): WithValidations<string>;
+
 /**
  * Headless contract with its key (used for property path prefix)
  */
@@ -302,8 +355,26 @@ interface HeadlessInstanceResolvedData {
  * a coordinateCounters map must be provided to auto-assign an index.
  */
 declare function buildInstanceCoordinateKey(element: HTMLElement, contractName: string, coordinateCounters?: Map<string, number>): string;
+/**
+ * A headless instance found inside a preserved forEach (fast phase).
+ * These instances have unresolved prop bindings and need per-item rendering
+ * at fast phase time. They are only allowed if the component has no slow phase.
+ */
+interface ForEachHeadlessInstance {
+    contractName: string;
+    /** The forEach attribute path on the ancestor element (e.g., "allProducts.items") */
+    forEachPath: string;
+    /** TrackBy key for the forEach (e.g., "_id") */
+    trackBy: string;
+    /** Prop bindings referencing forEach item fields (e.g., { productId: "{_id}" }) */
+    propBindings: Record<string, string>;
+    /** Coordinate suffix after trackBy values (e.g., "product-card:0") */
+    coordinateSuffix: string;
+}
 interface HeadlessInstanceDiscoveryResult {
     instances: DiscoveredHeadlessInstance[];
+    /** Headless instances inside preserved forEach elements (need server-time validation) */
+    forEachInstances: ForEachHeadlessInstance[];
     /** HTML with auto-generated ref attributes embedded on <jay:xxx> elements */
     preRenderedJayHtml: string;
 }
@@ -314,4 +385,4 @@ declare function resolveHeadlessInstances(preRenderedJayHtml: string, instanceDa
  */
 declare function hasSlowPhaseProperties(contract: Contract | undefined): boolean;
 
-export { type Contract, type ContractParam, type ContractProp, type ContractTag, ContractTagType, type DiscoveredHeadlessInstance, type EnumToImport, type HeadlessContractInfo, type HeadlessInstanceDiscoveryResult, type HeadlessInstanceResolvedData, JAY_IMPORT_RESOLVER, type JayContractImportLink, type JayHtmlSourceFile, type JayImportResolver, type PhaseViewStates, type RenderingPhase, type SlowRenderInput, type SlowRenderOutput, buildInstanceCoordinateKey, compileContract, contractToAllPhaseViewStates, contractToImportsViewStateAndRefs, contractToPhaseViewState, createPhaseContract, discoverHeadlessInstances, filterTagsByPhase, generateElementBridgeFile, generateElementDefinitionFile, generateElementFile, generateElementFileReactTarget, generateSandboxRootFile, generateTypes, getEffectivePhase, getJayHtmlImports, getLinkedContractDir, hasSlowPhaseProperties, isTagInPhase, loadLinkedContract, parseContract, parseEnumValues, parseIsEnum, parseJayFile, renderRefsType, resolveHeadlessInstances, slowRenderTransform, validateContractPhases };
+export { type ActionDefinition, type Contract, type ContractImportInfo, type ContractParam, type ContractProp, type ContractResolver, type ContractTag, ContractTagType, type DiscoveredHeadlessInstance, type EnumToImport, type ForEachHeadlessInstance, type HeadlessContractInfo, type HeadlessInstanceDiscoveryResult, type HeadlessInstanceResolvedData, JAY_IMPORT_RESOLVER, type JayContractImportLink, type JayHtmlSourceFile, type JayImportResolver, type PhaseViewStates, type RenderingPhase, type SlowRenderInput, type SlowRenderOutput, buildInstanceCoordinateKey, compileAction, compileContract, contractToAllPhaseViewStates, contractToImportsViewStateAndRefs, contractToPhaseViewState, createPhaseContract, defaultContractResolver, discoverHeadlessInstances, filterTagsByPhase, generateElementBridgeFile, generateElementDefinitionFile, generateElementFile, generateElementFileReactTarget, generateSandboxRootFile, generateTypes, getEffectivePhase, getJayHtmlImports, getLinkedContractDir, hasSlowPhaseProperties, isTagInPhase, loadLinkedContract, parseAction, parseContract, parseEnumValues, parseIsEnum, parseJayFile, renderRefsType, resolveHeadlessInstances, slowRenderTransform, validateContractPhases };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { RenderFragment, Imports, Import, JayImportedType, isObjectType as isObjectType$1, isImportedType, isRecursiveType, JayUnknown, WithValidations, isArrayType as isArrayType$1, isAtomicType, isPromiseType, isEnumType, hasRefs, GenerateTarget, JayComponentType, JayTypeAlias, mkRefsTree, mkRef, equalJayTypes, JayUnionType, JayHTMLType, getModeFileExtension, RuntimeMode, ImportsFor, nestRefs, JayErrorType, mergeRefsTrees, JayObjectType, JayArrayType, JayPromiseType, JAY_CONTRACT_EXTENSION as JAY_CONTRACT_EXTENSION$1, JayRecursiveType, JAY_FULLSTACK_COMPONENTS, JayEnumType, resolvePrimitiveType, SourceFileFormat, resolvePluginComponent } from "@jay-framework/compiler-shared";
+import { RenderFragment, Imports, Import, JayImportedType, isObjectType as isObjectType$1, isImportedType, isRecursiveType, JayUnknown, WithValidations, isArrayType as isArrayType$1, isAtomicType, isPromiseType, isEnumType, hasRefs, GenerateTarget, JayComponentType, JayTypeAlias, mkRefsTree, mkRef, equalJayTypes, JayUnionType, JayHTMLType, getModeFileExtension, RuntimeMode, ImportsFor, nestRefs, JayErrorType, mergeRefsTrees, JayObjectType, JayArrayType, JayPromiseType, JAY_CONTRACT_EXTENSION as JAY_CONTRACT_EXTENSION$1, JayRecursiveType, JAY_FULLSTACK_COMPONENTS, JayEnumType, resolvePrimitiveType, SourceFileFormat, JayOptionalType, isOptionalType, resolvePluginComponent, resolvePluginManifest } from "@jay-framework/compiler-shared";
 import path from "path";
 import { getLogger } from "@jay-framework/logger";
 import fs from "fs/promises";
@@ -13345,7 +13345,7 @@ function getComponentName(tagName, importedSymbols, headlessContractNames) {
   }
   return null;
 }
-function renderInterface(aType) {
+function renderInterface$1(aType) {
   let childInterfaces = [];
   let genInterface = "";
   if (isObjectType$1(aType)) {
@@ -13361,12 +13361,12 @@ function renderInterface(aType) {
           const optional = childType.isOptional ? "?" : "";
           return `  ${prop}${optional}: ${childType.name}`;
         } else if (isObjectType$1(childType)) {
-          childInterfaces.push(renderInterface(childType));
+          childInterfaces.push(renderInterface$1(childType));
           return `  ${prop}: ${childType.name}`;
         } else if (isArrayType$1(childType)) {
           let arrayItemType = childType.itemType;
           if (isObjectType$1(arrayItemType)) {
-            childInterfaces.push(renderInterface(arrayItemType));
+            childInterfaces.push(renderInterface$1(arrayItemType));
             return `  ${prop}: Array<${arrayItemType.name}>`;
           }
           if (arrayItemType instanceof JayImportedType) {
@@ -13388,10 +13388,10 @@ function renderInterface(aType) {
           if (isAtomicType(promiseItemType))
             return `  ${prop}: Promise<${promiseItemType.name}>`;
           else if (isObjectType$1(promiseItemType)) {
-            childInterfaces.push(renderInterface(promiseItemType));
+            childInterfaces.push(renderInterface$1(promiseItemType));
             return `  ${prop}: Promise<${promiseItemType.name}>`;
           } else if (isArrayType$1(promiseItemType) && isObjectType$1(promiseItemType.itemType)) {
-            childInterfaces.push(renderInterface(promiseItemType.itemType));
+            childInterfaces.push(renderInterface$1(promiseItemType.itemType));
             return `  ${prop}: Promise<Array<${promiseItemType.itemType.name}>>`;
           }
         } else if (isEnumType(childType)) {
@@ -13417,7 +13417,7 @@ ${childType.values.map((_) => "  " + _).join(",\n")}
   return [...childInterfaces, genInterface].join("\n\n");
 }
 function generateTypes(types2) {
-  return renderInterface(types2);
+  return renderInterface$1(types2);
 }
 class Indent {
   base;
@@ -14526,16 +14526,6 @@ ${indent.curr}return ${childElement.rendered}}, '${trackBy}')`,
       );
   }
   function renderHeadlessInstance(htmlElement, newContext, contractName) {
-    if (newContext.insideFastForEach) {
-      return new RenderFragment(
-        "",
-        Imports.none(),
-        [
-          `<jay:${contractName}> cannot be used inside a fast-phase forEach. Headless component instances require server-side rendering which is not available for dynamically-iterated arrays. Change the array's phase to "slow" in the contract to use slowForEach, or use a key-based headless component instead.`
-        ],
-        mkRefsTree([], {})
-      );
-    }
     const headlessImport = newContext.headlessImports.find(
       (h) => h.contractName === contractName
     );
@@ -14555,7 +14545,7 @@ ${indent.curr}return ${childElement.rendered}}, '${trackBy}')`,
     const interactiveViewStateType = `${pascal}InteractiveViewState`;
     const refsTypeName = `${pascal}Refs`;
     const elementType = `_Headless${pascal}${idx}Element`;
-    const renderType = `_Headless${pascal}${idx}ElementRender`;
+    const renderType2 = `_Headless${pascal}${idx}ElementRender`;
     const preRenderType = `_Headless${pascal}${idx}ElementPreRender`;
     newContext.usedComponentImports.add(interactiveViewStateType);
     for (const link of headlessImport.contractLinks) {
@@ -14629,15 +14619,14 @@ ${indent.curr}return ${childElement.rendered}}, '${trackBy}')`,
       newContext.coordinateCounters.set(counterKey, localIndex + 1);
       coordinateRef = String(localIndex);
     }
-    const coordinateKey2 = [
-      ...newContext.coordinatePrefix,
-      `${contractName}:${coordinateRef}`
-    ].join("/");
+    const isInsideForEach = newContext.insideFastForEach;
+    const coordinateSuffix = `${contractName}:${coordinateRef}`;
+    const coordinateKey2 = isInsideForEach ? void 0 : [...newContext.coordinatePrefix, coordinateSuffix].join("/");
     const renderFnCode = `
 // Inline template for headless component: ${contractName} #${idx}
 type ${elementType} = JayElement<${interactiveViewStateType}, ${refsTypeName}>;
-type ${renderType} = RenderElement<${interactiveViewStateType}, ${refsTypeName}, ${elementType}>;
-type ${preRenderType} = [${refsTypeName}, ${renderType}];
+type ${renderType2} = RenderElement<${interactiveViewStateType}, ${refsTypeName}, ${elementType}>;
+type ${preRenderType} = [${refsTypeName}, ${renderType2}];
 
 function ${renderFnName}(options?: RenderElementOptions): ${preRenderType} {
     ${renderedRefsManager}
@@ -14651,7 +14640,7 @@ ${inlineBody.rendered}
 const ${componentSymbol} = makeHeadlessInstanceComponent(
     ${renderFnName},
     ${pluginComponentName}.comp,
-    '${coordinateKey2}',
+    ${isInsideForEach ? `(dataIds) => [...dataIds, '${coordinateSuffix}'].toString()` : `'${coordinateKey2}'`},
     ${pluginComponentName}.contexts,
 );`;
     newContext.headlessInstanceDefs.push({
@@ -14999,7 +14988,7 @@ ${renderedRoot.rendered}
   const elementType = baseElementName + "Element";
   const refsType = baseElementName + "ElementRefs";
   const viewStateType = types2.name;
-  const renderType = `${elementType}Render`;
+  const renderType2 = `${elementType}Render`;
   const preRenderType = `${elementType}PreRender`;
   const contractType = `${baseElementName}Contract`;
   let imports = renderedRoot.imports.plus(Import.ConstructContext).plus(Import.RenderElementOptions).plus(Import.RenderElement).plus(Import.ReferencesManager).plus(Import.jayContract);
@@ -15009,8 +14998,8 @@ ${renderedRoot.rendered}
   const { imports: refImports, renderedRefs } = renderRefsType(renderedRoot.refs, refsType);
   imports = imports.plus(refImports);
   let renderedElement = `export type ${elementType} = JayElement<${viewStateType}, ${refsType}>
-export type ${renderType} = RenderElement<${viewStateType}, ${refsType}, ${elementType}>
-export type ${preRenderType} = [${refsType}, ${renderType}]
+export type ${renderType2} = RenderElement<${viewStateType}, ${refsType}, ${elementType}>
+export type ${preRenderType} = [${refsType}, ${renderType2}]
 export type ${contractType} = JayContract<${viewStateType}, ${refsType}>;
 `;
   if (importedSandboxedSymbols.size > 0) {
@@ -20427,9 +20416,252 @@ async function parseJayFile(html2, filename, filePath, options, linkedContractRe
 }
 function getJayHtmlImports(html2) {
   const root = parse_2(html2);
-  return root.querySelectorAll(
-    'script[type="application/jay-headfull"], script[type="application/jay-headless"]'
-  ).map((script) => script.getAttribute("src")).filter((src) => src !== null);
+  return root.querySelectorAll('script[type="application/jay-headfull"]').map((script) => script.getAttribute("src")).filter((src) => src !== null);
+}
+function parseArrayShorthand(value) {
+  if (value.endsWith("[]")) {
+    return value.slice(0, -2);
+  }
+  return null;
+}
+function resolveStringType(value, importAliases, path2) {
+  const arrayBase = parseArrayShorthand(value);
+  if (arrayBase) {
+    const itemType = resolveStringType(arrayBase, importAliases, path2);
+    if (itemType)
+      return new JayArrayType(itemType);
+    return null;
+  }
+  if (value.endsWith("?")) {
+    const alias = value.slice(0, -1);
+    if (importAliases.has(alias)) {
+      return new JayImportedType(alias, JayUnknown, true);
+    }
+    return null;
+  }
+  const primitive = resolvePrimitiveType(value);
+  if (primitive !== JayUnknown) {
+    return primitive;
+  }
+  if (parseIsEnum(value)) {
+    const name = path2.length > 0 ? path2[path2.length - 1] : "value";
+    return new JayEnumType(name, parseEnumValues(value));
+  }
+  if (importAliases.has(value)) {
+    return new JayImportedType(value, JayUnknown, false);
+  }
+  return null;
+}
+function resolveActionType(value, importAliases, path2) {
+  if (typeof value === "string") {
+    return resolveStringType(value, importAliases, path2);
+  }
+  if (Array.isArray(value)) {
+    if (value.length === 0)
+      return null;
+    const firstItem = value[0];
+    if (typeof firstItem === "string") {
+      const itemType = resolveStringType(firstItem, importAliases, [...path2, "item"]);
+      if (itemType)
+        return new JayArrayType(itemType);
+    } else if (typeof firstItem === "object" && firstItem !== null) {
+      const itemType = parseObjectType(firstItem, importAliases, [
+        ...path2,
+        "item"
+      ]);
+      return new JayArrayType(itemType);
+    }
+    return null;
+  }
+  if (typeof value === "object" && value !== null) {
+    if (Object.keys(value).length === 0) {
+      return new JayObjectType(path2.join("."), {});
+    }
+    return parseObjectType(value, importAliases, path2);
+  }
+  return null;
+}
+function parseObjectType(obj, importAliases, path2) {
+  const props = {};
+  for (const [rawKey, value] of Object.entries(obj)) {
+    const isOptional = rawKey.endsWith("?");
+    const name = isOptional ? rawKey.slice(0, -1) : rawKey;
+    const type2 = resolveActionType(value, importAliases, [...path2, name]);
+    if (type2) {
+      props[name] = isOptional ? new JayOptionalType(type2) : type2;
+    }
+  }
+  const typeName = path2.join(".");
+  return new JayObjectType(typeName, props);
+}
+function parseAction(actionYaml, fileName) {
+  try {
+    const parsed = jsYaml.load(actionYaml);
+    const validations = [];
+    if (!parsed || typeof parsed !== "object") {
+      return new WithValidations(void 0, [
+        "Action file is empty or not a valid YAML object"
+      ]);
+    }
+    if (!parsed.name || typeof parsed.name !== "string") {
+      validations.push(`Action must have a 'name' field (string)`);
+    }
+    if (!parsed.description || typeof parsed.description !== "string") {
+      validations.push(`Action must have a 'description' field (string)`);
+    }
+    if (parsed.inputSchema === void 0 || parsed.inputSchema === null) {
+      validations.push(`Action must have an 'inputSchema' field`);
+    }
+    if (validations.length > 0) {
+      return new WithValidations(void 0, validations);
+    }
+    const imports = {};
+    if (parsed.import && typeof parsed.import === "object") {
+      for (const [alias, contractPath] of Object.entries(
+        parsed.import
+      )) {
+        if (typeof contractPath === "string") {
+          imports[alias] = contractPath;
+        }
+      }
+    }
+    const importAliases = new Set(Object.keys(imports));
+    let inputType;
+    if (typeof parsed.inputSchema === "object" && parsed.inputSchema !== null && Object.keys(parsed.inputSchema).length > 0) {
+      inputType = parseObjectType(
+        parsed.inputSchema,
+        importAliases,
+        ["input"]
+      );
+    } else {
+      inputType = new JayObjectType("input", {});
+    }
+    let outputType;
+    if (parsed.outputSchema !== void 0 && parsed.outputSchema !== null) {
+      outputType = resolveActionType(parsed.outputSchema, importAliases, ["output"]) ?? void 0;
+    }
+    const definition = {
+      name: parsed.name,
+      description: parsed.description,
+      imports,
+      inputType,
+      outputType
+    };
+    return new WithValidations(definition, []);
+  } catch (e2) {
+    throw new Error(`Failed to parse action YAML for ${fileName}: ${e2.message}`);
+  }
+}
+function defaultContractResolver(contractSubpath) {
+  const baseName = contractSubpath.replace(".jay-contract", "");
+  const viewStateName = pascalCase(baseName) + "ViewState";
+  return { importPath: `./${contractSubpath}`, viewStateName };
+}
+function collectImportedAliases(type2, aliases2) {
+  if (isImportedType(type2)) {
+    aliases2.add(type2.name);
+  } else if (isOptionalType(type2)) {
+    collectImportedAliases(type2.innerType, aliases2);
+  } else if (isObjectType$1(type2)) {
+    for (const prop of Object.values(type2.props)) {
+      collectImportedAliases(prop, aliases2);
+    }
+  } else if (isArrayType$1(type2)) {
+    collectImportedAliases(type2.itemType, aliases2);
+  }
+}
+function renderType(type2, aliasToViewState, indent) {
+  if (isOptionalType(type2)) {
+    return renderType(type2.innerType, aliasToViewState, indent);
+  }
+  if (isAtomicType(type2)) {
+    return type2.name;
+  }
+  if (isEnumType(type2)) {
+    return type2.values.map((v) => `'${v}'`).join(" | ");
+  }
+  if (isImportedType(type2)) {
+    const viewStateName = aliasToViewState.get(type2.name) || type2.name;
+    return type2.isOptional ? `${viewStateName} | null` : viewStateName;
+  }
+  if (isArrayType$1(type2)) {
+    const itemStr = renderType(type2.itemType, aliasToViewState, indent + "  ");
+    return `Array<${itemStr}>`;
+  }
+  if (isObjectType$1(type2)) {
+    if (Object.keys(type2.props).length === 0) {
+      return "Record<string, unknown>";
+    }
+    return renderInlineObject(type2, aliasToViewState, indent);
+  }
+  return "unknown";
+}
+function renderInlineObject(type2, aliasToViewState, indent) {
+  const childIndent = indent + "  ";
+  const lines = Object.entries(type2.props).map(([prop, propType]) => {
+    const optional = isOptionalType(propType) ? "?" : "";
+    const tsType = renderType(propType, aliasToViewState, childIndent);
+    return `${childIndent}${prop}${optional}: ${tsType};`;
+  });
+  return `{
+${lines.join("\n")}
+${indent}}`;
+}
+function renderInterface(interfaceName, type2, aliasToViewState) {
+  const propKeys = Object.keys(type2.props);
+  if (propKeys.length === 0) {
+    return `export interface ${interfaceName} {}`;
+  }
+  const lines = propKeys.map((prop) => {
+    const optional = isOptionalType(type2.props[prop]) ? "?" : "";
+    const tsType = renderType(type2.props[prop], aliasToViewState, "  ");
+    return `  ${prop}${optional}: ${tsType};`;
+  });
+  return `export interface ${interfaceName} {
+${lines.join("\n")}
+}`;
+}
+function renderOutputType(typeName, outputType, aliasToViewState) {
+  if (isObjectType$1(outputType) && Object.keys(outputType.props).length > 0) {
+    return renderInterface(typeName, outputType, aliasToViewState);
+  }
+  const tsType = renderType(outputType, aliasToViewState, "");
+  return `export type ${typeName} = ${tsType};`;
+}
+function compileAction(actionWithValidations, contractResolver = defaultContractResolver) {
+  return actionWithValidations.map((action) => {
+    const baseName = pascalCase(action.name);
+    const sections = [];
+    const usedAliases = /* @__PURE__ */ new Set();
+    collectImportedAliases(action.inputType, usedAliases);
+    if (action.outputType) {
+      collectImportedAliases(action.outputType, usedAliases);
+    }
+    const aliasToViewState = /* @__PURE__ */ new Map();
+    const importStatements = [];
+    for (const alias of usedAliases) {
+      const contractSubpath = action.imports[alias];
+      if (!contractSubpath)
+        continue;
+      const resolved = contractResolver(contractSubpath);
+      if (!resolved)
+        continue;
+      aliasToViewState.set(alias, resolved.viewStateName);
+      importStatements.push(
+        `import { ${resolved.viewStateName} } from '${resolved.importPath}';`
+      );
+    }
+    if (importStatements.length > 0) {
+      sections.push(importStatements.join("\n"));
+    }
+    sections.push(renderInterface(`${baseName}Input`, action.inputType, aliasToViewState));
+    if (action.outputType) {
+      sections.push(
+        renderOutputType(`${baseName}Output`, action.outputType, aliasToViewState)
+      );
+    }
+    return sections.join("\n\n");
+  });
 }
 const ALIAS = Symbol.for("yaml.alias");
 const DOC = Symbol.for("yaml.document");
@@ -26890,6 +27122,9 @@ const JAY_IMPORT_RESOLVER = {
     return new WithValidations(null, [
       `Contract "${contractName}" not found for plugin "${pluginName}". For dynamic contracts, run 'jay-stack agent-kit' to materialize them first.`
     ]);
+  },
+  resolvePluginManifest(pluginName, projectRoot) {
+    return resolvePluginManifest(projectRoot, pluginName);
   }
 };
 function buildPhaseMap(contract, headlessContracts, importResolver) {
@@ -27208,20 +27443,23 @@ function discoverHeadlessInstances(preRenderedJayHtml) {
     }
   });
   const instances = [];
+  const forEachInstances = [];
   const coordinateCounters = /* @__PURE__ */ new Map();
-  function walk(element, insidePreservedForEach) {
+  function walk(element, insidePreservedForEach, forEachContexts) {
     const tagName = element.tagName?.toLowerCase();
-    const hasForEach = element.getAttribute("forEach") != null;
+    const forEachAttr = element.getAttribute("forEach");
+    const hasForEach = forEachAttr != null;
+    const trackByAttr = element.getAttribute("trackBy");
     if (tagName?.startsWith("jay:")) {
-      if (!insidePreservedForEach) {
-        const contractName = tagName.substring(4);
-        const props = {};
-        for (const [key, value] of Object.entries(element.attributes)) {
-          const lowerKey = key.toLowerCase();
-          if (lowerKey !== "ref" && !lowerKey.startsWith("jay")) {
-            props[toCamelCase(key)] = value;
-          }
+      const contractName = tagName.substring(4);
+      const props = {};
+      for (const [key, value] of Object.entries(element.attributes)) {
+        const lowerKey = key.toLowerCase();
+        if (lowerKey !== "ref" && !lowerKey.startsWith("jay")) {
+          props[toCamelCase(key)] = value;
         }
+      }
+      if (!insidePreservedForEach) {
         const hasUnresolvedProps = Object.values(props).some((v) => hasBindings(v));
         if (!hasUnresolvedProps) {
           const prefix = buildCoordinatePrefix(element);
@@ -27240,20 +27478,43 @@ function discoverHeadlessInstances(preRenderedJayHtml) {
             coordinate
           });
         }
+      } else {
+        const innerForEach = forEachContexts[forEachContexts.length - 1];
+        if (innerForEach) {
+          let ref = element.getAttribute("ref");
+          if (!ref) {
+            const counterKey = ["forEach", contractName].join("/");
+            const localIndex = coordinateCounters.get(counterKey) ?? 0;
+            coordinateCounters.set(counterKey, localIndex + 1);
+            ref = String(localIndex);
+          }
+          forEachInstances.push({
+            contractName,
+            forEachPath: innerForEach.forEachPath,
+            trackBy: innerForEach.trackBy,
+            propBindings: props,
+            coordinateSuffix: `${contractName}:${ref}`
+          });
+        }
       }
       return;
     }
+    const updatedForEachContexts = hasForEach && forEachAttr && trackByAttr ? [...forEachContexts, { forEachPath: forEachAttr, trackBy: trackByAttr }] : forEachContexts;
     for (const child of element.childNodes) {
       if (child.nodeType === NodeType.ELEMENT_NODE) {
-        walk(child, insidePreservedForEach || hasForEach);
+        walk(
+          child,
+          insidePreservedForEach || hasForEach,
+          updatedForEachContexts
+        );
       }
     }
   }
   const body = root.querySelector("body");
   if (body) {
-    walk(body, false);
+    walk(body, false, []);
   }
-  return { instances, preRenderedJayHtml: root.toString() };
+  return { instances, forEachInstances, preRenderedJayHtml: root.toString() };
 }
 function coordinateKey(coord) {
   return coord.join("/");
@@ -27344,11 +27605,13 @@ export {
   ContractTagType,
   JAY_IMPORT_RESOLVER,
   buildInstanceCoordinateKey,
+  compileAction,
   compileContract,
   contractToAllPhaseViewStates,
   contractToImportsViewStateAndRefs,
   contractToPhaseViewState,
   createPhaseContract,
+  defaultContractResolver,
   discoverHeadlessInstances,
   filterTagsByPhase,
   generateElementBridgeFile,
@@ -27363,6 +27626,7 @@ export {
   hasSlowPhaseProperties,
   isTagInPhase,
   loadLinkedContract,
+  parseAction,
   parseContract,
   parseEnumValues,
   parseIsEnum,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/compiler-jay-html",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "",
   "license": "Apache-2.0",
   "main": "dist/index.js",
@@ -34,12 +34,12 @@
   },
   "author": "",
   "dependencies": {
-    "@jay-framework/compiler-analyze-exported-types": "^0.12.0",
-    "@jay-framework/compiler-shared": "^0.12.0",
-    "@jay-framework/component": "^0.12.0",
-    "@jay-framework/logger": "^0.12.0",
-    "@jay-framework/runtime": "^0.12.0",
-    "@jay-framework/secure": "^0.12.0",
+    "@jay-framework/compiler-analyze-exported-types": "^0.13.0",
+    "@jay-framework/compiler-shared": "^0.13.0",
+    "@jay-framework/component": "^0.13.0",
+    "@jay-framework/logger": "^0.13.0",
+    "@jay-framework/runtime": "^0.13.0",
+    "@jay-framework/secure": "^0.13.0",
     "@types/js-yaml": "^4.0.9",
     "change-case": "^4.1.2",
     "js-yaml": "^4.1.0",
@@ -51,8 +51,8 @@
   },
   "devDependencies": {
     "@caiogondim/strip-margin": "^1.0.0",
-    "@jay-framework/4-react": "^0.12.0",
-    "@jay-framework/dev-environment": "^0.12.0",
+    "@jay-framework/4-react": "^0.13.0",
+    "@jay-framework/dev-environment": "^0.13.0",
     "@testing-library/jest-dom": "^6.2.0",
     "@types/js-beautify": "^1",
     "@types/node": "^20.11.5",