@jay-framework/compiler-jay-html 0.15.5 → 0.15.6

package/dist/index.d.cts

@@ -39,6 +39,8 @@ interface ContractParam {
 }
 interface Contract {
     name: string;
+    /** Human-readable description of the contract (for agent-kit and validation). */
+    description?: string;
     tags: Array<ContractTag>;
     props?: Array<ContractProp>;
     /** URL/load params (e.g. slug for [slug] route). Generates Params extends UrlParams. */
@@ -95,10 +97,16 @@ interface JayImportResolver {
     /**
      * 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.
+     * and reads the corresponding .jay-html file. Tries two conventions:
+     * 1. File-based: `<src>.jay-html` (e.g., `header/header.jay-html`)
+     * 2. Directory-based: `<src>/<basename>.jay-html` (e.g., `header/header/header.jay-html`)
+     * Returns the file content and the directory containing the jay-html file, or null if not found.
      */
-    readJayHtml(importingModuleDir: string, src: string): string | null;
+    readJayHtml(importingModuleDir: string, src: string): {
+        content: string;
+        componentDir: string;
+        filePath: string;
+    } | null;
 }
 declare const JAY_IMPORT_RESOLVER: JayImportResolver;
 
@@ -185,6 +193,11 @@ interface JayHtmlSourceFile extends CompilerSourceFile {
      * Used by the dev server to watch these files for changes.
      */
     linkedCssFiles?: string[];
+    /**
+     * Absolute paths to headfull FS component jay-html files included by this page.
+     * Includes nested headfull components. Used by the dev server to watch for changes.
+     */
+    linkedComponentFiles?: string[];
     filename?: string;
     contract?: Contract;
     contractRef?: string;
@@ -229,11 +242,12 @@ declare function generateServerElementFile(jayFile: JayHtmlSourceFile, _options?
 /**
  * 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.
+ * Assigns `jay-coordinate-base` and `jay-scope` attributes to all elements
+ * that need coordinates, in a single pass before either server or hydrate
+ * compilation runs. Both compilers read these attributes instead of computing
+ * coordinates independently.
  *
- * See Design Log #103, #106.
+ * See Design Log #103, #106, #126 (scoped coordinates).
  */
 
 interface AssignCoordinatesOptions {
@@ -254,7 +268,7 @@ interface AssignCoordinatesResult {
  */
 declare function assignCoordinatesToJayHtml(jayHtml: string, headlessContractNames: Set<string>): string;
 /**
- * Assign `jay-coordinate-base` attributes to elements in the DOM tree.
+ * Assign `jay-coordinate-base` and `jay-scope` 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).
@@ -278,7 +292,13 @@ declare function assignCoordinates(body: HTMLElement, options: AssignCoordinates
  * @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 parseJayFile(html: string, filename: string, filePath: string, options: ResolveTsConfigOptions, linkedContractResolver: JayImportResolver, projectRoot: string, 
+/** Optional source directory for resolving headfull FS files (jay-html, contracts).
+ *  When parsing pre-rendered files, filePath is in build/pre-rendered/ but headfull
+ *  relative paths were written for the original source directory. Pass the source
+ *  directory here so file resolution works correctly while module paths stay relative
+ *  to the actual filePath. */
+sourceDir?: string): Promise<WithValidations<JayHtmlSourceFile>>;
 declare function getJayHtmlImports(html: string): string[];
 
 declare const htmlElementTagNameMap: {