@jay-framework/compiler-shared 0.11.0 → 0.13.0

package/dist/index.d.ts

@@ -69,6 +69,8 @@ declare const Import: {
     mimicJayElement: ImportName;
     jayContract: ImportName;
     injectHeadLinks: ImportName;
+    makeJayComponent: ImportName;
+    makeHeadlessInstanceComponent: ImportName;
 };
 declare class Imports {
     private readonly imports;
@@ -85,14 +87,17 @@ 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 REACT = "react";
 declare const MAKE_JAY_COMPONENT = "makeJayComponent";
 declare const MAKE_JAY_TSX_COMPONENT = "makeJayTsxComponent";
@@ -111,7 +116,8 @@ declare enum JayTypeKind {
     array = 9,
     union = 10,
     promise = 11,
-    recursive = 12
+    recursive = 12,
+    optional = 13
 }
 interface JayType {
     name: string;
@@ -209,7 +215,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;
@@ -227,6 +240,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;
@@ -386,6 +422,20 @@ declare class WithValidations<Value> {
     flatMap<R>(func: (v: Value) => WithValidations<R>): WithValidations<R>;
     flatMapAsync<R>(func: (v: Value) => Promise<WithValidations<R>>): Promise<WithValidations<R>>;
     merge(other: WithValidations<Value>, merge: (t1: Value, t2: Value) => Value): WithValidations<Value>;
+    /**
+     * Append validations from another WithValidations without changing the value.
+     * Useful for collecting validations from side-effect operations.
+     */
+    withValidationsFrom<T>(other: WithValidations<T>): WithValidations<Value>;
+    /**
+     * Merge an array of WithValidations into a single WithValidations containing an array of values.
+     * All validations are collected.
+     */
+    static all<T>(items: WithValidations<T>[]): WithValidations<T[]>;
+    /**
+     * Create a WithValidations with no validations (pure value).
+     */
+    static pure<T>(value: T): WithValidations<T>;
 }
 declare function checkValidationErrors<T>(withValidations: WithValidations<T>): T;
 
@@ -460,6 +510,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.
  *
@@ -475,6 +526,17 @@ declare function removeComments(code: string): string;
  * ```
  */
 type PluginInitConfig = string;
+/**
+ * Dynamic contract generator configuration.
+ */
+interface DynamicContractConfig {
+    /** Path to the generator module (relative to plugin root) */
+    generator: string;
+    /** Path to the headless component (relative to plugin root) */
+    component: string;
+    /** Prefix for generated contract names (e.g., "cms" -> "cms/blog-posts") */
+    prefix: string;
+}
 /**
  * Plugin manifest structure from plugin.yaml
  */
@@ -482,22 +544,49 @@ 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;
         component: string;
         description?: string;
     }>;
-    dynamic_contracts?: {
-        generator: string;
-        component: string;
-        prefix: string;
-    };
-    /** Named exports from plugin backend bundle that are JayAction instances */
-    actions?: string[];
+    dynamic_contracts?: DynamicContractConfig | DynamicContractConfig[];
+    /** 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) */
+    setup?: {
+        /** Export name (NPM) or relative path (local) to setup handler function */
+        handler: string;
+        /** Export name for reference data generation (called by jay-stack agent-kit) */
+        references?: string;
+        /** Human-readable description of what setup does */
+        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
  */
@@ -521,31 +610,30 @@ 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>;
 
-export { CSS_EXTENSION, type CompilerSourceFile, 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_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_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, 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, 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, isTypeAliasType, isUnionType, jayTypeToJsonSchema, loadPluginManifest, mergeRefsTrees, mkRef, mkRefsTree, nestRefs, normalizeActionEntry, parseJayModuleSpecifier, prettify, prettifyHtml, removeComments, resolvePluginComponent, resolvePluginManifest, resolvePrimitiveType, withOriginalTrace, withoutExtension };

package/dist/index.js

@@ -13,14 +13,17 @@ 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 REACT = "react";
 const MAKE_JAY_COMPONENT = "makeJayComponent";
 const MAKE_JAY_TSX_COMPONENT = "makeJayTsxComponent";
@@ -400,6 +403,18 @@ const Import = {
     "injectHeadLinks",
     1
     /* implementation */
+  ),
+  makeJayComponent: importStatementFragment(
+    JAY_COMPONENT,
+    "makeJayComponent",
+    1
+    /* implementation */
+  ),
+  makeHeadlessInstanceComponent: importStatementFragment(
+    JAY_STACK_CLIENT_RUNTIME,
+    "makeHeadlessInstanceComponent",
+    1
+    /* implementation */
   )
 };
 class Imports {
@@ -480,6 +495,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 {
@@ -602,11 +618,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;
 }
@@ -692,6 +720,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";
@@ -894,13 +967,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 {
@@ -908,14 +981,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 {
@@ -928,6 +1001,28 @@ class WithValidations {
       ...other.validations
     ]);
   }
+  /**
+   * Append validations from another WithValidations without changing the value.
+   * Useful for collecting validations from side-effect operations.
+   */
+  withValidationsFrom(other) {
+    return new WithValidations(this.val, [...this.validations, ...other.validations]);
+  }
+  /**
+   * Merge an array of WithValidations into a single WithValidations containing an array of values.
+   * All validations are collected.
+   */
+  static all(items) {
+    const values = items.map((item) => item.val).filter((v) => v !== void 0);
+    const validations = items.flatMap((item) => item.validations);
+    return new WithValidations(values, validations);
+  }
+  /**
+   * Create a WithValidations with no validations (pure value).
+   */
+  static pure(value) {
+    return new WithValidations(value, []);
+  }
 }
 function checkValidationErrors(withValidations) {
   const { validations } = withValidations;
@@ -1090,6 +1185,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)) {
@@ -1102,8 +1204,20 @@ function loadPluginManifest(pluginDir) {
     return null;
   }
 }
-function resolveLocalPlugin(projectRoot, pluginName, contractName) {
-  const localPluginPath = path.join(projectRoot, "src/plugins", pluginName);
+function findDynamicContract(manifest, contractName) {
+  if (!manifest.dynamic_contracts) {
+    return null;
+  }
+  const slashIndex = contractName.indexOf("/");
+  if (slashIndex === -1) {
+    return null;
+  }
+  const prefix = contractName.substring(0, slashIndex);
+  const dynamicConfigs = Array.isArray(manifest.dynamic_contracts) ? manifest.dynamic_contracts : [manifest.dynamic_contracts];
+  return dynamicConfigs.find((config) => config.prefix === prefix) || null;
+}
+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;
@@ -1119,32 +1233,59 @@ function resolveLocalPlugin(projectRoot, pluginName, contractName) {
       `Failed to parse plugin.yaml for local plugin "${pluginName}" at ${pluginYamlPath}`
     ]);
   }
-  if (!manifest.contracts || manifest.contracts.length === 0) {
+  if (!manifest.contracts && !manifest.dynamic_contracts) {
     return new WithValidations(null, [
-      `Local plugin "${pluginName}" has no contracts defined in plugin.yaml`
+      `Local plugin "${pluginName}" has no contracts or dynamic_contracts defined in plugin.yaml`
     ]);
   }
-  const contract = manifest.contracts.find((c2) => c2.name === contractName);
-  if (!contract) {
-    const availableContracts = manifest.contracts.map((c2) => c2.name).join(", ");
-    return new WithValidations(null, [
-      `Contract "${contractName}" not found in local plugin "${pluginName}". Available contracts: ${availableContracts}`
-    ]);
+  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);
-  return new WithValidations(
-    {
-      contractPath: path.join(localPluginPath, contract.contract),
-      componentPath,
-      componentName: contract.component,
-      // This is the exported member name
-      isNpmPackage: false
-    },
-    []
-  );
+  if (manifest.contracts && manifest.contracts.length > 0) {
+    const contract = manifest.contracts.find((c2) => c2.name === contractName);
+    if (contract) {
+      return new WithValidations(
+        {
+          contractPath: path.join(localPluginPath, contract.contract),
+          componentPath,
+          componentName: contract.component,
+          isNpmPackage: false
+        },
+        []
+      );
+    }
+  }
+  const dynamicConfig = findDynamicContract(manifest, contractName);
+  if (dynamicConfig) {
+    return new WithValidations(
+      {
+        contractPath: "",
+        // Dynamic contracts don't have a static path
+        componentPath,
+        componentName: dynamicConfig.component,
+        isNpmPackage: false
+      },
+      []
+    );
+  }
+  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(", ");
+  return new WithValidations(null, [
+    `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`, {
@@ -1167,75 +1308,145 @@ function resolveNpmPlugin(projectRoot, pluginName, contractName) {
       `Failed to parse plugin.yaml for NPM package "${pluginName}" at ${pluginYamlPath}`
     ]);
   }
-  if (!manifest.contracts || manifest.contracts.length === 0) {
+  if (!manifest.contracts && !manifest.dynamic_contracts) {
     return new WithValidations(null, [
-      `NPM package "${pluginName}" has no contracts defined in plugin.yaml`
+      `NPM package "${pluginName}" has no contracts or dynamic_contracts defined in plugin.yaml`
     ]);
   }
-  const contract = manifest.contracts.find((c2) => c2.name === contractName);
-  if (!contract) {
-    const availableContracts = manifest.contracts.map((c2) => c2.name).join(", ");
-    return new WithValidations(null, [
-      `Contract "${contractName}" not found in NPM package "${pluginName}". Available contracts: ${availableContracts}`
-    ]);
+  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");
-  let componentPath;
-  let contractPath;
-  if (fs.existsSync(packageJsonPath)) {
-    try {
-      const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
-      const packageName = packageJson.name;
-      const moduleName = manifest.module || packageName;
-      if ((moduleName === packageName || !manifest.module) && packageJson.exports && packageJson.exports["."]) {
-        const mainExport = packageJson.exports["."];
-        const mainPath = typeof mainExport === "string" ? mainExport : mainExport.default || mainExport.import;
-        componentPath = path.join(npmPluginPath, mainPath);
-      } else {
-        componentPath = path.join(npmPluginPath, "dist/index.js");
+  const getComponentPath = () => {
+    if (fs.existsSync(packageJsonPath)) {
+      try {
+        const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+        const packageName = packageJson.name;
+        const moduleName = manifest.module || packageName;
+        if ((moduleName === packageName || !manifest.module) && packageJson.exports && packageJson.exports["."]) {
+          const mainExport = packageJson.exports["."];
+          const mainPath = typeof mainExport === "string" ? mainExport : mainExport.default || mainExport.import;
+          return path.join(npmPluginPath, mainPath);
+        }
+      } catch {
       }
-      const contractSpec = contract.contract;
-      const contractExportKey = "./" + contractSpec;
-      if (packageJson.exports && packageJson.exports[contractExportKey]) {
-        const exportPath = packageJson.exports[contractExportKey];
-        contractPath = path.join(npmPluginPath, exportPath);
+    }
+    return path.join(npmPluginPath, "dist/index.js");
+  };
+  if (manifest.contracts && manifest.contracts.length > 0) {
+    const contract = manifest.contracts.find((c2) => c2.name === contractName);
+    if (contract) {
+      const componentPath = getComponentPath();
+      let contractPath;
+      if (fs.existsSync(packageJsonPath)) {
+        try {
+          const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+          const contractSpec = contract.contract;
+          const contractExportKey = "./" + contractSpec;
+          if (packageJson.exports && packageJson.exports[contractExportKey]) {
+            const exportPath = packageJson.exports[contractExportKey];
+            contractPath = path.join(npmPluginPath, exportPath);
+          } else {
+            const possiblePaths = [
+              path.join(npmPluginPath, "dist", contractSpec),
+              path.join(npmPluginPath, "lib", contractSpec),
+              path.join(npmPluginPath, contractSpec)
+            ];
+            contractPath = possiblePaths.find((p) => fs.existsSync(p)) || possiblePaths[0];
+          }
+        } catch {
+          contractPath = path.join(npmPluginPath, "dist", contract.contract);
+        }
       } else {
-        const possiblePaths = [
-          path.join(npmPluginPath, "dist", contractSpec),
-          path.join(npmPluginPath, "lib", contractSpec),
-          path.join(npmPluginPath, contractSpec)
-        ];
-        contractPath = possiblePaths.find((p) => fs.existsSync(p)) || possiblePaths[0];
+        contractPath = path.join(npmPluginPath, "dist", contract.contract);
       }
-    } catch (error) {
-      componentPath = path.join(npmPluginPath, "dist/index.js");
-      contractPath = path.join(npmPluginPath, "dist", contract.contract);
+      return new WithValidations(
+        {
+          contractPath,
+          componentPath,
+          componentName: contract.component,
+          isNpmPackage: true,
+          packageName: pluginName
+        },
+        []
+      );
     }
-  } else {
-    componentPath = path.join(npmPluginPath, "dist/index.js");
-    contractPath = path.join(npmPluginPath, "dist", contract.contract);
   }
-  return new WithValidations(
-    {
-      contractPath,
-      componentPath,
-      componentName: contract.component,
-      // This is the exported member name
-      isNpmPackage: true,
-      packageName: pluginName
-    },
-    []
-  );
+  const dynamicConfig = findDynamicContract(manifest, contractName);
+  if (dynamicConfig) {
+    const componentPath = getComponentPath();
+    return new WithValidations(
+      {
+        contractPath: "",
+        // Dynamic contracts don't have a static path
+        componentPath,
+        componentName: dynamicConfig.component,
+        isNpmPackage: true,
+        packageName: pluginName
+      },
+      []
+    );
+  }
+  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(", ");
+  return new WithValidations(null, [
+    `Contract "${contractName}" not found in NPM package "${pluginName}". Available: ${allAvailable}`
+  ]);
 }
 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.`
   ]);
