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

package/dist/index.d.cts

@@ -31,9 +31,11 @@ interface ContractProp {
     description?: Array<string>;
     default?: string;
 }
-/** URL/load params for a page (e.g. [slug]). Always string in generated type (UrlParams = Record<string, string>). Design Log #85. */
+type ContractParamKind = 'required' | 'optional' | 'catch-all';
+/** URL/load params for a page (e.g. [slug]). Design Log #85, #113. */
 interface ContractParam {
     name: string;
+    kind: ContractParamKind;
 }
 interface Contract {
     name: string;
@@ -80,7 +82,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).
      */
@@ -90,6 +92,13 @@ interface JayImportResolver {
         metadata?: Record<string, unknown>;
     }>;
     resolvePluginManifest(pluginName: string, projectRoot: string): WithValidations<PluginManifest>;
+    /**
+     * Read a jay-html file adjacent to a component module.
+     * Given a module src path (e.g., "./header/header"), resolves to the absolute path
+     * and reads the corresponding .jay-html file (same base name + .jay-html extension).
+     * Returns the file content string, or null if not found.
+     */
+    readJayHtml(importingModuleDir: string, src: string): string | null;
 }
 declare const JAY_IMPORT_RESOLVER: JayImportResolver;
 
@@ -195,10 +204,69 @@ 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;
+
+/**
+ * Inject headfull full-stack component templates into jay-html.
+ * Finds <script type="application/jay-headfull" contract="..."> tags,
+ * reads each component's jay-html file, and injects the body content
+ * into matching <jay:Name> tags that are empty/self-closing.
+ *
+ * This must be called on the raw HTML string BEFORE the slow render pipeline,
+ * so that instance bindings can be resolved during pre-rendering.
+ *
+ * @param html - The raw jay-html content
+ * @param sourceDir - Absolute path to the directory containing the jay-html file
+ * @param importResolver - Resolver for reading component jay-html files
+ * @returns The HTML with headfull FS templates injected (or unchanged if none found)
+ */
+declare function injectHeadfullFSTemplates(html: string, sourceDir: string, importResolver: JayImportResolver): string;
 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 +453,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 ContractParamKind, 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, injectHeadfullFSTemplates, isTagInPhase, loadLinkedContract, parseAction, parseContract, parseEnumValues, parseIsEnum, parseJayFile, renderRefsType, resolveHeadlessInstances, slowRenderTransform, validateContractPhases };