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

package/dist/index.d.cts

@@ -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).
      */
@@ -195,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[];
 
@@ -385,4 +429,4 @@ declare function resolveHeadlessInstances(preRenderedJayHtml: string, instanceDa
  */
 declare function hasSlowPhaseProperties(contract: Contract | undefined): boolean;
 
-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 };
+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 };