@jay-framework/compiler-jay-html 0.12.0 → 0.14.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';
@@ -80,7 +80,7 @@ interface JayImportResolver {
     /**
      * Load a contract from a plugin, handling both static and dynamic contracts.
      * For static contracts, loads from the plugin's contract file.
-     * For dynamic contracts, loads from materialized location (build/materialized-contracts/).
+     * For dynamic contracts, loads from materialized location (agent-kit/materialized-contracts/).
      *
      * Returns the contract, path, and optional metadata (for dynamic contracts).
      */
@@ -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;
 
@@ -194,10 +195,54 @@ interface JayHtmlSourceFile extends CompilerSourceFile {
 declare function generateElementDefinitionFile(parsedFile: WithValidations<JayHtmlSourceFile>): WithValidations<string>;
 declare function generateElementFile(jayFile: JayHtmlSourceFile, importerMode: MainRuntimeModes): WithValidations<string>;
 declare function generateElementBridgeFile(jayFile: JayHtmlSourceFile): string;
+declare function generateElementHydrateFile(jayFile: JayHtmlSourceFile, importerMode: MainRuntimeModes): WithValidations<string>;
+interface ServerElementOptions {
+    /** Path to write debug coordinate pre-process output. When provided, the
+     *  serialized DOM with jay-coordinate-base attributes is returned via result. */
+    debugCoordinatePreprocessPath?: string;
+}
+declare function generateServerElementFile(jayFile: JayHtmlSourceFile, _options?: ServerElementOptions): WithValidations<string>;
 declare function generateSandboxRootFile(jayFile: JayHtmlSourceFile): string;
 
 declare function generateElementFileReactTarget(jayFile: JayHtmlSourceFile, importerMode: MainRuntimeModes): WithValidations<string>;
 
+/**
+ * Coordinate pre-processing for SSR/hydration consistency.
+ *
+ * Assigns `jay-coordinate-base` attributes to all elements that need coordinates,
+ * in a single pass before either server or hydrate compilation runs.
+ * Both compilers read this attribute instead of computing coordinates independently.
+ *
+ * See Design Log #103, #106.
+ */
+
+interface AssignCoordinatesOptions {
+    /** Set of headless contract names (for detecting <jay:xxx> tags) */
+    headlessContractNames: Set<string>;
+    /** @internal Auto-generated ref counters for headless instances without explicit refs.
+     *  Created automatically if not provided. */
+    _refCounters?: Map<string, number>;
+}
+interface AssignCoordinatesResult {
+    /** Serialized DOM with jay-coordinate-base attributes, for debug output */
+    debugHtml: string;
+}
+/**
+ * Assign coordinates to a full jay-html string and return the result.
+ * Used by the pre-render pipeline so discoverHeadlessInstances gets elements
+ * with jay-coordinate-base, matching the hydrate compiler's coordinate format.
+ */
+declare function assignCoordinatesToJayHtml(jayHtml: string, headlessContractNames: Set<string>): string;
+/**
+ * Assign `jay-coordinate-base` attributes to elements in the DOM tree.
+ *
+ * Must run after slow-render (which resolves slow conditions, unrolls slowForEach,
+ * and wraps multi-child headless inline templates).
+ *
+ * Mutates the DOM in place. Returns the serialized DOM for debug output.
+ */
+declare function assignCoordinates(body: HTMLElement, options: AssignCoordinatesOptions): AssignCoordinatesResult;
+
 declare function parseJayFile(html: string, filename: string, filePath: string, options: ResolveTsConfigOptions, linkedContractResolver: JayImportResolver, projectRoot: string): Promise<WithValidations<JayHtmlSourceFile>>;
 declare function getJayHtmlImports(html: string): string[];
 
@@ -211,6 +256,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 +399,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 +429,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 AssignCoordinatesOptions, type AssignCoordinatesResult, 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 ServerElementOptions, type SlowRenderInput, type SlowRenderOutput, assignCoordinates, assignCoordinatesToJayHtml, buildInstanceCoordinateKey, compileAction, compileContract, contractToAllPhaseViewStates, contractToImportsViewStateAndRefs, contractToPhaseViewState, createPhaseContract, defaultContractResolver, discoverHeadlessInstances, filterTagsByPhase, generateElementBridgeFile, generateElementDefinitionFile, generateElementFile, generateElementFileReactTarget, generateElementHydrateFile, generateSandboxRootFile, generateServerElementFile, generateTypes, getEffectivePhase, getJayHtmlImports, getLinkedContractDir, hasSlowPhaseProperties, isTagInPhase, loadLinkedContract, parseAction, parseContract, parseEnumValues, parseIsEnum, parseJayFile, renderRefsType, resolveHeadlessInstances, slowRenderTransform, validateContractPhases };