@jay-framework/compiler-shared 0.12.0 → 0.14.0

package/dist/index.d.ts

@@ -71,6 +71,19 @@ declare const Import: {
     injectHeadLinks: ImportName;
     makeJayComponent: ImportName;
     makeHeadlessInstanceComponent: ImportName;
+    HEADLESS_INSTANCES: ImportName;
+    useContext: ImportName;
+    currentConstructionContext: ImportName;
+    adoptText: ImportName;
+    adoptElement: ImportName;
+    childCompHydrate: ImportName;
+    hydrateConditional: ImportName;
+    hydrateForEach: ImportName;
+    adoptDynamicElement: ImportName;
+    STATIC: ImportName;
+    escapeHtml: ImportName;
+    escapeAttr: ImportName;
+    ServerRenderContext: ImportName;
 };
 declare class Imports {
     private readonly imports;
@@ -87,15 +100,18 @@ declare class Imports {
 declare const JAY_EXTENSION = ".jay-html";
 declare const CSS_EXTENSION = ".css";
 declare const JAY_CONTRACT_EXTENSION = ".jay-contract";
+declare const JAY_ACTION_EXTENSION = ".jay-action";
 declare const JAY_TS_EXTENSION = ".jay-html.ts";
 declare const JAY_DTS_EXTENSION = ".jay-html.d.ts";
 declare const JAY_CONTRACT_DTS_EXTENSION = ".jay-contract.d.ts";
+declare const JAY_ACTION_DTS_EXTENSION = ".jay-action.d.ts";
 declare const JAY_COMPONENT = "@jay-framework/component";
 declare const JAY_SECURE = "@jay-framework/secure";
 declare const JAY_RUNTIME = "@jay-framework/runtime";
 declare const JAY_4_REACT = "@jay-framework/4-react";
 declare const JAY_FULLSTACK_COMPONENTS = "@jay-framework/fullstack-component";
 declare const JAY_STACK_CLIENT_RUNTIME = "@jay-framework/stack-client-runtime";
+declare const JAY_SSR_RUNTIME = "@jay-framework/ssr-runtime";
 declare const REACT = "react";
 declare const MAKE_JAY_COMPONENT = "makeJayComponent";
 declare const MAKE_JAY_TSX_COMPONENT = "makeJayTsxComponent";
@@ -114,7 +130,8 @@ declare enum JayTypeKind {
     array = 9,
     union = 10,
     promise = 11,
-    recursive = 12
+    recursive = 12,
+    optional = 13
 }
 interface JayType {
     name: string;
@@ -212,7 +229,14 @@ declare class JayRecursiveType implements JayType {
     readonly kind = JayTypeKind.recursive;
     get name(): string;
 }
+declare class JayOptionalType implements JayType {
+    readonly innerType: JayType;
+    constructor(innerType: JayType);
+    readonly kind = JayTypeKind.optional;
+    get name(): string;
+}
 declare const JayErrorType: JayObjectType;
+declare function isOptionalType(aType: JayType): aType is JayOptionalType;
 declare function isAtomicType(aType: JayType): aType is JayAtomicType;
 declare function isTypeAliasType(aType: JayType): aType is JayTypeAlias;
 declare function isEnumType(aType: JayType): aType is JayEnumType;
@@ -230,6 +254,29 @@ declare function isCurrencyType(aType: JayType): aType is JayAtomicType;
 declare function isDateWithTimezoneType(aType: JayType): aType is JayAtomicType;
 declare function equalJayTypes(a: JayType, b: JayType): any;
 
+/**
+ * Converts JayType trees to JSON Schema.
+ *
+ * Used by the runtime to convert parsed .jay-action files into JSON Schema
+ * for AI agent tool definitions (e.g., Gemini function declarations).
+ */
+
+/**
+ * JSON Schema property definition.
+ */
+interface JsonSchemaProperty {
+    type: string;
+    description?: string;
+    enum?: string[];
+    items?: JsonSchemaProperty;
+    properties?: Record<string, JsonSchemaProperty>;
+    required?: string[];
+}
+/**
+ * Converts a JayType to a JSON Schema property.
+ */
+declare function jayTypeToJsonSchema(type: JayType): JsonSchemaProperty | null;
+
 interface JayImportName {
     name: string;
     as?: string;
@@ -254,6 +301,7 @@ declare const JAY_QUERY_PREFIX = "?jay-";
 declare const JAY_QUERY_MAIN_SANDBOX = "?jay-mainSandbox";
 declare const JAY_QUERY_WORKER_TRUSTED = "?jay-workerTrusted";
 declare const JAY_QUERY_WORKER_SANDBOX = "?jay-workerSandbox";
+declare const JAY_QUERY_HYDRATE = "?jay-hydrate";
 declare const JAY_QUERY_MAIN_SANDBOX_TS = "?jay-mainSandbox.ts";
 declare const JAY_QUERY_WORKER_TRUSTED_TS = "?jay-workerTrusted.ts";
 declare const JAY_QUERY_WORKER_SANDBOX_TS = "?jay-workerSandbox.ts";
@@ -308,6 +356,8 @@ interface ParsedJayModuleSpecifier {
     buildEnvironment?: JayBuildEnvironment;
     /** The runtime mode (sandbox modes) if present */
     runtimeMode?: RuntimeMode;
+    /** Whether this is a hydrate target (?jay-hydrate) */
+    isHydrate?: boolean;
     /** Any remaining query parameters (not jay-related) */
     otherQueryParams: string;
     /** The full query string for reconstruction */
@@ -477,6 +527,7 @@ declare function prettify(code: string, options?: prettier.Options): Promise<str
 declare function prettifyHtml(html: string): string;
 declare function removeComments(code: string): string;
 
+declare const LOCAL_PLUGIN_PATH = "src/plugins";
 /**
  * Plugin initialization configuration.
  *
@@ -510,6 +561,9 @@ interface PluginManifest {
     name: string;
     version?: string;
     module?: string;
+    /** When true, this plugin is loaded on every page regardless of usage in jay-html.
+     *  Useful for global tools like WebMCP, analytics, or dev tools. */
+    global?: boolean;
     contracts?: Array<{
         name: string;
         contract: string;
@@ -517,8 +571,10 @@ interface PluginManifest {
         description?: string;
     }>;
     dynamic_contracts?: DynamicContractConfig | DynamicContractConfig[];
-    /** Named exports from plugin backend bundle that are JayAction instances */
-    actions?: string[];
+    /** Named exports from plugin backend bundle that are JayAction instances.
+     *  Can be a string (export name, no metadata) or an object with a .jay-action file reference.
+     *  Actions with .jay-action metadata are exposed to AI agents; those without are not. */
+    actions?: ActionManifestEntry[];
     /** Plugin initialization configuration */
     init?: PluginInitConfig;
     /** Plugin setup configuration (Design Log #87) */
@@ -531,6 +587,23 @@ interface PluginManifest {
         description?: string;
     };
 }
+/**
+ * Action entry in plugin.yaml.
+ * - `string`: export name only, no metadata (not exposed to AI agents)
+ * - `{ name, action }`: export name + path to .jay-action metadata file
+ */
+type ActionManifestEntry = string | {
+    name: string;
+    action: string;
+};
+/**
+ * Normalizes an action manifest entry to { name, action? }.
+ * Strings become { name: string, action: undefined }.
+ */
+declare function normalizeActionEntry(entry: ActionManifestEntry): {
+    name: string;
+    action?: string;
+};
 /**
  * Result of resolving a plugin component
  */
@@ -554,31 +627,116 @@ interface PluginComponentResolution {
  */
 declare function loadPluginManifest(pluginDir: string): PluginManifest | null;
 /**
- * Resolves a plugin component from a local plugin directory (src/plugins/)
+ * Finds a dynamic contract config that matches the given contract name.
+ * Dynamic contracts use a prefix format: "prefix/name" (e.g., "list/recipes-list")
  *
- * @param projectRoot - Project root directory
- * @param pluginName - Name of the plugin
- * @param contractName - Name of the contract to resolve
- * @returns Resolution result with validation messages
+ * @param manifest - The plugin manifest
+ * @param contractName - The contract name to match (e.g., "list/recipes-list")
+ * @returns The matching DynamicContractConfig or null if not found
  */
-declare function resolveLocalPlugin(projectRoot: string, pluginName: string, contractName: string): WithValidations<PluginComponentResolution> | null;
+declare function findDynamicContract(manifest: PluginManifest, contractName: string): DynamicContractConfig | null;
 /**
- * Resolves a plugin component from an NPM package (node_modules/)
+ * Resolves a plugin component, trying local plugins first, then NPM packages
  *
  * @param projectRoot - Project root directory
- * @param pluginName - Name of the NPM package
+ * @param pluginName - Name of the plugin
  * @param contractName - Name of the contract to resolve
  * @returns Resolution result with validation messages
  */
-declare function resolveNpmPlugin(projectRoot: string, pluginName: string, contractName: string): WithValidations<PluginComponentResolution> | null;
+declare function resolvePluginComponent(projectRoot: string, pluginName: string, contractName: string): WithValidations<PluginComponentResolution>;
 /**
- * Resolves a plugin component, trying local plugins first, then NPM packages
+ * Resolves a plugin manifest from a local plugin or NPM package
  *
  * @param projectRoot - Project root directory
  * @param pluginName - Name of the plugin
- * @param contractName - Name of the contract to resolve
  * @returns Resolution result with validation messages
  */
-declare function resolvePluginComponent(projectRoot: string, pluginName: string, contractName: string): WithValidations<PluginComponentResolution>;
+declare function resolvePluginManifest(projectRoot: string, pluginName: string): WithValidations<PluginManifest>;
+
+/**
+ * Build-time utilities for coordinate template compilation.
+ *
+ * Coordinates may contain $placeholder segments (e.g. "0/$_id/1") that
+ * reference forEach trackBy variables. These utilities compile templates
+ * into JS string concatenation expressions — no runtime dependency.
+ */
+/**
+ * Compile a coordinate template with $placeholder syntax into a JS expression string.
+ *
+ * Static templates (no placeholders) return a quoted string literal.
+ * Dynamic templates compile to string concatenation expressions.
+ *
+ * @param template - Coordinate template, e.g. "0/$_id/1" or "product-card:0/0"
+ * @param varMappings - Maps placeholder names to JS expressions, e.g. { _id: "vs1._id" }
+ * @returns A JS expression string that evaluates to the final coordinate value
+ *
+ * @example
+ * // Static (no placeholders):
+ * compileCoordinateExpr("product-card:0/0", {})
+ * // → "'product-card:0/0'"
+ *
+ * // Dynamic (with placeholder):
+ * compileCoordinateExpr("0/$_id/1", { _id: "vs1._id" })
+ * // → "'0/' + escapeAttr(String(vs1._id)) + '/1'"
+ *
+ * // Placeholder at start:
+ * compileCoordinateExpr("$_id/product-card:0/0", { _id: "vs1._id" })
+ * // → "escapeAttr(String(vs1._id)) + '/product-card:0/0'"
+ */
+declare function compileCoordinateExpr(template: string, varMappings: Record<string, string>): string;
+/**
+ * Check if a coordinate template contains dynamic placeholders.
+ */
+declare function isStaticCoordinate(template: string): boolean;
+/**
+ * Compute the `__headlessInstances` key for a headless instance.
+ *
+ * The key format differs by context:
+ * - **Static**: `"product-card:0"` (just the coordinate suffix)
+ * - **forEach**: `"trackByValue,product-card:0"` (comma-separated, matching Array.toString())
+ * - **slowForEach**: `"p1/product-card:0"` (slash-separated, same as DOM coordinate)
+ *
+ * This function is used by both:
+ * - Server runtime (dev-server) when storing data in `__headlessInstances`
+ * - Client compiler when generating the key lookup in `makeHeadlessInstanceComponent`
+ *
+ * @param coordinateSuffix - The instance's coordinate suffix, e.g. "product-card:0"
+ * @param context - The context in which the instance appears
+ * @param prefix - For slowForEach: the jayTrackBy value (e.g. "p1").
+ *   For forEach: not used (key is computed at runtime from trackBy values).
+ * @returns For static/slowForEach: a literal key string.
+ *   For forEach: undefined (key must be computed at runtime).
+ */
+declare function computeInstanceKey(coordinateSuffix: string, context: 'static' | 'forEach' | 'slowForEach', prefix?: string): string | undefined;
+/**
+ * Compile a forEach instance key expression for generated code.
+ *
+ * For the server target, produces a JS expression that computes the key
+ * at runtime using the trackBy variable.
+ *
+ * For the client target (hydrate adopt path), the key is computed by
+ * `(dataIds) => dataIds.join(',')` — the coordinateBase already includes
+ * the suffix via `childCompHydrate`'s `forInstance` call.
+ *
+ * @param coordinateSuffix - e.g. "product-card:0"
+ * @param trackByExpr - JS expression for the trackBy value, e.g. "vs1._id"
+ * @returns A JS expression string that evaluates to the key
+ *
+ * @example
+ * compileForEachInstanceKeyExpr("product-card:0", "vs1._id")
+ * // → "String(vs1._id) + ',product-card:0'"
+ */
+declare function compileForEachInstanceKeyExpr(coordinateSuffix: string, trackByExpr: string): string;
+/**
+ * Runtime computation of a forEach instance key.
+ *
+ * Used by the dev server when storing data in `__headlessInstances`.
+ * Produces the same format as `compileForEachInstanceKeyExpr` generates
+ * at compile time: `"trackByValue,coordinateSuffix"`.
+ *
+ * @param trackByValue - The resolved trackBy value for the current item
+ * @param coordinateSuffix - e.g. "product-card:0"
+ */
+declare function computeForEachInstanceKey(trackByValue: string, coordinateSuffix: string): string;
 
-export { CSS_EXTENSION, type CompilerSourceFile, type DynamicContractConfig, GenerateTarget, type GenericTypescriptSourceFile, Import, type ImportName, type ImportedRefsTree, Imports, ImportsFor, JAY_4_REACT, JAY_COMPONENT, JAY_CONTRACT_DTS_EXTENSION, JAY_CONTRACT_EXTENSION, JAY_DTS_EXTENSION, JAY_EXTENSION, JAY_FULLSTACK_COMPONENTS, JAY_QUERY_CLIENT, JAY_QUERY_MAIN_SANDBOX, JAY_QUERY_MAIN_SANDBOX_TS, JAY_QUERY_PREFIX, JAY_QUERY_SERVER, JAY_QUERY_WORKER_SANDBOX, JAY_QUERY_WORKER_SANDBOX_TS, JAY_QUERY_WORKER_TRUSTED, JAY_QUERY_WORKER_TRUSTED_TS, JAY_RUNTIME, JAY_SECURE, JAY_STACK_CLIENT_RUNTIME, JAY_TS_EXTENSION, JayArrayType, JayAtomicType, JayBoolean, JayBuildEnvironment, JayComponentApiMember, JayComponentType, JayDate, JayElementConstructorType, JayElementType, JayEnumType, type JayEnvironment, JayErrorType, JayHTMLType, type JayImportLink, type JayImportName, JayImportedType, JayNumber, JayObjectType, JayPromiseType, JayRecursiveType, JayString, type JayType, JayTypeAlias, JayTypeKind, JayUnionType, JayUnknown, type JayValidations, MAKE_JAY_4_REACT_COMPONENT, MAKE_JAY_COMPONENT, MAKE_JAY_TSX_COMPONENT, type MainRuntimeModes, type ParsedJayModuleSpecifier, type PluginComponentResolution, type PluginInitConfig, type PluginManifest, REACT, type RecursiveRegion, type Ref, type RefsTree, RenderFragment, RuntimeMode, SourceFileFormat, TSX_EXTENSION, TS_EXTENSION, WithValidations, addBuildEnvironment, checkValidationErrors, equalJayTypes, getBasePath, getBuildEnvironment, getJayTsFileSourcePath, getMode, getModeFileExtension, getModeFromExtension, hasBuildEnvironment, hasExtension, hasJayExtension, hasJayModeExtension, hasRefs, isArrayType, isAtomicType, isComponentType, isCurrencyType, isDateWithTimezoneType, isElementConstructorType, isElementType, isEnumType, isHTMLType, isImportedType, isLocalModule, isObjectType, isPromiseType, isRecursiveType, isTypeAliasType, isUnionType, loadPluginManifest, mergeRefsTrees, mkRef, mkRefsTree, nestRefs, parseJayModuleSpecifier, prettify, prettifyHtml, removeComments, resolveLocalPlugin, resolveNpmPlugin, resolvePluginComponent, resolvePrimitiveType, withOriginalTrace, withoutExtension };
+export { type ActionManifestEntry, CSS_EXTENSION, type CompilerSourceFile, type DynamicContractConfig, GenerateTarget, type GenericTypescriptSourceFile, Import, type ImportName, type ImportedRefsTree, Imports, ImportsFor, JAY_4_REACT, JAY_ACTION_DTS_EXTENSION, JAY_ACTION_EXTENSION, JAY_COMPONENT, JAY_CONTRACT_DTS_EXTENSION, JAY_CONTRACT_EXTENSION, JAY_DTS_EXTENSION, JAY_EXTENSION, JAY_FULLSTACK_COMPONENTS, JAY_QUERY_CLIENT, JAY_QUERY_HYDRATE, JAY_QUERY_MAIN_SANDBOX, JAY_QUERY_MAIN_SANDBOX_TS, JAY_QUERY_PREFIX, JAY_QUERY_SERVER, JAY_QUERY_WORKER_SANDBOX, JAY_QUERY_WORKER_SANDBOX_TS, JAY_QUERY_WORKER_TRUSTED, JAY_QUERY_WORKER_TRUSTED_TS, JAY_RUNTIME, JAY_SECURE, JAY_SSR_RUNTIME, JAY_STACK_CLIENT_RUNTIME, JAY_TS_EXTENSION, JayArrayType, JayAtomicType, JayBoolean, JayBuildEnvironment, JayComponentApiMember, JayComponentType, JayDate, JayElementConstructorType, JayElementType, JayEnumType, type JayEnvironment, JayErrorType, JayHTMLType, type JayImportLink, type JayImportName, JayImportedType, JayNumber, JayObjectType, JayOptionalType, JayPromiseType, JayRecursiveType, JayString, type JayType, JayTypeAlias, JayTypeKind, JayUnionType, JayUnknown, type JayValidations, type JsonSchemaProperty, LOCAL_PLUGIN_PATH, MAKE_JAY_4_REACT_COMPONENT, MAKE_JAY_COMPONENT, MAKE_JAY_TSX_COMPONENT, type MainRuntimeModes, type ParsedJayModuleSpecifier, type PluginComponentResolution, type PluginInitConfig, type PluginManifest, REACT, type RecursiveRegion, type Ref, type RefsTree, RenderFragment, RuntimeMode, SourceFileFormat, TSX_EXTENSION, TS_EXTENSION, WithValidations, addBuildEnvironment, checkValidationErrors, compileCoordinateExpr, compileForEachInstanceKeyExpr, computeForEachInstanceKey, computeInstanceKey, equalJayTypes, findDynamicContract, getBasePath, getBuildEnvironment, getJayTsFileSourcePath, getMode, getModeFileExtension, getModeFromExtension, hasBuildEnvironment, hasExtension, hasJayExtension, hasJayModeExtension, hasRefs, isArrayType, isAtomicType, isComponentType, isCurrencyType, isDateWithTimezoneType, isElementConstructorType, isElementType, isEnumType, isHTMLType, isImportedType, isLocalModule, isObjectType, isOptionalType, isPromiseType, isRecursiveType, isStaticCoordinate, isTypeAliasType, isUnionType, jayTypeToJsonSchema, loadPluginManifest, mergeRefsTrees, mkRef, mkRefsTree, nestRefs, normalizeActionEntry, parseJayModuleSpecifier, prettify, prettifyHtml, removeComments, resolvePluginComponent, resolvePluginManifest, resolvePrimitiveType, withOriginalTrace, withoutExtension };

package/dist/index.js

@@ -13,15 +13,18 @@ import { createRequire } from "module";
 const JAY_EXTENSION = ".jay-html";
 const CSS_EXTENSION = ".css";
 const JAY_CONTRACT_EXTENSION = ".jay-contract";
+const JAY_ACTION_EXTENSION = ".jay-action";
 const JAY_TS_EXTENSION = ".jay-html.ts";
 const JAY_DTS_EXTENSION = ".jay-html.d.ts";
 const JAY_CONTRACT_DTS_EXTENSION = ".jay-contract.d.ts";
+const JAY_ACTION_DTS_EXTENSION = ".jay-action.d.ts";
 const JAY_COMPONENT = "@jay-framework/component";
 const JAY_SECURE = "@jay-framework/secure";
 const JAY_RUNTIME = "@jay-framework/runtime";
 const JAY_4_REACT = "@jay-framework/4-react";
 const JAY_FULLSTACK_COMPONENTS = "@jay-framework/fullstack-component";
 const JAY_STACK_CLIENT_RUNTIME = "@jay-framework/stack-client-runtime";
+const JAY_SSR_RUNTIME = "@jay-framework/ssr-runtime";
 const REACT = "react";
 const MAKE_JAY_COMPONENT = "makeJayComponent";
 const MAKE_JAY_TSX_COMPONENT = "makeJayTsxComponent";
@@ -413,6 +416,84 @@ const Import = {
     "makeHeadlessInstanceComponent",
     1
     /* implementation */
+  ),
+  HEADLESS_INSTANCES: importStatementFragment(
+    JAY_STACK_CLIENT_RUNTIME,
+    "HEADLESS_INSTANCES",
+    1
+    /* implementation */
+  ),
+  useContext: importStatementFragment(
+    JAY_RUNTIME,
+    "useContext",
+    1
+    /* implementation */
+  ),
+  currentConstructionContext: importStatementFragment(
+    JAY_RUNTIME,
+    "currentConstructionContext",
+    1
+    /* implementation */
+  ),
+  adoptText: importStatementFragment(
+    JAY_RUNTIME,
+    "adoptText",
+    1
+    /* implementation */
+  ),
+  adoptElement: importStatementFragment(
+    JAY_RUNTIME,
+    "adoptElement",
+    1
+    /* implementation */
+  ),
+  childCompHydrate: importStatementFragment(
+    JAY_RUNTIME,
+    "childCompHydrate",
+    1
+    /* implementation */
+  ),
+  hydrateConditional: importStatementFragment(
+    JAY_RUNTIME,
+    "hydrateConditional",
+    1
+    /* implementation */
+  ),
+  hydrateForEach: importStatementFragment(
+    JAY_RUNTIME,
+    "hydrateForEach",
+    1
+    /* implementation */
+  ),
+  adoptDynamicElement: importStatementFragment(
+    JAY_RUNTIME,
+    "adoptDynamicElement",
+    1
+    /* implementation */
+  ),
+  STATIC: importStatementFragment(
+    JAY_RUNTIME,
+    "STATIC",
+    1
+    /* implementation */
+  ),
+  escapeHtml: importStatementFragment(
+    JAY_SSR_RUNTIME,
+    "escapeHtml",
+    1
+    /* implementation */
+  ),
+  escapeAttr: importStatementFragment(
+    JAY_SSR_RUNTIME,
+    "escapeAttr",
+    1
+    /* implementation */
+  ),
+  ServerRenderContext: importStatementFragment(
+    JAY_SSR_RUNTIME,
+    "type ServerRenderContext",
+    1
+    /* implementation */
   )
 };
 class Imports {
@@ -493,6 +574,7 @@ var JayTypeKind = /* @__PURE__ */ ((JayTypeKind2) => {
   JayTypeKind2[JayTypeKind2["union"] = 10] = "union";
   JayTypeKind2[JayTypeKind2["promise"] = 11] = "promise";
   JayTypeKind2[JayTypeKind2["recursive"] = 12] = "recursive";
+  JayTypeKind2[JayTypeKind2["optional"] = 13] = "optional";
   return JayTypeKind2;
 })(JayTypeKind || {});
 class JayAtomicType {
@@ -615,11 +697,23 @@ class JayRecursiveType {
     return this.resolvedType?.name || `Recursive<${this.referencePath}>`;
   }
 }
+class JayOptionalType {
+  constructor(innerType) {
+    __publicField(this, "kind", 13);
+    this.innerType = innerType;
+  }
+  get name() {
+    return `${this.innerType.name}?`;
+  }
+}
 const JayErrorType = new JayObjectType("Error", {
   message: new JayAtomicType("string"),
   name: new JayAtomicType("string"),
   stack: new JayAtomicType("string")
 });
+function isOptionalType(aType) {
+  return aType.kind === 13;
+}
 function isAtomicType(aType) {
   return aType.kind === 0;
 }
@@ -695,7 +789,9 @@ function equalJayTypes(a, b) {
   else if (a instanceof JayObjectType && b instanceof JayObjectType) {
     const aProps = new Set(Object.keys(a.props));
     const bProps = new Set(Object.keys(b.props));
-    return aProps.size === bProps.size && [...aProps].map((aProp) => bProps.has(aProp) && equalJayTypes(a[aProp], b[aProp]));
+    return aProps.size === bProps.size && [...aProps].every(
+      (aProp) => bProps.has(aProp) && equalJayTypes(a.props[aProp], b.props[aProp])
+    );
   } else if (a instanceof JayUnionType && b instanceof JayUnionType) {
     return a.ofTypes.length === b.ofTypes.length && a.ofTypes.reduce((res, aType) => res && b.hasType(aType), true);
   } else if (a instanceof JayPromiseType && b instanceof JayPromiseType) {
@@ -705,6 +801,51 @@ function equalJayTypes(a, b) {
   } else
     ;
 }
+function jayTypeToJsonSchema(type) {
+  if (isOptionalType(type)) {
+    return jayTypeToJsonSchema(type.innerType);
+  }
+  if (isAtomicType(type)) {
+    const name = type.name.toLowerCase();
+    if (name === "string" || name === "number" || name === "boolean") {
+      return { type: name };
+    }
+    return { type: "string" };
+  }
+  if (isEnumType(type)) {
+    return { type: "string", enum: type.values };
+  }
+  if (isImportedType(type)) {
+    return { type: "object", description: `Contract: ${type.name}` };
+  }
+  if (isArrayType(type)) {
+    const itemSchema = jayTypeToJsonSchema(type.itemType);
+    if (itemSchema) {
+      return { type: "array", items: itemSchema };
+    }
+    return { type: "array" };
+  }
+  if (isObjectType(type)) {
+    const properties = {};
+    const required = [];
+    for (const [key, propType] of Object.entries(type.props)) {
+      const isOpt = isOptionalType(propType);
+      const schema = jayTypeToJsonSchema(propType);
+      if (schema) {
+        properties[key] = schema;
+        if (!isOpt) {
+          required.push(key);
+        }
+      }
+    }
+    return {
+      type: "object",
+      properties,
+      ...required.length > 0 && { required }
+    };
+  }
+  return null;
+}
 var RuntimeMode = /* @__PURE__ */ ((RuntimeMode2) => {
   RuntimeMode2["MainTrusted"] = "mainTrusted";
   RuntimeMode2["MainSandbox"] = "mainSandbox";
@@ -718,6 +859,7 @@ const JAY_QUERY_PREFIX = "?jay-";
 const JAY_QUERY_MAIN_SANDBOX = `${JAY_QUERY_PREFIX}${"mainSandbox"}`;
 const JAY_QUERY_WORKER_TRUSTED = `${JAY_QUERY_PREFIX}${"workerTrusted"}`;
 const JAY_QUERY_WORKER_SANDBOX = `${JAY_QUERY_PREFIX}${"workerSandbox"}`;
+const JAY_QUERY_HYDRATE = `${JAY_QUERY_PREFIX}hydrate`;
 const JAY_QUERY_MAIN_SANDBOX_TS = `${JAY_QUERY_PREFIX}${"mainSandbox"}${TS_EXTENSION}`;
 const JAY_QUERY_WORKER_TRUSTED_TS = `${JAY_QUERY_PREFIX}${"workerTrusted"}${TS_EXTENSION}`;
 const JAY_QUERY_WORKER_SANDBOX_TS = `${JAY_QUERY_PREFIX}${"workerSandbox"}${TS_EXTENSION}`;
@@ -780,6 +922,12 @@ var JayBuildEnvironment = /* @__PURE__ */ ((JayBuildEnvironment2) => {
 const JAY_QUERY_CLIENT = `${JAY_QUERY_PREFIX}${"client"}`;
 const JAY_QUERY_SERVER = `${JAY_QUERY_PREFIX}${"server"}`;
 const JAY_QUERY_PATTERNS = [
+  // Hydrate target
+  {
+    pattern: JAY_QUERY_HYDRATE,
+    buildEnv: "client",
+    isHydrate: true
+  },
   // Build environments
   {
     pattern: `${JAY_QUERY_PREFIX}${"client"}`,
@@ -831,13 +979,21 @@ function parseJayModuleSpecifier(specifier) {
   const fullQueryString = specifier.substring(queryIndex);
   let buildEnvironment;
   let runtimeMode;
+  let isHydrate;
   let remainingQuery = fullQueryString;
-  for (const { pattern, buildEnv, runtimeMode: rtMode } of JAY_QUERY_PATTERNS) {
+  for (const {
+    pattern,
+    buildEnv,
+    runtimeMode: rtMode,
+    isHydrate: hydrate
+  } of JAY_QUERY_PATTERNS) {
     if (remainingQuery.includes(pattern)) {
       if (buildEnv)
         buildEnvironment = buildEnv;
       if (rtMode)
         runtimeMode = rtMode;
+      if (hydrate)
+        isHydrate = true;
       remainingQuery = remainingQuery.replace(pattern, "");
     }
   }
@@ -846,6 +1002,7 @@ function parseJayModuleSpecifier(specifier) {
     basePath,
     buildEnvironment,
     runtimeMode,
+    isHydrate,
     otherQueryParams,
     fullQueryString
   };
@@ -907,13 +1064,13 @@ class WithValidations {
     this.validations = validations;
   }
   map(func) {
-    if (this.val)
+    if (this.val !== void 0)
       return new WithValidations(func(this.val), this.validations);
     else
       return new WithValidations(void 0, this.validations);
   }
   async mapAsync(func) {
-    if (this.val) {
+    if (this.val !== void 0) {
       const result = await func(this.val);
       return new WithValidations(result, this.validations);
     } else {
@@ -921,14 +1078,14 @@ class WithValidations {
     }
   }
   flatMap(func) {
-    if (this.val) {
+    if (this.val !== void 0) {
       let that = func(this.val);
       return new WithValidations(that.val, [...this.validations, ...that.validations]);
     } else
       return new WithValidations(void 0, this.validations);
   }
   async flatMapAsync(func) {
-    if (this.val) {
+    if (this.val !== void 0) {
       const result = await func(this.val);
       return new WithValidations(result.val, [...this.validations, ...result.validations]);
     } else {
@@ -1125,6 +1282,13 @@ function removeComments(code) {
   ).join("\n");
 }
 const require2 = createRequire(import.meta.url);
+const LOCAL_PLUGIN_PATH = "src/plugins";
+function normalizeActionEntry(entry) {
+  if (typeof entry === "string") {
+    return { name: entry };
+  }
+  return { name: entry.name, action: entry.action };
+}
 function loadPluginManifest(pluginDir) {
   const pluginYamlPath = path.join(pluginDir, "plugin.yaml");
   if (!fs.existsSync(pluginYamlPath)) {
@@ -1149,8 +1313,8 @@ function findDynamicContract(manifest, contractName) {
   const dynamicConfigs = Array.isArray(manifest.dynamic_contracts) ? manifest.dynamic_contracts : [manifest.dynamic_contracts];
   return dynamicConfigs.find((config) => config.prefix === prefix) || null;
 }
-function resolveLocalPlugin(projectRoot, pluginName, contractName) {
-  const localPluginPath = path.join(projectRoot, "src/plugins", pluginName);
+function resolveLocalPluginManifest(projectRoot, pluginName) {
+  const localPluginPath = path.join(projectRoot, LOCAL_PLUGIN_PATH, pluginName);
   const pluginYamlPath = path.join(localPluginPath, "plugin.yaml");
   if (!fs.existsSync(localPluginPath)) {
     return null;
@@ -1166,7 +1330,23 @@ function resolveLocalPlugin(projectRoot, pluginName, contractName) {
       `Failed to parse plugin.yaml for local plugin "${pluginName}" at ${pluginYamlPath}`
     ]);
   }
+  if (!manifest.contracts && !manifest.dynamic_contracts) {
+    return new WithValidations(null, [
+      `Local plugin "${pluginName}" has no contracts or dynamic_contracts defined in plugin.yaml`
+    ]);
+  }
+  return new WithValidations(manifest, []);
+}
+function resolveLocalPlugin(projectRoot, pluginName, contractName) {
+  const manifestWithValidations = resolveLocalPluginManifest(projectRoot, pluginName);
+  if (!manifestWithValidations) {
+    return null;
+  }
+  if (!manifestWithValidations.val || manifestWithValidations.validations.length > 0)
+    return new WithValidations(null, manifestWithValidations.validations);
+  const manifest = manifestWithValidations.val;
   const componentModule = manifest.module || "index.js";
+  const localPluginPath = path.join(projectRoot, LOCAL_PLUGIN_PATH, pluginName);
   const componentPath = path.join(localPluginPath, componentModule);
   if (manifest.contracts && manifest.contracts.length > 0) {
     const contract = manifest.contracts.find((c2) => c2.name === contractName);
@@ -1195,11 +1375,6 @@ function resolveLocalPlugin(projectRoot, pluginName, contractName) {
       []
     );
   }
-  if (!manifest.contracts && !manifest.dynamic_contracts) {
-    return new WithValidations(null, [
-      `Local plugin "${pluginName}" has no contracts or dynamic_contracts defined in plugin.yaml`
-    ]);
-  }
   const availableContracts = manifest.contracts?.map((c2) => c2.name) || [];
   const dynamicPrefixes = manifest.dynamic_contracts ? (Array.isArray(manifest.dynamic_contracts) ? manifest.dynamic_contracts : [manifest.dynamic_contracts]).map((c2) => `${c2.prefix}/*`) : [];
   const allAvailable = [...availableContracts, ...dynamicPrefixes].join(", ");
@@ -1207,7 +1382,7 @@ function resolveLocalPlugin(projectRoot, pluginName, contractName) {
     `Contract "${contractName}" not found in local plugin "${pluginName}". Available: ${allAvailable}`
   ]);
 }
-function resolveNpmPlugin(projectRoot, pluginName, contractName) {
+function resolveNpmPluginManifest(projectRoot, pluginName) {
   let pluginYamlPath;
   try {
     pluginYamlPath = require2.resolve(`${pluginName}/plugin.yaml`, {
@@ -1230,6 +1405,25 @@ function resolveNpmPlugin(projectRoot, pluginName, contractName) {
       `Failed to parse plugin.yaml for NPM package "${pluginName}" at ${pluginYamlPath}`
     ]);
   }
+  if (!manifest.contracts && !manifest.dynamic_contracts) {
+    return new WithValidations(null, [
+      `NPM package "${pluginName}" has no contracts or dynamic_contracts defined in plugin.yaml`
+    ]);
+  }
+  return new WithValidations(manifest, []);
+}
+function resolveNpmPlugin(projectRoot, pluginName, contractName) {
+  const manifestWithValidations = resolveNpmPluginManifest(projectRoot, pluginName);
+  if (!manifestWithValidations) {
+    return null;
+  }
+  if (!manifestWithValidations.val || manifestWithValidations.validations.length > 0)
+    return new WithValidations(null, manifestWithValidations.validations);
+  const manifest = manifestWithValidations.val;
+  const pluginYamlPath = require2.resolve(`${pluginName}/plugin.yaml`, {
+    paths: [projectRoot]
+  });
+  const npmPluginPath = path.dirname(pluginYamlPath);
   const packageJsonPath = path.join(npmPluginPath, "package.json");
   const getComponentPath = () => {
     if (fs.existsSync(packageJsonPath)) {
@@ -1301,11 +1495,6 @@ function resolveNpmPlugin(projectRoot, pluginName, contractName) {
       []
     );
   }
-  if (!manifest.contracts && !manifest.dynamic_contracts) {
-    return new WithValidations(null, [
-      `NPM package "${pluginName}" has no contracts or dynamic_contracts defined in plugin.yaml`
-    ]);
-  }
   const availableContracts = manifest.contracts?.map((c2) => c2.name) || [];
   const dynamicPrefixes = manifest.dynamic_contracts ? (Array.isArray(manifest.dynamic_contracts) ? manifest.dynamic_contracts : [manifest.dynamic_contracts]).map((c2) => `${c2.prefix}/*`) : [];
   const allAvailable = [...availableContracts, ...dynamicPrefixes].join(", ");
@@ -1315,17 +1504,97 @@ function resolveNpmPlugin(projectRoot, pluginName, contractName) {
 }
 function resolvePluginComponent(projectRoot, pluginName, contractName) {
   const localResult = resolveLocalPlugin(projectRoot, pluginName, contractName);
-  if (localResult !== null) {
+  if (localResult && localResult.val !== null && localResult.validations.length === 0) {
     return localResult;
   }
   const npmResult = resolveNpmPlugin(projectRoot, pluginName, contractName);
-  if (npmResult !== null) {
+  if (npmResult && npmResult.val !== null && npmResult.validations.length === 0) {
+    return npmResult;
+  }
+  if (localResult && localResult.validations.length > 0) {
+    return localResult;
+  }
+  if (npmResult && npmResult.validations.length > 0 && localResult === null) {
+    const npmError = npmResult.validations[0];
+    const isGenericPackageNotFound = npmError.startsWith("NPM package") && npmError.includes("not found") || npmError.startsWith("Plugin") && npmError.includes("not found");
+    if (!isGenericPackageNotFound) {
+      return npmResult;
+    }
+  }
+  return new WithValidations(null, [
+    `Plugin "${pluginName}" not found. Searched in src/plugins/${pluginName}/ and node_modules/${pluginName}/. Ensure the plugin is installed or exists in your project.`
+  ]);
+}
+function resolvePluginManifest(projectRoot, pluginName) {
+  const localResult = resolveLocalPluginManifest(projectRoot, pluginName);
+  if (localResult && localResult.val !== null && localResult.validations.length === 0) {
+    return localResult;
+  }
+  const npmResult = resolveNpmPluginManifest(projectRoot, pluginName);
+  if (npmResult && npmResult.val !== null && npmResult.validations.length === 0) {
     return npmResult;
   }
+  if (localResult && localResult.validations.length > 0) {
+    return localResult;
+  }
+  if (npmResult && npmResult.validations.length > 0 && localResult === null) {
+    const npmError = npmResult.validations[0];
+    const isGenericPackageNotFound = npmError.startsWith("NPM package") && npmError.includes("not found") || npmError.startsWith("Plugin") && npmError.includes("not found");
+    if (!isGenericPackageNotFound) {
+      return npmResult;
+    }
+  }
   return new WithValidations(null, [
     `Plugin "${pluginName}" not found. Searched in src/plugins/${pluginName}/ and node_modules/${pluginName}/. Ensure the plugin is installed or exists in your project.`
   ]);
 }
+function compileCoordinateExpr(template, varMappings) {
+  if (!template.includes("$")) {
+    return `'${template}'`;
+  }
+  const parts = [];
+  let remaining = template;
+  while (remaining.length > 0) {
+    const match = remaining.match(/\$([a-zA-Z_]\w*)/);
+    if (!match) {
+      parts.push(`'${remaining}'`);
+      break;
+    }
+    const placeholderName = match[1];
+    const placeholderStart = match.index;
+    if (placeholderStart > 0) {
+      parts.push(`'${remaining.substring(0, placeholderStart)}'`);
+    }
+    const varExpr = varMappings[placeholderName];
+    if (varExpr === void 0) {
+      throw new Error(
+        `compileCoordinateExpr: no mapping for placeholder "$${placeholderName}" in template "${template}"`
+      );
+    }
+    parts.push(`escapeAttr(String(${varExpr}))`);
+    remaining = remaining.substring(placeholderStart + match[0].length);
+  }
+  return parts.join(" + ");
+}
+function isStaticCoordinate(template) {
+  return !template.includes("$");
+}
+function computeInstanceKey(coordinateSuffix, context, prefix) {
+  switch (context) {
+    case "static":
+      return coordinateSuffix;
+    case "slowForEach":
+      return `${prefix}/${coordinateSuffix}`;
+    case "forEach":
+      return void 0;
+  }
+}
+function compileForEachInstanceKeyExpr(coordinateSuffix, trackByExpr) {
+  return `String(${trackByExpr}) + ',${coordinateSuffix}'`;
+}
+function computeForEachInstanceKey(trackByValue, coordinateSuffix) {
+  return [trackByValue, coordinateSuffix].toString();
+}
 const s = createRequire(import.meta.url), e = s("typescript"), u = e, c = new Proxy(e, {
   get(t, r) {
     return t[r];
@@ -1341,6 +1610,8 @@ export {
   Imports,
   ImportsFor,
   JAY_4_REACT,
+  JAY_ACTION_DTS_EXTENSION,
+  JAY_ACTION_EXTENSION,
   JAY_COMPONENT,
   JAY_CONTRACT_DTS_EXTENSION,
   JAY_CONTRACT_EXTENSION,
@@ -1348,6 +1619,7 @@ export {
   JAY_EXTENSION,
   JAY_FULLSTACK_COMPONENTS,
   JAY_QUERY_CLIENT,
+  JAY_QUERY_HYDRATE,
   JAY_QUERY_MAIN_SANDBOX,
   JAY_QUERY_MAIN_SANDBOX_TS,
   JAY_QUERY_PREFIX,
@@ -1358,6 +1630,7 @@ export {
   JAY_QUERY_WORKER_TRUSTED_TS,
   JAY_RUNTIME,
   JAY_SECURE,
+  JAY_SSR_RUNTIME,
   JAY_STACK_CLIENT_RUNTIME,
   JAY_TS_EXTENSION,
   JayArrayType,
@@ -1375,6 +1648,7 @@ export {
   JayImportedType,
   JayNumber,
   JayObjectType,
+  JayOptionalType,
   JayPromiseType,
   JayRecursiveType,
   JayString,
@@ -1382,6 +1656,7 @@ export {
   JayTypeKind,
   JayUnionType,
   JayUnknown,
+  LOCAL_PLUGIN_PATH,
   MAKE_JAY_4_REACT_COMPONENT,
   MAKE_JAY_COMPONENT,
   MAKE_JAY_TSX_COMPONENT,
@@ -1394,7 +1669,12 @@ export {
   WithValidations,
   addBuildEnvironment,
   checkValidationErrors,
+  compileCoordinateExpr,
+  compileForEachInstanceKeyExpr,
+  computeForEachInstanceKey,
+  computeInstanceKey,
   equalJayTypes,
+  findDynamicContract,
   getBasePath,
   getBuildEnvironment,
   getJayTsFileSourcePath,
@@ -1419,22 +1699,25 @@ export {
   isImportedType,
   isLocalModule,
   isObjectType,
+  isOptionalType,
   isPromiseType,
   isRecursiveType,
+  isStaticCoordinate,
   isTypeAliasType,
   isUnionType,
+  jayTypeToJsonSchema,
   loadPluginManifest,
   mergeRefsTrees,
   mkRef,
   mkRefsTree,
   nestRefs,
+  normalizeActionEntry,
   parseJayModuleSpecifier,
   prettify,
   prettifyHtml,
   removeComments,
-  resolveLocalPlugin,
-  resolveNpmPlugin,
   resolvePluginComponent,
+  resolvePluginManifest,
   resolvePrimitiveType,
   u as ts,
   c as tsBridge,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/compiler-shared",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "type": "module",
   "description": "",
   "license": "Apache-2.0",
@@ -25,10 +25,10 @@
   },
   "author": "",
   "dependencies": {
-    "@jay-framework/component": "^0.12.0",
-    "@jay-framework/runtime": "^0.12.0",
-    "@jay-framework/secure": "^0.12.0",
-    "@jay-framework/typescript-bridge": "^0.7.0",
+    "@jay-framework/component": "^0.14.0",
+    "@jay-framework/runtime": "^0.14.0",
+    "@jay-framework/secure": "^0.14.0",
+    "@jay-framework/typescript-bridge": "^0.9.0",
     "@types/js-yaml": "^4.0.9",
     "change-case": "^4.1.2",
     "js-beautify": "^1.14.11",
@@ -41,7 +41,7 @@
   },
   "devDependencies": {
     "@caiogondim/strip-margin": "^1.0.0",
-    "@jay-framework/dev-environment": "^0.12.0",
+    "@jay-framework/dev-environment": "^0.14.0",
     "@testing-library/jest-dom": "^6.2.0",
     "@types/js-beautify": "^1",
     "@types/node": "^20.11.5",