@@ -1255,6 +1466,8 @@ export {
   Imports,
   ImportsFor,
   JAY_4_REACT,
+  JAY_ACTION_DTS_EXTENSION,
+  JAY_ACTION_EXTENSION,
   JAY_COMPONENT,
   JAY_CONTRACT_DTS_EXTENSION,
   JAY_CONTRACT_EXTENSION,
@@ -1272,6 +1485,7 @@ export {
   JAY_QUERY_WORKER_TRUSTED_TS,
   JAY_RUNTIME,
   JAY_SECURE,
+  JAY_STACK_CLIENT_RUNTIME,
   JAY_TS_EXTENSION,
   JayArrayType,
   JayAtomicType,
@@ -1288,6 +1502,7 @@ export {
   JayImportedType,
   JayNumber,
   JayObjectType,
+  JayOptionalType,
   JayPromiseType,
   JayRecursiveType,
   JayString,
@@ -1295,6 +1510,7 @@ export {
   JayTypeKind,
   JayUnionType,
   JayUnknown,
+  LOCAL_PLUGIN_PATH,
   MAKE_JAY_4_REACT_COMPONENT,
   MAKE_JAY_COMPONENT,
   MAKE_JAY_TSX_COMPONENT,
@@ -1308,6 +1524,7 @@ export {
   addBuildEnvironment,
   checkValidationErrors,
   equalJayTypes,
+  findDynamicContract,
   getBasePath,
   getBuildEnvironment,
   getJayTsFileSourcePath,
@@ -1332,22 +1549,24 @@ export {
   isImportedType,
   isLocalModule,
   isObjectType,
+  isOptionalType,
   isPromiseType,
   isRecursiveType,
   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.11.0",
+  "version": "0.13.0",
   "type": "module",
   "description": "",
   "license": "Apache-2.0",
@@ -25,10 +25,10 @@
   },
   "author": "",
   "dependencies": {
-    "@jay-framework/component": "^0.11.0",
-    "@jay-framework/runtime": "^0.11.0",
-    "@jay-framework/secure": "^0.11.0",
-    "@jay-framework/typescript-bridge": "^0.6.0",
+    "@jay-framework/component": "^0.13.0",
+    "@jay-framework/runtime": "^0.13.0",
+    "@jay-framework/secure": "^0.13.0",
+    "@jay-framework/typescript-bridge": "^0.8.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.11.0",
+    "@jay-framework/dev-environment": "^0.13.0",
     "@testing-library/jest-dom": "^6.2.0",
     "@types/js-beautify": "^1",
     "@types/node": "^20.11.5",